Guía del lenguaje GQL para grafos en Microsoft Fabric

GQL (lenguaje de consulta de Graph) es el lenguaje de consulta estandarizado iso para las bases de datos de grafos. Use GQL para consultar, analizar y trabajar con datos de grafos de forma eficaz con grafos en Microsoft Fabric.

El mismo grupo de trabajo ISO que normaliza SQL desarrolla GQL. Como resultado, GQL comparte muchos conceptos con SQL, incluidas expresiones, predicados y tipos de datos. Si tiene experiencia con SQL, puede aplicar gran parte de ese conocimiento a GQL.

Este artículo es la guía integral de GQL en gráficos. Explica cómo encaja el lenguaje y enlaza con referencias específicas para obtener detalles completos de sintaxis y tipo. Abarca:

  • Conceptos básicos: estructuras de datos, patrones y aspectos básicos de la consulta de grafos
  • Afirmaciones esenciales: MATCH, FILTER, LET, WHEN, ORDER BY, LIMIT, y RETURN
  • Tipos de datos y expresiones: tipos de valor, operadores y funciones integradas
  • Técnicas avanzadas: composición de varias instrucciones, ámbito de variables y estrategias de agregación

Nota:

La norma internacional oficial para GQL es ISO/IEC 39075 Information Technology - Database Languages - GQL.

Si buscas orientación orientada a tareas en lugar de una guía de idiomas, consulta las guías prácticas:

Utiliza los artículos de referencia enfocados cuando necesites detalles completos:

Información necesaria Artículo definitivo
Sintaxis de un vistazo Referencia rápida de GQL
Sintaxis de composición de nodos, aristas, caminos y patrones Patrones de grafos de GQL
Operadores, predicados y funciones Expresiones, predicados y funciones de GQL
Sintaxis literal, comportamiento de valores y conversiones de tipos Valores y tipos de valor de GQL
Definiciones y restricciones de tipos de grafo Tipos de grafos GQL
Cobertura actual de características ISO GQL Conformidad con la norma GQL
Restricciones y límites actuales específicos de Fabric Limitaciones actuales

Prerrequisitos

Antes de empezar, asegúrese de que está familiarizado con estos conceptos:

  • Basic understanding of databases - Experiencia con cualquier sistema de base de datos como relacional (SQL), NoSQL o grafo es útil.
  • Conceptos del grafo : descripción de los nodos, los bordes y las relaciones en los datos conectados.
  • Aspectos básicos de la consulta: conocimiento de conceptos básicos de consulta, como el filtrado, la ordenación y la agregación.

Fondo recomendado:

  • La experiencia con lenguajes SQL o openCypher facilita el aprendizaje de la sintaxis de GQL (son raíces de GQL).
  • La familiaridad con el modelado de datos ayuda con el diseño del esquema de grafos.
  • Descripción del caso de uso específico de los datos de grafos.

Lo que necesita:

  • Acceso a un área de trabajo de grafo con funcionalidades de consulta.
  • Datos de ejemplo o voluntad de trabajar con nuestros ejemplos de redes sociales.
  • Editor de texto básico para escribir consultas.

Sugerencia

Si no está familiarizado con las bases de datos de grafos, comience con la introducción a los modelos de datos de grafos antes de continuar con esta guía.

Qué hace que GQL sea especial

GQL está diseñado específicamente para datos de grafos, por lo que su sintaxis expresa directamente cómo las entidades están conectadas. Mientras que SQL comúnmente expresa relaciones mediante uniones entre tablas, GQL utiliza patrones de grafos que se asemejan a diagramas de los datos.

Por ejemplo, la siguiente consulta encuentra parejas de personas que se conocen y que nacieron antes de 1999:

MATCH (person:Person)-[:knows]-(friend:Person)
WHERE person.birthday < 19990101
  AND friend.birthday < 19990101
RETURN person.firstName || ' ' || person.lastName AS person_name,
       friend.firstName || ' ' || friend.lastName AS friend_name

El patrón (person:Person)-[:knows]-(friend:Person) muestra la estructura de la relación para coincidir. Las variables vinculan a las dos personas para que la consulta pueda filtrar y devolver sus propiedades.

Aspectos básicos de GQL

Estos conceptos forman la base de GQL:

  • Los grafos contienen nodos y aristas con etiquetas y propiedades.
  • Los tipos de grafo definen formalmente los tipos de nodos, tipos de aristas y restricciones permitidas en un grafo.
  • Las consultas utilizan sentencias como MATCH, FILTER, y RETURN para procesar datos y producir resultados.
  • Los patrones describen las estructuras de grafos para que coincidan.
  • Las expresiones calculan, transforman y comparan valores.
  • Los predicados son expresiones booleanas utilizadas para probar condiciones.
  • Los tipos de valor definen los tipos de valores que las consultas pueden procesar y las propiedades del grafo pueden almacenar.

Entender los datos de grafos

Para trabajar con GQL, necesitas entender la estructura de grafo de propiedades etiquetada que el lenguaje consulta.

Nodos y bordes: los bloques de creación

Un grafo de propiedades etiquetadas contiene dos tipos de elementos de grafo:

  • Los nodos suelen representar entidades, como personas, organizaciones, publicaciones o productos.
  • Las aristas representan conexiones entre nodos, como que una persona conoce a otra persona o trabaja en una empresa.

Cada elemento de grafo tiene una identidad interna, una o más etiquetas y un conjunto de propiedades. Las etiquetas clasifican elementos, como Person o knows. Las propiedades son pares nombre-valor, como firstName: 'Alice' o birthday: 19730108u. En Graph, una arista siempre tiene exactamente una etiqueta.

Cada arista conecta exactamente dos nodos: un origen y un objetivo. La dirección de las aristas forma parte de la estructura del grafo. Por ejemplo, una workAt arista puede conectar un Person origen con un Company objetivo.

Nota:

Actualmente, Graph no soporta crear aristas no dirigidas. Puedes consultar una arista dirigida existente en cualquiera de las dos direcciones usando un patrón de aristas dirigidas como -[:knows]-.

Los grafos están bien formados: cada arista conecta dos nodos que existen en el mismo grafo.

Modelos de grafos y tipos de grafos

Un modelo de grafo Fabric define los tipos de nodos, tipos de aristas, propiedades, asignaciones de fuentes y claves disponibles en un grafo. Especifica qué filas de la tabla fuente se convierten en nodos y aristas y cómo se conectan esos elementos. Para orientación sobre modelado, véase Diseño de un esquema de grafo.

El estándar GQL utiliza un tipo de grafo para describir formalmente los tipos de nodos permitidos, tipos de aristas, propiedades y restricciones. Los tipos de grafo son el equivalente a nivel de lenguaje a la estructura representada por un modelo de grafo Fabric, pero actualmente Graf no acepta directamente declaraciones de tipo grafo GQL. Para la sintaxis formal y los conceptos, véase Tipos de grafos GQL.

Ejemplo de grafo utilizado en esta guía

Ejemplos utilizan el conjunto de datos de muestra de redes sociales, que incluye personas, lugares, organizaciones, mensajes, etiquetas y los bordes que los conectan.

El grafo de muestra conecta estas áreas:

  • La gente conoce a otras personas, trabaja en empresas y estudia en universidades.
  • Las ciudades, países o regiones y continentes forman una jerarquía geográfica.
  • Los foros contienen publicaciones, y la gente crea publicaciones y comentarios.
  • Las etiquetas categorizan el contenido y representan los intereses de las personas.

Diagrama que muestra el esquema de la red social.

Para ver la estructura completa del ejemplo, véase el ejemplo del esquema de redes sociales. Para conceptos generales de grafos, véase Grafos de propiedades etiquetados.

Las primeras consultas de GQL

Ahora que comprende los conceptos básicos del grafo, veamos cómo consultar datos de grafos mediante GQL. Estos ejemplos se crean de forma sencilla a compleja, lo que muestra cómo el enfoque de GQL hace que las consultas de grafos sean intuitivas y eficaces.

Empezar a ser sencillo: buscar todas las personas

Comience con la consulta más básica posible. Busque los nombres (nombre, apellidos) de todas las personas del:Person gráfico.

MATCH (p:Person)
RETURN p.firstName, p.lastName

Esta consulta se ejecuta de la siguiente manera:

  1. MATCH busca todos los nodos etiquetados como Person.
  2. RETURN muestra sus nombres y apellidos.

Agregar filtrado: buscar personas específicas

Ahora busque personas con características específicas. En este caso, busque a todos los usuarios llamados Alice y muestre sus nombres y cumpleaños.

MATCH (p:Person)
FILTER p.firstName = 'Alice'
RETURN p.firstName, p.lastName, p.birthday

Esta consulta se ejecuta de la siguiente manera:

  1. MATCH busca todos los nodos (p) con la etiqueta Person.
  2. FILTER nodos (p) cuyo nombre es Alice.
  3. RETURN muestra su nombre, apellido y cumpleaños.

Estructura de consulta básica

Las consultas GQL básicas siguen un patrón coherente: una secuencia de instrucciones que funcionan conjuntamente para buscar, filtrar y devolver datos. La mayoría de las consultas comienzan con MATCH encontrar patrones en el gráfico y terminan con RETURN especificar la salida.

Aquí tienes una consulta sencilla que encuentra pares de personas que se conocen y comparten el mismo día de nacimiento, y luego devuelve el recuento total de esos pares de amigos.

MATCH (n:Person)-[:knows]-(m:Person)
FILTER n.birthday = m.birthday
RETURN count(*) AS same_age_friends

Esta consulta se ejecuta de la siguiente manera:

  1. MATCH busca todos los pares de Person nodos que se conocen entre sí.
  2. FILTER mantiene solo los pares donde ambas personas tienen el mismo cumpleaños.
  3. RETURN cuenta cuántos pares de amigos existen.

Sugerencia

También puedes filtrar directamente en un patrón añadiendo una WHERE cláusula. Por ejemplo, MATCH (n:Person WHERE n.birthday < 19900101) solo Person empareja nodos con un birthday valor anterior a 1990.

GQL admite comentarios de línea de estilo // C, comentarios de línea de estilo -- SQL y comentarios de bloque de estilo /* */ C.

Afirmaciones comunes

  • MATCH: Identifica el patrón de grafos a buscar—aquí es donde defines la estructura de los datos que te interesan.
  • LET: Asigna nuevas variables o valores calculados basándose en datos emparejados—añade columnas derivadas al resultado.
  • FOR: Expande una lista en filas, con un desplazamiento opcional basado en ceros o posición ordinal basada en uno.
  • CALL: Ejecuta una subconsulta en línea para cada fila de entrada y añade las columnas devueltas por la subconsulta.
  • FILTER: Reduce los resultados aplicando condiciones—elimina filas que no cumplen los criterios.
  • ORDER BY: Ordena los datos filtrados—ayuda a organizar la salida en función de uno o más campos.
  • OFFSET y LIMIT: Restringir el número de filas devueltas—útil para paginación o consultas top-k.
  • RETURN: Especifica la salida final—define qué datos deben incluirse en el conjunto de resultados y realiza la agregación.
  • NEXT: Inicia otra etapa de consulta utilizando las columnas devueltas de la etapa anterior.

Cómo funcionan juntas las instrucciones

Las sentencias GQL forman una canalización, donde cada sentencia procesa la salida de la anterior. Esta ejecución secuencial facilita la lectura y depuración de consultas porque el orden de ejecución coincide con el orden de lectura.

Puntos clave:

  • Las sentencias se ejecutan efectivamente de forma secuencial.
  • Cada sentencia transforma los datos y los pasa a la siguiente.
  • Este proceso crea un flujo de datos claro y predecible que simplifica las consultas complejas.
  • NEXT Inicia una nueva fase de consulta. Solo están disponibles las columnas proyectadas por la afirmación anterior RETURN en la siguiente fase.
  • UNION, UNION DISTINCT, y UNION ALL combinan los resultados de bloques completos de consulta.

Nota:

Las sentencias tienen un orden lógico definido. Escribe consultas según este flujo de datos en lugar de depender de una estrategia física concreta.

Ejemplo de composición de instrucciones

La siguiente consulta de GQL encuentra a las primeras 10 personas que trabajan en empresas con "Air" en su nombre, las clasifica por nombre completo y devuelve su nombre completo junto con el nombre de sus empresas.

-- Data flows: Match → Let → Filter → Order → Limit → Return
MATCH (p:Person)-[:workAt]->(c:Company)           -- Input: unit table, Output: (p, c) table
LET fullName = p.firstName || ' ' || p.lastName   -- Input: (p, c) table, Output: (p, c, fullName) table
FILTER c.name CONTAINS 'Air'                      -- Input: (p, c, fullName) table, Output: filtered table
ORDER BY fullName                                 -- Input: filtered table, Output: sorted table
LIMIT 10                                          -- Input: sorted table, Output: top 10 rows table
RETURN fullName, c.name AS companyName            -- Input: top 10 rows table
                                                  -- Output: projected (fullName, companyName) result table

Esta consulta se ejecuta de la siguiente manera:

  1. MATCH Encuentra gente que trabaja en empresas.
  2. LET crea nombres completos mediante la combinación de nombres primero y de familia.
  3. FILTER solo se mantiene con empleados de empresas con "Air" en el nombre de su empresa.
  4. ORDER BY ordena por nombre completo.
  5. LIMIT toma los primeros 10 resultados.
  6. RETURN Devolve nombres completos y nombres de empresas.

Las variables conectan los datos

Las variables, como p, cy fullName en los ejemplos anteriores, llevan datos entre instrucciones. Al reutilizar un nombre de variable, GQL garantiza automáticamente que hace referencia a los mismos datos, creando condiciones de combinación eficaces. A veces, las variables también se denominan variables de enlace.

Puede clasificar variables de diferentes maneras:

Por origen de enlace:

Tipos de variables de patrón:

  • Variables de elemento : enlazar a los valores de referencia del elemento de grafo
    • Variables de nodo : enlace a nodos individuales
    • Variables perimetrales : enlace a bordes individuales
  • Variables de ruta de acceso: enlace a valores de ruta de acceso que representan rutas de acceso coincidentes

Por grado de referencia:

  • Variables singleton : enlazar a valores de referencia de elementos individuales a partir de patrones
  • Agrupar variables : vincular a listas de valores de referencia de elementos de patrones de longitud variable. Para más detalles, véase Funciones agregadas.

Resultados y resultados de ejecución

Al ejecutar una consulta, obtendrá un resultado de ejecución que consta de:

  • Un resultado, normalmente una tabla de resultados con los datos de tu RETURN declaración.
  • Información de estado que muestra si la consulta se realizó correctamente o no.

Tablas de resultados

La tabla de resultados , si está presente, es el resultado real de la ejecución de la consulta.

Una tabla de resultados incluye información sobre el nombre y el tipo de sus columnas, una secuencia de nombres de columna preferida que se usará para mostrar los resultados, si la tabla está ordenada y las filas reales.

Nota:

Si se produce un error en la ejecución, no se incluye ninguna tabla de resultados en el resultado de la ejecución.

Resultados omitidos

GQL también define un resultado omitido para sentencias que nunca producen filas, independientemente de los datos o del resultado de la evaluación. Un resultado omitido tiene código 00001de estado de finalización exitosa .

Un resultado omitido difiere de una tabla de resultados vacía. Una tabla vacía significa que una consulta que produce filas fue evaluada pero no produjo filas. La API de consulta puede representar un resultado omitido con el tipo NOTHINGde resultado .

Graph reserves omitió resultados para el soporte futuro de sentencias de lenguaje de definición de datos (DDL) y lenguaje de manipulación de datos (DML). Las sentencias de consulta actuales producen resultados de tablas, incluyendo tablas vacías.

Información de estado

Durante la ejecución de la consulta, el proceso detecta varias condiciones notables, como errores o advertencias. Cada condición se registra mediante un objeto de estado en la información de estado del resultado de ejecución.

La información de estado consta de un objeto de estado principal y una lista (posiblemente vacía) de otros objetos de estado. El objeto de estado principal siempre existe e indica si la ejecución de la consulta se realizó correctamente o no.

Cada objeto de estado incluye un código alfanumérico de cinco caracteres y una descripción de la condición registrada.

La API de consulta utiliza los siguientes códigos de estado primarios:

Código de estado de la API Meaning
00000 Completar con éxito al menos una fila.
00001 Finalización exitosa con resultado omitido. Reservado para futuros soportes DDL y DML.
01000 Una advertencia o condición informativa.
02000 Actualmente no hay filas disponibles desde una consulta que produzca filas.
42000 Un error de consulta corregible por el usuario.
50000 Un error del sistema o no clasificado.

La API conserva el GQLSTATUS canónico reportado por el motor de consulta en el _graphaneGqlStatus miembro del registro diagnóstico. Por ejemplo, el desbordamiento numérico usa GQLSTATUS 22003canónico , mientras que la división por cero usa 22012; ambos se representan por 42000 en el campo público status.code .

Importante

En el código de la aplicación, úsalo status.code para éxito amplio y manejo de errores. Utiliza el diagnóstico canónico GQLSTATUS cuando necesites distinguir una condición de consulta específica. No pruebes el texto de la descripción porque puede variar.

Además, los objetos de estado pueden contener un objeto de estado de causa subyacente y un registro de diagnóstico con información adicional que caracteriza la condición registrada.

Consulta la referencia de códigos de estado GQL

Conceptos e instrucciones esenciales

En esta sección se describen los bloques de creación principales que necesita para escribir consultas GQL eficaces. Cada concepto se basa en aptitudes prácticas de escritura de consultas.

Patrones de gráficos: encontrar estructura

Un patrón de grafo describe los nodos, aristas y caminos que deben coincidir. Vincular variables cuando las sentencias posteriores necesitan referirse a elementos emparejados:

MATCH (person:Person)-[employment:workAt]->(company:Company)
RETURN person.firstName, company.name, employment.workFrom

Coloca un predicado en línea cuando define qué nodo o arista puede participar en el patrón:

MATCH (person:Person WHERE person.firstName = 'Alice')
      -[:knows]->(friend:Person)
RETURN friend.firstName, friend.lastName

Reutiliza una variable para requerir dos posiciones de patrón que vinculen el mismo elemento. Separar patrones con comas para componer estructuras de grafos más grandes. Utiliza un cuantificador como {1,4} para repetir un patrón de aristas y hacer coincidir trayectorias de longitud variable.

Los modos de camino controlan la reutilización de elementos dentro de un camino:

Modo de ruta Comportamiento
WALK Permite nodos y bordes repetidos. Este modo es el valor predeterminado.
TRAIL Evita que se repitan los bordes.
SIMPLE Previene la repetición de nodos excepto el primer y último nodo compartidos.
ACYCLIC Previene todos los nodos repetidos.

Un prefijo de búsqueda de caminos controla qué caminos coincidentes se devuelven. ALL es el valor predeterminado. ANY SHORTEST devuelve un camino más corto para cada par origen-destino:

MATCH path = ANY SHORTEST
  (source:Person WHERE source.id = 123u)-[:knows]->{1,4}(target:Person)
RETURN target.id, path_length(path) AS hopCount

Los predicados en línea limitan la elegibilidad de ruta antes de la selección de camino. Las operaciones a nivel MATCH ... WHERE de instrucción y posteriores FILTER son postfiltros. Esta distinción puede cambiar ANY SHORTEST los resultados.

Para semánticas definitivas de nodos, aristas, caminos, composición, cuantificadores y colocación de predicados, véase Patrones de grafos GQL. Para las restricciones actuales de camino, véase Limitaciones actuales.

Instrucciones principales

GQL proporciona tipos de instrucción específicos que funcionan juntos para procesar los datos del grafo paso a paso. Comprender estas instrucciones es esencial para crear consultas eficaces.

Instrucción MATCH

Sintaxis:

MATCH <graph pattern>, <graph pattern>, ... [ WHERE <predicate> ]

La MATCH instrucción toma datos de entrada y busca patrones de grafos. Combina variables de entrada con variables de patrón y genera todas las combinaciones coincidentes.

Variables de entrada y salida:

-- Input: unit table (no columns, one row)
-- Pattern variables: p, c  
-- Output: table with (p, c) columns for each person-company match
MATCH (p:Person)-[:workAt]->(c:Company)

Filtrado de nivel de instrucción mediante WHERE:

-- Filter pattern matches
MATCH (p:Person)-[:workAt]->(c:Company) WHERE p.lastName = c.name

Puede filtrar todas las coincidencias después mediante WHERE. Este enfoque evita una instrucción independiente FILTER . Con un prefijo de búsqueda de caminos como ANY SHORTEST, el nivel WHERE de sentencia se aplica después de la selección de camino. Los predicados en línea en cambio limitan qué caminos son elegibles para la selección. Para más información, consulta Colocar predicados antes o después de la selección de caminos.

Combinación mediante variables de entrada:

Cuando MATCH no es la primera instrucción, combina los datos de entrada con coincidencias de patrón:

...
-- Input: table with 'targetCompany' column
-- Implicit join: targetCompany (equality join)
-- Output: table with (targetCompany, p, r) columns
MATCH (p:Person)-[r:workAt]->(targetCompany)

Importante

Graph soporta composición de enunciados lineales básicos y completos, incluyendo NEXT. También puedes combinar bloques de consulta con UNION, UNION DISTINCT, y UNION ALL. Las EXCEPToperaciones , INTERSECT, y OTHERWISE set aún no están soportadas. Para obtener más información, consulte el artículo sobre las limitaciones actuales.

Comportamientos clave de combinación:

Cómo MATCH controla la unión de datos:

  • Igualdad de variables: las variables de entrada se unen con variables de patrón mediante la coincidencia de igualdad
  • Combinación interna: las filas de entrada sin coincidencias de patrones se descartan. Use OPTIONAL MATCH para el comportamiento de combinación externa izquierda.
  • Orden de filtrado: Filtros a nivel WHERE de sentencia tras la búsqueda de patrones y la selección de rutas completada
  • Composición de patrones: Las variables compartidas limitan los patrones al mismo elemento. Los patrones desconectados forman un producto cartesiano.

Importante

Un patrón desconectado es válido, pero su producto cartesiano puede crear muchas filas. Utiliza variables compartidas cuando los patrones deberían referirse a los mismos elementos del grafo.

Patrones de unión con variables compartidas:

-- Shared variable 'p' joins the two patterns
-- Output: people with both workplace and residence data
MATCH (p:Person)-[:workAt]->(c:Company), 
      (p)-[:isLocatedIn]->(city:City)

Instrucción OPTIONAL MATCH

Sintaxis:

OPTIONAL MATCH <graph pattern> [ WHERE <predicate> ]

OPTIONAL MATCH funciona como MATCH pero usa la semántica de combinación externa izquierda. Si el patrón no encuentra ninguna coincidencia para una fila de entrada, la consulta conserva la fila con NULL valores para variables no coincidentes en lugar de descartarla.

Example:

-- Find all people and, if available, their workplace
MATCH (p:Person)
OPTIONAL MATCH (p)-[:workAt]->(c:Company)
RETURN p.firstName, p.lastName, c.name AS company_name

Las personas que no trabajan en ninguna empresa siguen apareciendo en los resultados con NULL para company_name.

Sugerencia

Use OPTIONAL MATCH cuando desee incluir entidades que podrían no tener una relación determinada, similar a una instancia de SQL LEFT JOIN.

Instrucción LET

Sintaxis:

LET <variable> = <expression>, <variable> = <expression>, ...

La LET instrucción crea variables calculadas y habilita la transformación de datos dentro de la canalización de consulta.

Creación de variables básicas:

MATCH (p:Person)
LET fullName = p.firstName || ' ' || p.lastName
RETURN *
LIMIT 1000

Cálculos complejos:

MATCH (p:Person)
LET adjustedAge = 2000 - (p.birthday / 10000),
    fullProfile = p.firstName || ' ' || p.lastName || ' (' || p.gender || ')'
RETURN *
LIMIT 1000

Comportamientos clave:

  • El motor de consultas evalúa expresiones para cada fila de entrada.
  • Los resultados se convierten en columnas nuevas en la tabla de salida.
  • Las variables solo pueden hacer referencia a variables existentes de instrucciones anteriores.
  • Varias asignaciones en una LET sentencia usan el mismo ámbito de entrada, por lo que una asignación no puede referenciar otra asignación de esa sentencia.

Instrucción FOR

Sintaxis:

FOR <variable> IN <list_expression>
  [ WITH OFFSET <offset_variable> | WITH ORDINALITY <ordinality_variable> ]

La FOR instrucción amplía una lista en filas. Para cada fila de entrada, emite una fila de salida para cada elemento de la lista y vincula ese elemento a la variable especificada. Otras variables de la fila de entrada siguen disponibles.

Úsalo WITH OFFSET para vincular un índice basado en cero, o para WITH ORDINALITY vincular una posición basada en uno.

LET cities = ['Seattle', 'London', 'Tokyo']
FOR city IN cities WITH ORDINALITY position
RETURN city, position

Esta consulta devuelve una fila para cada ciudad. Los position valores son 1, 2, y 3. Si reemplazas WITH ORDINALITY position por WITH OFFSET position, los valores son 0, 1, y 2.

La expresión fuente debe evaluarse a una lista. Un valor que no es de lista provoca que la consulta falle.

Instrucción CALL

Úsase CALL para ejecutar una subconsulta en línea para cada fila de entrada:

CALL {
  <query statements>
  RETURN <columns>
}

Las variables que ya están dentro del alcance están implícitamente disponibles dentro de la subconsulta. De las variables creadas dentro de la subconsulta, solo las columnas de su instrucción final RETURN quedan disponibles fuera de ella. Las variables creadas dentro de la subconsulta pero que no se devuelven permanecen locales.

La siguiente subconsulta correlacionada calcula el recuento de empleadores para cada persona:

MATCH (p:Person)
CALL {
  MATCH (p)-[:workAt]->(company:Company)
  RETURN count(*) AS employerCount
}
RETURN p.firstName, p.lastName, employerCount
ORDER BY employerCount DESC

Un ordinario CALL actúa como una unión interna dependiente. Produce una fila de salida por cada fila devuelta por la subconsulta. Si la subconsulta no devuelve filas, la fila exterior correspondiente no se devuelve. Si devuelve varias filas, la fila exterior aparece una vez por cada fila de subconsulta.

El ejemplo anterior count(*) siempre devuelve una fila de subconsulta porque utiliza un agregado no agrupado. Por lo tanto, una persona sin empleador compatible tiene un employerCount de 0.

Úsala OPTIONAL CALL como una unión izquierda dependiente. Cuando la subconsulta no devuelve filas, preserva una fila exterior y establece las columnas de subconsulta devueltas en NULL. Cuando la subconsulta devuelve varias filas, produce una fila de salida por cada fila de subconsulta.

MATCH (p:Person)
OPTIONAL CALL {
  MATCH (p)-[:workAt]->(company:Company)
  RETURN company.name AS companyName
}
RETURN p.firstName, p.lastName, companyName

Puedes anidar subconsultas en línea CALL . Una subconsulta anidada puede referenciar variables desde sus ámbitos de consulta adjuntos.

Importante

Termina cada cuerpo en línea CALL con RETURN. Graph no admite llamadas a procedimientos con nombre ni listas explícitas de importación de variables como CALL (p) { ... }.

Instrucción FILTER

Sintaxis:

FILTER [ WHERE ] <predicate>

La FILTER instrucción proporciona un control preciso sobre qué datos continúan a través de la canalización de consulta.

Filtrado básico:

MATCH (p:Person)
FILTER p.birthday < 19980101 AND p.gender = 'female'
RETURN *

Condiciones lógicas complejas:

MATCH (p:Person)
FILTER (p.gender = 'male' AND p.birthday < 19940101) 
  OR (p.gender = 'female' AND p.birthday < 19990101)
  OR p.browserUsed = 'Edge'
RETURN *

Patrones de filtrado compatibles con null:

Use estos patrones para controlar valores NULL de forma segura:

  • Comprobar los valores: : p.firstName IS NOT NULL tiene un nombre
  • Validar datos: : p.id > 0 identificador válido
  • Controlar los datos que faltan: NOT coalesce(p.locationIP, '10.x.x.x') STARTS WITH '10.x.x.x' : no se ha conectado desde la red local
  • Combinar condiciones: uso AND/OR con comprobaciones explícitas de valores NULL para lógica compleja

Precaución

Recuerde que las condiciones que implican valores NULL devuelven UNKNOWN, que filtra esas filas. Use comprobaciones explícitas IS NULL cuando necesite lógica inclusiva null.

Instrucción ORDER BY

Sintaxis:

ORDER BY <expression> [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ],
         <expression> [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ], ...

Ordenación de varios niveles con expresiones calculadas:

MATCH (p:Person)
RETURN *
ORDER BY p.firstName DESC,               -- Primary: by first name (Z-A)
         p.birthday ASC,                 -- Secondary: by age (oldest first)
         p.id DESC                       -- Tertiary: by ID (highest first)

Control nulo en la ordenación:

MATCH (p:Person)
RETURN p.firstName, p.birthday
ORDER BY p.birthday DESC NULLS LAST, p.firstName ASC

Detalles del comportamiento de ordenación:

Descripción del funcionamiento ORDER BY :

  • El motor de consultas evalúa las expresiones de cada fila y, a continuación, los resultados determinan el orden de las filas.
  • Varias claves de ordenación crean ordenación jerárquica (principal, secundaria, terciaria, etc.).
  • NULLS FIRST coloca los valores nulos antes que los valores no nulos. NULLS LAST los coloca después de valores no nulos.
  • La colocación nula es independiente de la dirección de ordenación. Si no especificas el orden nulo, NULLS LAST es el valor predeterminado tanto para ASC como DESCpara .
  • ASC (ascendente) es el orden predeterminado y debe especificar DESC explícitamente (descendente).
  • Puede ordenar por valores calculados, no solo por propiedades almacenadas.
Especificación de ordenación Orden resultante
ASC o ASC NULLS LAST Valores no nulos en orden ascendente, seguidos de valores nulos.
ASC NULLS FIRST Valores nulos, seguidos de valores no nulos en orden ascendente.
DESC o DESC NULLS LAST Valores no nulos en orden descendente, seguidos de valores nulos.
DESC NULLS FIRST Valores nulos, seguidos de valores no nulos en orden descendente.

Precaución

Solo la siguiente instrucción inmediatamente puede ver el criterio de ordenación que ORDER BY establece. Por lo tanto, ORDER BY seguido de RETURN * no genera un resultado ordenado.

Comparar:

MATCH (a:Person)-[r:knows]->(b:Person)
LET aName = a.firstName || ' ' || a.lastName
LET bName = b.firstName || ' ' || b.lastName
ORDER BY r.creationDate DESC
/* intermediary result _IS_ guaranteed to be ordered here */
RETURN aName, bName, r.creationDate AS since
/* final result _IS_ _NOT_ guaranteed to be ordered here  */

con:

MATCH (a:Person)-[r:knows]->(b:Person)
LET aName = a.firstName || ' ' || a.lastName
LET bName = b.firstName || ' ' || b.lastName
/* intermediary result _IS_ _NOT_ guaranteed to be ordered here */
RETURN aName, bName, r.creationDate AS since
ORDER BY r.creationDate DESC
/* final result _IS_ guaranteed to be ordered here              */

Esta diferencia tiene consecuencias inmediatas para las consultas "Top-k": LIMIT siempre debe seguir la ORDER BY instrucción que establece el criterio de ordenación previsto.

Instrucciones OFFSET y LIMIT

Sintaxis:

  OFFSET <offset> [ LIMIT <limit> ]
| LIMIT <limit>

Patrones comunes:

-- Basic top-N query
MATCH (p:Person)
RETURN *
ORDER BY p.id DESC
LIMIT 10                                 -- Top 10 by ID

Importante

Para obtener resultados de paginación predecibles, use ORDER BY siempre antes OFFSET y LIMIT para garantizar un orden de filas coherente entre las consultas.

RETURN: proyección de resultados básica

Sintaxis:

RETURN [ DISTINCT ] <expression> [ AS <alias> ], <expression> [ AS <alias> ], ...
[ ORDER BY <expression> [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ], ... ]
[ OFFSET <offset> ]
[ LIMIT <limit> ]

La RETURN instrucción genera la salida final de la consulta especificando qué datos aparecen en la tabla de resultados.

Salida básica:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName || ' ' || p.lastName AS name, 
       p.birthday, 
       c.name

Uso de alias para mayor claridad:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName AS first_name, 
       p.lastName AS last_name,
       c.name AS company_name

Combinar con la ordenación y los k superiores:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName || ' ' || p.lastName AS name, 
       p.birthday AS birth_year, 
       c.name AS company
ORDER BY birth_year ASC
LIMIT 10

Control duplicado mediante DISTINCT:

-- Remove duplicate combinations
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN DISTINCT p.gender, p.browserUsed, p.birthday AS birth_year
ORDER BY p.gender, p.browserUsed, birth_year

Combinar con la agregación:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN count(DISTINCT p) AS employee_count

RETURN con GROUP BY: proyección de resultados agrupados

Sintaxis:

RETURN [ DISTINCT ] <expression> [ AS <alias> ], <expression> [ AS <alias> ], ...
GROUP BY <variable>, <variable>, ...
[ ORDER BY <expression> [ ASC | DESC ], <expression> [ ASC | DESC ], ... ]
[ OFFSET <offset> ]
[ LIMIT <limit> ]

Use GROUP BY para agrupar filas por valores compartidos y funciones de agregado de proceso dentro de cada grupo.

Agrupación básica con agregación:

MATCH (p:Person)-[:workAt]->(c:Company)
LET companyId = c.id, companyName = c.name
RETURN companyId,
       companyName,
       count(*) AS employeeCount,
       avg(p.birthday) AS avg_birth_year
GROUP BY companyId, companyName
ORDER BY employeeCount DESC

Agrupación de varias columnas:

MATCH (p:Person)
LET gender = p.gender
LET browser = p.browserUsed
RETURN gender,
       browser,
       count(*) AS person_count,
       avg(p.birthday) AS avg_birth_year,
       min(p.creationDate) AS first_joined,
       max(p.id) AS highest_id
GROUP BY gender, browser
ORDER BY avg_birth_year DESC
LIMIT 10

Nota:

Para la agregación horizontal sobre patrones de longitud variable, véase Funciones agregadas.

Valores y tipos de valor

Los valores GQL incluyen Booleano, cadena, numérico, temporal, lista, nodo, arista, camino, nulo y nada. Los tipos son nulos a menos que especifiques NOT NULL. Las propiedades utilizan un subconjunto soportado del sistema completo de valores de consulta.

RETURN 42 AS integerValue,
       'Alice' AS stringValue,
       TRUE AS booleanValue,
       [1, 2, 3] AS listValue

Las comparaciones con nulo evalúan a UNKNOWN; usan IS NULL y IS NOT NULL para pruebas nulas. Las operaciones numéricas pueden aplicar conversiones implícitas entre tipos numéricos compatibles.

Nota:

No todos los tipos de valor GQL están soportados en todos los contextos de grafos. Para las restricciones actuales de propiedades y consultas, véase Tipos de datos.

Para la sintaxis literal, el comportamiento de comparación, las conversiones de tipos y la jerarquía de tipos, véase valores GQL y tipos de valor.

Expressions

Las expresiones calculan, comparan, agregan y transforman valores. Las formas comunes incluyen referencias de propiedades, operadores aritméticos y lógicos, predicados, llamadas a funciones, expresiones simples CASE y subconsultas:

MATCH (person:Person)
FILTER person.birthday < 19900101
RETURN person.firstName,
       CASE person.gender
         WHEN 'female' THEN 'F'
         WHEN 'male' THEN 'M'
         ELSE 'Other'
       END AS genderCode

GQL utiliza lógica de tres valores: las expresiones booleanas pueden evaluar hasta TRUE, FALSE, o UNKNOWN. A FILTER solo conserva filas para las que su predicado es TRUE.

Funciones agregadas como COUNT, SUM, AVG, MIN, y MAX resumen filas. Enumerar predicados como ALL, ANY, NONE, y SINGLE evaluar un predicado para los elementos de la lista. Las subconsultas de formulario EXISTS de procedimiento prueban si una consulta anidada devuelve una fila.

Para el comportamiento completo de operadores, predicados, agregados y funciones, véase expresiones, predicados y funciones GQL. Para ejemplos de filtrado y agrupación orientados a tareas, véase Filtrar y agregar datos de grafos.

Técnicas avanzadas de consulta

En esta sección se tratan patrones y técnicas sofisticados para crear consultas gráficas complejas y eficaces. Estos patrones van más allá del uso de instrucciones básicas para ayudarle a crear consultas analíticas eficaces.

Composición compleja de varias instrucciones

Importante

Graph admite la composición básica y completa de instrucciones lineales. Las EXCEPToperaciones , INTERSECT, y OTHERWISE set aún no están soportadas. Para obtener más información, consulte el artículo sobre las limitaciones actuales.

Comprender cómo crear consultas complejas de forma eficaz es fundamental para las consultas de grafos avanzadas.

UNION y UNION ALL

Utilice UNION, UNION DISTINCT, o UNION ALL para combinar resultados de dos o más bloques de consulta lineales:

<query block>
UNION [ DISTINCT | ALL ]
<query block>

-- Combine results from two separate pattern matches
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName AS name, c.name AS affiliation
UNION DISTINCT
MATCH (p:Person)-[:studyAt]->(u:University)
RETURN p.firstName AS name, u.name AS affiliation

Desnudo UNION es equivalente a UNION DISTINCT; ambos eliminan filas duplicadas. UNION ALL mantiene todas las filas, incluidos los duplicados.

Cada bloque de consulta debe devolver el mismo conjunto de nombres de columnas. El orden de las columnas puede variar entre bloques, y los tipos de datos deben ser compatibles.

NEXT

Úsase NEXT para ejecutar otra etapa de consulta contra la tabla devuelta por la etapa anterior:

<query stage>
RETURN <columns>
NEXT
<query stage>

La siguiente consulta encuentra a los empleados y sus empresas, y luego utiliza los nodos empleados devueltos en otra coincidencia de patrones:

MATCH (person:Person)-[:workAt]->(company:Company)
RETURN person, company.name AS companyName
NEXT
MATCH (person)-[:isLocatedIn]->(city:City)
RETURN person.firstName AS employee, companyName, city.name AS city

Solo las columnas devueltas por la etapa anterior están en el ámbito posterior NEXTa . Puedes usar varios NEXT separadores para construir una secuencia más larga de etapas de consulta.

Cualquiera de las etapas puede contener una unión de bloques de consulta. Una unión se evalúa dentro de su etapa antes de que la salida de la etapa cruce el NEXT límite. Si A, , y C representan bloques de consulta, A UNION B NEXT C agrupa como (A UNION B) NEXT C, mientras A NEXT B UNION C que agrupa como A NEXT (B UNION C)B.

Instrucciones condicionales

Utiliza una sentencia condicional para enrutar cada fila entrante a la primera rama cuyo predicado evalúe a TRUE:

WHEN <predicate> THEN <linear query statement or { query statements }>
[ WHEN <predicate> THEN <linear query statement or { query statements }> ... ]
[ ELSE <linear query statement or { query statements }> ]

Para enrutar filas de una etapa de consulta anterior, devuelva las columnas requeridas y use NEXT antes de la sentencia condicional:

MATCH (p:Person)
RETURN p.firstName AS name, p.birthday AS birthday
NEXT
WHEN birthday < 19800101u THEN
  RETURN name, 'Before 1980' AS era
WHEN birthday < 20000101u THEN
  RETURN name, '1980-1999' AS era
ELSE
  RETURN name, '2000 or later' AS era

Cada WHEN predicado debe ser booleano. El motor de consulta evalúa los predicados en orden de cada fila de entrada. Un predicado que evalúa o FALSEUNKNOWN no selecciona su rama. Después de que un predicado evalúa a TRUE, los predicados posteriores y los cuerpos de ramas no seleccionados no se evalúan. Si ningún predicado evalúa y TRUE no ELSEhay , la fila de entrada no se devuelve.

Los predicados y cuerpos de ramas pueden referenciar columnas de la etapa anterior. Una rama puede ser una sola afirmación lineal, o un procedimiento anidado encerrado entre llaves. Utiliza un procedimiento anidado cuando una rama necesita múltiples etapas o sentencias como CALL:

MATCH (p:Person)
RETURN p, p.firstName AS name
NEXT
WHEN p.gender = 'female' THEN {
  CALL {
    MATCH (p)-[:knows]->(friend:Person)
    RETURN count(*) AS friendCount
  }
  RETURN name, friendCount
}
ELSE
  RETURN name, 0u AS friendCount

Cada rama tiene su propio ámbito local. Las ramas hermanas no ven variables creadas por otra rama, y solo continúan las columnas de la última RETURN rama seleccionada después de la sentencia condicional. Cada rama debe devolver los mismos nombres de columna, y los tipos de resultados correspondientes deben ser compatibles. El motor de consulta obliga a tipos compatibles a un tipo de salida común. Una columna de rama retornada puede usar el mismo nombre que una columna entrante; el valor de rama reemplaza al valor entrante en la salida condicional.

Las sentencias condicionales son diferentes de CASE las expresiones. Graph soporta expresiones simples CASE <expression> WHEN <value>, pero no las CASE WHEN <predicate> que se buscan. Para más información, véase Expresiones condicionales.

Ámbito de variables y control de flujo avanzado

Las variables conectan datos entre instrucciones de consulta y habilitan recorridos de grafos complejos. Comprender las reglas de ámbito avanzadas le ayuda a escribir consultas sofisticadas de varias instrucciones.

Patrones de ámbito y enlace de variables

-- Variables flow forward through subsequent statements 
MATCH (p:Person)                                    -- Bind p 
LET fullName = p.firstName || ' ' || p.lastName     -- Bind concatenation of p.firstName and p.lastName as fullName
FILTER fullName CONTAINS 'Smith'                    -- Filter for fullNames with “Smith” substring (p is still bound)
RETURN p.id, fullName                               -- Only return p.id and fullName (p is dropped from scope)

Reutilización de variables para combinaciones entre instrucciones

-- Multi-statement joins using variable reuse
MATCH (p:Person)-[:workAt]->(:Company)          -- Find people with jobs
MATCH (p)-[:isLocatedIn]->(:City)               -- Same p: people with both job and residence
MATCH (p)-[:knows]->(friend:Person)             -- Same p: their social connections
RETURN *

Limitaciones y reglas de ámbito críticas

-- ✅ Backward references work
MATCH (p:Person)
LET adult = p.birthday < 20061231  -- Can reference p from previous statement
RETURN *

-- ❌ Forward references don't work  
LET adult = p.birthday < 20061231  -- Error: p not yet defined
MATCH (p:Person)
RETURN *

-- ❌ Variables in same LET statement can't reference each other
MATCH (p:Person)
LET name = p.firstName || ' ' || p.lastName,
    greeting = 'Hello, ' || name     -- Error: name not visible yet
RETURN *

-- ✅ Use separate statements for dependent variables
MATCH (p:Person)
LET name = p.firstName || ' ' || p.lastName
LET greeting = 'Hello, ' || name     -- Works: name now available
RETURN *

Visibilidad de variables en consultas complejas

-- Variables remain visible until overridden or query ends
MATCH (p:Person)                     -- p available from here
LET gender = p.gender                -- gender available from here  
MATCH (p)-[:knows]->(e:Person)       -- p still refers to original person
                                     -- e is a new variable for the friend
RETURN p.firstName AS manager, e.firstName AS friend, gender

Precaución

Las variables de la misma instrucción no se pueden hacer referencia entre sí, excepto en los patrones de grafos. Use instrucciones independientes para la creación de variables dependientes.

Filas agregadas y elementos de camino

GQL soporta dos contextos de agregación:

  • La agregación vertical resume las filas de entrada, opcionalmente particionadas por GROUP BY variables.
  • La agregación horizontal resume una lista de grupos limitada por un patrón de aristas de longitud variable dentro de un camino emparejado.
MATCH (person:Person)-[:workAt]->(company:Company)
LET companyId = company.id, companyName = company.name
RETURN companyId, companyName, count(*) AS employeeCount
GROUP BY companyId, companyName

MATCH (:Person)-[connections:knows]->{1,4}(:Person)
RETURN count(connections) AS pathLength

Para consultas agrupadas, filtros específicos de agregados, agregados de colección y enrutamiento condicional, véase Filtrar y agregar datos de grafos. Para ver reglas completas de resultados agregados, véase Funciones agregadas.

Gestionar nulos y errores de consulta

Utiliza pruebas nulas explícitas cuando los valores faltantes requieren un manejo distinto:

MATCH (person:Person)
FILTER person.browserUsed IS NULL
RETURN person.firstName

Una comparación con nulo evalúa a UNKNOWN, que a FILTER no retiene. Úsalo coalesce() cuando necesites un valor de respaldo.

Los resultados de la consulta incluyen información de estado para éxito, advertencias, condiciones de no datos, errores corregibles por el usuario y errores del sistema. Utiliza el código de estado público para un flujo de control amplio y el diagnóstico canónico de GQLSTATUS para una condición específica. Consulta Resultados y resultados de ejecución y la referencia de códigos de estado GQL.

Palabras reservadas

GQL reserva ciertas palabras clave que no se pueden usar como identificadores como variables, nombres de propiedad o nombres de etiqueta. Consulte la referencia de palabras reservadas de GQL para obtener la lista completa.

Si necesita usar palabras reservadas como identificadores, escapelas con acentos versos: `match`, `return`.

Para evitar el escape de palabras reservadas, use esta convención de nomenclatura:

  • Para los identificadores de una sola palabra, anexe un carácter de subrayado: :Product_
  • Para identificadores de varias palabras, use camelCase o PascalCase: :MyEntity, , :hasAttributetextColor

Pasos siguientes

Contenido relacionado

  • Se actualizó por última vez el