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]Vector search
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 scoreORDER BY score DESC LIMIT 2{title: 'graph storage engines', score: 0.99628…}{title: 'graph databases on S3', score: 0.99557…}| Function | Order by | Notes |
|---|---|---|
cosine_similarity(a, b) | DESC | NULL 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, scoreRETURN node.title AS title, score| Option | Default | Meaning |
|---|---|---|
label | required | Label to search. |
property | required | Property holding the vectors. |
query | required | Query vector (list or vector(…)). |
k | 10 | Results to return. |
ef | index default (64) | Beam width for the ANN index; higher trades latency for recall. |
metric | cosine | cosine, dot / dot_product, euclidean / l2. Use the vector index’s metric so the index can serve the search. |
filter | none | Metadata 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, scoreCALL db.index.vector.queryNodes('doc_emb', 2, $q, {ef: 200, filter: {live: true}}) YIELD node, scoreVector 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 EXISTSON :Doc(embedding) METRIC cosine DIMENSION 3-
METRICiscosine,dotoreuclidean;DIMENSIONis required. -
Optional build parameters:
WITH { r: 32, l_build: 64, alpha: 1.2 }. -
WITH { quantization: int8 }stores int8 codes (about 4× smaller), forMETRIC cosineonly. Full-precision vectors are still used to rerank. -
The Neo4j 5 spelling works too:
CREATE VECTOR INDEX doc_emb IF NOT EXISTSFOR (d:Doc) ON d.embeddingOPTIONS {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 titleORDER BY cosine_similarity(d.embedding, $q) DESC LIMIT 2Project [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.
Full-text search
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, scoreRETURN node.title AS title, score{title: 'graph storage engines', score: 0.6462…}{title: 'graph databases on S3', score: 0.6462…}| Option | Default | Meaning |
|---|---|---|
label | required | Label to search. |
text_property or text_properties | required | One property, or a list of string properties. |
query | required | Query string. |
k | all matches | Results to return. Unbounded results are capped by NAMIDB_SEARCH_MAX_RESULT_BYTES; pass a k. |
filter | none | Metadata 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 EXISTSsearch.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.
Hybrid search
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, scoreRETURN 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}| Option | Default | Meaning |
|---|---|---|
label | required | Label to search. |
query_text, text_property / text_properties | — | The BM25 leg. |
query_vector, vector_property | — | The vector leg. Give both or neither. |
k | 10 | Fused results to return. |
k_dense, k_sparse | 8 × k | Candidates fetched from each leg before fusion. |
fusion | 'rrf' | 'rrf' (Reciprocal Rank Fusion) or 'linear' (weighted, normalised scores). |
rrf_k | 60 | RRF constant. Must be > 0. |
alpha | 0.5 | For linear: weight of the vector leg; the BM25 leg gets 1 − alpha. |
ef, metric | as search.vector | Vector-leg tuning. |
filter | none | Applied 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, scoreRETURN node.title AS title// {title: 'graph databases on S3'}, {title: 'cooking pasta'}| Filter value | Means |
|---|---|
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
| Surface | Search procedures and functions | CREATE VECTOR INDEX / CREATE FULLTEXT INDEX |
|---|---|---|
| Python wheel | yes | yes |
| Docker image, release server binary | yes | yes |
| Server built from source | yes | with --features vector-index,text-index |
namidb CLI, namidb-mcp | yes (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.