Neo4j

Neo4j guarda documentos en tu base de datos Neo4j y busca en ellos por significado, igual que cualquier otra base vectorial. También puede buscar directamente en los nodos que ya tiene tu grafo, por ejemplo en las descripciones de tus incidencias o productos.

Una base de datos vectorial guarda textos de forma que se pueden buscar por su significado, no solo por palabras exactas. Así, un agente puede encontrar el párrafo de un manual que responde a una pregunta aunque esté escrito con otras palabras.

Si quieres además recorrer las relaciones del grafo, combinar significado y palabras clave o que el modelo escriba la consulta, usa Neo4j GraphRAG.

Cuándo usarlo

• Ya usas Neo4j y quieres tener tus documentos en la misma base que el resto de tus datos.
• Quieres buscar por significado en el texto de nodos que ya existen en tu grafo, sin copiarlos a otra base.
• Quieres preparar documentos que después consultarás con Neo4j GraphRAG.

Configuración

El campo Operation decide qué hace el componente, y según lo que elijas cambian los campos y las salidas:

• Add (por defecto): guarda en la base los documentos que recibe en Ingest Data. Si el índice no existe, lo crea.
• Search: busca los documentos más parecidos al texto de Search Query.
• Retriever: ofrece la base como buscador para que la use otro componente, por ejemplo un agente o una cadena de preguntas y respuestas.

Necesitas una credencial Neo4j API con la dirección, el usuario y la contraseña de tu base de datos. Consulta Credenciales.

Campo	Qué hace
Credential (obligatorio)	La credencial Neo4j API. Rellena Neo4j URL, Neo4j Username y Neo4j Password.
Operation	Qué hace el componente: Add, Search o Retriever.
Ingest Data (obligatorio)	Con Add. Los documentos que se guardan, normalmente los que salen de un divisor de textos.
Search Query	Con Search. El texto que se busca. Si lo dejas vacío no se devuelve nada.
Embedding	El conector donde enchufas el componente que convierte los textos en números para compararlos por significado, como FastEmbed Embeddings (Local). Usa siempre el mismo para guardar y para buscar.
Node Label	Con Search y Retriever, para buscar en nodos que ya tienes: la etiqueta de esos nodos, por ejemplo Incidencia.
Text Node Properties	Junto a Node Label: las propiedades con el texto en el que se busca, separadas por comas, por ejemplo titulo, descripcion.
Embedding Node Property	Junto a Node Label: la propiedad donde se guarda el vector de cada nodo. Vacío, se usa embedding. Los nodos que aún no lo tienen lo reciben la primera vez.

Opciones avanzadas

Campo	Qué hace
Index Name	El nombre del índice vectorial en Neo4j. Por defecto, nappai_neo4j_index. Usa el mismo para guardar y para buscar.
Number of Results	Cuántos documentos devuelve cada búsqueda. Por defecto, 4.
Filter by Metadata	Busca solo entre los documentos cuyos datos cumplen unas condiciones, por ejemplo marca igual a Vellani. Funciona con Search, Retriever y en modo herramienta. Ver Filtrar por metadatos.

Filtrar por metadatos

Cada documento guarda, además de su texto, unos datos (sus metadatos): la marca, el tipo de documento, el mes… El filtro hace que la búsqueda mire solo los documentos cuyos datos cumplen unas condiciones. Se aplica igual a Results, a Retriever y cuando un agente usa el componente como herramienta.

Activa Filter by Metadata (en las opciones avanzadas) y elige Filter Mode:

• Manual: escribes las condiciones en el nodo. En Number of Conditions eliges cuántas filas quieres, y cada fila tiene:

  • Field: el dato que se mira, por ejemplo marca.
  • Operator: Equal (igual), NotEqual (distinto), GreaterThan, GreaterThanEqual, LessThan, LessThanEqual (mayor, mayor o igual, menor, menor o igual), In (uno de una lista separada por comas, como Q90, S80), NotIn (ninguno de la lista) y Contains (el texto o la lista contiene el valor).
  • Type: Text, Int (número entero), Number (con decimales) o Boolean (true o false).
  • Value: el valor con el que se compara. Si se deja vacío, esa fila no filtra.

  Combine Conditions decide si se tienen que cumplir todas (AND) o basta con una (OR).

• Dynamic: las condiciones llegan como JSON en Metadata Filter (JSON), desde otro componente o escritas por un agente:

  • {"marca": "Vellani"}: valor exacto.
  • {"modelo": ["Q90", "S80"]}: cualquiera de la lista.
  • {"año": {">=": 2024}, "estado": {"!=": "archivado"}}: con operadores =, !=, >, >=, <, <=, in, not in y contains.

  Si pones varios campos, se tienen que cumplir todos. Vacío, no filtra. Un JSON mal escrito da un error en lugar de buscar sin filtro.

Que lo rellene el agente. Con el componente en modo herramienta, activa el modo herramienta de Value (con Field y Operator fijos, por ejemplo modelo y Equal) o el de Metadata Filter (JSON). El agente escribe el valor cuando la pregunta lo pide («solo la máquina Q90») y lo deja vacío cuando no. Cuéntale en la descripción de la herramienta qué campos y valores hay.

Listas. Si un dato es una lista, como las etiquetas que escribe Metadata Tagger, Equal e In aciertan cuando alguno de sus elementos coincide, y Contains busca dentro de ellos.

En Neo4j el filtro necesita Neo4j 5.18 o posterior. Contains no distingue mayúsculas, y ningún operador mira dentro de una lista: si filtras por listas, usa FAISS, Qdrant, PGVector o Elasticsearch.

Ejemplo: solo los manuales de una marca

1. Al guardar, cada fragmento lleva sus datos, por ejemplo tipo: manual y marca: Vellani (los pone el cargador de archivos o Metadata Tagger).
2. En el nodo con Operation en Search, activa Filter by Metadata, deja Filter Mode en Manual y rellena la fila: Field marca, Operator Equal, Type Text, Value Vellani.
3. Busca «qué significa el error E07»: solo salen fragmentos de documentos de Vellani.

El mismo filtro en modo Dynamic es {"marca": "Vellani"}. Los nodos guardados antes conservan sus filtros; los nombres nuevos de los campos aparecen al actualizar el nodo.

Resultado

Las salidas dependen de Operation:

• Results: con Add y Search. Con Search, la lista de documentos encontrados, que puedes pasar a un prompt o a un agente.
• Vector Store: con Add. La base de datos, para conectarla a componentes que trabajan con una base vectorial.
• Retriever: con Retriever. El buscador, para conectarlo a componentes que piden un buscador.

En modo herramienta, un agente puede usar el componente para buscar por sí mismo. Consulta Tool Mode.

Ejemplo

Un servicio técnico ya tiene sus incidencias en Neo4j, cada una con una descripción de la avería, y quiere encontrar averías parecidas a la que cuenta un cliente.

1. Añade Neo4j con Operation en Search y elige tu credencial Neo4j API.
2. Escribe Incidencia en Node Label y descripcion en Text Node Properties.
3. Conecta FastEmbed Embeddings (Local) a Embedding y ejecuta el flujo una vez: las incidencias reciben su vector.
4. Escribe «la cafetera pierde agua por debajo» en Search Query y revisa Results.

Buenas prácticas

• Guarda y busca siempre con el mismo componente de embeddings: si cambias de modelo, vuelve a guardar los documentos en un índice nuevo.
• Para preguntas que cuentan, comparan o cruzan relaciones («¿qué cliente tiene más incidencias?»), usa Neo4j GraphRAG en modo Text2Cypher.

Componentes relacionados

• Neo4j GraphRAG: preguntas a un grafo de Neo4j, recorriendo sus relaciones o escribiendo la consulta.
• FastEmbed Embeddings (Local): convierte los textos para buscarlos por significado, sin salir de NappAI.

Ver también

• Bases vectoriales: en qué se diferencian FAISS, Chroma, Qdrant, PGVector y Neo4j, y cuál elegir.