Neo4j GraphRAG

Neo4j GraphRAG guarda tus datos en un grafo de Neo4j y responde preguntas sobre él. En un grafo los datos están conectados: cada incidencia con su cliente, su máquina y el técnico que la atiende. Por eso responde bien preguntas que cruzan relaciones («¿qué incidencias abiertas tiene el técnico que atiende a este cliente?») o que cuentan y comparan («¿qué cliente tiene más incidencias?»), donde una búsqueda solo por texto se queda corta.

El mismo componente hace las dos mitades del trabajo. Operation decide cuál, y el nodo muestra solo los campos de esa operación:

Guardar: Add Records convierte filas (de una tabla, una hoja o una base de datos) en nodos y relaciones sin escribir Cypher. Build Graph lee documentos con un modelo de IA y extrae de ellos las entidades y sus relaciones.
Encontrar y responder: Vector e Hybrid buscan por significado y por palabras; Vector + Graph e Hybrid + Graph traen además los nodos relacionados con cada resultado; Text2Cypher escribe la consulta que responde a la pregunta; Cypher Query ejecuta una consulta tuya con valores que rellena el agente; Graph Schema describe lo que contiene el grafo.

Así se guarda un historial en Neo4j, de registros y de documentos, y se monta un agente que lo consulta sin escribir Cypher:

Lo que ves en el vídeo

Guardar registros (flujo «Neo4j GraphRAG · guardar registros»): Storage Files lee incidencias.json con Content en Text, y Neo4j GraphRAG en la operación Add Records guarda cada incidencia con Node Label Incidencia, Key Property codigo y tres líneas en Relationships que la unen a su bar, su técnico y su máquina. Al ejecutarlo: 24 incidencias, 72 relaciones y los dos índices de búsqueda creados solos, en menos de un segundo.
Graph Schema enseña lo que hay ahora en el grafo: las etiquetas con cuántos nodos tiene cada una, sus propiedades con valores de ejemplo, las relaciones y los índices.
Guardar documentos (flujo «Neo4j GraphRAG · guardar documentos»): Storage Search encuentra los tres informes mensuales en PDF, Storage Files los lee en lote y Neo4j GraphRAG en la operación Build Graph saca las entidades con DeepSeek, guiado por Allowed Patterns, Node Types y Extraction Instructions. Resultado: 40 nodos y 72 relaciones a partir del texto.
El agente (flujo «Neo4j GraphRAG · agente») tiene tres herramientas de Neo4j GraphRAG: «Incidencias de un técnico» en Cypher Query, con una consulta fija cuyos $tecnico y $estado rellena el agente; «Casos parecidos» en Hybrid + Graph con la Retrieval Query vacía, que trae solo los vecinos de cada resultado; y «Consultar el grafo» en Text2Cypher, con dos ejemplos en Examples.
«¿Qué incidencias abiertas tiene Lucía Ortega?»: el agente llama a la consulta fija con tecnico Lucía Ortega y estado abierta, y responde con las tres, cada una con su bar y su máquina.
«Una Aurora no dosifica y marca E07: ¿ha pasado antes y quién lo arregló?»: la búsqueda encuentra los dos casos iguales, resueltos por Javier Ruiz y Rocío Benítez cambiando el caudalímetro VL-1180.
«¿Cuántas incidencias ha tenido cada marca?»: Text2Cypher escribe la consulta que cuenta (Vellani 9, Jaltec 8, Molinar 7). Puedes ver la consulta que escribió al abrir la herramienta.

Cuándo usarlo

Tienes registros con campos (incidencias, pedidos, contratos) y quieres cargarlos en Neo4j con sus relaciones para preguntar por ellos: Add Records.
Tu información está en documentos (informes, partes de trabajo, correos) y quieres convertirla en un grafo de entidades y relaciones: Build Graph.
Tus usuarios preguntan cuántos, cuál es el que más, quién tiene o qué hay pendiente: preguntas que se responden contando o filtrando registros, no leyendo un párrafo. Text2Cypher o Cypher Query.
Quieres encontrar casos parecidos a una descripción con todo su contexto (cliente, técnico, máquina): Hybrid + Graph.
Quieres que un agente consulte el grafo por su cuenta, como herramienta, sin que nadie escriba consultas.

Operaciones

Guardar datos

Operación	Qué hace
Add Records	Cada fila que llega a Ingest Data se convierte en un nodo de tipo Node Label, identificado por Key Property: si la clave ya existe, el nodo se actualiza en lugar de duplicarse. Las columnas que indicas en Relationships se convierten en nodos enlazados (el cliente, el técnico, la máquina). Calcula los vectores de cada fila con Embedding y crea los índices de búsqueda. No usa ningún modelo de IA.
Build Graph	Un Language Model lee cada documento de Ingest Data y extrae las entidades y relaciones que pide tu esquema (Allowed Patterns y Node Types). Une las menciones de una misma entidad (ignorando mayúsculas y tildes, también con las que ya están en Neo4j) y, si un documento posterior cambia un dato, como el estado, se queda con el más reciente. Los documentos largos se leen por partes. Con Save Source Chunks guarda también cada texto, enlazado a las entidades que menciona.

Operación

Qué hace

Add Records

Cada fila que llega a Ingest Data se convierte en un nodo de tipo Node Label, identificado por Key Property: si la clave ya existe, el nodo se actualiza en lugar de duplicarse. Las columnas que indicas en Relationships se convierten en nodos enlazados (el cliente, el técnico, la máquina). Calcula los vectores de cada fila con Embedding y crea los índices de búsqueda. No usa ningún modelo de IA.

Build Graph

Un Language Model lee cada documento de Ingest Data y extrae las entidades y relaciones que pide tu esquema (Allowed Patterns y Node Types). Une las menciones de una misma entidad (ignorando mayúsculas y tildes, también con las que ya están en Neo4j) y, si un documento posterior cambia un dato, como el estado, se queda con el más reciente. Los documentos largos se leen por partes. Con Save Source Chunks guarda también cada texto, enlazado a las entidades que menciona.

Encontrar y responder

Operación	Qué hace
Vector	Busca los nodos cuyo texto se parece por significado a la pregunta.
Hybrid	Busca por significado y por palabras a la vez. Útil cuando la pregunta lleva nombres, códigos o referencias exactas.
Vector + Graph / Hybrid + Graph	Igual que las anteriores y, además, devuelve cada resultado con los nodos con los que está conectado: el cliente, el técnico y la máquina de una incidencia, por ejemplo. No necesitas escribir nada; si quieres elegir tú qué traer, escribe una Retrieval Query.
Text2Cypher	El modelo lee la estructura del grafo, con sus valores reales, y escribe la consulta que responde a la pregunta. Es la operación que cuenta, ordena y filtra sobre todo el grafo. Si la consulta falla o no encuentra nada, la revisa una vez.
Cypher Query	Ejecuta una consulta que escribes tú, con huecos (`$tecnico`) que se rellenan en cada ejecución. Usada como herramienta, cada hueco es un dato que el agente escribe. Siempre es exacta y no usa ningún modelo.
Graph Schema	Devuelve qué contiene el grafo: tipos de nodo con cuántos hay, sus propiedades con valores de ejemplo, las relaciones y los índices de búsqueda.

Text2Cypher, Cypher Query y Graph Schema solo leen: si una consulta intentase crear, cambiar o borrar datos, Neo4j la rechaza. Solo escriben Add Records y Build Graph.

Para saber qué forma de guardar conviene a tus datos y cuánto cuesta cada una, consulta GraphRAG con Neo4j.

Configuración

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. Por defecto, Vector.
Search Query	Vector, Hybrid, «+ Graph» y Text2Cypher. La pregunta. Si un agente usa el componente como herramienta, la escribe él.
Node Label	Add Records (obligatorio). El tipo de nodo en que se convierte cada fila, por ejemplo `Incidencia`. En Build Graph es opcional: el tipo de nodo que quieres poder buscar por significado.
Key Property	Add Records. La columna que identifica cada fila, por ejemplo `codigo`. Si la dejas vacía, se usa `codigo`, `code`, `id` o `nombre`, la primera que tengan las filas.
Relationships	Add Records. Qué columnas se convierten en nodos enlazados, una por línea: `columna -> RELACION -> Tipo.propiedad`. Las columnas entre paréntesis se guardan en ese nodo. Consulta el ejemplo.
Allowed Patterns	Build Graph. El esquema del grafo, una conexión por línea, por ejemplo `(Incidencia)-[:DE_CLIENTE]->(Cliente)`. Solo se guardan esos tipos de nodo y de relación. Si lo dejas vacío, el modelo decide.
Node Types	Build Graph. Los tipos de nodo, separados por comas, con sus propiedades si quieres fijarlas: la primera identifica al nodo y, tras dos puntos, los únicos valores que admite. Por ejemplo, `Incidencia(codigo, fecha, estado: abierta \| cerrada), Cliente(nombre)`.
Save Source Chunks	Build Graph. Guarda también cada texto como un nodo `Chunk` enlazado con las entidades que menciona, que se puede buscar con el índice `chunk_vector`.
Examples	Text2Cypher. Preguntas con la consulta que las responde. Consulta Ejemplos para Text2Cypher.
Cypher Query	Cypher Query. La consulta que se ejecuta. Cada `$nombre` que escribas se convierte en un campo del nodo y, como herramienta, en un dato que rellena el agente.
Retrieval Query	«+ Graph», opcional. Qué devolver de cada resultado, donde `node` es el nodo encontrado y `score` su puntuación. Si la dejas vacía, cada resultado llega con sus nodos relacionados.
Vector Index	Nombre del índice de búsqueda por significado. Al guardar, si lo dejas vacío, se crea uno con el nombre del tipo de nodo, por ejemplo `incidencia_vector`. Al buscar, si lo dejas vacío, se usa el único que haya en la base de datos.
Full-text Index	Nombre del índice de búsqueda por palabras, con la misma regla: al guardar se crea, por ejemplo, `incidencia_text`; al buscar se usa el único que haya.
Ingest Data	Add Records y Build Graph. Conector inferior. Las filas o documentos que se guardan.
Embedding	Conector inferior. El modelo que convierte el texto en vectores. Usa el mismo para guardar y para buscar.
Language Model	Conector inferior. Build Graph y Text2Cypher. El modelo que extrae las entidades o escribe la consulta.

Los conectores están en la parte inferior del nodo para que sigan visibles cuando el componente cuelga de las Tools de un agente.

Opciones avanzadas

Campo	Qué hace
Database	La base de datos dentro de Neo4j. Por defecto, `neo4j`.
Relationship Types	Build Graph. Tipos de relación separados por comas. No hace falta si ya están en Allowed Patterns.
Write Query	Add Records. Una consulta Cypher que se ejecuta para cada fila (`row`) en lugar de Node Label, Key Property y Relationships, para tener el control total. El vector de cada fila está en `row.embedding`.
Extraction Instructions	Build Graph. Indicaciones para el modelo, por ejemplo cómo escribir un nombre: «El modelo de una máquina se escribe sin la marca».
Parallel Requests	Build Graph. Cuántos textos lee el modelo a la vez (de 1 a 20, por defecto 5).
Full-text Analyzer	Add Records y Build Graph. El idioma del índice de búsqueda por palabras (`spanish`, `english`…), para que «averías» encuentre «avería». Por defecto, `standard`.
Text Property	La propiedad del nodo con el texto que se vectoriza, se indexa y se devuelve. Por defecto, `text`. Si una fila no tiene `text`, se usa su `descripcion`, `description`, `summary` o `content`.
Number of Results	Cuántos resultados se devuelven, de 1 a 100. Por defecto, 5. En Text2Cypher y Cypher Query, una consulta puede devolver hasta 20 filas por cada resultado, para que un listado largo llegue completo.

Resultado

Results: en todas las operaciones. Los resultados de la búsqueda, las filas de la consulta, la descripción del grafo o el resumen de lo guardado (cuántos nodos y relaciones, y qué índices se crearon). Si una consulta no encuentra nada, devuelve la consulta que se ejecutó, para que el agente pueda intentarlo con otros valores.
Retriever: en Vector, Hybrid, «+ Graph» y Text2Cypher, para conectarlo a componentes que piden un buscador.

Uso como herramienta de un agente

Conecta Neo4j GraphRAG a la entrada Tools de un Agent. Según la operación, el agente escribe:

Operación	Lo que escribe el agente	Nombre de la herramienta por defecto
Vector, Hybrid, «+ Graph»	La pregunta (Search Query)	`neo4j_graph_search`
Text2Cypher	La pregunta	`neo4j_graph_query`
Cypher Query	Un valor por cada `$nombre` de la consulta	`neo4j_cypher_query`
Graph Schema	Nada	`neo4j_graph_schema`

En la pestaña Tool, Tool Name y Tool Description son el nombre y la explicación con los que el agente decide cuándo usar la herramienta. Al cambiar de operación se proponen unos que encajan con ella; cámbialos para decir qué contiene tu grafo: «Consulta incidencias, clientes, técnicos y máquinas del servicio técnico: cuántas, de quién, en qué estado».

Ejemplos

Todos los ejemplos usan las incidencias de un servicio técnico de cafeteras: 24 incidencias de julio a septiembre, cada una con su cliente, su técnico y su máquina.

1. Cargar registros con Add Records

Las filas llegan, por ejemplo, de una hoja de cálculo, con las columnas codigo, fecha, cliente, tecnico, modelo, marca, codigo_error, descripcion y estado.

Selecciona Add Records y conecta las filas a Ingest Data y FastEmbed Embeddings (Local) a Embedding.
Node Label: Incidencia. Key Property: codigo.

Relationships:

cliente -> DE_CLIENTE -> Cliente.nombre
tecnico -> ASIGNADA_A -> Tecnico.nombre
modelo -> EN_MAQUINA -> Maquina.modelo (marca)

En avanzado, Full-text Analyzer: spanish.
Ejecuta. El resultado dice: «Wrote 24 record(s) into Neo4j as Incidencia merged by codigo; relationships: 24 DE_CLIENTE, 24 ASIGNADA_A, 24 EN_MAQUINA. Indexes: incidencia_vector, incidencia_text.»

El grafo queda con 24 incidencias, 8 clientes, 4 técnicos y 4 máquinas (cada máquina con su marca), y la descripción de cada incidencia como su texto. Si vuelves a ejecutarlo, no se duplica nada: cada incidencia se actualiza por su código, y si una fila cambia de técnico, la relación antigua se sustituye por la nueva.

Si prefieres escribir la consulta, por ejemplo para guardar la fecha como fecha, pon en Write Query:

MERGE (c:Cliente {nombre: row.cliente})
MERGE (t:Tecnico {nombre: row.tecnico})
MERGE (m:Maquina {modelo: row.modelo}) SET m.marca = row.marca
MERGE (i:Incidencia {codigo: row.codigo})
SET i.text = row.descripcion, i.estado = row.estado, i.fecha = date(row.fecha),
    i.codigo_error = row.codigo_error, i.embedding = row.embedding
MERGE (i)-[:DE_CLIENTE]->(c)
MERGE (i)-[:ASIGNADA_A]->(t)
MERGE (i)-[:EN_MAQUINA]->(m)

Con Node Label Incidencia, los índices se crean igual.

2. Construir el grafo desde documentos con Build Graph

Los informes mensuales cuentan las mismas incidencias en texto.

Selecciona Build Graph. Conecta los documentos a Ingest Data, un modelo a Language Model y el de embeddings a Embedding.

Allowed Patterns:

(Incidencia)-[:DE_CLIENTE]->(Cliente)
(Incidencia)-[:ASIGNADA_A]->(Tecnico)
(Incidencia)-[:EN_MAQUINA]->(Maquina)

Node Types: Incidencia(codigo, fecha, estado: abierta | cerrada, codigo_error), Cliente(nombre), Tecnico(nombre), Maquina(modelo, marca).
Node Label: Incidencia. En avanzado, Extraction Instructions: «El modelo de una Maquina se escribe sin la marca (Brío 2G, Aurora 3G, M64 OD); la marca va en marca.» y Full-text Analyzer: spanish.
Ejecuta. Con los 9 documentos de la base de conocimiento (manuales, políticas e informes), el resultado fue el mismo grafo que con Add Records: 24 incidencias, 8 clientes, 4 técnicos, 4 máquinas y 72 relaciones, todas correctas, con el estado final de las incidencias que se cerraron un mes después.

3. Buscar casos parecidos con Hybrid + Graph

Selecciona Hybrid + Graph y conecta el mismo modelo de Embedding. Deja vacíos Vector Index, Full-text Index y Retrieval Query.
Pregunta «La cafetera pierde agua por el portafiltros». Cada resultado llega así:

Incidencia INC-2608-05 (fecha: 2026-08-19, estado: cerrada): Fuga de agua por el portafiltros del grupo 2 sin ningún código de error. La junta del portafiltros estaba endurecida y agrietada. Se cambiaron las juntas JT-120 de los dos grupos y la ducha del grupo 2.
  EN_MAQUINA -> Maquina Brío 2G (marca: Jaltec)
  ASIGNADA_A -> Tecnico Lucía Ortega
  DE_CLIENTE -> Cliente Bar Los Arcos

Vector e Hybrid devuelven solo el texto de cada incidencia, sin sus nodos relacionados.

4. Responder con Text2Cypher

Selecciona Text2Cypher y conecta un modelo a Language Model.
Escribe en Examples dos o tres preguntas típicas con su consulta (consulta Ejemplos para Text2Cypher).
Pregunta «¿Cuántas incidencias abiertas tiene asignadas Lucía Ortega?». El modelo escribe MATCH (i:Incidencia)-[:ASIGNADA_A]->(t:Tecnico {nombre: 'Lucía Ortega'}) WHERE i.estado = 'abierta' RETURN count(i) AS total y el resultado es total: 3.

5. Una consulta fija con Cypher Query

Cuando la pregunta siempre tiene la misma forma, escribe tú la consulta y deja los valores para el agente:

MATCH (i:Incidencia)-[:ASIGNADA_A]->(t:Tecnico {nombre: $tecnico})
WHERE i.estado = $estado
OPTIONAL MATCH (i)-[:DE_CLIENTE]->(c:Cliente)
RETURN i.codigo AS incidencia, c.nombre AS cliente

El nodo muestra los campos tecnico y estado. Rellénalos o conecta el componente a un agente: la herramienta le pide tecnico y estado, y con «Lucía Ortega» y «abierta» devuelve INC-2608-02 (Bar La Giralda), INC-2609-02 (Café Alameda) e INC-2609-06 (Cervecería Macarena). Los valores llegan como texto; para compararlos con un número, usa toInteger($valor).

6. Ver qué contiene el grafo con Graph Schema

Selecciona Graph Schema y ejecuta. El resultado, abreviado:

- Incidencia (24)
    codigo (String): e.g. 'INC-2607-01', 'INC-2607-02', … (24 different values)
    estado (String): one of 'cerrada', 'abierta'
    fecha (Date): from '2026-07-03' to '2026-09-29'
- Tecnico (4)
    nombre (String): one of 'Javier Ruiz', 'Lucía Ortega', 'Manuel Campos', 'Rocío Benítez'
- (:Incidencia)-[:ASIGNADA_A]->(:Tecnico) (24)
Search indexes:
- incidencia_vector: vector on Incidencia.embedding

Te sirve para escribir los ejemplos de Text2Cypher o una Cypher Query, y como herramienta para que un agente sepa qué puede preguntar.

Ejemplos para Text2Cypher

Text2Cypher ya enseña al modelo los nombres y los valores reales del grafo. Los ejemplos de Examples le enseñan además la forma de tus preguntas. Escribe pares de pregunta y consulta, con los nombres de tu grafo, que cubran lo que preguntan tus usuarios: contar con filtros, recorrer varias relaciones y filtrar por fechas.

Pregunta: ¿Cuántas incidencias cerradas tiene Rocío Benítez?
Cypher: MATCH (i:Incidencia)-[:ASIGNADA_A]->(t:Tecnico {nombre: 'Rocío Benítez'}) WHERE i.estado = 'cerrada' RETURN count(i) AS total

Pregunta: ¿Qué clientes tuvieron incidencias en máquinas Jaltec en agosto?
Cypher: MATCH (i:Incidencia)-[:EN_MAQUINA]->(m:Maquina {marca: 'Jaltec'}), (i)-[:DE_CLIENTE]->(c:Cliente) WHERE i.fecha >= date('2026-08-01') AND i.fecha < date('2026-09-01') RETURN DISTINCT c.nombre AS cliente

Los ejemplos no tienen que coincidir con las preguntas reales. Si guardas las fechas como texto (por ejemplo con Add Records sin Write Query), el filtro por mes se escribe i.fecha STARTS WITH '2026-08'.

Buenas prácticas

Usa el mismo modelo de Embedding para guardar y para buscar; si no, los vectores no son compatibles.
En Build Graph, escribe siempre el esquema: Allowed Patterns y Node Types con sus propiedades. Sin esquema, el modelo inventa nombres distintos para lo mismo en cada documento.
Si una propiedad solo puede tomar unos valores, decláralos en Node Types (estado: abierta | cerrada): un valor distinto nunca sustituye a uno bueno.
Para preguntas que cuentan o comparan, usa Text2Cypher o Cypher Query. Las búsquedas («+ Graph» incluidas) solo ven los resultados que encuentran.
Con varios índices en la base de datos, escribe en Vector Index y Full-text Index el que quieres usar.
Para un agente que atiende a clientes, usa en la credencial un usuario de Neo4j que solo pueda leer.

Componentes relacionados

Neo4j: guarda documentos en Neo4j como base vectorial.
SelfQueryRetriever: búsqueda con filtros en una base vectorial.
Local Rerank: reordena los resultados de una búsqueda por relevancia.
Agent: el agente que puede usar este componente como herramienta.

Para elegir cómo guardar tus datos y comparar las técnicas con cifras, consulta GraphRAG con Neo4j.