Búsqueda vectorial, full-text e híbrida
En NamiDB la búsqueda es Cypher normal. Los embeddings y el texto son
propiedades de los nodos; los ordenas con funciones o con los
procedimientos search.*, y un índice, cuando lo declaras, cambia el costo
de una consulta pero nunca su resultado.
Los ejemplos usan estos datos (se muestra Python; cualquier cliente funciona):
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]Búsqueda vectorial
Guarda un embedding como una lista de flotantes y ordena por una función de distancia:
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…}| Función | Ordenar | Notas |
|---|---|---|
cosine_similarity(a, b) | DESC | NULL para un vector de magnitud cero, así que esas filas quedan fuera de un KNN. |
dot_product(a, b) | DESC | |
euclidean_distance(a, b) | ASC |
El mismo KNN como procedimiento:
CALL search.vector({label: 'Doc', property: 'embedding', query: $q, k: 2})YIELD node, scoreRETURN node.title AS title, score| Opción | Por defecto | Significado |
|---|---|---|
label | obligatoria | Label en el que buscar. |
property | obligatoria | Propiedad que contiene los vectores. |
query | obligatoria | Vector de consulta (lista o vector(…)). |
k | 10 | Resultados a retornar. |
ef | valor del índice (64) | Ancho del beam para el índice ANN; un valor mayor cambia latencia por recall. |
metric | cosine | cosine, dot / dot_product, euclidean / l2. Usa la métrica del índice vectorial para que el índice pueda servir la búsqueda. |
filter | ninguno | Elegibilidad por metadatos, aplicada antes de k (consulta Filtros). |
Una opción desconocida es un error (search.vector does not recognise the option …; allowed options: label, property, query, k, ef, metric, filter).
La forma compatible con Neo4j recibe el nombre de un índice:
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, scoreÍndices vectoriales
Sin un índice, la búsqueda vectorial es un scan exacto del label. Para colecciones grandes, declara un índice persistente de vecinos más cercanos aproximados (ANN):
CREATE VECTOR INDEX doc_emb IF NOT EXISTSON :Doc(embedding) METRIC cosine DIMENSION 3-
METRICescosine,dotoeuclidean;DIMENSIONes obligatoria. -
Parámetros de construcción opcionales:
WITH { r: 32, l_build: 64, alpha: 1.2 }. -
WITH { quantization: int8 }guarda códigos int8 (unas 4× más pequeños), solo paraMETRIC cosine. Los vectores de precisión completa se siguen usando para reordenar. -
La sintaxis de Neo4j 5 también funciona:
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]lo elimina.
Una vez que un índice vectorial cubre una propiedad, las escrituras verifican la dimensión: un vector de tamaño incorrecto se rechaza (HTTP 409):
constraint violation: Doc.embedding embedding has dim 2 but vector index `doc_emb` declares 3 (dimension constraint)y una lista de flotantes del tamaño correcto se guarda como vector denso para que el índice pueda incluirla.
El optimizador reescribe la forma natural del KNN para usar el índice:
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)La puntuación con índice es igual a la puntuación exacta para todas las
métricas, y un WHERE en el mismo MATCH se aplica antes del LIMIT. Para
la forma natural, el ancho del beam se puede definir con el parámetro
reservado $__vector_ef; es un ajuste no estable que podría reemplazarse
por sintaxis de consulta en una versión futura.
Cuándo se usa el índice. Los cuerpos del índice los construye la
compactación; las escrituras recientes se sirven desde la tabla en memoria y
los archivos de datos más nuevos. Siempre que no se puede demostrar la
frescura (todavía no hay cuerpo, un segmento corrupto o faltante), la
consulta pasa automáticamente al scan exacto. En el servidor esto ocurre en
segundo plano; en Python embebido llama a flush() y compact() después de
una carga masiva.
Búsqueda full-text
search.bm25 ordena documentos con BM25 completo (frecuencia inversa de
documento, saturación de frecuencia de términos, normalización por
longitud):
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…}| Opción | Por defecto | Significado |
|---|---|---|
label | obligatoria | Label en el que buscar. |
text_property o text_properties | obligatoria | Una propiedad, o una lista de propiedades string. |
query | obligatoria | String de consulta. |
k | todos los matches | Resultados a retornar. Los resultados sin límite se acotan con NAMIDB_SEARCH_MAX_RESULT_BYTES; pasa un k. |
filter | ninguno | Elegibilidad por metadatos (consulta Filtros). |
El string de consulta admite términos simples, frases entre comillas y
prefijos con * al final:
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'}Para una puntuación por fila sin estadísticas del corpus, usa la función
escalar bm25(text, query).
Índices full-text
Sin un índice, search.bm25 escanea el label y calcula las estadísticas del
corpus en cada consulta. Declara un índice invertido persistente para
responder desde los postings:
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 usa el índice automáticamente cuando su label y su conjunto
de propiedades coinciden. Igual que con los índices vectoriales, la base la
construye la compactación, las escrituras posteriores se agregan como
segmentos delta, y cualquier hueco en la cobertura pasa al scan exacto.
Búsqueda híbrida
search.hybrid ejecuta una parte vectorial y una parte BM25 y las fusiona,
por defecto con 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}| Opción | Por defecto | Significado |
|---|---|---|
label | obligatoria | Label en el que buscar. |
query_text, text_property / text_properties | — | La parte BM25. |
query_vector, vector_property | — | La parte vectorial. Indica ambas o ninguna. |
k | 10 | Resultados fusionados a retornar. |
k_dense, k_sparse | 8 × k | Candidatos que se obtienen de cada parte antes de la fusión. |
fusion | 'rrf' | 'rrf' (Reciprocal Rank Fusion) o 'linear' (puntuaciones ponderadas y normalizadas). |
rrf_k | 60 | Constante de RRF. Debe ser > 0. |
alpha | 0.5 | Para linear: peso de la parte vectorial; la parte BM25 recibe 1 − alpha. |
ef, metric | como en search.vector | Ajuste de la parte vectorial. |
filter | ninguno | Se aplica a ambas partes antes de la fusión. |
Filtros
search.vector, db.index.vector.queryNodes, search.bm25 y
search.hybrid aceptan un mapa filter. Restringe qué nodos son elegibles
antes de cortar el top k, así que un filtro selectivo sigue
retornando k resultados en lugar de una porción truncada de un top-k
global:
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'}| Valor del filtro | Significa |
|---|---|
Un escalar, {tenant: 'acme'} | Igualdad |
Una lista, {tier: [1, 2, 3]} | IN |
Un mapa de operadores, {year: {gte: 2024}} | Rango o comparación: gt, gte, lt, lte, eq, ne |
Las claves se combinan con AND:
filter: {tenant: ['acme', 'globex'], year: {gte: 2024}}.
Declara un índice ordinario sobre las propiedades del filtro
(CREATE INDEX FOR (d:Doc) ON (d.tenant)). Los filtros indexados de
igualdad / IN sobre strings y booleanos se evalúan dentro de los cuerpos
de los índices vectoriales y de texto; los filtros numéricos, de rango y no
indexados usan una búsqueda que se va ampliando con un fallback exacto. En
ambos casos los resultados son los mismos; el índice cambia el costo.
YIELD node WHERE … no es sintaxis de filtro; pon la condición en
filter, o filtra después con un WITH node, score WHERE … posterior.
Disponibilidad
| Superficie | Procedimientos y funciones de búsqueda | CREATE VECTOR INDEX / CREATE FULLTEXT INDEX |
|---|---|---|
| Wheel de Python | sí | sí |
| Imagen Docker, binario del servidor del release | sí | sí |
| Servidor compilado desde el código fuente | sí | con --features vector-index,text-index |
CLI namidb, namidb-mcp | sí (ruta exacta) | no |
Los ajustes de memoria y capacidad para índices grandes
(NAMIDB_SEARCH_WORKSPACE_MAX_BYTES, NAMIDB_SEARCH_INDEX_CACHE_MAX_BYTES,
límites de postings de filtros) están en
Memoria y cachés y en la
referencia de configuración.