Compartilhar via

Referência rápida de GQL

Observação

Esse recurso está atualmente em versão prévia pública. Essa versão prévia é oferecida sem um SLA e não é recomendada para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.

Este artigo é uma referência rápida da sintaxe GQL (Graph Query Language) para grafo no Microsoft Fabric. Para obter explicações detalhadas, consulte o guia de linguagem GQL.

Importante

Este artigo utiliza exclusivamente o conjunto de dados de exemplos de grafos de redes sociais.

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 e, em seguida, 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

Ordem da instrução:

Importante

O Graph no Microsoft Fabric ainda não dá suporte à composição de instrução arbitrária. Consulte o artigo sobre as limitações atuais.

As instruções geralmente podem aparecer em qualquer ordem em uma consulta:

  • MATCH – Especifique os padrões de grafo a serem encontrados.
  • LET – Definir variáveis de expressões.
  • FILTER – Manter as linhas correspondentes às condições.
  • ORDER BY – Classificar resultados.
  • OFFSET – Ignorar muitas linhas.
  • LIMIT – Restrinja o número de linhas.
  • RETURN – Gerar os resultados finais.

Cada instrução se baseia na anterior, de modo que você refina e formate incrementalmente a saída da 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.

FILTRO

Mantenha as 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

Classifique os resultados.

Sintaxe:

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

Example:

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

Importante

A ordem solicitada das linhas só garante que se mantenha imediatamente após uma instrução anterior ORDER BY . Quaisquer declarações seguintes (se estiverem presentes) não garantem 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.

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, os nós geralmente são usados 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]->()                 -- Binding a path variable

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

Vários padrões

Vários padrões permitem que você corresponda 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
BOOL             -- TRUE, FALSE, UNKNOWN
ZONED DATETIME   -- ZONED_DATETIME('2023-01-15T10:30:00Z')

Saiba mais sobre tipos básicos nos valores e tipos de valor GQL.

Tipos de valor de referência

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

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

Saiba mais sobre os tipos de valor de referência nos valores e tipos de valor GQL.

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

Saiba mais sobre os tipos de coleção nos valores e tipos de valor GQL.

Tipos materiais e anuláveis

Todo tipo de valor é nulo (incluindo o valor nulo) ou material (exclui-lo). Por padrão, os tipos são nuláveis, a menos que explicitamente especificados como NOT NULL.

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

& Operadores de Expressões

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                     -- Boolean logic

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

Arithmetic

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

+, -, *, /                       -- Basic arithmetic operations

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

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

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

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

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 values into a list

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)               -- Change case (US ASCII only)
trim(s)                          -- Remove leading and trailing whitespace
string_join(list, separator)     -- Join list elements with a separator

Saiba mais sobre as funções de cadeia de caracteres nas funções e expressões GQL.

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 be at most size `n`

Saiba mais sobre as funções de lista nas 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
nodes(path)                      -- Get path nodes
edges(path)                      -- Get path edges

Saiba mais sobre as funções de grafo nas funções e expressões GQL.

Funções temporais

As funções temporais permitem que você trabalhe com valores de data e hora.

zoned_datetime()               -- Get the current timestamp

Saiba mais sobre funções temporais nas 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

Saiba mais sobre funções genéricas nas funções e expressões GQL.

Padrões comuns

Localizar conexões

-- Friends of friends  
MATCH (me:Person {firstName: 'Annemarie'})-[:knows]->{2}(fof:Person)
WHERE fof <> me
RETURN DISTINCT fof.firstName

Aggregation

-- Count by group
MATCH (p:Person)-[:isLocatedIn]->(c:City)
RETURN c.name AS name, count(*) AS population
GROUP BY name
ORDER BY population DESC

Top k

-- Top 10
MATCH (p:Person)-[:hasCreator]-(m:Post)
RETURN p.firstName AS name, count(m) AS posts
GROUP BY name
ORDER BY posts DESC
LIMIT 10

Filtragem e condições

-- Complex conditions
MATCH (p:Person)-[:isLocatedIn]->(c:City)
WHERE p.birthday >= 19800101 AND p.birthday <= 20000101
  AND c.name IN ['Seattle', 'Portland']
  AND p.firstName IS NOT NULL
RETURN p.firstName, p.birthday

Passagem de caminho

-- Variable length paths
MATCH p = TRAIL (src:Person {firstName: 'Annemarie'})-[:knows]->{1,3}(dst:Person)
WHERE dst.firstName = 'Alexander'
RETURN p

Conteúdo relacionado

  • Last updated on