---
title: "Vector Search in HeliosDB"
---

# Vector Search in HeliosDB

---

## Overview

HeliosDB provides vector similarity search for semantic search, recommendation systems, and AI-powered applications. The vector search engine combines high-performance indexing algorithms with SIMD-accelerated distance calculations to deliver sub-10ms query latency on million-scale datasets.

### Key Capabilities

- **Native Vector Data Type**: First-class `VECTOR(n)` column type with SQL integration
- **Multiple Index Types**: HNSW for high recall, IVF for memory efficiency
- **SIMD Acceleration**: AVX-512/AVX2 optimized distance calculations (5-10x speedup)
- **Hybrid Search**: Combine vector similarity with keyword (BM25) and metadata filtering
- **Distributed Search**: Sharded indexes with automatic query routing
- **RAG Integration**: Native support for Retrieval-Augmented Generation pipelines
- **Multi-Modal Support**: Text, image, audio, and video embeddings

---

## Vector Data Types and Dimensions

### VECTOR Type Syntax

```sql
-- Create table with vector column
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    title TEXT,
    content TEXT,
    embedding VECTOR(768)    -- 768-dimensional vector
);

-- Supported dimensions: 1 to 65536
-- Common embedding sizes:
--   384:  all-MiniLM-L6-v2, distilbert-base
--   512:  CLIP ViT-B/32, sentence-transformers
--   768:  BERT-base, RoBERTa, PubMedBERT
--   1024: BERT-large, ImageBind
--   1536: OpenAI text-embedding-ada-002
--   3072: OpenAI text-embedding-3-large
```

### Vector Literal Formats

```sql
-- Standard bracket notation
INSERT INTO documents (embedding) VALUES ('[0.1, 0.2, 0.3, 0.4]');

-- Explicit CAST
INSERT INTO documents (embedding) VALUES ('[0.1, 0.2, 0.3]'::VECTOR(3));

-- Scientific notation supported
INSERT INTO documents (embedding) VALUES ('[1e-3, 2.5e-2, -3.7e-1]');

-- From array
INSERT INTO documents (embedding) VALUES (ARRAY[0.1, 0.2, 0.3]::VECTOR);
```

### Dimension Guidelines

| Embedding Model | Dimensions | Use Case |
|-----------------|------------|----------|
| all-MiniLM-L6-v2 | 384 | General text, fast inference |
| CLIP ViT-B/32 | 512 | Image-text cross-modal |
| BERT-base | 768 | Text understanding |
| text-embedding-ada-002 | 1536 | OpenAI general purpose |
| text-embedding-3-large | 3072 | OpenAI high accuracy |

---

## Similarity Search Algorithms

HeliosDB supports multiple distance metrics for vector similarity comparison:

### Cosine Similarity

Best for normalized vectors and text embeddings.

```sql
-- Cosine distance (1 - cosine_similarity)
-- Range: [0, 2] where 0 = identical, 2 = opposite
SELECT id, content, embedding <=> query_vector AS distance
FROM documents
ORDER BY embedding <=> query_vector
LIMIT 10;
```

**When to use:**
- Text embeddings (BERT, GPT, Sentence Transformers)
- Normalized vectors
- Semantic similarity search
- Document retrieval

### L2 (Euclidean) Distance

Best for image embeddings and non-normalized vectors.

```sql
-- L2 distance
-- Range: [0, infinity) where 0 = identical
SELECT id, content, embedding <-> query_vector AS distance
FROM documents
ORDER BY embedding <-> query_vector
LIMIT 10;
```

**When to use:**
- Image embeddings (ResNet, VGG, CLIP images)
- General-purpose vector search
- Clustering and anomaly detection
- Vectors where magnitude matters

### Inner Product (Dot Product)

Best for Maximum Inner Product Search (MIPS) applications.

```sql
-- Inner product (negative for similarity ordering)
-- Range: (-infinity, infinity) where larger = more similar
SELECT id, content, embedding <#> query_vector AS distance
FROM documents
ORDER BY embedding <#> query_vector
LIMIT 10;
```

**When to use:**
- Already normalized vectors
- Collaborative filtering
- Matrix factorization models
- Neural network activations

### Distance Operators Summary

| Operator | Distance Metric | Formula | Best For |
|----------|-----------------|---------|----------|
| `<=>` | Cosine | 1 - (a.b)/(|a||b|) | Text embeddings |
| `<->` | L2 (Euclidean) | sqrt(sum((a-b)^2)) | Image embeddings |
| `<#>` | Inner Product | -sum(a*b) | MIPS, normalized vectors |

---

## Index Types

### HNSW (Hierarchical Navigable Small World)

The default and recommended index type for most use cases. HNSW builds a multi-layer graph structure for fast approximate nearest neighbor search.

```sql
-- Create HNSW index
CREATE INDEX idx_docs_embedding ON documents
  USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 200);

-- Index parameters:
-- m: connections per node (8-64, default 16)
-- ef_construction: build quality (100-500, default 200)
```

**Performance Characteristics:**
- Search complexity: O(log N)
- Insert throughput: 10K vectors/sec
- Query latency (p99): <10ms
- Recall@10: 95%+
- Memory: ~400 bytes/vector (with M=16)

### IVF (Inverted File Index)

Memory-efficient index for billion-scale datasets with optional quantization.

```sql
-- Create IVF index
CREATE INDEX idx_docs_embedding ON documents
  USING ivfflat (embedding vector_l2_ops)
  WITH (lists = 1000);

-- Index parameters:
-- lists: number of clusters (sqrt(N) is good starting point)
```

**Performance Characteristics:**
- Search complexity: O(sqrt(N))
- Insert throughput: 100K vectors/sec
- Query latency (p99): <20ms
- Recall@10: 90%+
- Memory: ~100 bytes/vector (with PQ)

### Index Type Comparison

| Feature | HNSW | IVF |
|---------|------|-----|
| **Recall** | 95%+ | 90%+ |
| **Latency** | <10ms | <20ms |
| **Memory** | High | Low (with PQ) |
| **Build Time** | Moderate | Fast |
| **Updates** | Fast | Rebuild needed |
| **Best For** | <10M vectors | >10M vectors |

---

## SQL Integration

### Basic Similarity Search

```sql
-- Find 10 most similar documents
SELECT id, title, embedding <=> '[0.1, 0.2, ...]'::VECTOR AS similarity
FROM documents
ORDER BY embedding <=> '[0.1, 0.2, ...]'::VECTOR
LIMIT 10;
```

### Similarity Search with Filtering

```sql
-- Vector search with metadata filters
SELECT id, title, embedding <=> query_embedding AS distance
FROM documents
WHERE category = 'technology'
  AND created_at > '2024-01-01'
ORDER BY embedding <=> query_embedding
LIMIT 10;
```

### Distance Threshold Search

```sql
-- Find all vectors within distance threshold
SELECT id, title
FROM documents
WHERE embedding <=> query_embedding < 0.3
ORDER BY embedding <=> query_embedding;
```

### Batch Vector Search

```sql
-- Search for multiple queries at once
SELECT q.query_id, d.id, d.title,
       d.embedding <=> q.embedding AS distance
FROM queries q
CROSS JOIN LATERAL (
    SELECT id, title, embedding
    FROM documents
    ORDER BY embedding <=> q.embedding
    LIMIT 5
) d
ORDER BY q.query_id, distance;
```

---

## RAG and LLM Integration

HeliosDB provides native support for Retrieval-Augmented Generation (RAG) pipelines.

### RAG Pipeline Architecture

```
User Query
    |
    v
[Embedding Model] --> Query Vector
    |
    v
[Vector Search] --> Top-K Documents
    |
    v
[Context Assembly] --> Prompt
    |
    v
[LLM] --> Generated Response
```

### RAG SQL Functions

```sql
-- Built-in RAG search function
SELECT * FROM rag_search(
    collection => 'knowledge_base',
    query => 'What is vector search?',
    top_k => 5,
    embedding_model => 'text-embedding-ada-002'
);

-- With metadata filtering
SELECT * FROM rag_search(
    collection => 'knowledge_base',
    query => 'machine learning best practices',
    top_k => 10,
    filters => '{"category": "ML", "year": 2024}'::jsonb
);
```

### Hybrid RAG Search

Combine semantic similarity with keyword matching for improved retrieval:

```sql
-- Hybrid search combining vector + BM25
SELECT
    d.id,
    d.content,
    (0.7 * vector_score + 0.3 * bm25_score) AS hybrid_score
FROM documents d
JOIN (
    SELECT id, embedding <=> query_vector AS vector_score
    FROM documents
    ORDER BY embedding <=> query_vector
    LIMIT 100
) v ON d.id = v.id
JOIN (
    SELECT id, ts_rank(to_tsvector(content), query) AS bm25_score
    FROM documents
    WHERE to_tsvector(content) @@ plainto_tsquery('machine learning')
) t ON d.id = t.id
ORDER BY hybrid_score DESC
LIMIT 10;
```

### LLM Integration Example

```sql
-- Generate embeddings using built-in embedding function
INSERT INTO documents (title, content, embedding)
VALUES (
    'Vector Search Guide',
    'This document explains vector search...',
    generate_embedding('This document explains vector search...', 'text-embedding-ada-002')
);

-- Query with automatic embedding generation
SELECT * FROM semantic_search(
    table_name => 'documents',
    query_text => 'How does similarity search work?',
    column => 'embedding',
    limit => 5
);
```

---

## Performance Characteristics

### Benchmark Results

| Dataset Size | Index Type | Query Latency (p99) | Recall@10 | QPS |
|--------------|------------|---------------------|-----------|-----|
| 100K | HNSW | 2ms | 97% | 15,000 |
| 1M | HNSW | 8ms | 96% | 10,000 |
| 10M | HNSW | 15ms | 95% | 5,000 |
| 100M | IVF-PQ | 25ms | 92% | 3,000 |

### SIMD Acceleration

HeliosDB automatically uses the best available SIMD instructions:

| Instruction Set | Distance Calc Time (128D) | Speedup |
|-----------------|---------------------------|---------|
| Scalar | ~500ns | 1x |
| AVX2 | ~80ns | 6x |
| AVX-512 | ~45ns | 11x |

---

## Related Documentation

| Document | Description |
|----------|-------------|
| [QUICK_START.md](https://www.heliosdb.com/docs/full/features/vector-search/quick_start/) | Getting started tutorial |
| [INDEXING_GUIDE.md](https://www.heliosdb.com/docs/full/features/vector-search/indexing_guide/) | Index tuning and configuration |
| [EXAMPLES.md](https://www.heliosdb.com/docs/full/features/vector-search/examples/) | Production use cases |
| [Multimodal Search](https://www.heliosdb.com/docs/full/features/multimodal-vector/readme/) | Cross-modal search |

---

## Architecture

```
                        Query Vector
                             |
                             v
              +----------------------------+
              |     Query Optimizer        |
              |  (Cost-based planning)     |
              +----------------------------+
                             |
              +--------------+--------------+
              |                             |
              v                             v
    +------------------+         +------------------+
    |   HNSW Index     |         |    IVF Index     |
    | (High Recall)    |         | (Memory Efficient)|
    +------------------+         +------------------+
              |                             |
              v                             v
    +------------------+         +------------------+
    | SIMD Distance    |         | Product Quantizer|
    | (AVX-512/AVX2)   |         | (8-bit codes)    |
    +------------------+         +------------------+
              |                             |
              +--------------+--------------+
                             |
                             v
              +----------------------------+
              |    Result Merger           |
              | (Score normalization)      |
              +----------------------------+
                             |
                             v
                      Top-K Results
```

---