Guia de idioma GQL

Observação

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

A Linguagem de Consulta do Grafo GQL é a linguagem de consulta padronizada por ISO para bancos de dados de grafo. Ele ajuda você a consultar e trabalhar com dados de grafo com eficiência.

O GQL é desenvolvido pelo mesmo grupo de trabalho ISO que padroniza SQL, garantindo consistência e rigor. Se você está familiarizado com SQL, vai encontrar muitas semelhanças no GQL (expressões, predicados, tipos) - facilitando o começo. Este guia atende aos recém-chegados aprendendo conceitos básicos da GQL e usuários experientes que buscam técnicas avançadas e informações de referência abrangentes.

Observação

O Padrão Internacional oficial para GQL é a ISO/IEC 39075 Information Technology – Linguagens de Banco de Dados – GQL.

Pré-requisitos

Antes de mergulhar na GQL, você deve estar familiarizado com estes conceitos:

• Compreensão básica de bancos de dados - Experiência com qualquer sistema de banco de dados (como relacional (SQL), 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 dos 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 (elas são as raízes do 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ê precisará:

• Acesso ao Microsoft Fabric com funcionalidades de grafo
• Dados de exemplo ou disposição para trabalhar com nossos exemplos de rede social
• Editor de texto básico para escrever consultas

Dica

Se você não estiver familiarizado com bancos de dados de grafo, comece com a visão geral dos modelos de dados do grafo antes de continuar com este guia.

O que torna a GQL especial

O GQL foi projetado especificamente para dados de grafo. Isso torna natural e intuitivo trabalhar com informações conectadas.

Diferente do SQL, que depende de joins de tabelas para expressar relacionamentos, o GQL utiliza padrões visuais de grafos, que refletem diretamente como as entidades são conectadas, facilitando a leitura e a raciocínio das consultas.

Digamos que você queira encontrar pessoas e seus amigos (pessoas que se conhecem) que nasceram antes de 1999. Veja como a GQL expressa isso usando um padrão visual de gráfico:

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

Esta consulta encontra amigos (pessoas que se conhecem) que nasceram antes de 1999. O padrão (person:Person)-[:knows]-(friend:Person) mostra visualmente a estrutura de relação que você está procurando , assim como desenhar um diagrama de seus dados.

Conceitos básicos da GQL

Antes de se aprofundar em consultas, entenda estes conceitos fundamentais que formam a base da GQL:

• Grafos armazenam seus dados como nós (entidades) e arestas (relacionamentos), cada um com rótulos e propriedades
• Os tipos de grafo agem como esquemas, definindo quais nós e bordas podem existir em seu grafo
• Restrições são regras e restrições adicionais impostas pelos tipos de grafos em grafos para garantir a integridade dos dados
• As consultas usam instruções como MATCH, FILTERe RETURN para processar dados e mostrar resultados
• Os padrões descrevem as estruturas de grafo que você deseja encontrar usando a sintaxe visual intuitiva
• Expressões executam cálculos e comparações em seus dados, semelhantes às expressões SQL
• Predicados são expressões de valores booleanos usadas para filtrar resultados dentro de consultas
• Os tipos de valor definem quais tipos de valores você pode processar e armazenar

Noções básicas sobre dados do grafo

Para trabalhar efetivamente com a GQL, você precisa entender como os dados do grafo são estruturados. Essa base ajuda você a escrever consultas melhores e modelar seus dados com eficiência.

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

No GQL, você trabalha com grafos de propriedade rotulados. Um grafo consiste em dois tipos de elementos:

Os nós normalmente representam as entidades (os "substantivos") em seu sistema , coisas como pessoas, organizações, postagens ou produtos. São objetos independentes que existem em seu domínio. Os nós às vezes também são chamados de vértices.

As bordas representam relações entre entidades (os "verbos")— como suas entidades se conectam e interagem. Por exemplo, pessoas se conhecem (:knows), organizações que atuam em regiões específicas (:operates), ou clientes que compraram produtos (:purchased).
Às vezes, as bordas também são chamadas de relações.

Cada elemento de grafo tem estas características:

• Uma ID interna que a identifica exclusivamente
• Um ou mais rótulos — nomes descritivos como Person ou knows. No Microsoft Fabric, as arestas dos grafos sempre têm exatamente uma etiqueta.
• Propriedades — pares nome-valor que armazenam dados sobre o elemento (como firstName: "Alice" ou birthday: "19730108").

Como os grafos são estruturados

Cada borda conecta exatamente dois nós: uma origem e um destino. Essa conexão cria a estrutura do grafo e mostra como as entidades se relacionam entre si. A direção das bordas é importante — um Person que follows outro Person cria uma relação direcionada.

Observação

O Graph no Microsoft Fabric atualmente não suporta arestas não direcionadas.

Grafos de propriedades suportados no Microsoft Fabric são sempre bem formados, o que significa que cada aresta conecta dois nós válidos. Se você vir uma borda em um grafo, ambos os pontos de extremidade existirão no mesmo grafo.

Modelos de grafo e tipos de grafo

A estrutura de um grafo no Microsoft Fabric é descrita por seu modelo de grafo, que atua como um esquema de banco de dados para seu domínio de aplicativo. Os modelos de grafo definem:

• Quais nós e bordas podem existir
• Quais rótulos e propriedades eles podem ter
• Como nós e bordas podem se conectar

Os modelos de grafo também garantem a integridade dos dados por meio de restrições, especialmente restrições de chave de nó que especificam quais propriedades identificam exclusivamente cada nó.

Observação

Os modelos de grafo podem ser especificados usando a sintaxe padrão GQL, caso em que são chamados de tipos de grafo.

Um exemplo prático: rede social

Ao longo desta documentação, usamos um exemplo de rede social para ilustrar os conceitos da GQL. Entender esse domínio ajuda você a seguir os exemplos e aplicar padrões semelhantes aos seus próprios dados.

Observação

O exemplo da rede social é derivado do LDBC SNB (LDBC Social Network Benchmark) publicado pelo GDC (Graph Data Council). Consulte o artigo "O LDBC Social Network Benchmark" para obter mais detalhes.

As entidades de rede social

Nossa rede social inclui esses principais tipos de nós, representando entidades do domínio:

As pessoas têm informações pessoais, como nomes, aniversários e gêneros. Eles vivem em cidades e formam conexões sociais.

Os locais formam uma hierarquia geográfica:

• Cidades como "Nova York" ou "Londres"
• Países/regiões como "Estados Unidos" ou "Reino Unido"
• Continentes como "América do Norte" ou "Europa"

Organizações em que as pessoas passam tempo:

• Universidades onde as pessoas estudam
• Empresas em que as pessoas trabalham

Conteúdo e discussões:

• Fóruns com títulos que contêm postagens
• Postagens com conteúdo, idioma e imagens opcionais
• Comentários que respondem a postagens ou outros comentários
• Marcas que categorizam o conteúdo e representam interesses

Como tudo se conecta

As conexões entre entidades tornam a rede interessante:

• As pessoas se conhecem (amizades, :knows)
• As pessoas trabalham em empresas (:workAt) ou estudam em universidades (:studyAt)
• Pessoas criam posts e comentários (:hasCreator)
• Pessoas curtem posts e comentários (:likes)
• Postagens, fóruns, comentários podem ter tags (:hasTag)
• As pessoas têm interesse em tags específicas (:hasInterest)
• Fóruns contêm posts (:containerOf) e têm membros (:hasMember) e moderadores (:hasModerator)

As bordas do grafo representam relações de domínio. Essa rede avançada cria muitas oportunidades para consultas e análises interessantes.

Exibir especificação de esquema completa

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

Vamos começar com a consulta mais básica possível, encontre os nomes (primeiro nome, sobrenome) de todas as pessoas (:Persons) no gráfico.

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

Esta consulta é executada da seguinte forma:

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

Adicionar filtragem: localizar pessoas específicas

Agora vamos encontrar pessoas com características específicas, neste caso, todos chamados Alice, e mostrar seus nomes e datas de nascimento.

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

Esta consulta é executada 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 nome, sobrenome 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 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

Esta consulta é executada da seguinte forma:

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

Dica

A filtragem também pode ser executada diretamente como parte de um padrão acrescentando uma WHERE cláusula. Por exemplo, MATCH (n:Person WHERE n.age > 23) corresponderá apenas Person aos nós cuja age propriedade é maior que 23.

Observação

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

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.
• Isso cria um fluxo de dados claro e previsível que simplifica consultas complexas.

Importante

Internamente, a execução das instruções pode ser reordenada e as instruções individuais podem ser executadas em paralelo pelo Microsoft Fabric para maximizar o desempenho. No entanto, isso não afetará a correção dos resultados.

Exemplo

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

Esta consulta é executada da seguinte forma:

1. MATCH encontra pessoas que trabalham em empresas com "Air" no nome
2. LET cria nomes completos combinando nomes e sobrenomes
3. FILTER mantém apenas funcionários da Contoso
4. ORDER BY ordenação por nome completo
5. LIMIT Leva os primeiros 10 resultados
6. RETURN Nomes das devoluções e localizações 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.

As variáveis podem ser categorizadas de maneiras diferentes:

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 – associar a listas de valores de referência de elemento de padrões de comprimento variável (consulte Técnicas avançadas de agregação)

Resultados e resultados de execução

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

• Uma tabela de resultados (opcional) com os dados da instrução RETURN .
• Informações de status mostrando 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.

Observação

No caso de falha de execução, nenhuma tabela de resultados é incluída no resultado da execução.

Informações de status

Várias condições notáveis (como erros ou avisos) são detectadas durante a execução da consulta. Cada condição desse tipo é 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 objetos de status adicionais. O objeto de status primário está sempre presente e indica se a execução da consulta foi bem-sucedida ou falhou.

Cada objeto de status inclui um código de status de 5 dígitos (chamado GQLSTATUS) que identifica a condição registrada, bem como uma mensagem que o descreve.

Códigos de status de êxito:

GQLSTATUS	Message	When
00000	observação: conclusão bem-sucedida	Sucesso com pelo menos uma linha
00001	observação: conclusão bem-sucedida – resultado omitido	Êxito sem tabela (atualmente não utilizado)
02000	observação: sem dados	Sucesso com zero linhas

Outros códigos de status indicam mais erros ou avisos detectados durante a execução da consulta.

Exibir referência completa de códigos GQLSTATUS

Importante

No código do aplicativo, sempre dependa de códigos de status para testar determinadas condições. Os códigos de status são garantidos como estáveis e seu significado geral não será alterado no futuro. Não teste o conteúdo das mensagens, pois a mensagem concreta reportada para um código de status pode mudar no futuro dependendo da consulta ou até mesmo entre execuções da mesma consulta.

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 caracterizando 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 grafo: localizando estrutura

Os padrões de grafo são o coração das consultas GQL. Eles permitem que você descreva a estrutura de dados que você está procurando usando sintaxe visual intuitiva que se parece com as relações que você deseja encontrar.

Padrões simples:

Comece com padrões básicos de relação:

-- Find direct friendships
(p:Person)-[:knows]->(f:Person)

-- Find people working at any company
(p:Person)-[:workAt]->(c:Company)

-- Find cities in any country/region
(ci:City)-[:isPartOf]->(co:Country)  

Padrões com dados específicos:

-- Find who works at Microsoft specifically
(p:Person)-[:workAt]->(c:Company)
WHERE p.firstName = 'Annemarie'

-- Find friends who are both young
(p:Person)-[:knows]->(f:Person)  
WHERE p.birthday > 19950101 AND f.birthday > 19950101

Expressões de rótulo para seleção de entidade flexível:

(:Person|Company)-[:isLocatedIn]->(p:City|Country)  -- OR with |
(:Place&City)                                       -- AND with &  
(:Person&!Company)                                  -- NOT with !

Observação

Modelos de grafos com múltiplos elementos ainda não são suportados (problema conhecido).

As expressões de rótulo permitem que você corresponda a diferentes tipos de nós em um único padrão, tornando suas consultas mais flexíveis.

A reutilização de variável cria junções poderosas:

-- Find coworkers: people who work at the same company
(c:Company)<-[:workAt]-(x:Person)-[:knows]-(y:Person)-[:workAt]->(c)

A reutilização da variável c garante que ambas as pessoas trabalhem na mesma empresa, criando uma restrição de junção automática. Esse padrão é um padrão-chave para expressar relações de "mesma entidade".

Importante

Insight crítico: a reutilização de variável em padrões cria restrições estruturais. Essa técnica é como você expressa relações complexas de grafo, como "amigos que trabalham na mesma empresa" ou "pessoas na mesma cidade".

Filtragem de nível de padrão com WHERE:

-- Filter during pattern matching (more efficient)
(p:Person WHERE p.birthday < 19940101)-[:workAt]->(c:Company WHERE c.id > 1000)

-- Filter edges during matching  
(p:Person)-[w:workAt WHERE w.workFrom >= 2000]->(c:Company)

Padrões de comprimento variável limitados:

(:Person)-[:knows]->{1,3}(:Person)  -- Friends up to 3 degrees away

Padrões TRAIL para passagem sem ciclo:

Use TRAIL padrões para evitar ciclos durante a passagem de grafo, garantindo que cada borda seja visitada no máximo uma vez:

-- Find paths without visiting the same :knows edge twice
MATCH TRAIL (src:Person)-[:knows]->{1,4}(dst:Person)
WHERE src.firstName = 'Alice' AND dst.firstName = 'Bob'
RETURN count(*) AS num_connections

-- Find acyclic paths in social networks
MATCH TRAIL (p:Person)-[e:knows]->{,3}(celebrity:Person)
RETURN 
  p.firstName || ' ' || p.lastName AS person_name, 
  celebrity.firstName || ' ' || celebrity.lastName AS celebrity_name, 
  count(e) AS distance
LIMIT 1000

Associação de borda de comprimento variável:

Em padrões de comprimento variável, as variáveis de borda capturam informações diferentes com base no contexto:

-- Edge variable 'e' binds to a single edge for each result row
MATCH (p:Person)-[e:knows]->(friend:Person)
RETURN p.firstName, e.creationDate, friend.firstName  -- e refers to one specific relationship
LIMIT 1000

-- Edge variable 'e' binds to a group list of all edges in the path
MATCH (p:Person)-[e:knows]->{2,4}(friend:Person)  
RETURN 
  p.firstName || ' ' || p.lastName AS person_name, 
  friend.firstName || ' ' || friend.lastName AS friend_name, 
  -- e is a list
  size(e) AS num_edges
LIMIT 1000

Essa distinção é crucial para usar variáveis de borda corretamente.

Padrões complexos com várias relações:

MATCH (p:Person), (p)-[:workAt]->(c:Company), (p)-[:isLocatedIn]->(city:City)
RETURN p.firstName, p.lastName, c.name AS company_name, city.name AS city_name
LIMIT 1000

Esse padrão localiza as pessoas juntamente com seu local de trabalho e residência, mostrando como uma pessoa se conecta a várias outras entidades.

Aprenda a sintaxe de padrão abrangente e técnicas avançadas

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, unindo variáveis de entrada com variáveis padrão e gerando 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 com WHERE:

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

Todas as correspondências podem ser filtradas após o uso WHERE, evitando uma instrução separada FILTER .

Junção com 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 no Microsoft Fabric ainda não dá suporte à composição de instrução arbitrária. Consulte o artigo sobre as limitações atuais.

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 (sem junções esquerda/direita)
• Ordem de filtragem: filtros no nível WHERE da instrução após a conclusão da correspondência de padrões
• Conectividade padrão: vários padrões devem compartilhar pelo menos uma variável para a junção adequada
• Desempenho: variáveis compartilhadas criam restrições de junção eficientes

Importante

Restrição: se essa MATCH não for a primeira instrução, pelo menos uma variável de entrada deverá ingressar com uma variável padrão. Vários padrões devem ter uma variável em comum.

Vários padrões exigem 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 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:

• Expressões são avaliadas 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
• Várias atribuições em uma LET são avaliadas em paralelo (sem referências cruzadas)

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, '127.0.0.1') STARTS WITH '127.0.0' - não se conectou da rede local
• Combinar condições: usar AND/OR com verificações nulas explícitas para lógica complexa

Cuidado

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.

Instrução ORDER BY

Sintaxe:

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

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:

ORDER BY coalesce(p.gender, 'not specified') DESC -- Treat NULL as 'not specified'

Detalhes do comportamento de classificação:

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

• Avaliação de expressão: expressões são avaliadas para cada linha e, em seguida, os resultados determinam a ordem da linha
• Várias chaves de classificação: criar ordenação hierárquica (primária, secundária, terciária etc.)
• Tratamento nulo: NULL é sempre tratado como o menor valor em comparações
• Ordem padrão: ASC (crescente) é padrão, DESC (decrescente) deve ser especificada explicitamente
• Classificação computada: você pode classificar por valores calculados, não apenas propriedades armazenadas

Cuidado

A ordem de classificação estabelecida por ORDER BY ela só é visível para a instrução imediatamente a seguir. Portanto, ORDER BY seguido por RETURN * NÃO produz um resultado ordenado.

Comparar:

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

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

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

Importante

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

RETURN: projeção de resultado básico

Sintaxe:

RETURN [ DISTINCT ] <expression> [ AS <alias> ], <expression> [ AS <alias> ], ...
[ ORDER BY <expression> [ ASC | DESC ], <expression> [ ASC | DESC ], ... ]
[ 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 com 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 companyName = c.name
RETURN companyName, 
       count(*) AS employeeCount,
       avg(p.birthday) AS avg_birth_year
GROUP BY 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 obter técnicas avançadas de agregação, incluindo agregação horizontal em padrões de comprimento variável, consulte Técnicas avançadas de agregação.

Tipos de dados: trabalhando com valores

O GQL dá suporte a tipos de dados avançados para armazenar e manipular diferentes tipos de informações em seu grafo.

Tipos de valor básicos:

• Números: INT64, UINT64para DOUBLE cálculos e medidas
• Texto: STRING para nomes, descrições e dados textuais
• Lógica: BOOL com três valores: TRUE, FALSE e UNKNOWN (para tratamento nulo)
• Hora: ZONED DATETIME para carimbos de data/hora com informações de fuso horário
• Coleções: LIST<T> para múltiplos valores do mesmo tipo T, PATH para resultados de percorrido de grafos
• Elementos do grafo: NODE e EDGE para referenciar dados de grafo

Importante

Certos tipos de valor não são admitidos como os tipos de valores de propriedade. Em particular, todos os valores envolvendo valores de referência de elementos do grafo não podem ser usados como valores de propriedade (como listas de nós ou caminhos).

Literais de exemplo:

42                                     -- Integer literal
"Hello, graph!"                        -- String  literal
TRUE                                   -- Boolean literal
ZONED_DATETIME('2024-01-15T10:30:00Z') -- DateTime with timezone literakl
[1, 2, 3]                              -- Literal list of integers

Padrões críticos de tratamento nulo:

-- Equality predicates with NULL always returns UNKNOWN
5 = NULL                              -- Evaluates to UNKNOWN (not FALSE!)
NULL = NULL                           -- Evaluates to UNKNOWN (not TRUE!)

-- Use IS NULL predicates for explicit null testing
p.nickname IS NULL                    -- Evaluates to TRUE if nickname is null
p.nickname IS NOT NULL                -- Evaluates to TRUE if nickname has a value

-- Use the COALESCE function for null-safe value selection
coalesce(p.nickname, p.firstName, '???')  -- Evaluates to first non-null value

Implicações lógicas de três valores:

-- In FILTER statements, only TRUE values pass through
FILTER p.birthday > 0        -- Removes rows where birthday is null or missing or zero

-- It's important to understand that NOT UNKNOWN = UNKNOWN
FILTER NOT (p.birthday > 0)  -- Removes rows where birthday is null or missing or positive

-- Use explicit null handling for inclusive filtering
FILTER p.birthday < 19980101 OR p.birthday IS NULL -- Includes null birthdays

Cuidado

Lógica com três valores significa NULL = NULL retornos UNKNOWN, não TRUE. Esse comportamento afeta a filtragem e as junções. Sempre use IS NULL para testes nulos.

Saiba detalhes abrangentes do sistema de tipos

Expressões: transformando e analisando dados

As expressões permitem calcular, comparar e transformar dados em suas consultas. Elas são semelhantes às expressões no SQL, mas têm recursos extras para o tratamento de dados de grafo.

Tipos de expressão comuns:

p.birthday < 19980101   -- Birth year comparison  
p.firstName || ' ' || p.lastName               -- String concatenation
count(*)                                       -- Aggregation
p.firstName IN ['Alice', 'Bob']                -- List membership
coalesce(p.firstName, p.lastName)              -- Null handling

Composição de predicado complexa:

-- Combine conditions with proper precedence
FILTER (p.birthday > 19560101 AND p.birthday < 20061231) 
  AND ((p.gender IN ['male', 'female']) OR (p.browserUsed IS NOT NULL))

-- Use parentheses for clarity and correctness
FILTER p.gender = 'female' AND (p.firstName STARTS WITH 'A' OR p.id > 1000)

Correspondência de padrão de cadeia de caracteres:

-- Pattern matching with different operators
p.locationIP CONTAINS '192.168'      -- Substring search
p.firstName STARTS WITH 'John'       -- Prefix matching  
p.lastName ENDS WITH 'son'           -- Suffix matching

-- Case-insensitive operations
upper(p.firstName) = 'ALICE'         -- Convert to uppercase for comparison

Funções internas por categoria:

O GQL fornece estas categorias de função para diferentes necessidades de processamento de dados:

• Funções de agregação: count(), , sum(), avg(), min()max() para resumir dados
• Funções de cadeia de caracteres: char_length(), upper(), para lower()trim() processamento de texto
• Funções de grafo: nodes(), edges()para labels() analisar estruturas de grafo
• Funções gerais: coalesce() para lidar com valores nulos normalmente

Precedência do operador para expressões complexas:

1. Acesso à propriedade (.)
2. Multiplicação/Divisão (*, /)
3. Adição/subtração (+, -)
4. Comparação (=, , <>, <, >, <=) >=
5. Negação lógica (NOT)
6. Conjunção lógica (AND)
7. Disjunção lógica (OR)

Na lista acima, um operador com número menor "se liga mais apertado" do que um operador com número maior. Exemplo: NOT n.prop OR m.prop é (NOT n.prop) OR m.prop , mas não 'NOT (n.prop OU m.prop)

Dica

Use parênteses para tornar a precedência explícita. Expressões complexas são mais fáceis de ler e depurar quando o agrupamento é claro.

Aprenda a sintaxe de expressão abrangente e todas as funções internas

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 complexa de várias instruções

Importante

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

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

Progressão de padrão de várias etapas:

-- Build complex analysis step by step
MATCH (company:Company)<-[:workAt]-(employee:Person)
LET companyName = company.name
MATCH (employee)-[:isLocatedIn]->(city:City)
FILTER employee.birthday < 19850101
LET cityName = city.name
RETURN companyName, cityName, avg(employee.birthday) AS avgBirthday, count(employee) AS employeeCount
GROUP BY companyName, cityName
ORDER BY avgBirthday DESC

Essa consulta aumenta progressivamente a complexidade: encontre empresas, seus funcionários, localizações dos funcionários, filtre empresas com funcionários nascidos antes de 1985, calcule a data de nascimento média e resuma e ordene os resultados.

Uso da agregação horizontal:

-- Find people and their minimum distance to people working at Microsoft
MATCH TRAIL (p:Person)-[e:knows]->{,5}(:Person)-[:workAt]->(:Company { name: 'Microsoft'})
LET p_name = p.lastName || ', ' || p.firstName
RETURN p_name, min(count(e)) AS minDistance 
GROUP BY p_name
ORDER BY minDistance DESC

Observação

Esta consulta ainda não é suportada (problema conhecido).

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á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 fullNume
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 new variable for managed employee
RETURN p.firstName AS manager, e.firstName AS friend, gender

Cuidado

Variáveis na mesma instrução não podem fazer referência umas às outras (exceto em padrões de grafo). Use instruções separadas para a criação de variável dependente.

Técnicas avançadas de agregação

O GQL dá suporte a dois tipos distintos de agregação para analisar dados entre grupos e coleções: agregação vertical com GROUP BY e agregação horizontal em padrões de comprimento variável.

Agregação vertical com GROUP BY

A agregação vertical (coberta RETURN com GROUP BY) agrupa linhas por valores compartilhados e agregações de computação em cada grupo:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN c.name AS companyName, 
       count(*) AS employee_count, 
       avg(p.birthday) AS avg_birth_year
GROUP BY companyName

Essa abordagem cria uma linha de resultado por empresa, agregando todos os funcionários em cada grupo.

Agregação horizontal com variáveis de lista de grupos

A agregação horizontal calcula agregações sobre coleções associadas por padrões de comprimento variável. Quando você usa bordas de comprimento variável, a variável de borda se torna uma variável de lista de grupos que contém todas as bordas em cada caminho correspondente:

-- Group list variable 'edges' enables horizontal aggregation
MATCH (p:Person)-[edges:knows]->{2,4}(friend:Person)
RETURN p.firstName || ' ' || p.lastName AS person_name, 
       friend.firstName || ' ' || friend.lastName AS friend_name,
       size(edges) AS degrees_of_separation,
       avg(edges.creationDate) AS avg_connection_age,
       min(edges.creationDate) AS oldest_connection

Observação

Esta consulta ainda não é suportada (problema conhecido).

Principais diferenças:

• A agregação vertical resume entre linhas - ou - agrupa linhas e resume entre linhas em cada grupo
• Agregação horizontal resume elementos em coleções de borda individuais
• As variáveis de lista de grupos só vêm de padrões de borda de comprimento variável

Contextos de associação de borda de comprimento variável

Entender como as variáveis de borda se associam em padrões de comprimento variável é crucial:

Durante a correspondência de padrões (contexto singleton):

-- Edge variable 'e' refers to each individual edge during filtering
MATCH (p:Person)-[e:knows WHERE e.creationDate > zoned_datetime('2000-01-01T00:00:00Z')]->{2,4}(friend:Person)
-- 'e' is evaluated for each edge in the path during matching
RETURN *

Em expressões de resultado (contexto de grupo):

-- Edge variable 'edges' becomes a list of all qualifying edges
MATCH (p:Person)-[e:knows]->{2,4}(friend:Person)
RETURN size(e) AS num_edges,                    -- Number of edges in path
       e[0].creationDate AS first_edge,         -- First edge in path
       avg(e.creationDate) AS avg_age           -- Horizontal aggregation

Observação

Esta consulta ainda não é suportada (problema conhecido).

Combinando agregação vertical e horizontal

Você pode combinar ambos os tipos de agregação em padrões de análise sofisticados:

-- Find average connection age by city pairs
MATCH (p1:Person)-[:isLocatedIn]->(c1:City)
MATCH (p2:Person)-[:isLocatedIn]->(c2:City)
MATCH (p1)-[e:knows]->{1,3}(p2)
RETURN c1.name AS city1,
       c2.name AS city2,
       count(*) AS connection_paths,                  -- Vertical: count paths per city pair
       avg(size(e)) AS avg_degrees,                   -- Horizontal then vertical: path lengths
       avg(avg(e.creationDate)) AS avg_connection_age -- Horizontal then vertical: connection ages
GROUP BY city1, city2

Observação

Esta consulta ainda não é suportada (problema conhecido).

Dica

A agregação horizontal sempre tem precedência sobre a agregação vertical. Para converter uma lista de grupos em uma lista regular, use collect_list(edges).

Observação

Para obter uma referência detalhada de função de agregação, consulte funções e expressões GQL.

Estratégias de tratamento de erros

Entender padrões de erro comuns ajuda você a escrever consultas robustas.

Manipule os dados ausentes normalmente:

MATCH (p:Person)
-- Use COALESCE for missing properties
LET displayName = coalesce(p.firstName, p.lastName, 'Unknown')
LET contact = coalesce(p.locationIP, p.browserUsed, 'No info')
RETURN *

Use verificações nulas explícitas:

MATCH (p:Person)
-- Be explicit about null handling
FILTER p.id IS NOT NULL AND p.id > 0
-- Instead of just: FILTER p.id > 0
RETURN *

Informações adicionais

Códigos GQLSTATUS

Conforme explicado na seção sobre os resultados da consulta, a GQL relata informações de status avançadas relacionadas ao êxito ou à possível falha de execução. Consulte a referência de códigos de status GQL para a lista completa.

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

Agora que você entende os conceitos básicos da GQL, aqui está seu roteiro de aprendizagem recomendado:

Continue criando suas habilidades de GQL

Para iniciantes:

• Experimente o início rápido – Siga nosso tutorial prático para obter experiência prática
• Praticar consultas básicas – Experimente os exemplos deste guia com seus próprios dados
• Aprender padrões de grafo – Dominar a sintaxe de padrão abrangente
• Explorar tipos de dados – Entender valores e tipos de valor GQL

Para usuários experientes:

• Expressões avançadas – funções e expressões GQL mestras
• Design de esquema – Aprenda tipos e restrições de grafo GQL
• Explorar tipos de dados – Entender valores e tipos de valor GQL

Materiais de referência

Mantenha essas referências úteis para pesquisas rápidas:

• Referência rápida de GQL – Referência rápida de sintaxe
• Códigos de status GQL – Referência completa do código de erro
• Palavras reservadas GQL – Lista completa de palavras-chave reservadas

Explorar o Microsoft Fabric

Conheça a plataforma:

• Modelos de dados do Graph – Noções básicas sobre conceitos de grafo e modelagem
• Grafo versus bancos de dados relacionais – Escolha a abordagem certa
• Experimente o Microsoft Fabric gratuitamente – Obter experiência prática
• Tutoriais de ponta a ponta – Cenários de aprendizado completos

Participar

• Compartilhar comentários – Ajudar a melhorar nossa documentação e ferramentas
• Ingressar na comunidade – Conectar-se a outros profissionais de banco de dados de grafo
• Mantenha-se atualizado - Siga os comunicados do Microsoft Fabric para novos recursos

Dica

Comece com o tutorial de início rápido se preferir aprender fazendo ou mergulhe em padrões de grafo se quiser dominar a linguagem de consulta primeiro.

Conteúdo relacionado

Mais detalhes sobre os principais tópicos:

• Exemplo de esquema de rede social – exemplo de trabalho completo do esquema de grafo
• Padrões de grafo GQL – Sintaxe de padrão abrangente e técnicas avançadas de correspondência
• Expressões e funções GQL - Todos os tipos de expressão e funções internas
• Tipos de grafo GQL - Tipos e restrições de grafo
• Valores e tipos de valor GQL – Referência completa do sistema de tipos e manipulação de valor

Referências rápidas:

• Referência abreviada de GQL – Referência rápida de sintaxe
• Códigos de status GQL – Referência completa do código de erro
• Palavras reservadas GQL – Lista completa de palavras-chave reservadas

Grafo no Microsoft Fabric:

• Modelos de dados do Graph – Noções básicas sobre conceitos de grafo e modelagem
• Gráfico e bancos de dados relacionais – Diferenças e quando usar cada um
• Experimente o Microsoft Fabric gratuitamente
• Tutoriais completos no Microsoft Fabric