Guia da linguagem GQL para grafos no Microsoft Fabric

GQL (Graph Query Language) é a linguagem de consulta padronizada pela ISO para bases de dados de grafos. Use o GQL para consultar, analisar e trabalhar com dados de grafos de forma eficiente através do gráfico no Microsoft Fabric.

O mesmo grupo de trabalho ISO que padroniza o SQL desenvolve o GQL. Como resultado, o GQL partilha muitos conceitos com o SQL, incluindo expressões, predicados e tipos de dados. Se tiveres experiência em SQL, podes aplicar grande parte desse conhecimento ao GQL.

Este artigo é o guia completo de GQL em gráficos. Explica como a linguagem se encaixa e liga a referências focadas para detalhes completos da sintaxe e do tipo. Cobre:

  • Conceitos fundamentais: Estruturas de dados de grafos, padrões e fundamentos de consultas
  • Afirmações essenciais: MATCH, FILTER, LET, WHEN, ORDER BY, LIMIT, e RETURN
  • Tipos de dados e expressões: Tipos de valor, operadores e funções incorporadas
  • Técnicas avançadas: composição multi-afirmações, escopo de variáveis e estratégias de agregação

Observação

A norma internacional oficial para GQL é a ISO/IEC 39075 Information Technology - Database Languages - GQL.

Se procura orientação orientada para tarefas em vez de um guia linguístico, veja os guias práticos:

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

Informações obrigatórias Artigo definitivo
Sintaxe num olhar Referência rápida GQL
Sintaxe de composição de nós, arestas, caminhos e padrões Padrões de grafos GQL
Operadores, predicados e funções Expressões, predicados e funções GQL
Sintaxe literal, comportamento de valores e conversões de tipos Valores GQL e tipos de valor
Definições e restrições de tipos de grafo Tipos de gráficos GQL
Cobertura atual de funcionalidades ISO GQL Conformidade com a norma GQL
Restrições e limites atuais específicos da Fabric Limitações atuais

Pré-requisitos

Antes de começar, certifique-se de que está familiarizado com estes conceitos:

  • Compreensão básica de bases de dados - Experiência com qualquer sistema de base de dados como relacional (SQL), NoSQL ou grafo é útil.
  • Conceitos de grafos - Compreensão de nós, arestas e relações em dados ligados.
  • Fundamentos das consultas - Conhecimento de conceitos básicos de consultas como filtragem, ordenação e agregação.

Antecedentes recomendados:

  • A experiência com linguagens SQL ou openCypher torna a aprendizagem da sintaxe GQL mais fácil (são as raízes do GQL).
  • A familiaridade com modelação de dados ajuda no desenho de esquemas de grafos.
  • Compreensão do seu caso de uso específico para dados de grafos.

O que precisa:

  • Acesso a um espaço de trabalho de grafos com capacidades de consulta.
  • Exemplos de dados ou disposição para trabalhar com as nossas redes sociais.
  • Editor de texto básico para escrever consultas.

Sugestão

Se você é novo em bancos de dados gráficos, comece com a visão geral dos modelos de dados gráficos antes de continuar com este guia.

O que torna a GQL especial

O GQL foi concebido especificamente para dados de grafos, pelo que a sua sintaxe expressa diretamente como as entidades estão conectadas. Enquanto o SQL normalmente expressa relações através de joins entre tabelas, o GQL utiliza padrões de grafos que se assemelham a diagramas dos dados.

Por exemplo, a consulta seguinte encontra pares de pessoas que se conhecem e que 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 da relação para corresponder. As variáveis associam as duas pessoas para que a consulta possa filtrar e devolver as suas propriedades.

Fundamentos do GQL

Estes conceitos formam a base do GQL:

  • Os 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 permitidas num grafo.
  • As consultas utilizam instruções como MATCH, FILTER, e RETURN para processar dados e produzir resultados.
  • Os padrões descrevem as estruturas dos grafos para corresponder.
  • As 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 as consultas podem processar e as propriedades do grafo podem armazenar.

Compreender dados de grafos

Para trabalhar com GQL, é necessário compreender a estrutura de grafo de propriedades rotulada que a linguagem consulta.

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

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

  • Os nós normalmente representam entidades, como pessoas, organizações, publicações ou produtos.
  • As arestas representam ligações entre nós, como uma pessoa conhecer outra pessoa ou trabalhar numa empresa.

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

Cada aresta liga 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 ligar uma Person origem a um Company alvo.

Observação

O Graph atualmente não suporta a criação de arestas não direcionadas. Pode consultar uma aresta dirigida existente em qualquer direção usando um padrão de arestas qualquer dirigido, como -[:knows]-.

Os grafos são bem formados: cada aresta liga dois nós que existem no mesmo grafo.

Modelos e tipos de gráficos

Um modelo de grafo Fabric define os tipos de nós, tipos de arestas, propriedades, mapeamentos de origem e chaves disponíveis num grafo. Especifica quais as linhas da tabela de origem que se tornam nós e arestas e como esses elementos se ligam. Para orientações de modelação, veja Desenhar um esquema de grafo.

O padrão GQL utiliza 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 ao nível da linguagem à estrutura representada por um modelo de grafo Fabric, mas o Grafo atualmente não aceita declarações de tipo grafo GQL diretamente. Para a sintaxe formal e conceitos, veja tipos de grafos GQL.

Exemplo de grafo usado neste guia

Exemplos utilizam o conjunto de dados de amostras das redes sociais, que inclui pessoas, lugares, organizações, mensagens, etiquetas e as arestas que os ligam.

O grafo de exemplo liga estas á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.
  • Os fóruns contêm publicações, e as pessoas criam publicações e comentários.
  • As etiquetas categorizam o conteúdo e representam os interesses das pessoas.

Diagrama mostrando o esquema de rede social.

Para a estrutura completa do exemplo, veja o exemplo do esquema das redes sociais. Para conceitos gerais de grafos, veja Grafos de propriedades rotulados.

Suas primeiras consultas GQL

Agora que você entende noções básicas de gráficos, vamos ver como consultar dados de gráficos usando GQL. Estes exemplos são construídos de simples a complexos, mostrando como a abordagem do GQL torna as consultas gráficas intuitivas e poderosas.

Comece simples: encontre todas as pessoas

Comece pela pergunta mais básica possível. Encontre os nomes (primeiro nome, apelido) de todas as pessoas (:Personpessoas) no gráfico.

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

Esta consulta funciona da seguinte forma:

  1. MATCH encontra todos os nós rotulados Person.
  2. RETURN mostra o primeiro e o apelido deles.

Adicionar filtragem: encontrar pessoas específicas

Agora encontra pessoas com características específicas. Neste caso, encontra toda a gente chamada Alice e mostra os seus nomes e datas de nascimento.

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

Esta consulta funciona da seguinte forma:

  1. MATCH encontra todos os nós (p) rotulados como Pessoa.
  2. FILTER nós (p) cujo primeiro nome é Alice.
  3. RETURN Mostra o seu próprio, apelido e data de nascimento.

Estrutura de consulta básica

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

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

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

Esta consulta funciona da seguinte forma:

  1. MATCH encontra todos os pares de Person nós que se conhecem.
  2. FILTER Fica apenas com os pares em que ambas as pessoas têm o mesmo aniversário.
  3. RETURN Conta quantos pares de amigos assim existem.

Sugestão

Também pode filtrar diretamente num padrão acrescentando uma WHERE cláusula. Por exemplo, MATCH (n:Person WHERE n.birthday < 19900101) corresponde apenas Person a nós com um birthday valor anterior a 1990.

O GQL suporta comentários de linha no estilo // C, comentários de linha no estilo -- SQL e comentários em bloco no estilo /* */ C.

Afirmações comuns

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

Como as declarações funcionam juntas

As instruções GQL formam um pipeline, onde cada instrução processa a saída da anterior. Esta 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 executam-se efetivamente sequencialmente.
  • Cada instrução transforma dados e passa-os para a seguinte.
  • Este 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 fase seguinte.
  • UNION, UNION DISTINCT, e UNION ALL combinam os resultados dos blocos completos de consulta.

Observação

As instruções têm uma ordem lógica definida. Escreva consultas de acordo com este fluxo de dados em vez de depender de uma estratégia física específica.

Exemplo de composição de enunciado

A consulta GQL seguinte encontra as primeiras 10 pessoas a trabalhar em empresas com "Air" no nome, ordena-as pelo nome completo e devolve o nome completo juntamente com o nome das suas 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

Esta consulta funciona da seguinte forma:

  1. MATCH Encontra pessoas que trabalham em empresas.
  2. LET cria nomes completos combinando nomes próprios e apelidos.
  3. FILTER mantém apenas os funcionários das empresas com "Air" no nome da empresa.
  4. ORDER BY Ordena pelo nome completo.
  5. LIMIT Tira os primeiros 10 resultados.
  6. RETURN Devolve nomes completos e nomes das empresas.

As variáveis conectam seus dados

Variáveis, como p, c, e fullName nos exemplos anteriores, transportam dados entre sentenças. Quando você reutiliza um nome de variável, o GQL garante automaticamente que ele se refira aos mesmos dados, criando condições de junção poderosas. Às vezes, as variáveis também são chamadas de variáveis de ligação.

Pode categorizar variáveis de diferentes formas:

Por fonte de ligação:

  • Variáveis de padrão - ligadas por padrões gráficos correspondentes
  • Variáveis regulares - ligadas por outros constructos linguísticos

Tipos de variáveis padrão:

  • Variáveis de elemento - ligar aos valores de referência do elemento gráfico
    • Variáveis de nó - ligam-se a nós individuais
    • Variáveis de borda - vincular-se a bordas individuais
  • Variáveis de caminho - vinculam-se a valores de caminho que representam caminhos correspondentes

Por grau de referência:

  • Variáveis singleton - ligam-se a valores de referência de elementos individuais a partir de padrões
  • Variáveis de grupo - associar a listas de valores de referência de elementos a partir de padrões de comprimento variável. Para mais detalhes, veja Funções agregadas.

Resultados e resultados da execução

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

  • Um resultado, normalmente uma tabela de resultados com os dados da sua RETURN declaração.
  • Informação de estado que mostra se a consulta teve sucesso 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 nome de coluna preferencial a ser usada para exibir resultados, se a tabela está ordenada e as próprias linhas reais.

Observação

Se a execução falhar, nenhuma tabela de resultados é incluída no resultado da execução.

Resultados omitidos

O GQL também define um resultado omitido para afirmações que nunca produzem linhas, independentemente dos dados ou do resultado da avaliação. Um resultado omitido tem código 00001de estado 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 .

As 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 de consulta atuais produzem resultados de tabelas, incluindo tabelas vazias.

Informações de status

Durante a execução da consulta, o processo deteta várias condições relevantes, como erros ou avisos. Cada condição é registada por um objeto de estado na informação de estado do resultado da execução.

A informação de estado consiste num objeto de estado primário e numa lista (possivelmente vazia) de outros objetos de estado. O objeto de estado primário existe sempre e indica se a execução da consulta foi bem-sucedida ou falhou.

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

A API de Consulta utiliza os seguintes códigos de estado primários:

Código de estado da API Meaning
00000 Conclusão bem-sucedida com pelo menos uma carreira.
00001 Conclusão bem-sucedida com resultado omitido. Reservado para futuros suportes DDL e DML.
01000 Um aviso ou condição informativa.
02000 Atualmente, não existem linhas disponíveis a partir de uma consulta de produção de linhas.
42000 Um erro de consulta corrigível pelo utilizador.
50000 Um erro do sistema ou não classificado.

A API preserva o GQLSTATUS canónico reportado pelo motor de consulta no _graphaneGqlStatus membro do registo de 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 .

Importante

No código da aplicação, use status.code para sucesso amplo e gestão de erros. Use o diagnóstico canónico GQLSTATUS quando precisar de distinguir uma condição específica de consulta. Não teste o texto da descrição porque pode variar.

Além disso, os objetos de estado podem conter um objeto de estado de causa subjacente e um registo de diagnóstico com informação adicional que caracteriza a condição registada.

Consulte a referência dos códigos de estado GQL

Conceitos e enunciados essenciais

Esta seção aborda os principais blocos de construção que você precisa para escrever consultas GQL eficazes. Cada conceito se baseia em habilidades práticas de escrita de consultas.

Padrões de gráficos: encontrar estrutura

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

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

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

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

Reutilizar uma variável para exigir duas posições de padrão para ligar o mesmo elemento. Separar 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.

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

Modo de trajecto Comportamento
WALK Permite nós e arestas repetidos. Este modo é o padrão.
TRAIL Previne arestas repetidas.
SIMPLE Previne a repetição de nós, exceto um primeiro e último nós partilhados.
ACYCLIC Previne todos os nós repetidos.

Um prefixo de pesquisa de caminho controla quais os caminhos correspondentes que são devolvidos. ALL é o padrão. ANY SHORTEST devolve 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

Os predicados inline limitam a elegibilidade do caminho antes da seleção do caminho. Operações ao nível MATCH ... WHERE da instrução e posteriores FILTER são pós-filtros. Esta distinção pode alterar ANY SHORTEST os resultados.

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

Principais declarações

O GQL fornece tipos de instruções específicos que trabalham juntos para processar os dados do gráfico passo a passo. Compreender essas declarações é essencial para criar consultas eficazes.

Declaração MATCH

Sintaxe:

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

A MATCH instrução recebe dados de entrada e encontra padrões de grafos. Junta variáveis de entrada com variáveis de padrão e produz 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 ao nível da instrução usando ONDE:

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

Pode filtrar todos os matches WHEREusando . Esta abordagem evita uma declaração separada FILTER . Com um prefixo de pesquisa de caminho como ANY SHORTEST, o nível WHERE da instrução aplica-se após a seleção do caminho. Os predicados em linha, em vez disso, restringem quais caminhos são elegíveis para seleção. Para mais informações, veja Colocar predicados antes ou depois da seleção do caminho.

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

Importante

O Graph suporta composição básica e completa de instruções lineares, incluindo NEXT. Também pode combinar blocos de consulta com UNION, UNION DISTINCT, e UNION ALL. As EXCEPToperações , INTERSECT, e OTHERWISE set ainda não são suportadas. Para mais informações, consulte o artigo sobre limitações atuais.

Principais comportamentos de junção:

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

  • Igualdade de variáveis: As variáveis de entrada juntam-se às variáveis do padrão usando a correspondência de igualdade
  • Junção interna: As linhas de entrada sem correspondências de padrões são descartadas. Use OPTIONAL MATCH para comportamento de junção à esquerda para fora.
  • Ordem de filtragem: Filtros ao nível WHERE da instrução após correspondência de padrões e seleção de caminho concluída
  • Composição do padrão: Variáveis partilhadas limitam os padrões ao mesmo elemento. Padrões desconexos formam um produto cartesiano.

Importante

Um padrão desconectado é válido, mas o seu produto cartesiano pode criar muitas linhas. Use variáveis partilhadas quando os padrões devem referir-se aos mesmos elementos do grafo.

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

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

Declaração OPTIONAL MATCH

Sintaxe:

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

OPTIONAL MATCH Funciona como, MATCH mas usa semântica de junção à esquerda. Se o padrão não encontrar correspondência para uma linha de entrada, a consulta mantém a linha com NULL valores para variáveis não correspondidas em vez de a descartar.

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

Pessoas que não trabalham em nenhuma empresa continuam a aparecer nos resultados com NULL para company_name.

Sugestão

Use OPTIONAL MATCH quando quiser incluir entidades que possam não ter uma relação específica, semelhante a um SQL LEFT JOIN.

Declaração LET

Sintaxe:

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

A LET instrução cria variáveis computadas e permite a transformação de dados dentro do pipeline de consulta.

Criação de variáveis básicas:

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 motor de consulta avalia expressões para cada linha de entrada.
  • Os resultados tornam-se novas colunas na tabela de saída.
  • As variáveis só podem referenciar variáveis existentes a partir de instruções anteriores.
  • Múltiplas atribuições numa LET instrução usam o mesmo âmbito de entrada, por isso uma atribuição não pode referenciar outra atribuição a partir dessa instrução.

Declaração FOR

Sintaxe:

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

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

Use WITH OFFSET para ligar 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

Esta consulta devolve uma linha para cada cidade. Os position valores são 1, 2, e 3. Se 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 com que a consulta falhe.

Declaraçã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 âmbito estão implicitamente disponíveis dentro da subconsulta. Das variáveis criadas dentro da subconsulta, apenas colunas da sua instrução final RETURN ficam disponíveis fora dela. As variáveis criadas dentro da subquery mas não devolvidas 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 atua como uma junção interior dependente. Produz uma linha de saída para cada linha devolvida pela subconsulta. Se a subconsulta não devolver linhas, a linha exterior correspondente não é devolvida. Se devolver várias linhas, a linha exterior aparece uma vez para cada linha de subconsulta.

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

Usar OPTIONAL CALL como uma união dependente à esquerda. Quando a subconsulta não devolve linhas, preserva uma linha exterior e define as colunas da subconsulta devolvidas para NULL. Quando a subconsulta devolve várias linhas, 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

Podes criar subconsultas inline CALL . Uma subconsulta aninhada pode referenciar variáveis a partir dos seus escopos de consulta envolventes.

Importante

Termine cada corpo em linha CALL com RETURN. O Graph não suporta chamadas de procedimentos nomeadas nem listas explícitas de importação de variáveis como CALL (p) { ... }.

Declaração FILTER

Sintaxe:

FILTER [ WHERE ] <predicate>

A FILTER instrução fornece controle preciso sobre quais dados prosseguem através 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 estes padrões para manipular valores nulos com segurança:

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

Atenção

Lembre-se de que as condições que envolvem valores nulos retornam UNKNOWN, o que filtra essas linhas. Use verificações explícitas IS NULL quando precisar de lógica de inclusão nula.

Declaraçã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:

Compreender como ORDER BY funciona:

  • O motor de consulta avalia expressões para cada linha e depois os resultados determinam a ordem das linhas.
  • Múltiplas chaves de ordenação criam ordenação hierárquica (primária, secundária, terciária, e assim por diante).
  • NULLS FIRST coloca os valores nulos antes dos valores não nulos. NULLS LAST coloca-os após valores não nulos.
  • A colocação nula é independente da direção de ordenação. Se não especificares a ordem nula, NULLS LAST é o padrão para ambos ASC , e DESCpara .
  • ASC (ascendente) é a ordem padrão, e deve especificar DESC explicitamente (descendente).
  • Podes ordenar por valores calculados, não apenas por propriedades armazenadas.
Especificação de ordenação Ordem resultante
ASC ou ASC NULLS LAST Valores não nulos em ordem crescente, seguidos de valores nulos.
ASC NULLS FIRST Valores nulos, seguidos de valores não nulos por ordem crescente.
DESC ou DESC NULLS LAST Valores não nulos por ordem decrescente, seguidos de valores nulos.
DESC NULLS FIRST Valores nulos, seguidos de valores não nulos por ordem decrescente.

Atenção

Só a instrução imediatamente seguinte pode ver a ordem de ordenação que ORDER BY estabelece. Portanto, ORDER BY seguido de RETURN * não produz um resultado ordenado.

Compare:

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

Por:

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

Esta diferença tem consequências imediatas para consultas "Top-k": LIMIT deve sempre seguir a ORDER BY instrução que estabelece a ordem de ordenação pretendida.

OFFSET e LIMIT declarações

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

Importante

Para resultados de paginação previsíveis, use ORDER BY sempre antes OFFSET e LIMIT para garantir uma ordenação de linha consistente nas consultas.

RETURN: projeção básica de resultados

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

Manipulação de duplicados 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

Combinar com agregação:

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

RETURN com GROUP BY: projeção de resultados agrupados

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 calcular funções agregadas dentro de 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

Observação

Para agregação horizontal sobre padrões de comprimento variável, veja Funções agregadas.

Valores e tipos de valor

Os valores GQL incluem Booleano, string, numérico, temporal, lista, nó, aresta, caminho, nulo e nada. Os tipos são anuláveis, a menos que 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. As operações numéricas podem aplicar conversões implícitas entre tipos numéricos compatíveis.

Observação

Nem todos os tipos de valor GQL são suportados em todos os contextos de grafo. Para restrições atuais de propriedades e consultas, veja Tipos de dados.

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

Expressions

As 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

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

Agregam funções como COUNT, SUM, AVG, MIN, e MAX resumem linhas. Lista predicados como ALL, ANY, , NONEe SINGLE avalia um predicado para elementos de lista. Subconsultas de formulário EXISTS de procedimento testam se uma consulta aninhada devolve 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 sofisticadas para a criação de consultas gráficas complexas e eficientes. Esses padrões vão além do uso básico de instruções para ajudá-lo a compor consultas analíticas poderosas.

Composição complexa de múltiplas instruções

Importante

O Graph suporta composição básica e completa de instruções lineares. As EXCEPToperações , INTERSECT, e OTHERWISE set ainda não são suportadas. Para mais informações, consulte o artigo sobre limitações atuais.

Compreender como compor consultas complexas de forma eficiente é crucial para consultas gráficas avançadas.

UNION e UNION ALL

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

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

Cada bloco de consulta deve devolver 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 fase de consulta contra a tabela devolvida pela etapa anterior:

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

A consulta seguinte encontra os colaboradores e as suas empresas, e depois utiliza os nós de colaboradores devolvidos noutra 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 devolvidas pelo estágio anterior estão no âmbito após NEXT. Pode usar múltiplos NEXT separadores para construir uma sequência mais longa de estágios de consulta.

Qualquer etapa pode conter uma união de blocos de consulta. Uma união é avaliada dentro do seu estágio antes de a saída do estágio cruzar o NEXT limite. 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 grupos como A NEXT (B UNION C).

Instruções condicionais

Use uma instrução condicional para encaminhar 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 encaminhar linhas de uma fase de consulta anterior, devolve 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 motor de consulta avalia os predicados por ordem para cada linha de entrada. Um predicado que avalia ou FALSEUNKNOWN não seleciona o seu ramo. Depois de um predicado avaliar para TRUE, predicados posteriores e corpos de ramos não selecionados não são avaliados. Se nenhum predicado avalia e TRUE não ELSEhouver , a linha de entrada não é devolvida.

Predicados e corpos de ramificação podem referenciar colunas do estágio anterior. Um ramo pode ser uma única instrução linear ou um procedimento aninhado encerrado em colchetes. Use um procedimento aninhado quando um ramo necessita 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 o seu próprio âmbito local. Ramos irmãos não veem variáveis criadas por outro ramo, e apenas as colunas do ramo final RETURN selecionado continuam após a instrução condicional. Cada ramo deve devolver os mesmos nomes de colunas, e os tipos de resultados correspondentes devem ser compatíveis. O motor de consulta obriga tipos compatíveis a um tipo de saída comum. Uma coluna de ramo retornada pode usar o mesmo nome de uma coluna de entrada; o valor de ramo substitui o valor de entrada na saída condicional.

As sentenças condicionais são diferentes das 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 permitem travessias gráficas complexas. Compreender as regras de escopo avançadas ajuda você a escrever consultas sofisticadas de várias instruções.

Padrões de ligação e definição de variáveis

-- 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áveis para joins 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 críticas de âmbito 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

Atenção

As variáveis na mesma instrução não podem referenciar-se umas às outras, exceto em padrões de grafos. Use instruções separadas para a criação de variáveis dependentes.

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 coleção e encaminhamento 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 em falta necessitem de 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 retém. Usa coalesce() quando precisares de um valor de reserva.

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

Palavras reservadas

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

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

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

  • Para identificadores de uma única palavra, acrescente um sublinhado: :Product_
  • Para identificadores multipalavras, use camelCase ou PascalCase: :MyEntity, :hasAttribute, textColor

Próximos passos

Conteúdo relacionado

  • Last updated on