HeliosDB Nano vs Vector Databases

Choose HeliosDB Nano when vectors sit next to relational data and you want joins, SQL filters and ACID transactions over both in one embedded or server database; keep a dedicated vector database when you need billions of vectors, a managed cloud service, built-in geographic distribution, or a vector-only workload.

Vector databases like Pinecone, Weaviate, Milvus, and Qdrant are purpose-built for vector search. HeliosDB Nano puts HNSW vector search inside a relational SQL engine, so one system can hold both the vectors and the data they describe.

---

Quick Comparison

---

The Architecture Problem

With Separate Vector Database

+---------------+     +---------------+     +---------------+
|  Your App     |---->|  PostgreSQL   |     |   Pinecone    |
|               |---->|  (metadata)   |     |  (vectors)    |
+---------------+     +---------------+     +---------------+
                             |                    |
                             +--------------------+
                              Must sync manually

Problems:

• Data consistency between systems
• Complex sync logic
• Multiple points of failure
• Higher latency (multiple network hops)
• More operational overhead
• Higher costs

With HeliosDB Nano

+---------------+     +-------------------+
|  Your App     |---->|  HeliosDB Nano    |
|               |     | (vectors + SQL)   |
+---------------+     +-------------------+

Benefits:

• Single source of truth
• ACID transactions for vectors + metadata
• One query for hybrid search
• Embedded deployment option
• Simpler architecture

---

Vector Search Capabilities

HNSW Index

-- Same HNSW algorithm as Pinecone, Qdrant, etc.
CREATE INDEX ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 200);

-- Tune search precision
SET hnsw.ef_search = 100;

Distance Functions

-- Cosine distance (normalized vectors)
SELECT * FROM docs ORDER BY embedding <=> $query LIMIT 10;

-- Euclidean distance (L2)
SELECT * FROM docs ORDER BY embedding <-> $query LIMIT 10;

-- Inner product
SELECT * FROM docs ORDER BY embedding <#> $query LIMIT 10;

Product Quantization

Product Quantization is in Nano's default build: add WITH (quantization='product') to an HNSW index. Indexes are unquantized unless you ask, and durable restart-surviving PQ-HNSW indexes need the vector-persist build, which keeps PQ codes in RAM with full vectors on disk and reranks results exactly (Product Quantization guide). Resident-memory savings and recall are measured on representative fixtures on the benchmarks page. Measure recall on your own embeddings before relying on any ratio.

-- Product Quantization in the default build
CREATE INDEX ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (quantization = 'product');

---

What Vector DBs Can't Do

1. Relational Joins

-- HeliosDB Nano: One query for everything
SELECT
    d.title,
    d.content,
    a.name AS author,
    c.name AS category,
    d.embedding <=> $query AS relevance
FROM documents d
JOIN authors a ON d.author_id = a.id
JOIN categories c ON d.category_id = c.id
WHERE c.name = 'Technology'
  AND a.verified = true
ORDER BY relevance
LIMIT 10;

-- Vector DB: Requires multiple queries and app-side joins

2. Complex Aggregations

-- HeliosDB Nano: Analytics on vector data
SELECT
    category,
    COUNT(*) AS doc_count,
    AVG(embedding <=> $query) AS avg_relevance,
    MIN(embedding <=> $query) AS best_match
FROM documents
WHERE embedding <=> $query < 0.5
GROUP BY category
ORDER BY avg_relevance;

-- Vector DB: Would need to export data for analysis

3. ACID Transactions

-- HeliosDB Nano: Atomic update of document and embedding
BEGIN;
UPDATE documents
SET content = $new_content, embedding = $new_embedding
WHERE id = $doc_id;
UPDATE search_index SET updated_at = NOW() WHERE doc_id = $doc_id;
COMMIT;

-- Vector DB: No transactional guarantees, eventual consistency

4. SQL-Based Metadata Filtering

-- Complex filters that vector DBs struggle with
SELECT * FROM documents
WHERE embedding <=> $query < 0.5
  AND created_at > NOW() - INTERVAL '30 days'
  AND author_id IN (SELECT id FROM authors WHERE department = 'Engineering')
  AND NOT EXISTS (
    SELECT 1 FROM flagged_content
    WHERE flagged_content.doc_id = documents.id
  )
ORDER BY embedding <=> $query
LIMIT 10;

5. Time-Travel for Vectors

-- What were the search results a week ago? (needs retention that reaches back that far)
SELECT * FROM documents
AS OF TIMESTAMP '2026-01-19 00:00:00'
ORDER BY embedding <=> $query
LIMIT 10;

-- Compare embedding drift
SELECT
    d.id,
    d_old.embedding <=> d.embedding AS drift
FROM documents d
JOIN documents AS OF TIMESTAMP '2026-01-01' d_old ON d.id = d_old.id
WHERE d.embedding <=> d_old.embedding > 0.1;

---

Migration from Vector Databases

From Pinecone

# Export from Pinecone
import pinecone

index = pinecone.Index("my-index")
vectors = index.fetch(ids=all_ids)

# Import to HeliosDB Nano (embedded Python binding)
import json
import heliosdb_nano

db = heliosdb_nano.EmbeddedDatabase("./app-data")
db.execute("""
    CREATE TABLE documents (
        id TEXT PRIMARY KEY,
        embedding VECTOR(768),
        metadata JSONB
    )
""")

db.execute_many(
    "INSERT INTO documents (id, embedding, metadata) VALUES ($1, $2, $3)",
    [(id, json.dumps(data['values']), json.dumps(data['metadata']))
     for id, data in vectors.items()]
)

From Qdrant

# Export from Qdrant
from qdrant_client import QdrantClient

client = QdrantClient("localhost", port=6333)
points = client.scroll("my_collection", limit=10000)[0]

# Import to HeliosDB Nano
db.execute_many(
    "INSERT INTO documents (id, embedding, metadata) VALUES ($1, $2, $3)",
    [(str(point.id), json.dumps(point.vector), json.dumps(point.payload))
     for point in points]
)

---

Performance Comparison

We do not publish a head-to-head benchmark against Pinecone, Weaviate or Qdrant, so this page carries no throughput, latency or recall figures for them. Nano's own vector results, including Product Quantization memory and recall measured on representative fixtures, are on the benchmarks page, and all of them are single-node. Measure each candidate on your own data before choosing.

---

Use Case: RAG Application

With Pinecone + PostgreSQL

# Two separate systems
pg_conn = psycopg2.connect(PG_URL)
pinecone_index = pinecone.Index("docs")

def search(query):
    # Get embedding
    embedding = model.encode(query)

    # Search vectors
    vector_results = pinecone_index.query(embedding, top_k=10)
    ids = [r.id for r in vector_results.matches]

    # Fetch metadata from PostgreSQL
    docs = pg_conn.execute(
        "SELECT * FROM documents WHERE id = ANY($1)",
        [ids]
    )

    # Manually combine results
    return combine(vector_results, docs)

With HeliosDB Nano

# One query does everything
def search(query):
    embedding = model.encode(query)

    return db.query("""
        SELECT
            d.*,
            a.name AS author_name,
            array_agg(t.name) AS tags,
            d.embedding <=> $1::vector(768) AS relevance
        FROM documents d
        JOIN authors a ON d.author_id = a.id
        LEFT JOIN document_tags dt ON d.id = dt.document_id
        LEFT JOIN tags t ON dt.tag_id = t.id
        WHERE d.embedding <=> $1::vector(768) < 0.5
        GROUP BY d.id, a.name
        ORDER BY relevance
        LIMIT 10
    """, [embedding])

---

When to Use a Dedicated Vector DB

Consider Pinecone, Qdrant, or similar if you:

• Need massive scale (billions of vectors)
• Want managed cloud service with no operations
• Have vector-only use cases (no relational data)
• Need geographic distribution built-in
• Require specialized vector features (multimodal, etc.)

---

When HeliosDB is not the right fit

• Your client casts bound query vectors with a bare ::vector. That cast fails on a bound parameter today; inline literals work, and the Nano page shows a bound parameter with an explicit dimension ($1::vector(768)). Known limitations
• You expect restart-surviving vector indexes from the default build. Product Quantization is in the default build, but durable restart-surviving PQ-HNSW indexes need the vector-persist build. Nano vector search
• You need billions of vectors across many nodes. Published HeliosDB benchmarks are single-node, and Nano's sharding tier is a non-default build feature. Benchmarks · High availability
• Your hybrid search needs strong keyword relevance. The full-text side has no stemming and no phrase queries yet (both are planned), and GIN indexes are accepted but not consulted at runtime. Full-text search compatibility
• You need expression indexes. CREATE INDEX on an expression is rejected. Known limitations
• Several in-process writers need independent transactions. The embedded API has one transaction slot per process; independent sessions need server mode. Concurrency and transactions

---

Summary