Vector Search in HeliosDB¶

Version: v7.0 Status: Production Ready Package: heliosdb-vector

Overview¶

HeliosDB provides enterprise-grade vector similarity search capabilities, enabling semantic search, recommendation systems, and AI-powered applications at scale. 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¶

-- 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¶

-- 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.

-- 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.

-- 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.

-- 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
`<->`	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.

-- 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.

-- 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¶

-- 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¶

-- 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¶

-- 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¶

-- 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¶

-- 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:

-- 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¶

-- 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

Document	Description
QUICK_START.md	Getting started tutorial
INDEXING_GUIDE.md	Index tuning and configuration
EXAMPLES.md	Production use cases
Hybrid Search Guide	Dense + sparse fusion
Multimodal Search	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

Status: Production Ready Version: v7.0 Last Updated: January 2026