Skip to content
HeliosDB HeliosDB Lite

Vector Search

Built-in HNSW vector indexing for similarity search, RAG applications, and AI/ML workloads. In HeliosDB Lite, vector search runs in SQL, over the PostgreSQL wire, over REST (/v1/branches/{branch}/query) or in embedded mode. The REST vector-store endpoints are planned.

Creating Vector Tables

CREATE TABLE documents (
    id INTEGER PRIMARY KEY,
    content TEXT,
    category TEXT,
    embedding VECTOR(384)
);

Inserting Vectors

INSERT INTO documents (id, content, category, embedding)
VALUES (1, 'Machine learning basics', 'tech', '[0.1, 0.2, 0.3, ...]');

Nearest Neighbor (Euclidean)

SELECT content FROM documents
ORDER BY embedding <-> '[0.15, 0.25, ...]'
LIMIT 10;

Cosine Distance

SELECT content FROM documents
ORDER BY embedding <=> '[0.15, 0.25, ...]'
LIMIT 10;

Creating Vector Indexes

HNSW Index

CREATE INDEX docs_embedding_idx ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 200, ef_search = 100);

HNSW with Product Quantization

Product Quantization stores compact codes instead of full vectors in the index. Request it per index:

CREATE INDEX docs_embedding_pq_idx ON documents
USING hnsw (embedding)
WITH (quantization = 'product', pq_subquantizers = 8, pq_centroids = 256);

Indexes are not quantized unless you ask. In HeliosDB Nano, Product Quantization cut resident vector-index RAM by about 16x at recall-safe defaults (recall@10 0.987 vs 0.989; internal tests, Nano 3.32.1 vs an unquantized index). No Lite-specific measurement has been published.

Vector Operators

OperatorDescription
<->Euclidean distance
<=>Cosine distance
<#>Negative inner product

Combine vector ordering with ordinary SQL predicates:

SELECT content FROM documents
WHERE category = 'tech'
ORDER BY embedding <-> '[0.1, 0.2, ...]'
LIMIT 10;

Tuning Performance

HNSW parameters are set per index in the WITH clause: m (graph degree), ef_construction (build-time candidate list) and ef_search (query-time candidate list). Higher values improve recall and cost more memory or time.

REPL Commands

In the REPL, \help vectors lists the vector commands. The vector-store commands (\vectors, \vector create, \vector stats) use the same vector-store engine as the planned REST vector-store endpoints. Use SQL tables with VECTOR(n) columns today.