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 ageORDER 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 sinceORDER 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 hopsORDER 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 roleORDER 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 namesORDER 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 nWHERE n > 1RETURN 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 knowsORDER 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, friendsORDER BY name// {name: 'Alice', friends: 1}, {name: 'Bob', friends: 1}, {name: 'Carol', friends: 0}Listas de entrada, filas de salida
UNWIND ['Alice', 'Carol'] AS whoMATCH (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 nameUNIONMATCH (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 bandORDER 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.nameProject [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.