Vector search - NetlyDB documentation

What it does

An embedding model turns text (or an image, or anything else it understands) into a list of numbers - a vector - such that similar meanings produce nearby vectors. Vector search stores those vectors next to your documents and returns the documents whose vectors are closest to a query vector. That is how an application finds "documents about key rotation" when none of them contain the exact words the user typed.

Documents as points placed by meaning. A query lands nearest the documents that mean the same thing, whatever words they use.

Vector search is part of the Community edition. You bring the vectors; see Semantic search for producing them.

Index strategies

Strategy	Behaviour
Flat (default)	Exact: scores every vector, using SIMD instructions. Results are labelled exact.
HNSW	Approximate: searches a navigable graph instead of scoring every vector. Tunable with `m`, `efConstruction` and `efSearch` (defaults 16, 200 and 64; `efSearch` is raised to at least `k`). Results are labelled approximate.

Flat scores the query against every stored vector. HNSW starts at an entry point and walks a graph towards the neighbourhood, visiting far fewer vectors.

Metrics: cosine, dot product and Euclidean distance. For every metric a higher score means closer.

public record Article
{
    public Guid Id { get; init; }
    public string Title { get; init; } = "";
    public string Content { get; init; } = "";
    public float[] Embedding { get; init; } = [];   // produced by the embedding model you choose
}

// Flat (exact) index by default...
articles.CreateVectorIndex(x => x.Embedding, dimensions: 1536, VectorMetric.Cosine);

// ...or an approximate HNSW graph index:
articles.CreateVectorIndex(x => x.Embedding, dimensions: 1536, VectorMetric.Cosine,
    options: VectorIndexOptions.Hnsw(m: 16, efConstruction: 200, efSearch: 64));

// k-nearest-neighbour search; a higher score is closer for every metric
float[] queryEmbedding = await myEmbeddingModel.EmbedAsync("how do I rotate keys?");
var hits = articles.VectorSearch(x => x.Embedding, queryEmbedding, k: 5);

Vectors kept outside the document

When the document has no float[] property - or you want several embeddings per document - keep vectors in a named external index and set them by document id.

// No float[] property on the document? Keep vectors in a named external index.
articles.CreateExternalVectorIndex("semantic", dimensions: 1536, VectorMetric.Cosine);

articles.SetVector(documentId, vector, "semantic");
articles.SetVectors(batch, "semantic");   // IEnumerable<(Guid Id, float[] Vector)>

var hits = articles.VectorSearch(queryEmbedding, k: 5, indexName: "semantic");

Where else it is available

The Management UI's Search page: search by text, by a similar document, or by a raw vector Enterprise.
The MCP server's SemanticSearch tool, when an embedding provider is registered Enterprise.

Things to know

HNSW recall has not been measured by NetlyDB yet. Approximate results are labelled as such, but their quality is not quantified. A recall-measurement harness is planned work.
The HNSW graph is not persisted; it is rebuilt from the stored vectors on load, so startup time grows with index size.
A vector set with SetVector is durable from the next snapshot. Setting one triggers an index-only snapshot, so the window is small, but a process that stops inside it loses vectors that cannot be regenerated.
Vectors in an external index are not replicated to other cluster nodes. Vectors stored on a document property travel with the document.
There is no filtering inside the vector search itself: filter the returned candidates in your code.
Vector indexes exist for document collections, not file collections.