Saltearse al contenido

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 score
ORDER BY score DESC LIMIT 2
{title: 'graph storage engines', score: 0.99628…}
{title: 'graph databases on S3', score: 0.99557…}
FunciónOrdenarNotas
cosine_similarity(a, b)DESCNULL 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, score
RETURN node.title AS title, score
OpciónPor defectoSignificado
labelobligatoriaLabel en el que buscar.
propertyobligatoriaPropiedad que contiene los vectores.
queryobligatoriaVector de consulta (lista o vector(…)).
k10Resultados a retornar.
efvalor del índice (64)Ancho del beam para el índice ANN; un valor mayor cambia latencia por recall.
metriccosinecosine, dot / dot_product, euclidean / l2. Usa la métrica del índice vectorial para que el índice pueda servir la búsqueda.
filterningunoElegibilidad 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, score
CALL 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 EXISTS
ON :Doc(embedding) METRIC cosine DIMENSION 3
  • METRIC es cosine, dot o euclidean; DIMENSION es 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 para METRIC 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 EXISTS
    FOR (d:Doc) ON d.embedding
    OPTIONS {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 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)

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, score
RETURN node.title AS title, score
{title: 'graph storage engines', score: 0.6462…}
{title: 'graph databases on S3', score: 0.6462…}
OpciónPor defectoSignificado
labelobligatoriaLabel en el que buscar.
text_property o text_propertiesobligatoriaUna propiedad, o una lista de propiedades string.
queryobligatoriaString de consulta.
ktodos los matchesResultados a retornar. Los resultados sin límite se acotan con NAMIDB_SEARCH_MAX_RESULT_BYTES; pasa un k.
filterningunoElegibilidad 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 EXISTS

search.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, 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}
OpciónPor defectoSignificado
labelobligatoriaLabel en el que buscar.
query_text, text_property / text_properties—La parte BM25.
query_vector, vector_property—La parte vectorial. Indica ambas o ninguna.
k10Resultados fusionados a retornar.
k_dense, k_sparse8 × kCandidatos que se obtienen de cada parte antes de la fusión.
fusion'rrf''rrf' (Reciprocal Rank Fusion) o 'linear' (puntuaciones ponderadas y normalizadas).
rrf_k60Constante de RRF. Debe ser > 0.
alpha0.5Para linear: peso de la parte vectorial; la parte BM25 recibe 1 − alpha.
ef, metriccomo en search.vectorAjuste de la parte vectorial.
filterningunoSe 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, score
RETURN node.title AS title
// {title: 'graph databases on S3'}, {title: 'cooking pasta'}
Valor del filtroSignifica
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

SuperficieProcedimientos y funciones de búsquedaCREATE VECTOR INDEX / CREATE FULLTEXT INDEX
Wheel de Pythonsísí
Imagen Docker, binario del servidor del releasesísí
Servidor compilado desde el código fuentesícon --features vector-index,text-index
CLI namidb, namidb-mcpsí (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.