Referência rápida de GQL

Este artigo é uma referência rápida para a sintaxe GQL (Graph Query Language) para grafo no Microsoft Fabric. Use para recuperar sintaxe e defaults. Para uma explicação de ponta a ponta, veja o guia da linguagem GQL; cada seção faz link para a referência focada que possui todos os detalhes.

Observação

Este artigo usa principalmente o conjunto de dados de grafo de exemplo de rede social. Ele também fornece alguns exemplos que usam o conjunto de dados adventure works do tutorial de grafo.

Estrutura da consulta

As consultas GQL usam uma sequência de instruções que definem quais dados obter do grafo, como processá-los e como mostrar os resultados. Cada instrução tem uma finalidade específica e, juntas, criam um pipeline linear que corresponde aos dados do grafo e os transforma passo a passo.

Fluxo de consulta típico:
Uma consulta GQL geralmente começa especificando o padrão de grafo a ser correspondido. Em seguida, ele usa instruções opcionais para criação de variável, filtragem, classificação, paginação e saída de resultado.

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

Composição da declaração:

Importante

Instruções formam um pipeline ordenado e não podem ser rearranjadas arbitrariamente. Consulte o artigo sobre as limitações atuais.

  • MATCH – Especifique os padrões de grafo a serem encontrados.
  • LET – Definir variáveis de expressões.
  • FOR – Expandir uma lista em linhas.
  • CALL – Executar uma subconsulta inline e adicionar suas colunas retornadas.
  • FILTER – Manter as linhas correspondentes às condições.
  • WHEN – Rotear cada linha de entrada para o primeiro desvio condicional correspondente.
  • ORDER BY – Classificar resultados.
  • OFFSET – Ignorar muitas linhas.
  • LIMIT – Restrinja o número de linhas.
  • RETURN – Gerar os resultados finais.
  • NEXT – Iniciar outra etapa de consulta usando as colunas retornadas pela etapa anterior.

Cada instrução se baseia na anterior, de modo que você refina e formate incrementalmente a saída da consulta. Use UNION, UNION DISTINCT, ou UNION ALL para combinar blocos completos de consulta. Para obter mais informações sobre cada instrução, consulte as seções a seguir.

Instruções de consulta

MATCH

Encontre padrões de grafo em seus dados.

Sintaxe:

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

Example:

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

Para obter mais informações sobre a MATCH instrução, consulte os padrões do Graph.

DEIXAR

Crie variáveis usando expressões.

Sintaxe:

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

Example:

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

Para obter mais informações sobre a LET instrução, consulte o guia de linguagem GQL.

FOR

Expande uma lista em linhas e, opcionalmente, retorna a posição de cada elemento.

Sintaxe:

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 começa em 0. WITH ORDINALITY começa em 1.

Para obter mais informações sobre a FOR instrução, consulte o guia de linguagem GQL.

CALL

Executa uma subconsulta inline para cada linha de entrada. Variáveis já no escopo estão implicitamente disponíveis dentro da subconsulta.

Sintaxe:

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

Das variáveis criadas dentro da subconsulta, apenas colunas de sua instrução final RETURN ficam disponíveis fora dela. Ordinary CALL elimina uma linha externa quando a subconsulta não retorna linhas e a multiplica quando a subconsulta retorna várias linhas. OPTIONAL CALL preserva uma linha externa com NULL colunas de subconsulta quando a subconsulta não retorna linhas.

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

Para mais informações sobre subconsultas inline, consulte o guia de linguagem GQL.

FILTRO

Mantém linhas que correspondem às condições.

Sintaxe:

FILTER [ WHERE ] <predicate>
...

Example:

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

Para obter mais informações sobre a FILTER instrução, consulte o guia de linguagem GQL.

ORDENAR POR

Classifica os resultados.

Sintaxe:

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

Example:

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

A colocação nula é independente da direção de ordenação. O padrão é NULLS LAST para ambos ASC e DESC; especificar NULLS FIRST colocar valores nulos antes dos valores não nulos.

Importante

A ordem solicitada das linhas só garante que se mantenha imediatamente após uma instrução anterior ORDER BY . Quaisquer instruções a seguir (se presentes) não têm garantia de preservar tal ordem.

Para obter mais informações sobre a ORDER BY instrução, consulte o guia de linguagem GQL.

DESLOCAMENTO/LIMITE

Ignore linhas e limite o número de resultados.

Sintaxe:

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 obter mais informações sobre as instruções e OFFSET instruçõesLIMIT, consulte o guia de idioma GQL.

RETURN

Produza os resultados finais.

Sintaxe:

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

Example:

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

Para obter mais informações sobre a RETURN instrução, consulte o guia de linguagem GQL.

NEXT

Inicia outra etapa de consulta. Apenas colunas retornadas pelo estágio anterior estão disponíveis após NEXT.

Sintaxe:

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

Example:

RETURN 1 AS value
NEXT
RETURN value + 1 AS nextValue

Qualquer estágio pode conter uma união de blocos de consulta. A união é avaliada dentro dessa etapa antes que sua saída cruze a NEXT fronteira.

Para mais informações sobre NEXT, consulte o guia de linguagem GQL.

Instruções de condição

Roteia cada linha de entrada para o primeiro WHEN ramo cujo predicado avalia para TRUE.

Sintaxe:

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

Os predicados devem ser booleanos e são avaliados em ordem. FALSE e UNKNOWN cair para o próximo galho. Se nenhum branch coincidir e não ELSEhouver , a linha de entrada é omitida. Predicados após a primeira correspondência e corpos de ramificação não selecionados não são avaliados.

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

Todos os ramos devem devolver os mesmos nomes de colunas com tipos de dados compatíveis. Envolva um ramo em órteas quando ele contém um procedimento aninhado.

Para mais informações, veja Sentenças condicionais.

UNION

Combina a saída de blocos completos de consulta.

Sintaxe:

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

Exponha UNION e UNION DISTINCT remova linhas duplicadas. UNION ALL preserva as linhas duplicadas. Cada bloco de consulta deve retornar o mesmo conjunto de nomes de colunas com tipos de dados compatíveis.

Para mais informações sobre sindicatos, consulte o guia de linguagem da GQL.

Padrões de grafo

Os padrões de grafo descrevem a estrutura do grafo a ser correspondida.

Padrões de nó

Em bancos de dados de grafo, use nós para representar entidades, como pessoas, produtos ou locais.

Os padrões de nó descrevem como corresponder nós no grafo. Você pode filtrar por rótulo ou associar variáveis.

(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 obter mais informações sobre padrões de nó, consulte os padrões do Graph.

Padrões de borda

Os padrões de borda especificam relações entre nós, incluindo direção e tipo de borda. Em bancos de dados de grafo, uma borda representa uma conexão ou relação entre dois nós.

<-[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 obter mais informações sobre padrões de borda, consulte os padrões do Graph.

Expressões de rótulo

As expressões de rótulo permitem que você corresponda nós com combinações de rótulos específicas usando 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 obter mais informações sobre expressões de rótulo, consulte os padrões do Graph.

Padrões de caminho

Os padrões de caminho descrevem passagens pelo grafo, incluindo contagens de salto e associações de variáveis.

(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 é o modo de caminho padrão e permite nós e arestas repetidas. TRAIL previne arestas repetidas. SIMPLE impede a repetição de nós, exceto para o fechamento do primeiro ciclo, e ACYCLIC impede todos os nós repetidos. Ambos os modos únicos de nós também impedem a repetição das arestas porque o reuso de arestas repetiria os nós endpoint. ALL é a busca de caminho padrão. ANY SHORTEST retorna um caminho mais curto para cada par fonte-destino e não escolhe deterministicamente entre caminhos ligados.

Quantificadores suportados incluem fixos {n}, limitados {m,n} e {,n}, e não limitados {m,}, *, e +. Padrões ilimitados ALL WALK não são suportados; use um modo de caminho terminante. Ilimitado ANY SHORTEST WALK possui restrições adicionais de forma e valor de caminho. Para detalhes, veja padrões de gráficos GQL.

Para obter mais informações sobre padrões de caminho, consulte os padrões do Graph.

Vários padrões

Use vários padrões para corresponder a estruturas de grafo complexas e não lineares em uma única consulta.

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

Para obter mais informações sobre vários padrões, consulte os padrões do Graph.

Valores e tipos de valor

Tipos básicos

Tipos básicos são valores de dados primitivos, como cadeias de caracteres, números, boolianos e 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')

O sufixo d ou D cria um literal aproximado FLOAT64 . Um expoente sem sufixo também cria um FLOAT64 valor. Os f sufixos e F literal não são suportados atualmente.

Para obter mais informações sobre tipos básicos, consulte valores GQL e tipos de valor.

Tipos de valor de referência

Os tipos de valor de referência são nós e bordas que você usa como valores em consultas.

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

Para obter mais informações sobre tipos de valor de referência, consulte valores GQL e tipos de valor.

Tipos de coleção

Os tipos de coleção agrupam vários valores, como listas e caminhos.

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

Para obter mais informações sobre tipos de coleção, consulte valores GQL e tipos de valor.

Tipos materiais e anuláveis

Cada tipo de valor é anulável (inclui o valor nulo) ou material (exclui-o). Por padrão, os tipos são anuláveis, a menos que você especifique NOT NULLexplicitamente.

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

& Operadores de Expressões

Condicional

Expressões simples CASE comparam uma expressão com um ou mais valores.

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

Expressões pesquisadas CASE WHEN <predicate> não são suportadas. Use uma instrução condicional para rotear linhas com base em predicados.

Para obter mais informações sobre expressões condicionais, consulte as expressões e funções GQL.

Comparison

Os operadores de comparação comparam valores e verificam se há igualdade, ordenação ou nulos.

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

Para obter mais informações sobre predicados de comparação, consulte as funções e expressões GQL.

Lógico

Operadores lógicos combinam ou negam condições boolianas em consultas.

AND, OR, NOT, XOR               -- Boolean logic

Para obter mais informações sobre expressões lógicas, consulte as expressões e funções GQL.

EXISTS

Testa se uma subconsulta de formulário de procedimento retorna pelo menos uma linha.

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

EXISTS retorna um valor booleano não nulo. Use NOT EXISTS para testar que a subconsulta não retorna linhas. Você pode usar o resultado em WHERE ou FILTER, LET, RETURN, ORDER BY, e agregar o filtro ou expressões de origem. EXISTS não é suportado dentro de um filtro de predicados de lista.

Importante

Formulários apenas de padrões de grafo, como EXISTS { (p)-[:knows]->(friend) } e EXISTS ((p)-[:knows]->(friend)) não são suportados. Use o formulário de procedimento com MATCH mostrado no exemplo anterior.

Caution

Um agregado não agrupado como RETURN count(*) , retorna uma linha mesmo quando nenhum padrão coincide. Como EXISTS testa as linhas, essa forma avalia para TRUE.

Para mais informações sobre EXISTS, veja Subconsultas de existência.

Arithmetic

Operadores aritméticos executam cálculos em números.

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

Para obter mais informações sobre expressões aritméticas, consulte as funções e expressões GQL.

Padrões de cadeia de caracteres

Predicados de padrão de cadeia de caracteres correspondem a subcadeias de caracteres, prefixos ou sufixos em cadeias de caracteres.

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 obter mais informações sobre predicados de padrão de cadeia de caracteres, consulte as funções e expressões GQL.

Listar operações

Listar associação de teste de operações, elementos de acesso e tamanho da lista de medidas.

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

As funções predicadas da lista retornam TRUE, FALSE, ou UNKNOWN de acordo com os resultados do filtro. Para uma lista vazia, ALL e NONE retorne TRUE, enquanto ANY e SINGLE retorne FALSE. Uma lista de fonte nula retorna UNKNOWN.

A ligação de elementos é local ao filtro e pode sombrear uma variável externa. Agregados sobre essa ligação local e EXISTS subconsultas dentro do filtro não são suportados.

Para mais informações, veja Listar funções predicadas.

Acesso à propriedade

O acesso à propriedade obtém o valor de uma propriedade de um nó ou borda.

n.firstName                      -- Property access

Para obter mais informações sobre o acesso à propriedade, consulte as funções e expressões GQL.

Functions

Use funções embutidas para transformar valores, inspecionar elementos de grafos e agregar linhas.

Funções numéricas

Funções numéricas calculam valores numéricos ou produzem intervalos inteiros.

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

Outras funções trigonométricas suportadas são TAN, COT, ATAN, SINH, COSH, e TANH. Exceto por ABS e RANGE, essas funções numéricas retornam DOUBLE.

Saiba mais sobre funções numéricas em expressões e funções GQL.

Funções de agregação

Valores de resumo de computação de funções agregadas para grupos de linhas (agregação vertical) ou sobre os elementos de uma lista de grupos (agregação 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

Sem agrupar colunas, uma consulta agregada sem linhas de entrada retorna 0 para COUNT, uma lista vazia para COLLECT_LIST e COLLECT_ELEMENTS, e nula para SUM, AVG, MIN, MAX, e COLLECT_ONE. Um argumento de lista de grupos torna o agregado horizontal.

Saiba mais sobre as funções de agregação nas funções e expressões GQL.

Funções de cadeia de caracteres

As funções de cadeia de caracteres permitem que você trabalhe e analise valores de cadeia de caracteres.

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

Padrões regex, substituições e opções devem ser literais. Para assinaturas, flags e comportamento nulo, veja Funções de string.

Listar funções

As funções de lista permitem que você trabalhe com listas, como verificar tamanho ou tamanho de corte.

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

Para obter mais informações sobre funções de lista, consulte funções e expressões GQL.

Funções de grafo

As funções de grafo permitem obter informações de nós, caminhos e bordas.

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 obter mais informações sobre funções de grafo, consulte funções e expressões GQL.

Funções temporais

As funções temporais permitem que você trabalhe com valores de data e 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 obter mais informações sobre funções temporais, consulte funções e expressões GQL.

Funções genéricas

Funções genéricas permitem que você trabalhe com dados de maneiras comuns.

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 obter mais informações sobre funções genéricas, consulte funções e expressões GQL.

Exemplos orientados a tarefas

Use os artigos de instruções quando precisar de padrões completos e prontos para adaptação:

Conteúdo relacionado

  • Last updated on