Partilhar via

Referência rápida do GQL

Observação

Esta funcionalidade está atualmente em pré-visualização pública. Essa visualização é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

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

Importante

Este artigo utiliza exclusivamente o conjunto de dados gráfico de exemplo de redes sociais.

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 especificando o padrão gráfico a ser correspondido e, em seguida, usa instruções opcionais para criação de variáveis, filtragem, classificação, paginação e saída 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

Ordem do extrato:

Importante

O gráfico no Microsoft Fabric ainda não oferece suporte à composição de instrução arbitrária. Veja o artigo sobre as limitações atuais.

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

  • MATCH – Especifique padrões gráficos para encontrar.
  • LET – Definir variáveis a partir de expressões.
  • FILTER – Mantenha as linhas correspondendo às condições.
  • ORDER BY – Ordenar resultados.
  • OFFSET – Pule muitas linhas.
  • LIMIT – Restringir o número de linhas.
  • RETURN – Produzir os resultados finais.

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

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

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

FILTRAR

Mantenha linhas que correspondam à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 idiomas GQL.

ORDENAR POR

Ordene 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ó é 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>
...

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

Padrões gráficos

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

Padrões de nó

Em bancos de dados gráficos, os nós geralmente são usados para representar entidades, como pessoas, produtos ou lugares.

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 rótulo permitem fazer a correspondência de 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 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]->()                 -- Binding a path variable

Para obter mais informações sobre padrões de caminho, consulte Padrões de gráfico.

Vários padrões

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

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

Tipos de valores 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 GQL e nos 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

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

Tipos materiais e anuláveis

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

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

Expressões & operadores

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

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

Arithmetic

Os operadores aritméticos realizam cálculos em números.

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

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

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

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

Funções

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

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)               -- 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 funções de cadeia de caracteres nas expressões e funções GQL.

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

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

Saiba mais sobre as funções gráficas nas expressões e funções GQL.

Funções temporais

As funções temporais permitem trabalhar com valores de data e hora.

zoned_datetime()               -- Get the current timestamp

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

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

Padrões comuns

Encontrar 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

Topo 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

Percurso transversal

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