Guia de linguagem GQL para grafo no Microsoft Fabric

GQL (Graph Query Language) é a linguagem de consulta padronizada por ISO para bancos de dados de grafo. Use o GQL para consultar, analisar e trabalhar com dados de grafo com eficiência com o grafo no Microsoft Fabric.

O mesmo grupo de trabalho ISO que padroniza o SQL desenvolve o GQL. Como resultado, a GQL compartilha muitos conceitos com SQL, incluindo expressões, predicados e tipos de dados. Se você tiver experiência com SQL, poderá aplicar grande parte desse conhecimento à GQL.

Este artigo é o guia completo para GQL em gráficos. Ele explica como a linguagem se encaixa e faz links para referências focadas para detalhes completos da sintaxe e do tipo. Isso abrange:

• Conceitos principais: estruturas de dados do Graph, padrões e conceitos básicos de consulta
• Afirmações essenciais:MATCH , FILTER, LET, WHEN, ORDER BY, LIMIT, , eRETURN
• Tipos de dados e expressões: tipos de valor, operadores e funções internas
• Técnicas avançadas: composição de várias instruções, escopo de variável e estratégias de agregação

Se você está procurando orientação orientada para tarefas em vez de um guia de idioma, veja os guias práticos:

• Escrever consultas GQL comuns — vizinhos, passagem de vários saltos, conexões compartilhadas e verificações de existência de entidade
• Filtrar e agregar dados de grafo — FILTER, WHERE, GROUP BY e funções de agregação
• Escrever consultas de padrão de grafo — padrões de vários saltos, modos de caminho, reutilização de variável e OPTIONAL MATCH
• Otimizar o desempenho da consulta GQL — estratégia de filtragem, limites de passagem e recomendações de restrição de chave

Use os artigos de referência focados quando precisar de detalhes completos:

Pré-requisitos

Antes de começar, verifique se você está familiarizado com estes conceitos:

• A compreensão de bancos de dados – a experiência com qualquer sistema de banco de dados, como SQL (relacional), NoSQL ou grafo, é útil.
• Conceitos de grafo – Noções básicas sobre nós, bordas e relações em dados conectados.
• Conceitos básicos de consulta – conhecimento de conceitos básicos de consulta, como filtragem, classificação e agregação.

Plano de fundo recomendado:

• A experiência com linguagens SQL ou openCypher facilita o aprendizado da sintaxe GQL (são raízes da GQL).
• A familiaridade com a modelagem de dados ajuda no design do esquema de grafo.
• Noções básicas sobre seu caso de uso específico para dados de grafo.

O que você precisa:

• Acesso a um workspace de grafo com recursos de consulta.
• Dados de exemplo ou disposição para trabalhar com nossos exemplos de rede social.
• Editor de texto básico para escrever consultas.

O que torna a GQL especial

O GQL foi projetado especificamente para dados de grafos, então sua sintaxe expressa diretamente como as entidades são conectadas. Enquanto o SQL comumente expressa relacionamentos por meio de joins entre tabelas, o GQL usa padrões de grafos que se assemelham a diagramas dos dados.

Por exemplo, a consulta a seguir encontra pares de pessoas que se conhecem e nasceram antes de 1999:

MATCH (person:Person)-[:knows]-(friend:Person)
WHERE person.birthday < 19990101
  AND friend.birthday < 19990101
RETURN person.firstName || ' ' || person.lastName AS person_name,
       friend.firstName || ' ' || friend.lastName AS friend_name

O padrão (person:Person)-[:knows]-(friend:Person) mostra a estrutura de relacionamento para corresponder. Variáveis vinculam as duas pessoas para que a consulta possa filtrar e devolver suas propriedades.

Conceitos básicos da GQL

Esses conceitos formam a base do GQL:

• Grafos contêm nós e arestas com rótulos e propriedades.
• Os tipos de grafo definem formalmente os tipos de nós, tipos de arestas e restrições permitidos em um grafo.
• Consultas usam instruções como MATCH, FILTER, e RETURN para processar dados e produzir resultados.
• Padrões descrevem as estruturas do grafo para corresponder.
• Expressões calculam, transformam e comparam valores.
• Predicados são expressões booleanas usadas para testar condições.
• Os tipos de valor definem os tipos de valores que consultas podem processar e propriedades de grafo podem armazenar.

Compreender dados de grafos

Para trabalhar com GQL, você precisa entender a estrutura do grafo de propriedades rotulados que a linguagem consulta.

Nós e bordas: os blocos de construção

Um grafo de propriedades rotulado contém dois tipos de elementos do grafo:

• Nós normalmente representam entidades, como pessoas, organizações, postagens ou produtos.
• Arestas representam conexões entre nós, como uma pessoa conhecendo outra pessoa ou trabalhando em uma empresa.

Todo elemento do grafo possui uma identidade interna, um ou mais rótulos e um conjunto de propriedades. Rótulos classificam elementos, como Person ou knows. Propriedades são pares nome-valor, como firstName: 'Alice' ou birthday: 19730108u. Em Graph, uma aresta sempre tem exatamente um rótulo.

Cada aresta conecta exatamente dois nós: uma origem e um alvo. A direção das arestas faz parte da estrutura do grafo. Por exemplo, uma workAt aresta pode conectar uma Person origem a um Company alvo.

Grafos são bem formados: cada aresta conecta dois nós que existem no mesmo grafo.

Modelos de grafo e tipos de grafo

Um modelo de grafo Fabric define os tipos de nós, tipos de arestas, propriedades, mapeamentos de origem e chaves disponíveis em um grafo. Ele especifica quais linhas de tabela de origem se tornam nós e arestas e como esses elementos se conectam. Para orientações de modelagem, veja Projete um esquema de grafo.

O padrão GQL usa um tipo de grafo para descrever formalmente tipos de nós permitidos, tipos de aresta, propriedades e restrições. Os tipos de grafo são o equivalente em nível de linguagem à estrutura representada por um modelo de grafo Fabric, mas o Grafo atualmente não aceita declarações do tipo grafo GQL diretamente. Para a sintaxe formal e conceitos, veja Tipos de grafos GQL.

Exemplo de gráfico usado neste guia

Exemplos usam o conjunto de dados de amostras de redes sociais, que inclui pessoas, lugares, organizações, mensagens, tags e as bordas que os conectam.

O grafo de exemplo conecta essas áreas:

• As pessoas conhecem outras pessoas, trabalham em empresas e estudam em universidades.
• Cidades, países ou regiões e continentes formam uma hierarquia geográfica.
• Fóruns contêm postagens, e as pessoas criam posts e comentários.
• Tags categorizam o conteúdo e representam os interesses das pessoas.

Para a estrutura completa do exemplo, veja o exemplo do esquema de rede social. Para conceitos gerais de grafos, veja Grafos de propriedades rotulados.

Suas primeiras consultas GQL

Agora que você entende as noções básicas do grafo, vamos ver como consultar dados de grafo usando GQL. Esses exemplos são compilados de simples a complexos, mostrando como a abordagem da GQL torna as consultas de grafo intuitivas e poderosas.

Inicie simples: localizar todas as pessoas

Comece com a consulta mais básica possível. Localize os nomes (nome, sobrenome) de todas as pessoas (:Persons) no grafo.

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

Essa consulta é executada da seguinte maneira:

1. MATCH localiza todos os nós rotulados Person.
2. RETURN mostra seus nomes e sobrenomes.

Adicionar filtragem: localizar pessoas específicas

Agora encontre pessoas com características específicas. Nesse caso, encontre todos chamados Alice e mostrem seus nomes e aniversários.

MATCH (p:Person)
FILTER p.firstName = 'Alice'
RETURN p.firstName, p.lastName, p.birthday

Essa consulta é executada da seguinte maneira:

1. MATCH localiza todos os nós (p) rotulados Pessoa.
2. FILTER nós (p) cujo nome é Alice.
3. RETURN mostra seu nome, sobrenome e aniversário.

Estrutura de consulta básica

Todas as consultas GQL básicas seguem um padrão consistente: uma sequência de instruções que funcionam em conjunto para localizar, filtrar e retornar dados. A maioria das consultas começa com MATCH para encontrar padrões no gráfico e termina com RETURN para especificar a saída.

Aqui está uma consulta simples que encontra pares de pessoas que se conhecem e compartilham o mesmo aniversário, e depois retorna a contagem total desses pares de amigos.

MATCH (n:Person)-[:knows]-(m:Person)
FILTER n.birthday = m.birthday
RETURN count(*) AS same_age_friends

Essa consulta é executada da seguinte maneira:

1. MATCH localiza todos os pares de Person nós que se conhecem.
2. FILTER mantém apenas os pares em que ambas as pessoas têm o mesmo aniversário.
3. RETURN conta quantos pares de amigos existem.

A GQL dá suporte a comentários de linha no estilo // C, comentários de linha no estilo -- SQL e comentários de bloco no estilo /* */ C.

Afirmações comuns

• MATCH: Identifica o padrão de gráfico a ser buscado — é aí que você define a estrutura dos dados que lhe interessam.
• LET: Atribui novas variáveis ou valores calculados com base em dados combinados — adiciona colunas derivadas ao resultado.
• FOR: Expande uma lista em linhas, com um deslocamento opcional baseado em zero ou posição ordinal baseada em um.
• CALL: Executa uma subconsulta inline para cada linha de entrada e adiciona as colunas retornadas pela subconsulta.
• FILTER: Reduz os resultados aplicando condições — remove linhas que não atendem aos critérios.
• ORDER BY: Ordena os dados filtrados — ajuda a organizar a saída com base em um ou mais campos.
• OFFSET e LIMIT: Restringa o número de linhas retornadas — útil para paginação ou consultas top-k.
• RETURN: Especifica a saída final — define quais dados devem ser incluídos no conjunto de resultados e realiza agregação.
• NEXT: Inicia outra etapa de consulta usando as colunas retornadas da etapa anterior.

Como as instruções funcionam em conjunto

As instruções GQL formam um pipeline, onde cada instrução processa a saída da anterior. Essa execução sequencial torna as consultas fáceis de ler e depurar porque a ordem de execução corresponde à ordem de leitura.

Pontos principais:

• As instruções são executadas efetivamente sequencialmente.
• Cada instrução transforma dados e os passa para a próxima.
• Esse processo cria um fluxo de dados claro e previsível que simplifica consultas complexas.
• NEXT Inicia uma nova fase de consulta. Apenas as colunas projetadas pela instrução anterior RETURN estão disponíveis na próxima etapa.
• UNION, UNION DISTINCT, e UNION ALL combinam os resultados dos blocos completos de consulta.

Exemplo de composição de instrução

A consulta a seguir da GQL encontra as 10 primeiras pessoas trabalhando em empresas com "Air" no nome, as classifica pelo nome completo e retorna o nome completo junto com o nome das empresas.

-- Data flows: Match → Let → Filter → Order → Limit → Return
MATCH (p:Person)-[:workAt]->(c:Company)           -- Input: unit table, Output: (p, c) table
LET fullName = p.firstName || ' ' || p.lastName   -- Input: (p, c) table, Output: (p, c, fullName) table
FILTER c.name CONTAINS 'Air'                      -- Input: (p, c, fullName) table, Output: filtered table
ORDER BY fullName                                 -- Input: filtered table, Output: sorted table
LIMIT 10                                          -- Input: sorted table, Output: top 10 rows table
RETURN fullName, c.name AS companyName            -- Input: top 10 rows table
                                                  -- Output: projected (fullName, companyName) result table

Essa consulta é executada da seguinte maneira:

1. MATCH Encontre pessoas que trabalham em empresas.
2. LET cria nomes completos combinando nomes de família e primeiro.
3. FILTER mantém apenas funcionários de empresas com "Air" no nome da empresa.
4. ORDER BY classifica por nome completo.
5. LIMIT obtém os primeiros 10 resultados.
6. RETURN Retorna nomes completos e nomes das empresas.

Variáveis conectam seus dados

Variáveis, como p, ce fullName nos exemplos anteriores, carregam dados entre instruções. Quando você reutiliza um nome de variável, a GQL garante automaticamente que ela se refira aos mesmos dados, criando condições de junção avançadas. Às vezes, as variáveis também são chamadas de variáveis de associação.

Você pode categorizar variáveis de diferentes maneiras:

Por origem da associação:

• Variáveis de padrão – associadas por padrões de grafo correspondentes
• Variáveis regulares - associadas por outros constructos de linguagem

Tipos de variável de padrão:

• Variáveis de elemento – associar a valores de referência de elemento de grafo
  • Variáveis de nó – associar a nós individuais
  • Variáveis de borda – associar a bordas individuais
• Variáveis de caminho – associar a valores de caminho que representam caminhos correspondentes

Por grau de referência:

• Variáveis singleton – associar a valores de referência de elemento individual de padrões
• Variáveis de grupo - vincular a listas de valores de referência de elementos de padrões de comprimento variável. Para detalhes, veja Funções agregadas.

Resultados e resultados de execução

Ao executar uma consulta, você obtém de volta um resultado de execução que consiste em:

• Um resultado, normalmente uma tabela de resultados com os dados da sua RETURN afirmação.
• Informações de status que mostram se a consulta foi bem-sucedida ou não.

Tabelas de resultados

A tabela de resultados - se presente - é o resultado real da execução da consulta.

Uma tabela de resultados inclui informações sobre o nome e o tipo de suas colunas, uma sequência de nomes de coluna preferencial a ser usada para exibir resultados, se a tabela é ordenada e as próprias linhas reais.

Resultados omitidos

O GQL também define um resultado omitido para instruções que nunca produzem linhas, independentemente dos dados ou do resultado da avaliação. Um resultado omitido tem código 00001de status de conclusão bem-sucedida .

Um resultado omitido difere de uma tabela de resultados vazia. Uma tabela vazia significa que uma consulta que gera linhas foi avaliada, mas não produziu linhas. A API de consulta pode representar um resultado omitido com o tipo NOTHINGde resultado .

Reservas de grafos omitiram resultados para suporte futuro a instruções de linguagem de definição de dados (DDL) e linguagem de manipulação de dados (DML). As instruções atuais de consulta produzem resultados de tabelas, incluindo tabelas vazias.

Informações de status

Durante a execução da consulta, o processo detecta várias condições notáveis, como erros ou avisos. Cada condição é registrada por um objeto de status nas informações de status do resultado da execução.

As informações de status consistem em um objeto de status primário e uma lista (possivelmente vazia) de outros objetos de status. O objeto de status primário sempre existe e indica se a execução da consulta foi bem-sucedida ou falhou.

Cada objeto de status inclui um código alfanumérico de cinco caracteres e uma descrição da condição registrada.

A API de consulta utiliza os seguintes códigos de status primários:

A API preserva o GQLSTATUS canônico reportado pelo mecanismo de consulta no _graphaneGqlStatus membro do registro diagnóstico. Por exemplo, o overflow numérico usa GQLSTATUS 22003canônico , enquanto a divisão por zero usa 22012; ambos são representados por 42000 no campo público status.code .

Além disso, os objetos de status podem conter um objeto de status de causa subjacente e um registro de diagnóstico com mais informações que caracterizam a condição registrada.

Conceitos e instruções essenciais

Esta seção aborda os principais blocos de construção necessários para escrever consultas GQL eficazes. Cada conceito se baseia em habilidades práticas de escrita de consulta.

Padrões de grafos: encontrar estrutura

Um padrão de grafo descreve os nós, arestas e caminhos a serem correspondidos. Vincular variáveis quando instruções posteriores precisam se referir a elementos combinados:

MATCH (person:Person)-[employment:workAt]->(company:Company)
RETURN person.firstName, company.name, employment.workFrom

Coloque um predicado em linha quando ele define qual nó ou aresta pode participar do padrão:

MATCH (person:Person WHERE person.firstName = 'Alice')
      -[:knows]->(friend:Person)
RETURN friend.firstName, friend.lastName

Reutilize uma variável para exigir duas posições de padrão para vincular o mesmo elemento. Separe padrões com vírgulas para compor estruturas de grafos maiores. Use um quantificador como {1,4} para repetir um padrão de arestas e corresponder caminhos de comprimento variável.

Modos de caminho controlam a reutilização de elementos dentro de um caminho:

Um prefixo de busca de caminho controla quais caminhos correspondentes são retornados. ALL é o padrão. ANY SHORTEST retorna um caminho mais curto para cada par fonte-destino:

MATCH path = ANY SHORTEST
  (source:Person WHERE source.id = 123u)-[:knows]->{1,4}(target:Person)
RETURN target.id, path_length(path) AS hopCount

Predicados inline limitam a elegibilidade de caminho antes da seleção de caminhos. Operações em nível MATCH ... WHERE de instrução e posteriores FILTER são pós-filtros. Essa distinção pode mudar ANY SHORTEST os resultados.

Para semântica definitiva de nó, aresta, caminho, composição, quantificador e posicionamento de predicados, veja padrões de grafos GQL. Para as restrições atuais de caminho, veja Limitações atuais.

Instruções principais

O GQL fornece tipos de instrução específicos que trabalham juntos para processar os dados do grafo passo a passo. Entender essas instruções é essencial para criar consultas efetivas.

Instrução MATCH

Sintaxe:

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

A MATCH instrução usa dados de entrada e localiza padrões de grafo. Ele une variáveis de entrada com variáveis padrão e gera todas as combinações correspondentes.

Variáveis de entrada e saída:

-- Input: unit table (no columns, one row)
-- Pattern variables: p, c  
-- Output: table with (p, c) columns for each person-company match
MATCH (p:Person)-[:workAt]->(c:Company)

Filtragem no nível da instrução usando WHERE:

-- Filter pattern matches
MATCH (p:Person)-[:workAt]->(c:Company) WHERE p.lastName = c.name

Você pode pós-filtrar todas as correspondências usando WHERE. Essa abordagem evita uma instrução separada FILTER . Com um prefixo de busca de caminho como ANY SHORTEST, o nível WHERE da instrução aplica-se após a seleção de caminhos. Predicados inline, por outro lado, restringem quais caminhos são elegíveis para seleção. Para mais informações, veja Colocar predicados antes ou depois da seleção de caminhos.

Junção usando variáveis de entrada:

Quando MATCH não é a primeira instrução, ela une dados de entrada com correspondências de padrão:

...
-- Input: table with 'targetCompany' column
-- Implicit join: targetCompany (equality join)
-- Output: table with (targetCompany, p, r) columns
MATCH (p:Person)-[r:workAt]->(targetCompany)

Comportamentos de junção de chave:

Como MATCH lida com a junção de dados:

• Igualdade variável: variáveis de entrada se unem a variáveis de padrão usando correspondência de igualdade
• Junção interna: linhas de entrada sem correspondências de padrão são descartadas. Use OPTIONAL MATCH para o comportamento de junção esquerda-externa.
• Ordem de filtragem: Filtros em nível WHERE de instrução após a correspondência de padrões e a seleção de caminho concluídas
• Composição do padrão: Variáveis compartilhadas restringem padrões ao mesmo elemento. Padrões desconectados formam um produto cartesiano.

Padrões de junção com variáveis compartilhadas:

-- Shared variable 'p' joins the two patterns
-- Output: people with both workplace and residence data
MATCH (p:Person)-[:workAt]->(c:Company), 
      (p)-[:isLocatedIn]->(city:City)

Instrução OPTIONAL MATCH

Sintaxe:

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

OPTIONAL MATCH funciona como MATCH , mas usa semântica de junção esquerda-externa. Se o padrão não encontrar correspondência para uma linha de entrada, a consulta manterá a linha com NULL valores para variáveis incompatíveis em vez de descartá-la.

Example:

-- Find all people and, if available, their workplace
MATCH (p:Person)
OPTIONAL MATCH (p)-[:workAt]->(c:Company)
RETURN p.firstName, p.lastName, c.name AS company_name

As pessoas que não trabalham em nenhuma empresa ainda aparecem nos resultados para NULLcompany_name.

Instrução LET

Sintaxe:

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

A LET instrução cria variáveis computadas e habilita a transformação de dados no pipeline de consulta.

Criação de variável básica:

MATCH (p:Person)
LET fullName = p.firstName || ' ' || p.lastName
RETURN *
LIMIT 1000

Cálculos complexos:

MATCH (p:Person)
LET adjustedAge = 2000 - (p.birthday / 10000),
    fullProfile = p.firstName || ' ' || p.lastName || ' (' || p.gender || ')'
RETURN *
LIMIT 1000

Principais comportamentos:

• O mecanismo de consulta avalia expressões para cada linha de entrada.
• Os resultados se tornam novas colunas na tabela de saída.
• As variáveis só podem referenciar variáveis existentes de instruções anteriores.
• Múltiplas atribuições em uma LET instrução usam o mesmo escopo de entrada, então uma atribuição não pode referenciar outra atribuição a partir dessa instrução.

Instrução FOR

Sintaxe:

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

A FOR declaração expande uma lista em linhas. Para cada linha de entrada, ela emite uma linha de saída para cada elemento da lista e vincula esse elemento à variável especificada. Outras variáveis da linha de entrada permanecem disponíveis.

Use WITH OFFSET para vincular um índice baseado em zero, ou para WITH ORDINALITY vincular uma posição baseada em um.

LET cities = ['Seattle', 'London', 'Tokyo']
FOR city IN cities WITH ORDINALITY position
RETURN city, position

Essa consulta retorna uma linha para cada cidade. Os position valores são 1, 2, e 3. Se você substituir WITH ORDINALITY position por WITH OFFSET position, os valores são 0, 1, e 2.

A expressão fonte deve ser avaliada para uma lista. Um valor não de lista faz a consulta falhar.

Instrução CALL

Use CALL para executar uma subconsulta inline para cada linha de entrada:

CALL {
  <query statements>
  RETURN <columns>
}

Variáveis que já estão no escopo estão implicitamente disponíveis dentro da subconsulta. Das variáveis criadas dentro da subconsulta, apenas colunas de sua instrução final RETURN ficam disponíveis fora dela. Variáveis criadas dentro da subconsulta, mas não retornadas, permanecem locais.

A seguinte subconsulta correlacionada calcula a contagem de empregadores para cada pessoa:

MATCH (p:Person)
CALL {
  MATCH (p)-[:workAt]->(company:Company)
  RETURN count(*) AS employerCount
}
RETURN p.firstName, p.lastName, employerCount
ORDER BY employerCount DESC

Um ordinário CALL age como uma junção interna dependente. Ele produz uma linha de saída para cada linha retornada pela subconsulta. Se a subconsulta não retorna linhas, a linha externa correspondente não é retornada. Se ele retorna várias linhas, a linha externa aparece uma vez para cada linha de subconsulta.

O exemplo anterior count(*) sempre retorna uma linha de subconsulta porque usa um agregado não agrupado. Uma pessoa sem empregador correspondente, portanto, tem um employerCount de 0.

Use OPTIONAL CALL como uma junção à esquerda dependente. Quando a subconsulta não retorna linhas, ela preserva uma linha externa e define as colunas da subconsulta retornadas para NULL. Quando a subconsulta retorna várias linhas, ela produz uma linha de saída para cada linha da subconsulta.

MATCH (p:Person)
OPTIONAL CALL {
  MATCH (p)-[:workAt]->(company:Company)
  RETURN company.name AS companyName
}
RETURN p.firstName, p.lastName, companyName

Você pode aninhar subconsultas inline CALL . Uma subconsulta aninhada pode referenciar variáveis a partir de seus escopos de consulta que contenham.

Instrução FILTER

Sintaxe:

FILTER [ WHERE ] <predicate>

A FILTER instrução fornece controle preciso sobre quais dados prossiga por meio do pipeline de consulta.

Filtragem básica:

MATCH (p:Person)
FILTER p.birthday < 19980101 AND p.gender = 'female'
RETURN *

Condições lógicas complexas:

MATCH (p:Person)
FILTER (p.gender = 'male' AND p.birthday < 19940101) 
  OR (p.gender = 'female' AND p.birthday < 19990101)
  OR p.browserUsed = 'Edge'
RETURN *

Padrões de filtragem com reconhecimento nulo:

Use esses padrões para lidar com valores nulos com segurança:

• Verifique se há valores: p.firstName IS NOT NULL – tem um nome
• Validar dados: p.id > 0 – ID válida
• Manipular dados ausentes: NOT coalesce(p.locationIP, '10.x.x.x') STARTS WITH '10.x.x.x' - não se conectou da rede local
• Combinar condições: usar AND/OR com verificações nulas explícitas para lógica complexa

Instrução ORDER BY

Sintaxe:

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

Classificação de vários níveis com expressões computadas:

MATCH (p:Person)
RETURN *
ORDER BY p.firstName DESC,               -- Primary: by first name (Z-A)
         p.birthday ASC,                 -- Secondary: by age (oldest first)
         p.id DESC                       -- Tertiary: by ID (highest first)

Tratamento nulo na classificação:

MATCH (p:Person)
RETURN p.firstName, p.birthday
ORDER BY p.birthday DESC NULLS LAST, p.firstName ASC

Detalhes do comportamento de classificação:

Noções básicas sobre como ORDER BY funciona:

• O mecanismo de consulta avalia expressões para cada linha e, em seguida, os resultados determinam a ordem da linha.
• Várias chaves de classificação criam ordenação hierárquica (primária, secundária, terciária e assim por diante).
• NULLS FIRST coloca valores nulos antes dos valores não nulos. NULLS LAST os coloca após valores não nulos.
• A colocação nula é independente da direção de ordenação. Se você não especificar ordem nula, NULLS LAST é o padrão para ambos ASC e DESC.
• ASC (crescente) é a ordem padrão e você deve especificar explicitamente (decrescente DESC ).
• Você pode classificar por valores calculados, não apenas propriedades armazenadas.

MATCH (a:Person)-[r:knows]->(b:Person)
LET aName = a.firstName || ' ' || a.lastName
LET bName = b.firstName || ' ' || b.lastName
ORDER BY r.creationDate DESC
/* intermediary result _IS_ guaranteed to be ordered here */
RETURN aName, bName, r.creationDate AS since
/* final result _IS_ _NOT_ guaranteed to be ordered here  */

MATCH (a:Person)-[r:knows]->(b:Person)
LET aName = a.firstName || ' ' || a.lastName
LET bName = b.firstName || ' ' || b.lastName
/* intermediary result _IS_ _NOT_ guaranteed to be ordered here */
RETURN aName, bName, r.creationDate AS since
ORDER BY r.creationDate DESC
/* final result _IS_ guaranteed to be ordered here              */

Instruções OFFSET e LIMIT

Sintaxe:

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

Padrões comuns:

-- Basic top-N query
MATCH (p:Person)
RETURN *
ORDER BY p.id DESC
LIMIT 10                                 -- Top 10 by ID

RETURN: projeção de resultado básico

Sintaxe:

RETURN [ DISTINCT ] <expression> [ AS <alias> ], <expression> [ AS <alias> ], ...
[ ORDER BY <expression> [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ], ... ]
[ OFFSET <offset> ]
[ LIMIT <limit> ]

A RETURN instrução produz a saída final da consulta especificando quais dados aparecem na tabela de resultados.

Saída básica:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName || ' ' || p.lastName AS name, 
       p.birthday, 
       c.name

Usando aliases para maior clareza:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName AS first_name, 
       p.lastName AS last_name,
       c.name AS company_name

Combine com classificação e top-k:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName || ' ' || p.lastName AS name, 
       p.birthday AS birth_year, 
       c.name AS company
ORDER BY birth_year ASC
LIMIT 10

Tratamento duplicado usando DISTINCT:

-- Remove duplicate combinations
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN DISTINCT p.gender, p.browserUsed, p.birthday AS birth_year
ORDER BY p.gender, p.browserUsed, birth_year

Combine com a agregação:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN count(DISTINCT p) AS employee_count

RETURN com GROUP BY: projeção de resultado agrupado

Sintaxe:

RETURN [ DISTINCT ] <expression> [ AS <alias> ], <expression> [ AS <alias> ], ...
GROUP BY <variable>, <variable>, ...
[ ORDER BY <expression> [ ASC | DESC ], <expression> [ ASC | DESC ], ... ]
[ OFFSET <offset> ]
[ LIMIT <limit> ]

Use GROUP BY para agrupar linhas por valores compartilhados e funções de agregação de computação em cada grupo.

Agrupamento básico com agregação:

MATCH (p:Person)-[:workAt]->(c:Company)
LET companyId = c.id, companyName = c.name
RETURN companyId,
       companyName,
       count(*) AS employeeCount,
       avg(p.birthday) AS avg_birth_year
GROUP BY companyId, companyName
ORDER BY employeeCount DESC

Agrupamento de várias colunas:

MATCH (p:Person)
LET gender = p.gender
LET browser = p.browserUsed
RETURN gender,
       browser,
       count(*) AS person_count,
       avg(p.birthday) AS avg_birth_year,
       min(p.creationDate) AS first_joined,
       max(p.id) AS highest_id
GROUP BY gender, browser
ORDER BY avg_birth_year DESC
LIMIT 10

Valores e tipos de valor

Os valores GQL incluem Booleano, string, numérico, temporal, lista, nó, borda, caminho, nulo e nada. Os tipos são nulláveis, a menos que você especifique NOT NULL. As propriedades utilizam um subconjunto suportado do sistema completo de valores de consulta.

RETURN 42 AS integerValue,
       'Alice' AS stringValue,
       TRUE AS booleanValue,
       [1, 2, 3] AS listValue

Comparações com nulo avaliam para UNKNOWN; usam IS NULL e IS NOT NULL para testes nulos. Operações numéricas podem aplicar conversões implícitas entre tipos numéricos compatíveis.

Para sintaxe literal, comportamento de comparação, conversões de tipos e hierarquia de tipos, veja valores GQL e tipos de valor.

Expressions

Expressões calculam, comparam, agregam e transformam valores. Formas comuns incluem referências de propriedades, operadores aritméticos e lógicos, predicados, chamadas de funções, expressões simples CASE e subconsultas:

MATCH (person:Person)
FILTER person.birthday < 19900101
RETURN person.firstName,
       CASE person.gender
         WHEN 'female' THEN 'F'
         WHEN 'male' THEN 'M'
         ELSE 'Other'
       END AS genderCode

GQL usa lógica de três valores: expressões booleanas podem avaliar para TRUE, FALSE, ou UNKNOWN. A FILTER mantém apenas linhas para as quais seu predicado é TRUE.

Agregar funções como COUNT, SUM, AVG, , MIN, e MAX resumir linhas. Liste predicados como ALL, ANY, , NONE, e SINGLE avalie um predicado para elementos de lista. Subconsultas de formulário EXISTS de procedimento testam se uma consulta aninhada retorna uma linha.

Para o comportamento completo de operadores, predicados, agregados e funções, veja expressões, predicados e funções GQL. Para exemplos de filtragem e agrupamento orientados a tarefas, veja Filtrar e agregar dados de grafos.

Técnicas avançadas de consulta

Esta seção aborda padrões e técnicas sofisticados para criar consultas de grafo complexas e eficientes. Esses padrões vão além do uso básico da instrução para ajudá-lo a compor consultas analíticas avançadas.

Composição multiestimulação complexa

Entender como compor consultas complexas com eficiência é crucial para consultas avançadas de grafo.

UNION e UNION ALL

Use UNION, UNION DISTINCT, ou UNION ALL para combinar resultados de dois ou mais blocos lineares de consulta:

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

-- Combine results from two separate pattern matches
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName AS name, c.name AS affiliation
UNION DISTINCT
MATCH (p:Person)-[:studyAt]->(u:University)
RETURN p.firstName AS name, u.name AS affiliation

Sem UNION é equivalente a UNION DISTINCT; ambos removem linhas duplicadas. UNION ALL mantém todas as linhas, incluindo duplicatas.

Cada bloco de consulta deve retornar o mesmo conjunto de nomes de colunas. A ordem das colunas pode variar entre blocos, e os tipos de dados devem ser compatíveis.

NEXT

Use NEXT para executar outra etapa de consulta contra a tabela retornada pela etapa anterior:

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

A consulta a seguir encontra funcionários e suas empresas, então usa os nós de funcionários retornados em outra correspondência de padrão:

MATCH (person:Person)-[:workAt]->(company:Company)
RETURN person, company.name AS companyName
NEXT
MATCH (person)-[:isLocatedIn]->(city:City)
RETURN person.firstName AS employee, companyName, city.name AS city

Apenas as colunas retornadas pelo estágio anterior estão no escopo após NEXT. Você pode usar múltiplos NEXT separadores para construir uma sequência mais longa de estágios de consulta.

Qualquer estágio pode conter uma união de blocos de consulta. Uma união é avaliada dentro de seu estágio antes que a saída do estágio cruze a NEXT fronteira. Se A, B, e C representam blocos de consulta, A UNION B NEXT C agrupa como (A UNION B) NEXT C, enquanto A NEXT B UNION C grupo como A NEXT (B UNION C).

Instruções de condição

Use uma instrução condicional para rotear cada linha de entrada para o primeiro ramo cujo predicado avalia para TRUE:

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

Para rotear linhas de uma etapa de consulta anterior, retorne as colunas necessárias e use NEXT antes da instrução condicional:

MATCH (p:Person)
RETURN p.firstName AS name, p.birthday AS birthday
NEXT
WHEN birthday < 19800101u THEN
  RETURN name, 'Before 1980' AS era
WHEN birthday < 20000101u THEN
  RETURN name, '1980-1999' AS era
ELSE
  RETURN name, '2000 or later' AS era

Cada WHEN predicado deve ser booleano. O mecanismo de consulta avalia os predicados em ordem para cada linha de entrada. Um predicado que avalia ou FALSEUNKNOWN não seleciona seu ramo. Após um predicado avaliar para TRUE, predicados posteriores e corpos de ramificação não selecionados não são avaliados. Se nenhum predicado avalia para TRUE e não ELSEhouver , a linha de entrada não é retornada.

Predicados e corpos de ramificação podem referenciar colunas do estágio anterior. Um branch pode ser uma única instrução linear ou um procedimento aninhado encerrado entre colchetes. Use um procedimento aninhado quando um branch precisar de múltiplas etapas ou instruções como CALL:

MATCH (p:Person)
RETURN p, p.firstName AS name
NEXT
WHEN p.gender = 'female' THEN {
  CALL {
    MATCH (p)-[:knows]->(friend:Person)
    RETURN count(*) AS friendCount
  }
  RETURN name, friendCount
}
ELSE
  RETURN name, 0u AS friendCount

Cada ramo tem seu próprio escopo local. Ramos irmãos não veem variáveis criadas por outro ramo, e apenas as colunas do ramo final RETURN do ramo selecionado continuam após a instrução condicional. Cada branch deve devolver os mesmos nomes de colunas, e os tipos de resultado correspondentes devem ser compatíveis. O motor de consulta coage tipos compatíveis a um tipo de saída comum. Uma coluna de ramificação retornada pode usar o mesmo nome de uma coluna de entrada; o valor de ramificação substitui o valor de entrada na saída condicional.

Sentenças condicionais são diferentes de CASE expressões. O Graph suporta expressões simples CASE <expression> WHEN <value>, mas não pesquisadas CASE WHEN <predicate> . Para mais informações, veja Expressões condicionais.

Escopo variável e controle de fluxo avançado

As variáveis conectam dados entre instruções de consulta e habilitam passagens de grafo complexas. Entender regras de escopo avançadas ajuda você a escrever consultas sofisticadas de várias instruções.

Padrões de associação e escopo de variável

-- Variables flow forward through subsequent statements 
MATCH (p:Person)                                    -- Bind p 
LET fullName = p.firstName || ' ' || p.lastName     -- Bind concatenation of p.firstName and p.lastName as fullName
FILTER fullName CONTAINS 'Smith'                    -- Filter for fullNames with “Smith” substring (p is still bound)
RETURN p.id, fullName                               -- Only return p.id and fullName (p is dropped from scope) 

Reutilização de variável para junções entre instruções

-- Multi-statement joins using variable reuse
MATCH (p:Person)-[:workAt]->(:Company)          -- Find people with jobs
MATCH (p)-[:isLocatedIn]->(:City)               -- Same p: people with both job and residence
MATCH (p)-[:knows]->(friend:Person)             -- Same p: their social connections
RETURN *

Regras de escopo críticas e limitações

-- ✅ Backward references work
MATCH (p:Person)
LET adult = p.birthday < 20061231  -- Can reference p from previous statement
RETURN *

-- ❌ Forward references don't work  
LET adult = p.birthday < 20061231  -- Error: p not yet defined
MATCH (p:Person)
RETURN *

-- ❌ Variables in same LET statement can't reference each other
MATCH (p:Person)
LET name = p.firstName || ' ' || p.lastName,
    greeting = 'Hello, ' || name     -- Error: name not visible yet
RETURN *

-- ✅ Use separate statements for dependent variables
MATCH (p:Person)
LET name = p.firstName || ' ' || p.lastName
LET greeting = 'Hello, ' || name     -- Works: name now available
RETURN *

Visibilidade variável em consultas complexas

-- Variables remain visible until overridden or query ends
MATCH (p:Person)                     -- p available from here
LET gender = p.gender                -- gender available from here  
MATCH (p)-[:knows]->(e:Person)       -- p still refers to original person
                                     -- e is a new variable for the friend
RETURN p.firstName AS manager, e.firstName AS friend, gender

Linhas agregadas e elementos de caminho

O GQL suporta dois contextos de agregação:

• A agregação vertical resume as linhas de entrada, opcionalmente particionadas por GROUP BY variáveis.
• A agregação horizontal resume uma lista de grupos limitada por um padrão de arestas de comprimento variável dentro de um caminho correspondente.

MATCH (person:Person)-[:workAt]->(company:Company)
LET companyId = company.id, companyName = company.name
RETURN companyId, companyName, count(*) AS employeeCount
GROUP BY companyId, companyName

MATCH (:Person)-[connections:knows]->{1,4}(:Person)
RETURN count(connections) AS pathLength

Para consultas agrupadas, filtros específicos de agregados, agregados de coleta e roteamento condicional, veja Filtrar e agregar dados de grafos. Para regras completas de resultados agregados, veja Funções agregadas.

Lidar com nulos e erros de consulta

Use testes nulos explícitos quando valores ausentes exigirem tratamento distinto:

MATCH (person:Person)
FILTER person.browserUsed IS NULL
RETURN person.firstName

Uma comparação com null avalia para UNKNOWN, que a FILTER não mantém. Use coalesce() quando precisar de um valor de reserva.

Os resultados das consultas incluem informações de status para sucesso, avisos, condições de ausência de dados, erros corrigíveis pelo usuário e erros do sistema. Use o código de status público para fluxo de controle amplo e o diagnóstico canônico GQLSTATUS para uma condição específica. Veja Resultados e resultados de execução e a referência aos códigos de status GQL.

Palavras reservadas

O GQL reserva determinadas palavras-chave que você não pode usar como identificadores, como variáveis, nomes de propriedade ou nomes de rótulo. Consulte a referência de palavras reservadas GQL para a lista completa.

Se você precisar usar palavras reservadas como identificadores, escape-as com backticks: `match`, `return`.

Para evitar o escape de palavras reservadas, use esta convenção de nomenclatura:

• Para identificadores de palavra única, acrescente um sublinhado: :Product_
• Para identificadores de várias palavras, use camelCase ou PascalCase: :MyEntity, , :hasAttributetextColor

Próximas etapas

• Siga o quickstart ou o tutorial do GQL para uma introdução prática.
• Use consultas GQL comuns de Write para tarefas prontas a adaptar em grafos.
• Use padrões de grafos GQL, expressões GQL, predicados e funções, e valores e tipos de valor GQL para referência detalhada.
• Use Design a Graph Schema para o fluxo de trabalho de modelagem Fabric suportado.

Conteúdo relacionado

• Referência rápida de GQL
• Conformidade com o padrão GQL
• API de consulta GQL
• Limitações atuais