Skip to main content
Version: 0.1.0

Embeddings and Vector Search

RaisinDB stores vector embeddings alongside your content and provides fast approximate nearest neighbor (ANN) search via an integrated HNSW index. This means you can query semantically similar content using standard SQL — no external vector database required.

How Embeddings Work in RaisinDB​

Every node in RaisinDB can have an associated embedding vector. When you create or update a node, RaisinDB can automatically generate an embedding from the node's content using your configured AI provider.

Node created/updated
        │
        ▼
  Embedding job queued
        │
        ▼
  Provider generates vector
  (e.g., OpenAI text-embedding-3-small → 1536 dimensions)
        │
        ▼
  Vector stored in HNSW index
  (scoped to tenant/repo/branch/workspace)

Embedding generation is asynchronous — it runs through the job system so write operations are never blocked.

Configuring Auto-Embedding​

To enable automatic embedding generation, ensure your tenant has an embedding provider configured (see AI Provider Configuration). Embeddings are generated for node content based on your configuration.

Vector Search with SQL​

RaisinDB integrates vector search directly into the SQL engine using the VECTOR_SEARCH function.

Find the 10 most similar nodes to a query vector:

SELECT id, name, properties, __distance
FROM 'default'
WHERE VECTOR_SEARCH(embedding, $1, 10)
ORDER BY __distance ASC
  • $1 is the query vector (typically generated from a text query using the same embedding model)
  • 10 is the number of results (top-k)
  • __distance is the cosine distance (lower = more similar)

Understanding Distance Scores​

RaisinDB uses cosine distance (1 - cosine similarity):

DistanceCosine SimilarityInterpretation
0.01.0Identical vectors
0.2 – 0.40.8 – 0.6Semantically similar
0.4 – 0.60.6 – 0.4Weakly related
> 0.6< 0.4Not related

KNN Queries​

K-nearest neighbor queries return the k closest vectors to your query:

-- Find 5 articles most similar to a query
SELECT id, name, properties->>'title'::String AS title, __distance
FROM 'default'
WHERE VECTOR_SEARCH(embedding, $1, 5)
  AND node_type = 'article'
ORDER BY __distance ASC

You can combine VECTOR_SEARCH with additional WHERE clauses. The vector search runs first to identify candidates, then additional filters are applied.

Search Modes​

RaisinDB supports two search modes for handling multi-chunk documents:

  • Documents mode (default) — deduplicates results by source document, returning the best matching chunk per document
  • Chunks mode — returns all matching chunks ranked by similarity

Documents mode is typically what you want for RAG applications, where you need unique source documents rather than multiple chunks from the same document.

Distance Filtering in WHERE Clauses​

You can filter results by distance directly in SQL using the <=> operator. The HNSW engine extracts the threshold and applies it during the search for optimal performance:

-- Only return results within a cosine distance of 0.3
SELECT id, name, properties->>'title'::String AS title
FROM 'default'
WHERE embedding <=> EMBEDDING('machine learning') < 0.3
ORDER BY embedding <=> EMBEDDING('machine learning');

Configurable Default Max Distance​

By default, vector search filters out results beyond a maximum distance threshold. You can configure this per-tenant:

ALTER EMBEDDING CONFIG SET DEFAULT_MAX_DISTANCE = '0.5';

This replaces the previous hard-coded threshold and gives you control over how aggressively distant results are filtered.

Hybrid Search: Vector + Full-Text​

Combine vector similarity with traditional SQL filters for more precise results:

-- Vector search + keyword filter
SELECT id, name, properties->>'title'::String AS title, __distance
FROM 'default'
WHERE VECTOR_SEARCH(embedding, $1, 20)
  AND properties->>'category'::String = 'technology'
ORDER BY __distance ASC
LIMIT 10
-- Vector search + path hierarchy
SELECT id, name, __distance
FROM 'default'
WHERE VECTOR_SEARCH(embedding, $1, 10)
  AND PATH_STARTS_WITH(path, '/knowledge-base/docs/')
ORDER BY __distance ASC

This lets you scope vector search to specific categories, content types, or locations in the content hierarchy.

HYBRID_SEARCH Table Function​

The HYBRID_SEARCH table function combines full-text search and vector similarity using Reciprocal Rank Fusion (RRF) to produce a single ranked result set. This is the recommended approach when you want the best of both keyword matching and semantic search:

SELECT * FROM HYBRID_SEARCH('how does authentication work', 10);

This returns up to 10 results with the following columns:

ColumnTypeDescription
node_idTEXTThe matched node ID
nameTEXTNode name
pathTEXTNode path in the content hierarchy
node_typeTEXTNode type
scoreDOUBLECombined RRF score (higher = more relevant)
fulltext_rankDOUBLEFull-text search rank
vector_rankDOUBLEVector similarity rank
vector_distanceDOUBLERaw vector distance
propertiesJSONNode properties
tip

HYBRID_SEARCH is ideal for RAG applications where pure vector search may miss keyword-specific matches and pure full-text search may miss semantically similar content.

Filtering by Node Type​

Restrict vector search to specific node types:

-- Only search within FAQ entries
SELECT id, name, properties->>'question'::String AS question, __distance
FROM 'default'
WHERE VECTOR_SEARCH(embedding, $1, 10)
  AND node_type = 'faq:Entry'
ORDER BY __distance ASC

HNSW indexes are scoped to tenant, repository, and branch. When you create a new branch, the vector index is efficiently copied for the new branch context. This means:

  • Vector search on main returns different results than on feature-branch if content diverged
  • Each agent branch has its own independent vector index
  • Merging branches reconciles both content and vector indexes
-- Search on a specific branch (set via connection context)
-- psql -U tenant1/repo1/feature-branch
SELECT id, name, __distance
FROM 'default'
WHERE VECTOR_SEARCH(embedding, $1, 10)
ORDER BY __distance ASC

Scoring Configuration​

For multi-chunk documents, RaisinDB provides scoring controls:

  • Position decay — earlier chunks in a document score higher than later chunks
  • First chunk boost — the first chunk of a document gets a configurable score boost

These settings help ensure that the beginning of a document (which often contains the most relevant summary information) is weighted appropriately.

Document Chunking​

When chunking is enabled in your embedding configuration, long documents are automatically chunked before embedding. The embedding worker splits content using the configured strategy, generates embeddings for each chunk via the batch embedding API, and stores them in the HNSW index with chunk metadata.

No manual chunking is needed — the pipeline handles splitting, embedding, and indexing automatically when nodes are created or updated.

Vector Index Management​

RaisinDB provides SQL commands to manage and monitor HNSW indexes:

-- Rebuild the vector index from stored embeddings
REBUILD VECTOR INDEX;

-- Verify index integrity
VERIFY VECTOR INDEX;

-- Show index health statistics
SHOW VECTOR INDEX HEALTH;

These commands are available via SQL and pgwire, making them accessible from psql or any PostgreSQL-compatible client.

EXPLAIN for Vector Queries​

Use EXPLAIN to inspect how vector queries are executed:

EXPLAIN SELECT id, name, __distance
FROM 'default'
WHERE VECTOR_SEARCH(embedding, $1, 10)
ORDER BY __distance ASC;

This shows the VectorScan plan details, including the number of candidates, distance metric, and any threshold filtering applied.

Performance Characteristics​

The HNSW index provides:

  • O(log n) search time — fast even with millions of vectors
  • Memory-bounded — uses an LRU cache to limit memory usage
  • Persistent — periodic snapshots to disk with dirty tracking
  • Crash-safe — graceful shutdown ensures all dirty indexes are saved
  • Multi-tenant — separate indexes per tenant/repo/branch

Next Steps​