Saltearse al contenido
NamiDB NamiDB

Leer datos

NamiDB implementa un subset estricto de openCypher 9 más GQL (ISO/IEC 39075:2024). Cada consulta LDBC SNB Interactive Complex Read (IC01 hasta IC12) parsea, planifica y se ejecuta de extremo a extremo sobre esta superficie, así que las cláusulas de lectura de abajo están bien ejercitadas en la práctica.

Para la cobertura exacta del parser y los gaps conocidos, consulta Subset soportado. Para el catálogo de operadores y funciones, ver Operadores y funciones.

MATCH

La cláusula básica de matching de patrones. Las variables en () bindean nodos; las variables en [] bindean relaciones.

MATCH (p:Person)
RETURN p.name

Los patrones pueden encadenarse a través de relaciones:

MATCH (a:Person)-[:KNOWS]->(b:Person)
RETURN a.name AS a, b.name AS b

Múltiples labels y predicados de propiedades inline:

MATCH (p:Person {name: 'Alice'})-[:KNOWS]->(friend:Person)
WHERE friend.age >= 18
RETURN friend.name

Patrones de relación con longitud variable (acotada):

MATCH (a:Person {name: 'Alice'})-[:KNOWS*1..3]->(reach:Person)
RETURN DISTINCT reach.name

WHERE

Filtra las filas bindeadas. Soporta operadores de comparación (=, <>, <, <=, >, >=), operadores booleanos (AND, OR, NOT), IN, IS NULL / IS NOT NULL, predicados sobre strings (STARTS WITH, ENDS WITH, CONTAINS) y acceso a propiedades (n.prop).

MATCH (p:Person)
WHERE p.age >= 18
  AND p.country IN ['US', 'CA', 'MX']
  AND p.name STARTS WITH 'A'
RETURN p.name, p.age

WHERE puede aparecer después de MATCH, OPTIONAL MATCH o WITH. El optimizador empuja los predicados hacia la capa de almacenamiento para que bloom filters, fence pointers y el pruning de row groups de Parquet puedan saltar trabajo.

OPTIONAL MATCH

Como MATCH, pero si el patrón falla en bindear, las columnas del patrón opcional quedan en NULL en vez de descartar la fila. Semántica de left join.

MATCH (p:Person)
OPTIONAL MATCH (p)-[:OWNS]->(car:Car)
RETURN p.name, car.model

WITH

Encadena resultados intermedios hacia la siguiente cláusula. Úsalo para proyectar antes de encadenar otro MATCH, filtrar sobre una agregación, o partir una consulta en etapas.

MATCH (p:Person)-[:KNOWS]->(friend)
WITH p, count(friend) AS friend_count
WHERE friend_count > 5
RETURN p.name, friend_count
ORDER BY friend_count DESC

RETURN

Proyecta las columnas finales. Soporta aliasing (AS), DISTINCT, expresiones y agregaciones.

MATCH (p:Person)
RETURN DISTINCT p.country AS country, count(*) AS n
ORDER BY n DESC
LIMIT 10

Formas comunes:

RETURN p                            -- nodo completo
RETURN p.name, p.age                -- propiedades
RETURN p.name AS name               -- con alias
RETURN p.first_name + ' ' + p.last  -- expresión
RETURN count(*) AS n                -- agregación

ORDER BY, SKIP, LIMIT

Ordenamiento y paginación. Se encadenan sobre RETURN (o WITH).

MATCH (p:Person)
RETURN p.name, p.age
ORDER BY p.age DESC
SKIP 20
LIMIT 10

Múltiples claves de ordenamiento, direcciones mixtas:

MATCH (p:Person)
RETURN p.country, p.age, p.name
ORDER BY p.country ASC, p.age DESC

Agregaciones

El set estándar: count(*), count(expr), sum, avg, min, max, collect.

MATCH (p:Person)-[:LIVES_IN]->(city:City)
RETURN city.name AS city,
       count(p)   AS people,
       avg(p.age) AS avg_age
ORDER BY people DESC

collect(expr) acumula filas en una lista, útil para dar forma a la salida:

MATCH (p:Person)-[:KNOWS]->(friend)
RETURN p.name, collect(friend.name) AS friends

DISTINCT funciona dentro de las agregaciones:

MATCH (p:Person)-[:LIVES_IN]->(city:City)
RETURN count(DISTINCT city) AS cities

EXISTS (subconsulta)

Verifica si un patrón existe, sin materializarlo. El optimizador decorrelaciona esto a un hash semi-join (RFC-014) para que se ejecute en una sola pasada.

MATCH (p:Person)
WHERE EXISTS {
  MATCH (p)-[:KNOWS]->(:Person {country: 'MX'})
}
RETURN p.name

UNWIND

Expande una lista a filas. Útil para conectar datos externos (parámetros) dentro de un patrón.

UNWIND $names AS name
MATCH (p:Person {name: name})
RETURN p.name, p.age

Inspección del plan

Agrega EXPLAIN VERBOSE a cualquier consulta para ver el plan elegido, las estimaciones de selectividad y las anotaciones de costo por operador:

Ventana de terminal
namidb explain --verbose \
  "MATCH (a:Person)-[:KNOWS]->(b) RETURN b ORDER BY b.id LIMIT 20"

La inspección del plan toca el parser, el lowerer y el optimizador, pero no el almacenamiento, así que es seguro ejecutarla contra un namespace de producción sin I/O.

Consulta la página de la CLI para la referencia completa de los flags de explain.

Siguientes pasos