Saltearse al contenido

Leer datos

Todos los ejemplos de esta página se ejecutan contra este grafo pequeño. Pégalo en cualquier cliente para seguirlos:

CREATE (alice:Person {name: 'Alice', age: 30, city: 'Lima'}),
(bob:Person {name: 'Bob', age: 25, city: 'Quito'}),
(carol:Person:Admin {name: 'Carol', age: 41, city: 'Lima'}),
(acme:Company {name: 'Acme'}),
(alice)-[:KNOWS {since: 2020}]->(bob),
(bob)-[:KNOWS {since: 2021}]->(carol),
(alice)-[:WORKS_AT {role: 'engineer'}]->(acme),
(carol)-[:WORKS_AT {role: 'cto'}]->(acme)

Los resultados se muestran como filas, tal como los retornan .rows() en el cliente de Python y rows en la API HTTP.

Hacer match de nodos

MATCH (p:Person)
RETURN p.name AS name, p.age AS age
ORDER BY age DESC
{name: 'Carol', age: 41}
{name: 'Alice', age: 30}
{name: 'Bob', age: 25}

Filtra inline con un mapa de propiedades, o con WHERE para condiciones más ricas:

MATCH (p:Person {city: 'Lima'}) RETURN p.name AS name ORDER BY name
// {name: 'Alice'}, {name: 'Carol'}
MATCH (p:Person)
WHERE p.age >= 30 AND p.city = 'Lima'
RETURN p.name AS name ORDER BY name
// {name: 'Alice'}, {name: 'Carol'}

Un nodo con varios labels hace match con cada uno de ellos; (n:Person|Company) hace match con cualquiera de los dos:

MATCH (n:Person|Company) RETURN labels(n) AS labels, n.name AS name ORDER BY name
{labels: ['Company'], name: 'Acme'}
{labels: ['Person'], name: 'Alice'}
{labels: ['Person'], name: 'Bob'}
{labels: ['Admin', 'Person'], name: 'Carol'}

Retornar un nodo completo te da su id, labels y propiedades:

MATCH (p:Person) RETURN p ORDER BY p.name LIMIT 1
{"p": {"_kind": "node", "id": "01a19a62-6427-7db1-8897-f10d97824111",
"label": "Person", "labels": ["Person"],
"properties": {"age": 30, "city": "Lima", "name": "Alice"}}}

El id es un UUID asignado al crear el nodo. Léelo en Cypher como id(p), elementId(p) o p._id; busca un nodo por su id con MATCH (p:Person {_id: $id}).

Hacer match de relaciones

MATCH (a:Person)-[k:KNOWS]->(b:Person)
RETURN a.name AS from, b.name AS to, k.since AS since
ORDER BY since
{from: 'Alice', to: 'Bob', since: 2020}
{from: 'Bob', to: 'Carol', since: 2021}

La dirección es ->, <-, u omitida (-) para cualquiera de las dos. -[:A|B]-> hace match con cualquiera de los dos tipos, y --> con cualquier tipo. Filtra el otro extremo como cualquier nodo:

MATCH (p:Person)-[:WORKS_AT]->(:Company {name: 'Acme'})
RETURN p.name AS name ORDER BY name
// {name: 'Alice'}, {name: 'Carol'}

Caminos de longitud variable

MATCH (:Person {name: 'Alice'})-[:KNOWS*1..2]->(f)
RETURN f.name AS name ORDER BY name
// {name: 'Bob'}, {name: 'Carol'}

Los límites pueden ser * (uno o más), *n, *n..m, *..m, *n.. y *0..m (cero saltos incluye el nodo inicial), y también parámetros: *1..$hops. Vincula el camino para inspeccionarlo:

MATCH p = (:Person {name: 'Alice'})-[:KNOWS*]->(b)
RETURN [n IN nodes(p) | n.name] AS route, length(p) AS hops
ORDER BY hops
{route: ['Alice', 'Bob'], hops: 1}
{route: ['Alice', 'Bob', 'Carol'], hops: 2}

Una variable de relación en un salto de longitud variable (-[rs:KNOWS*1..2]->) es la lista de relaciones, así que size(rs) es la cantidad de saltos.

Caminos más cortos

Primero vincula ambos extremos y luego pide el camino entre ellos. El límite superior es obligatorio:

MATCH (a:Person {name: 'Alice'})
MATCH (c:Person {name: 'Carol'})
MATCH p = shortestPath((a)-[:KNOWS*..10]-(c))
RETURN length(p) AS hops
// {hops: 2}

allShortestPaths(…) tiene la misma forma y retorna todos los caminos de longitud mínima. Para caminos más cortos con pesos sobre un subgrafo completo, usa algo.shortest_path.

Matches opcionales

OPTIONAL MATCH conserva la fila y completa con NULL cuando el patrón no tiene match:

MATCH (p:Person)
OPTIONAL MATCH (p)-[w:WORKS_AT]->(c:Company)
RETURN p.name AS name, c.name AS company, w.role AS role
ORDER BY name
{name: 'Alice', company: 'Acme', role: 'engineer'}
{name: 'Bob', company: null, role: null}
{name: 'Carol', company: 'Acme', role: 'cto'}

Un OPTIONAL MATCH hace match con su patrón completo o con nada; nunca conserva la mitad de un patrón de varios saltos.

Agregación

Los elementos no agregados en RETURN (o WITH) son la clave de agrupación:

MATCH (p:Person)
RETURN p.city AS city, count(*) AS people, avg(p.age) AS avg_age,
collect(p.name) AS names
ORDER BY city
{city: 'Lima', people: 2, avg_age: 35.5, names: ['Alice', 'Carol']}
{city: 'Quito', people: 1, avg_age: 25.0, names: ['Bob']}

Agregaciones disponibles: count(*), count(x), sum, avg, min, max, collect, stdev, stdevp, percentileCont, percentileDisc, cada una con DISTINCT opcional (count(DISTINCT p.city)).

Encadenar con WITH

WITH cierra una etapa y empieza la siguiente. Úsalo para filtrar sobre una agregación:

MATCH (p:Person)
WITH p.city AS city, count(*) AS n
WHERE n > 1
RETURN city, n
// {city: 'Lima', n: 2}

Ordenar y paginar

MATCH (p:Person) RETURN p.name AS name ORDER BY p.age DESC SKIP 1 LIMIT 1
// {name: 'Alice'}
MATCH (p:Person) RETURN DISTINCT p.city AS city ORDER BY city
// {city: 'Lima'}, {city: 'Quito'}

SKIP y LIMIT aceptan un literal entero o un $parameter.

Verificaciones de existencia y subconsultas

// People without a job:
MATCH (p:Person)
WHERE NOT EXISTS { MATCH (p)-[:WORKS_AT]->() }
RETURN p.name AS name
// {name: 'Bob'}

Las formas más cortas WHERE (p)-[:WORKS_AT]->() y WHERE exists((p)-[:WORKS_AT]->()) también funcionan.

Una pattern comprehension recopila los matches por fila:

MATCH (p:Person)
RETURN p.name AS name, [(p)-[:KNOWS]->(f) | f.name] AS knows
ORDER BY name
{name: 'Alice', knows: ['Bob']}
{name: 'Bob', knows: ['Carol']}
{name: 'Carol', knows: []}

Un CALL { … } correlacionado se ejecuta una vez por cada fila de entrada; importa variables con un WITH al inicio:

MATCH (p:Person)
CALL { WITH p MATCH (p)-[:KNOWS]->(f) RETURN count(f) AS friends }
RETURN p.name AS name, friends
ORDER BY name
// {name: 'Alice', friends: 1}, {name: 'Bob', friends: 1}, {name: 'Carol', friends: 0}

Listas de entrada, filas de salida

UNWIND ['Alice', 'Carol'] AS who
MATCH (p:Person {name: who})
RETURN p.name AS name, p.age AS age
// {name: 'Alice', age: 30}, {name: 'Carol', age: 41}

Pasa la lista como parámetro (UNWIND $names AS who) para buscar muchas claves en una sola sentencia.

Combinar resultados con UNION

MATCH (p:Person) RETURN p.name AS name
UNION
MATCH (c:Company) RETURN c.name AS name
// {name: 'Alice'}, {name: 'Bob'}, {name: 'Carol'}, {name: 'Acme'}

Cada rama debe retornar los mismos nombres de columna en el mismo orden. UNION elimina duplicados; UNION ALL los conserva.

Valores condicionales

MATCH (p:Person)
RETURN p.name AS name,
CASE WHEN p.age >= 40 THEN 'senior'
WHEN p.age >= 30 THEN 'mid'
ELSE 'junior' END AS band
ORDER BY name
// {name: 'Alice', band: 'mid'}, {name: 'Bob', band: 'junior'}, {name: 'Carol', band: 'senior'}

Parámetros

Pasa siempre los valores como parámetros en lugar de insertarlos en el texto de la consulta. Es más seguro, permite que el motor reutilice planes y mantiene los valores fuera del log de consultas lentas:

MATCH (p:Person) WHERE p.age IN $ages RETURN p.name AS name ORDER BY name
// with {"ages": [25, 41]}: {name: 'Bob'}, {name: 'Carol'}

Ver el plan

Antepón EXPLAIN a una consulta para obtener el plan en lugar de los resultados:

EXPLAIN MATCH (p:Person)-[:KNOWS]->(f) WHERE p.age > 26 RETURN f.name
Project [f.name=f.name]
Expand source=p edge_type=KNOWS dir=-> target=f
NodeScan label=Person alias=p projection=[age, id] predicates=[p.age > 26]

EXPLAIN VERBOSE agrega estimaciones de filas; EXPLAIN RAW muestra el plan antes de la optimización. Un índice o restricción declarado convierte un NodeScan filtrado en una búsqueda por índice.

Nombres de columnas

Un elemento con alias (RETURN p.name AS name) toma el nombre de su alias. Un elemento sin alias toma su texto canónico, por ejemplo p.name o count(*); las expresiones complejas se normalizan (RETURN 'a' STARTS WITH 'b' vuelve como ('a' STARTS WITH 'b')). Ponle alias a todo lo que vaya a leer un programa.