Referencia rápida de GQL

Este artículo es una referencia rápida para la sintaxis de GQL (lenguaje de consulta de Graph) para graph en Microsoft Fabric. Úsalo para recuperar sintaxis y valores predeterminados. Para una explicación de extremo a extremo, consulte la guía del lenguaje GQL; cada sección enlaza con la referencia enfocada que posee todos los detalles.

Nota:

En este artículo se usa principalmente el conjunto de datos del gráfico de ejemplo de red social. También proporciona algunos ejemplos que usan el conjunto de datos Adventure Works del tutorial de grafos.

Estructura de la consulta

Las consultas GQL usan una secuencia de instrucciones que definen qué datos obtener del grafo, cómo procesarlos y cómo mostrar los resultados. Cada instrucción tiene un propósito específico y, juntos, crean una canalización lineal que coincide con los datos del grafo y lo transforman paso a paso.

Flujo de consulta típico:
Normalmente, una consulta GQL se inicia especificando el patrón de grafo que debe coincidir. A continuación, usa instrucciones opcionales para la creación de variables, el filtrado, la ordenación, la paginación y la salida de resultados.

Example:

MATCH (n:Person)-[:knows]->(m:Person) 
LET fullName = n.firstName || ' ' || n.lastName 
FILTER m.gender = 'female' 
ORDER BY fullName ASC 
OFFSET 10
LIMIT 5 
RETURN fullName, m.firstName

Composición de la declaración:

Importante

Las sentencias forman una tubería ordenada y no pueden reorganizarse arbitrariamente. Consulte el artículo sobre las limitaciones actuales.

  • MATCH : especifique los patrones de grafos que se van a buscar.
  • LET – Definir variables a partir de expresiones.
  • FOR – Expandir una lista en filas.
  • CALL – Ejecutar una subconsulta en línea y añadir sus columnas devueltas.
  • FILTER – Mantener las condiciones de coincidencia de filas.
  • WHEN – Enrutar cada fila de entrada a la primera rama condicional correspondiente.
  • ORDER BY – Ordenar los resultados.
  • OFFSET – Omitir muchas filas.
  • LIMIT : restringe el número de filas.
  • RETURN : genera los resultados finales.
  • NEXT – Iniciar otra etapa de consulta utilizando las columnas devueltas por la etapa anterior.

Cada instrucción se basa en la anterior, por lo que se refina incrementalmente y se da forma a la salida de la consulta. Utiliza UNION, UNION DISTINCT, o UNION ALL para combinar bloques completos de consulta. Para obtener más información sobre cada instrucción, consulte las secciones siguientes.

Instrucciones de consulta

MATCH

Busque patrones de grafos en los datos.

Sintaxis:

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

Example:

MATCH (n:Person)-[:knows]-(m:Person) WHERE n.birthday > 2000
RETURN *

Para obtener más información sobre la MATCH instrucción , vea Los patrones de Graph.

DEJAR

Cree variables mediante expresiones.

Sintaxis:

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

Example:

MATCH (n:Person)
LET fullName = n.firstName || ' ' || n.lastName
RETURN fullName

Para obtener más información sobre la LET instrucción , consulte la guía del lenguaje GQL.

FOR

Expande una lista en filas y opcionalmente devuelve la posición de cada elemento.

Sintaxis:

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

Example:

FOR value IN [10, 20] WITH OFFSET index
RETURN value, index

WITH OFFSET empieza en 0. WITH ORDINALITY empieza en 1.

Para obtener más información sobre la FOR instrucción , consulte la guía del lenguaje GQL.

CALL

Ejecuta una subconsulta en línea para cada fila de entrada. Las variables ya en el alcance están implícitamente disponibles dentro de la subconsulta.

Sintaxis:

[ OPTIONAL ] CALL {
  <query statements>
  RETURN <columns>
}
...

De las variables creadas dentro de la subconsulta, solo las columnas de su instrucción final RETURN quedan disponibles fuera de ella. Ordinario CALL elimina una fila exterior cuando la subconsulta no devuelve filas y la multiplica cuando la subconsulta devuelve varias filas. OPTIONAL CALL preserva una fila exterior con NULL columnas de subconsulta cuando la subconsulta no devuelve filas.

MATCH (p:Person)
CALL {
  MATCH (p)-[:knows]->(friend:Person)
  RETURN count(*) AS friendCount
}
RETURN p.firstName, friendCount

Para más información sobre las subconsultas en línea, consulte la guía del lenguaje GQL.

FILTRO

Mantiene las filas que coinciden con las condiciones.

Sintaxis:

FILTER [ WHERE ] <predicate>
...

Example:

MATCH (n:Person)-[:knows]->(m:Person)
FILTER WHERE n.birthday > m.birthday
RETURN *

Para obtener más información sobre la FILTER instrucción , consulte la guía del lenguaje GQL.

ORDENAR POR

Ordena los resultados.

Sintaxis:

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

Example:

MATCH (n:Person)
RETURN *
ORDER BY n.lastName ASC NULLS LAST, n.firstName ASC

La colocación nula es independiente de la dirección de ordenación. El valor por defecto es NULLS LAST tanto para como DESCpara ; especificar NULLS FIRST colocar valores nulos antes que valores ASC no nulos.

Importante

El orden solicitado de filas solo garantiza que se cumpla inmediatamente después de una instrucción anterior ORDER BY . No se garantiza que las siguientes instrucciones (si están presentes) conserven este orden.

Para obtener más información sobre la ORDER BY instrucción , consulte la guía del lenguaje GQL.

OFFSET/LIMIT

Omita las filas y limite el número de resultados.

Sintaxis:

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

Example:

MATCH (n:Person)
ORDER BY n.birthday
OFFSET 10 LIMIT 20
RETURN n.firstName || ' ' || n.lastName AS name, n.birthday

Para obtener más información sobre las OFFSET instrucciones y LIMIT , consulte la guía del lenguaje GQL.

RETURN

Genera los resultados finales.

Sintaxis:

RETURN [ DISTINCT ] <expression> [ AS <alias> ], ...

Example:

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

Para obtener más información sobre la RETURN instrucción , consulte la guía del lenguaje GQL.

NEXT

Comienza otra fase de consulta. Solo las columnas devueltas por la etapa anterior están disponibles después NEXTde .

Sintaxis:

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

Example:

RETURN 1 AS value
NEXT
RETURN value + 1 AS nextValue

Cualquiera de las etapas puede contener una unión de bloques de consulta. La unión se evalúa dentro de esa etapa antes de que su salida cruce el NEXT límite.

Para más información sobre NEXT, consulta la guía de lenguaje GQL.

Instrucciones condicionales

Ruta cada fila de entrada a la primera WHEN rama cuyo predicado evalúa a TRUE.

Sintaxis:

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 }> ]

Los predicados deben ser booleanos y evaluarse en orden. FALSE y UNKNOWN caer hasta la siguiente rama. Si ninguna rama coincide y no ELSEhay , se omite la fila de entrada. No se evalúan los predicados después de la primera coincidencia y los cuerpos de ramas no seleccionados.

RETURN 'Alice' AS name, 19900101u AS birthday
NEXT
WHEN birthday < 20000101u THEN
  RETURN name, 'Before 2000' AS era
ELSE
  RETURN name, '2000 or later' AS era

Todas las ramas deben devolver los mismos nombres de columna con tipos de datos compatibles. Encierra una rama con enlaces cuando contenga un procedimiento anidado.

Para más información, véase Sentencias condicionales.

UNION

Combina la salida de bloques completos de consulta.

Sintaxis:

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

Desnuda UNION y UNION DISTINCT elimina filas duplicadas. UNION ALL preserva filas duplicadas. Cada bloque de consulta debe devolver el mismo conjunto de nombres de columnas con tipos de datos compatibles.

Para más información sobre los sindicatos, consulte la guía de lenguaje de GQL.

Patrones de grafos

Los patrones de grafo describen la estructura del grafo que se va a coincidir.

Patrones de nodo

En las bases de datos de grafos, use nodos para representar entidades, como personas, productos o lugares.

Los patrones de nodo describen cómo hacer coincidir nodos en el gráfico. Puede filtrar por etiqueta o enlazar variables.

(n)              -- Any node
(n:Person)       -- Node with Person label  
(n:City&Place)   -- Node with City AND Place label
(:Person)        -- Person node, don't bind variable

Para obtener más información sobre los patrones de nodo, consulte Los patrones de Graph.

Patrones perimetrales

Los patrones perimetrales especifican relaciones entre nodos, incluido el tipo de dirección y borde. En las bases de datos de grafos, un borde representa una conexión o relación entre dos nodos.

<-[e]-             -- Incoming edge
-[e]->             -- Outgoing edge
-[e]-              -- Any edge
-[e:knows]->       -- Edge with label ("relationship type")
-[e:knows|likes]-> -- Edges with different labels
-[:knows]->        -- :knows edge, don't bind variable

Para obtener más información sobre los patrones perimetrales, consulte Los patrones de Graph.

Expresiones de etiqueta

Las expresiones de etiqueta permiten hacer coincidir nodos con combinaciones de etiquetas específicas mediante operadores lógicos.

:Person&Company                  -- Both Person AND Company labels
:Person|Company                  -- Person OR Company labels
:!Company                        -- NOT Company label
:(Person|!Company)&Active        -- Complex expressions with parentheses

Para obtener más información sobre las expresiones de etiqueta, consulte Los patrones de Graph.

Patrones de ruta de acceso

Los patrones de ruta de acceso describen recorridos a través del gráfico, incluidos los recuentos de saltos y los enlaces de variables.

(a)-[:knows|likes]->{1,3}(b)        -- 1-3 hops via knows/likes
p=()-[:knows]->()                   -- Bind a path variable
MATCH REPEATABLE ELEMENTS (a)->(b)  -- Explicit default match mode
MATCH DIFFERENT EDGES (a)->(b), (a)->(c)
MATCH ALL TRAIL (a)->{1,4}(b)       -- Every edge-unique path
MATCH p = ANY SHORTEST (a)->{1,4}(b) -- One shortest path per endpoint pair

WALK es el modo de ruta por defecto y permite la repetición de nodos y aristas. TRAIL evita que se repitan los bordes. SIMPLE impide nodos repetidos excepto en un ciclo de cierre por orden de último y ACYCLIC evita todos los nodos repetidos. Ambos modos únicos de nodo también evitan aristas repetidas porque la reutilización de aristas repetiría nodos de punto final. ALL es la búsqueda de ruta por defecto. ANY SHORTEST devuelve un camino más corto para cada par origen-destino y no elige determinísticamente entre caminos vinculados.

Los cuantificadores soportados incluyen fijos {n}, acotados {m,n} y {,n}, y no acotados {m,}, *, y +. No se soportan patrones ilimitados ALL WALK ; utiliza un modo de camino de terminación. Sin límites ANY SHORTEST WALK tiene restricciones adicionales de forma y valor de camino. Para más detalles, véase Patrones de gráficos GQL.

Para obtener más información sobre los patrones de ruta de acceso, consulte Los patrones de Graph.

Varios patrones

Use varios patrones para que coincidan con estructuras de grafos complejas y no lineales en una sola consulta.

(a)->(b), (a)->(c)               -- Multiple edges from same node
(a)->(b)<-(c), (b)->(d)          -- Nonlinear structures

Para obtener más información sobre varios patrones, consulte Los patrones de Graph.

Valores y tipos de valor

Tipos básicos

Los tipos básicos son valores de datos primitivos, como cadenas, números, booleanos y datetimes.

STRING           -- 'hello', "world"
INT64            -- 42, -17
FLOAT64          -- 3.14, -2.5e10, -17d
BOOL             -- TRUE, FALSE, UNKNOWN
ZONED DATETIME   -- ZONED_DATETIME('2023-01-15T10:30:00Z')

El d sufijo or D crea un literal aproximado FLOAT64 . Un exponente sin sufijo también crea un FLOAT64 valor. Los f sufijos y F literales no están soportados actualmente.

Para obtener más información sobre los tipos básicos, vea Valores de GQL y tipos de valor.

Tipos de valor de referencia

Los tipos de valor de referencia son nodos y bordes que se usan como valores en las consultas.

NODE             -- Node reference values
EDGE             -- Edge reference values

Para obtener más información sobre los tipos de valor de referencia, vea Valores de GQL y tipos de valor.

Tipos de colección

Los tipos de colección agrupan varios valores, como listas y rutas de acceso.

LIST<INT64>      -- [1, 2, 3]
LIST<STRING>     -- ['a', 'b', 'c']
PATH             -- Path values

Para obtener más información sobre los tipos de colección, vea Valores y tipos de valor de GQL.

Tipos materiales y anulables

Cada tipo de valor es que acepta valores NULL (incluye el valor NULL) o material (lo excluye). De forma predeterminada, los tipos admiten valores NULL a menos que especifique NOT NULLexplícitamente .

STRING NOT NULL  -- Material (Non-nullable) string type
INT64            -- Nullable (default) integer type

Expresiones y operadores

Condicional

Las expresiones simples CASE comparan una expresión con uno o más valores.

CASE expr WHEN val THEN val ELSE val END -- Simple CASE
NULLIF(a, b)                           -- NULL if a = b

No se admiten expresiones buscadas CASE WHEN <predicate> . Utiliza una sentencia condicional para enrutar filas basadas en predicados.

Para obtener más información sobre las expresiones condicionales, consulte las funciones y expresiones GQL.

Comparación

Los operadores de comparación comparan valores y comprueban si hay igualdad, ordenación o valores NULL.

=, <>, <, <=, >, >=              -- Standard comparison
IS NULL, IS NOT NULL             -- Null checks

Para obtener más información sobre los predicados de comparación, consulte las funciones y expresiones de GQL.

Logical

Los operadores lógicos combinan o niegan las condiciones booleanas en las consultas.

AND, OR, NOT, XOR               -- Boolean logic

Para obtener más información sobre las expresiones lógicas, consulte las funciones y expresiones GQL.

EXISTS

Prueba si una subconsulta procedimiento-formulario devuelve al menos una fila.

EXISTS {
  MATCH (p)-[:knows]->(friend:Person)
  RETURN friend
}

EXISTS devuelve un valor booleano no nulo. Úsalo NOT EXISTS para comprobar que la subconsulta no devuelve filas. Puedes usar el resultado en WHERE o FILTER, LET, RETURN, ORDER BY, y agregar el filtro o expresiones fuente. EXISTS no está soportado dentro de un filtro de predicados de lista.

Importante

No se soportan formas solo de patrones de grafo como EXISTS { (p)-[:knows]->(friend) } y EXISTS ((p)-[:knows]->(friend)) Graph. Utiliza el formulario de procedimiento con MATCH mostrado en el ejemplo anterior.

Caution

Un agregado no agrupado como RETURN count(*) devuelve una fila incluso cuando ningún patrón coincide. Como EXISTS prueba las filas, esa forma evalúa a TRUE.

Para más información sobre EXISTS, véase Subconsultas de existencia.

Arithmetic

Los operadores aritméticos realizan cálculos en números.

+, -, *, /                       -- Basic arithmetic operations
1.00m / 8.00m                    -- Exact result: 0.1250m

Para obtener más información sobre las expresiones aritméticas, consulte las funciones y expresiones GQL.

Patrones de cadena

Los predicados de patrón de cadena coinciden con subcadenas, prefijos o sufijos en cadenas.

n.firstName CONTAINS 'John'          -- Has substring
n.browserUsed STARTS WITH 'Chrome'   -- Starts with prefix
n.locationIP ENDS WITH '.1'          -- Ends with suffix
MSFT.REGEXP_LIKE(n.firstName, '^jo', 'i') -- RE2 regular expression

Para obtener más información sobre los predicados de patrón de cadena, consulte las funciones y expresiones GQL.

Operaciones de lista

Enumerar las operaciones prueba la pertenencia, los elementos de acceso y la longitud de la lista de medida.

n.gender IN ['male', 'female']    -- Membership test
n.tags[0]                        -- First element
size(n.tags)                     -- List length
ALL(x IN n.tags WHERE x <> '')   -- Every element matches
ANY(x IN n.tags WHERE x = 'gql') -- At least one element matches
NONE(x IN n.tags WHERE x = '')   -- No element matches
SINGLE(x IN n.tags WHERE x = 'gql') -- Exactly one element matches

Las funciones predicadas de lista devolven TRUE, FALSE, o UNKNOWN según los resultados del filtro. Para una lista vacía, ALL y NONE return TRUE, mientras ANY que y SINGLE return FALSE. Una lista de fuentes nulas devuelve UNKNOWN.

La unión de elementos es local al filtro y puede sombrear una variable externa. No se soportan agregados sobre ese enlace local y EXISTS subconsultas dentro del filtro.

Para más información, véase Listar funciones predicadas.

Property Access

El acceso a la propiedad obtiene el valor de una propiedad desde un nodo o borde.

n.firstName                      -- Property access

Para obtener más información sobre el acceso a propiedades, vea las funciones y expresiones GQL.

Functions

Utiliza funciones integradas para transformar valores, inspeccionar elementos de grafos y agregar filas.

Funciones numéricas

Las funciones numéricas calculan valores numéricos o producen rangos enteros.

abs(value)                       -- Absolute value; preserves the numeric type
power(base, exponent)            -- Exponentiation; returns DOUBLE
sin(radians), cos(radians)       -- Trigonometric functions
asin(value), acos(value)         -- Inverse functions; value must be in [-1, 1]
degrees(radians)                 -- Convert radians to degrees
radians(degrees)                 -- Convert degrees to radians
range(start, end)                -- Integer range with step 1
range(start, end, step)          -- Integer range with a nonzero step

Otras funciones trigonométricas soportadas son TAN, COT, ATAN, SINH, COSH, y TANH. Excepto para ABS y RANGE, estas funciones numéricas devolven DOUBLE.

Aprende más sobre funciones numéricas en expresiones y funciones GQL.

Funciones agregadas

Las funciones de agregado calculan valores de resumen para grupos de filas (agregación vertical) o sobre los elementos de una lista de grupos (agregación horizontal).

count(*)                         -- Count all rows
count(expr)                      -- Count non-null values
sum(p.birthday)                  -- Sum values
avg(p.birthday)                  -- Average
min(p.birthday), max(p.birthday) -- Minimum and maximum values
collect_list(p.firstName)        -- Collect inputs, including nulls
collect_one(p.firstName)         -- Select one non-null value
collect_elements(p.roles)        -- Concatenate list-valued inputs
count(DISTINCT expr)             -- Remove duplicate expression values
count(*) FILTER (WHERE predicate LIMIT 10) -- Filter and limit this aggregate

Sin agrupar columnas, una consulta agregada sin filas de entrada devuelve 0 para COUNT, una lista vacía para COLLECT_LIST y COLLECT_ELEMENTS, y nula para SUM, AVG, MIN, MAX, y COLLECT_ONE. Un argumento de lista de grupos hace que el agregado sea horizontal.

Obtenga más información sobre las funciones de agregado en las expresiones y funciones de GQL.

Funciones de cadena

Las funciones de cadena permiten trabajar con valores de cadena y analizarlos.

char_length(s)                   -- String length
upper(s), lower(s)               -- Unicode case mapping
casefold(s)                      -- Unicode caseless form
normalize(s)                     -- Normalize a string to NFC
normalize(s, NFD)                -- Normalize a string to NFD
trim(s)                          -- Trim spaces
trim(leading '_' from s)         -- Trim one custom byte
string_join(list)                -- Join with ", "
string_join(list, delimiter)     -- Join with a custom delimiter
MSFT.REGEXP_COUNT(s, pattern)    -- Count RE2 matches
MSFT.REGEXP_INSTR(s, pattern)    -- Find a zero-based match position
MSFT.REGEXP_SUBSTR(s, pattern)   -- Return matching text
MSFT.REGEXP_REPLACE(s, pattern, replacement) -- Replace matches

Los patrones regex, reemplazos y opciones deben ser literales. Para firmas, flags y comportamiento nulo, véase Funciones de cadena.

Enumerar funciones

Las funciones de lista permiten trabajar con listas, como comprobar la longitud o el tamaño de recorte.

size(list)                       -- List length
trim(list, n)                    -- Trim a list to at most n elements

Para obtener más información sobre las funciones de lista, vea Expresiones y funciones de GQL.

Funciones de grafo

Las funciones de grafo permiten obtener información de nodos, rutas de acceso y bordes.

labels(node)                     -- Get node labels
element_id(node_or_edge)         -- Get an opaque element identifier
nodes(path)                      -- Get path nodes
edges(path)                      -- Get path edges
elements(path)                   -- Get all path nodes and edges
path_length(path)                -- Get number of edges in a path

Para obtener más información sobre las funciones de grafo, consulte Expresiones y funciones de GQL.

Funciones temporales

Las funciones temporales permiten trabajar con valores de fecha y hora.

CURRENT_TIMESTAMP                -- Get the current zoned datetime
ZONED_DATETIME(string)           -- Parse an ISO 8601 zoned datetime
DURATION(string)                 -- Parse an ISO 8601 day-time duration

Para obtener más información sobre las funciones temporales, vea Expresiones y funciones de GQL.

Funciones genéricas

Las funciones genéricas permiten trabajar con datos de maneras comunes.

coalesce(expr1, expr2, ...)    -- Get the first non-null value
to_json_string(value)          -- Convert value to JSON string
nullif(a, b)                   -- NULL if a = b, else a

Para obtener más información sobre las funciones genéricas, vea Expresiones y funciones GQL.

Ejemplos orientados a tareas

Utiliza los artículos prácticos cuando necesites patrones de consulta completos y listos para adaptar:

Contenido relacionado

  • Last updated on