Skip to content

Vector, full-text and hybrid search

Search in NamiDB is ordinary Cypher. Embeddings and text are node properties; you rank them with functions or with the search.* procedures, and an index, when you declare one, changes the cost of a query but never its result.

The examples use this data (Python shown; any client works):

import namidb
db = namidb.Client("file:///var/lib/namidb?ns=docs")
docs = [
("graph storage engines", "nodes and edges in a bucket", [0.9, 0.1, 0.0], "acme", 2024, True),
("vector search basics", "nearest neighbours over embeddings", [0.1, 0.9, 0.1], "acme", 2025, True),
("graph databases on S3", "object storage is the database", [0.8, 0.2, 0.1], "globex", 2023, False),
("cooking pasta", "boil water, add salt", [0.0, 0.1, 0.9], "globex", 2022, True),
]
for title, body, emb, tenant, year, live in docs:
db.cypher(
"CREATE (:Doc {title: $t, body: $b, embedding: $e, tenant: $tn, year: $y, live: $l})",
params={"t": title, "b": body, "e": emb, "tn": tenant, "y": year, "l": live},
)
q = [0.85, 0.15, 0.05]

Store an embedding as a list of floats and rank by a distance function:

MATCH (d:Doc)
RETURN d.title AS title, cosine_similarity(d.embedding, $q) AS score
ORDER BY score DESC LIMIT 2
{title: 'graph storage engines', score: 0.99628…}
{title: 'graph databases on S3', score: 0.99557…}
FunctionOrder byNotes
cosine_similarity(a, b)DESCNULL for a zero-magnitude vector, so such rows drop out of a KNN.
dot_product(a, b)DESC
euclidean_distance(a, b)ASC

The same KNN as a procedure:

CALL search.vector({label: 'Doc', property: 'embedding', query: $q, k: 2})
YIELD node, score
RETURN node.title AS title, score
OptionDefaultMeaning
labelrequiredLabel to search.
propertyrequiredProperty holding the vectors.
queryrequiredQuery vector (list or vector(…)).
k10Results to return.
efindex default (64)Beam width for the ANN index; higher trades latency for recall.
metriccosinecosine, dot / dot_product, euclidean / l2. Use the vector index’s metric so the index can serve the search.
filternoneMetadata eligibility, applied before k (see Filters).

An unknown option is an error (search.vector does not recognise the option …; allowed options: label, property, query, k, ef, metric, filter).

The Neo4j-compatible form takes an index name:

CALL db.index.vector.queryNodes('doc_emb', 2, $q) YIELD node, score
CALL db.index.vector.queryNodes('doc_emb', 2, $q, {ef: 200, filter: {live: true}}) YIELD node, score

Vector indexes

Without an index, vector search is an exact scan of the label. For large collections, declare a persistent approximate-nearest-neighbour index:

CREATE VECTOR INDEX doc_emb IF NOT EXISTS
ON :Doc(embedding) METRIC cosine DIMENSION 3
  • METRIC is cosine, dot or euclidean; DIMENSION is required.

  • Optional build parameters: WITH { r: 32, l_build: 64, alpha: 1.2 }.

  • WITH { quantization: int8 } stores int8 codes (about 4× smaller), for METRIC cosine only. Full-precision vectors are still used to rerank.

  • The Neo4j 5 spelling works too:

    CREATE VECTOR INDEX doc_emb IF NOT EXISTS
    FOR (d:Doc) ON d.embedding
    OPTIONS {indexConfig: {`vector.dimensions`: 3, `vector.similarity_function`: 'cosine'}}
  • DROP VECTOR INDEX doc_emb [IF EXISTS] removes it.

Once a vector index covers a property, writes are dimension-checked: a vector of the wrong size is rejected (HTTP 409):

constraint violation: Doc.embedding embedding has dim 2 but vector index `doc_emb` declares 3 (dimension constraint)

and a correct-size float list is stored as a dense vector so the index can include it.

The optimizer rewrites the natural KNN form to use the index:

EXPLAIN MATCH (d:Doc) RETURN d.title AS title
ORDER BY cosine_similarity(d.embedding, $q) DESC LIMIT 2
Project [title=d.title]
VectorSearch label=Some("Doc") prop=embedding k=2 metric=cosine_similarity => d (score=score)

The indexed score equals the exact score for every metric, and a WHERE on the same MATCH is applied before the LIMIT. For the natural form, the beam width can be set with the reserved parameter $__vector_ef; it is a non-stable knob that may be replaced by query syntax in a later release.

When the index is used. Index bodies are built by compaction; recent writes are served from the in-memory table and newer data files. Whenever freshness cannot be proven (no body yet, a corrupt or missing segment), the query falls back to the exact scan automatically. On the server this happens in the background; in embedded Python call flush() and compact() after a bulk load.

search.bm25 ranks documents with full BM25 (inverse document frequency, term-frequency saturation, length normalisation):

CALL search.bm25({label: 'Doc', text_properties: ['title', 'body'], query: 'graph', k: 10})
YIELD node, score
RETURN node.title AS title, score
{title: 'graph storage engines', score: 0.6462…}
{title: 'graph databases on S3', score: 0.6462…}
OptionDefaultMeaning
labelrequiredLabel to search.
text_property or text_propertiesrequiredOne property, or a list of string properties.
queryrequiredQuery string.
kall matchesResults to return. Unbounded results are capped by NAMIDB_SEARCH_MAX_RESULT_BYTES; pass a k.
filternoneMetadata eligibility (see Filters).

The query string supports plain terms, quoted phrases and trailing-* prefixes:

CALL search.bm25({label: 'Doc', text_properties: ['title', 'body'],
query: '"object storage" data*', k: 10})
YIELD node, score RETURN node.title AS title
// {title: 'graph databases on S3'}

For per-row scoring without corpus statistics, use the scalar bm25(text, query).

Full-text indexes

Without an index, search.bm25 scans the label and computes corpus statistics per query. Declare a persistent inverted index to answer from postings instead:

CREATE FULLTEXT INDEX doc_text IF NOT EXISTS ON :Doc(title, body)
// Neo4j 5 spelling:
CREATE FULLTEXT INDEX doc_text IF NOT EXISTS FOR (d:Doc) ON EACH [d.title, d.body]
DROP INDEX doc_text IF EXISTS

search.bm25 uses the index automatically when its label and property set match. Like vector indexes, the base is built by compaction, later writes are added as delta segments, and any gap in coverage falls back to the exact scan.

search.hybrid runs a vector leg and a BM25 leg and fuses them, by default with Reciprocal Rank Fusion:

CALL search.hybrid({
label: 'Doc',
query_text: 'graph', text_properties: ['title', 'body'],
query_vector: $q, vector_property: 'embedding',
k: 3
}) YIELD node, score
RETURN node.title AS title, score
{title: 'graph storage engines', score: 0.03279}
{title: 'graph databases on S3', score: 0.03226}
{title: 'vector search basics', score: 0.01587}
OptionDefaultMeaning
labelrequiredLabel to search.
query_text, text_property / text_properties—The BM25 leg.
query_vector, vector_property—The vector leg. Give both or neither.
k10Fused results to return.
k_dense, k_sparse8 × kCandidates fetched from each leg before fusion.
fusion'rrf''rrf' (Reciprocal Rank Fusion) or 'linear' (weighted, normalised scores).
rrf_k60RRF constant. Must be > 0.
alpha0.5For linear: weight of the vector leg; the BM25 leg gets 1 − alpha.
ef, metricas search.vectorVector-leg tuning.
filternoneApplied to both legs before fusion.

Filters

search.vector, db.index.vector.queryNodes, search.bm25 and search.hybrid take a filter map. It restricts which nodes are eligible before the top k is cut, so a selective filter still returns k results instead of a truncated slice of a global top-k:

CALL search.vector({
label: 'Doc', property: 'embedding', query: $q, k: 2,
filter: {tenant: 'globex'}
}) YIELD node, score
RETURN node.title AS title
// {title: 'graph databases on S3'}, {title: 'cooking pasta'}
Filter valueMeans
A scalar, {tenant: 'acme'}Equality
A list, {tier: [1, 2, 3]}IN
A map of operators, {year: {gte: 2024}}Range or comparison: gt, gte, lt, lte, eq, ne

Keys combine with AND: filter: {tenant: ['acme', 'globex'], year: {gte: 2024}}.

Declare an ordinary index on the filter properties (CREATE INDEX FOR (d:Doc) ON (d.tenant)). Indexed string and boolean equality / IN filters are evaluated inside the vector and text index bodies; numeric, range and unindexed filters use a widening search with an exact fallback. Either way the results are the same; the index changes the cost.

YIELD node WHERE … is not filter syntax; put the condition in filter, or post-filter with a following WITH node, score WHERE ….

Availability

SurfaceSearch procedures and functionsCREATE VECTOR INDEX / CREATE FULLTEXT INDEX
Python wheelyesyes
Docker image, release server binaryyesyes
Server built from sourceyeswith --features vector-index,text-index
namidb CLI, namidb-mcpyes (exact path)no

Memory and capacity settings for large indexes (NAMIDB_SEARCH_WORKSPACE_MAX_BYTES, NAMIDB_SEARCH_INDEX_CACHE_MAX_BYTES, filter posting limits) are in Memory and caches and the configuration reference.