---
title: "Vector Search"
description: "Built-in HNSW vector indexing in HeliosDB Lite, queried in SQL, with optional Product Quantization for similarity search and RAG workloads."
---

# 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

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

## Inserting Vectors

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

## Vector Search

### Nearest Neighbor (Euclidean)

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

### Cosine Distance

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

## Creating Vector Indexes

### HNSW Index

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

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

| Operator | Description |
|----------|-------------|
| `<->` | Euclidean distance |
| `<=>` | Cosine distance |
| `<#>` | Negative inner product |

## Filtered Search

Combine vector ordering with ordinary SQL predicates:

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

## Related

- [SQL Reference](https://www.heliosdb.com/docs/lite/user-guide/sql-reference/): vector syntax
- [REST API](https://www.heliosdb.com/docs/lite/website/api/readme/#vector-search-over-sql): running vector queries over REST