Referência rápida do GQL

Este artigo é uma referência rápida para a sintaxe GQL (Graph Query Language) para grafos no Microsoft Fabric. Usa-o para recordar sintaxe e defaults. Para uma explicação de ponta a ponta, consulte o guia da linguagem GQL; cada secção liga à referência focada que detém todos os detalhes.

Observação

Este artigo utiliza principalmente o conjunto de dados de exemplos de grafos de redes sociais. Também fornece alguns exemplos que utilizam o conjunto de dados Adventure Works do tutorial de grafos.

Estrutura da consulta

As consultas GQL usam uma sequência de instruções que definem quais dados obter do gráfico, 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 gráfico e os transforma passo a passo.

Fluxo de consulta típico:
Uma consulta GQL geralmente começa por especificar o padrão do grafo para corresponder. Depois, utiliza instruções opcionais para criação de variáveis, filtragem, ordenação, paginação e saída de resultados.

Exemplo:

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

As instruções formam um pipeline ordenado e não podem ser reorganizadas arbitrariamente. Veja o artigo sobre as limitações atuais.

  • MATCH – Especifique padrões gráficos para encontrar.
  • LET – Definir variáveis a partir de expressões.
  • FOR – Expandir uma lista em linhas.
  • CALL – Executar uma subconsulta inline e adicionar as colunas devolvidas.
  • FILTER – Mantenha as linhas correspondendo às condições.
  • WHEN – Encaminhar cada linha de entrada para o primeiro ramo condicional correspondente.
  • ORDER BY – Ordenar resultados.
  • OFFSET – Pule muitas linhas.
  • LIMIT – Restringir o número de linhas.
  • RETURN – Produzir os resultados finais.
  • NEXT – Iniciar outra fase de consulta usando as colunas devolvidas pela etapa anterior.

Cada instrução se baseia na anterior, para que você refine e modele 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.

Declarações de consulta

MATCH

Encontre padrões gráficos em seus dados.

Sintaxe:

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

Exemplo:

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 gráficos.

DEIXAR

Cria variáveis usando expressões.

Sintaxe:

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

Exemplo:

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 idiomas GQL.

FOR

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

Sintaxe:

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

Exemplo:

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 idiomas GQL.

CALL

Executa uma subconsulta inline para cada linha de entrada. As variáveis já no âmbito estão implicitamente disponíveis dentro da subconsulta.

Sintaxe:

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

Das variáveis criadas dentro da subconsulta, apenas colunas da sua instrução final RETURN ficam disponíveis fora dela. Ordinary CALL elimina uma linha exterior quando a subconsulta não retorna linhas e multiplica-a quando a subconsulta devolve várias linhas. OPTIONAL CALL preserva uma linha exterior 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 da linguagem GQL.

FILTRAR

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

Sintaxe:

FILTER [ WHERE ] <predicate>
...

Exemplo:

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 idiomas GQL.

ORDENAR POR

Classifica os resultados.

Sintaxe:

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

Exemplo:

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 para colocar valores nulos antes dos valores não nulos.

Importante

A ordem solicitada das linhas só é garantida de se manter imediatamente após uma afirmação ORDER BY anterior. Quaisquer declarações seguintes (se existirem) não garantem preservar tal ordem.

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

COMPENSAÇÃO/LIMITE

Pule linhas e limite o número de resultados.

Sintaxe:

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

Exemplo:

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 OFFSET instruções and LIMIT , consulte o guia de idiomas GQL.

RETURN

Produza os resultados finais.

Sintaxe:

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

Exemplo:

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

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

NEXT

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

Sintaxe:

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

Exemplo:

RETURN 1 AS value
NEXT
RETURN value + 1 AS nextValue

Qualquer etapa pode conter uma união de blocos de consulta. A união é avaliada dentro dessa fase antes de a sua saída ultrapassar a NEXT fronteira.

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

Instruções condicionais

Encaminha 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 por ordem. FALSE e UNKNOWN cair até ao ramo seguinte. Se nenhum branch coincidir e não ELSEhouver , a linha de entrada é omitida. Os predicados após a primeira correspondência e os corpos de ramos 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

Todas as ramificações devem devolver os mesmos nomes de colunas com tipos de dados compatíveis. Envolva um ramo em órtese quando este contém um procedimento aninhado.

Para mais informações, consulte Declarações condicionais.

UNION

Combina a saída de blocos completos de consulta.

Sintaxe:

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

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

Para mais informações sobre sindicatos, consulte o guia linguístico da GQL.

Padrões gráficos

Os padrões gráficos descrevem a estrutura do gráfico a ser correspondida.

Padrões de nó

Em bases de dados de grafos, utiliza-se nós para representar entidades, como pessoas, produtos ou locais.

Os padrões de nó descrevem como fazer a correspondência de nós no gráfico. Você pode filtrar por rótulo ou vincular 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 Padrões de gráfico.

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 gráficos, uma aresta 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 Padrões de gráfico.

Expressões de rótulo

As expressões de etiquetas permitem-lhe emparelhar nós com combinações específicas de etiquetas 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 Padrões gráficos.

Padrões de caminho

Os padrões de caminho descrevem as travessias através do gráfico, incluindo contagens de saltos e ligações 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 a repetição de nós e arestas. TRAIL previne arestas repetidas. SIMPLE impede a repetição de nós, exceto de um ciclo de fecho por ordem de penúltimo, e ACYCLIC impede todos os nós repetidos. Ambos os modos únicos de nós também impedem a repetição das arestas porque a reutilização das arestas repetiria os nós do endpoint. ALL é a pesquisa de caminho padrão. ANY SHORTEST devolve 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 ilimitados {m,}, *, e +. Padrões ilimitados ALL WALK não são suportados; use um modo de caminho de terminação. Ilimitado ANY SHORTEST WALK tem 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 Padrões de gráfico.

Vários padrões

Use múltiplos padrões para corresponder estruturas complexas de grafos não lineares numa ú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 Padrões gráficos.

Valores e tipos de valor

Tipos básicos

Tipos básicos são valores de dados primitivos como strings, números, booleanos 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 atualmente suportados.

Para mais informações sobre tipos básicos, veja Valores GQL e tipos de valor.

Tipos de valores de referência

Os tipos de valor de referência são nós e arestas que usas como valores nas consultas.

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

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

Tipos de recolha

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 mais informações sobre tipos de coleções, consulte valores GQL e tipos de valor.

Tipos materiais e anuláveis

Cada tipo de valor pode ser anulado (inclui o valor nulo) ou material (exclui-lo). Por defeito, os tipos são anuláveis, a menos que especifique NOT NULLexplicitamente .

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

Expressões & operadores

Conditional

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 encaminhar linhas com base em predicados.

Para 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 expressões e funções GQL.

Logical

Os operadores lógicos combinam ou negam condições booleanas 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 procedimento-formulário devolve pelo menos uma linha.

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

EXISTS devolve um valor booleano não nulo. Use NOT EXISTS para testar que a subquery não devolve linhas. Pode usar o resultado em WHERE ou FILTER, LET, RETURN, ORDER BY, e o filtro agregado ou expressões de origem. EXISTS não é suportado dentro de um filtro de predicados de lista.

Importante

Formulários apenas com 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(*) devolve 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

Os operadores aritméticos realizam 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 expressões e funções GQL.

Padrões de cadeia de caracteres

Predicados de padrão de cadeia de caracteres correspondem a substrings, prefixos ou sufixos em strings.

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 expressões e funções GQL.

Listar operações

Listar operações testar associação, elementos de acesso e medir o comprimento da lista.

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 de predicado de lista devolvem TRUE, FALSE, ou UNKNOWN de acordo com os resultados do filtro. Para uma lista vazia, ALL e NONE return TRUE, enquanto ANY e SINGLE return FALSE. Uma lista de fonte nula devolve UNKNOWN.

A ligação de elementos é local ao filtro e pode sombrear uma variável exterior. 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 de predicado.

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 expressões e funções GQL.

Funções

Use funções incorporadas para transformar valores, inspecionar elementos do grafo e agregar linhas.

Funções numéricas

As 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 para ABS e RANGE, estas funções numéricas retornam DOUBLE.

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

Funções agregadas

As funções agregadas calculam valores de resumo 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 devolve 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 funções agregadas nas expressões e funçõ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 cadeia.

Listar funções

As funções de lista permitem-lhe trabalhar com listas, como verificar o comprimento ou o tamanho do corte.

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

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

Funções gráficas

As funções de gráfico 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 mais informações sobre funções de grafo, veja expressões e funções GQL.

Funções temporais

As funções temporais permitem trabalhar 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 mais informações sobre funções temporais, consulte expressões e funções GQL.

Funções genéricas

As funções genéricas permitem-lhe trabalhar com dados de formas 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 mais informações sobre funções genéricas, veja expressões e funções GQL.

Exemplos orientados por tarefas

Use os artigos práticos quando precisar de padrões de consulta completos e prontos a adaptar:

Conteúdo relacionado

  • Last updated on