Expressões, predicados e funções GQL

Este artigo fornece uma referência abrangente para expressões GQL, predicados e funções internas disponíveis no graph em consultas do Microsoft Fabric. Use essa referência para entender como executar cálculos, filtrar resultados e transformar dados em suas consultas de grafo.

Para obter uma visão geral da linguagem de consulta GQL e exemplos de consulta de ponta a ponta, consulte o guia de linguagem GQL. Para obter informações sobre tipos de dados compatíveis e sintaxe literal, consulte valores GQL e tipos de valor.

Literals

Literais são expressões simples que avaliam diretamente o valor declarado. O artigo de valores e tipos de valor GQL explica literais de cada tipo de valor em detalhes.

Example:

1
1.0d
TRUE
"Hello, graph!"
[ 1, 2, 3 ]
NULL

Para obter uma sintaxe literal detalhada para cada tipo de dados, consulte valores GQL e tipos de valor.

Predicates

Predicados são expressões boolianas que você normalmente usa para filtrar resultados em consultas GQL. Eles são avaliados como TRUE, FALSEou UNKNOWN (nulo).

Predicados de comparação

Use estes operadores para comparar valores:

• = (igual)
• <> (não é igual)
• < (menor que)
• > (maior que)
• <= (menor ou igual)
• >= (maior ou igual)

O GQL usa uma lógica de três valores em que as comparações com o retorno UNKNOWNnulo :

Para obter um comportamento de comparação específico, consulte a documentação de cada tipo de valor em valores GQL e tipos de valor.

Example:

MATCH (p:Person)
FILTER WHERE p.birthday <= 20050915
RETURN p.firstName

Regras de coerção numéricas:

Use as seguintes regras em ordem de precedência:

1. Expressões de comparação que envolvem argumentos de tipos numéricos aproximados coagim todos os argumentos a serem de um tipo numérico aproximado.
2. Expressões de comparação que envolvem argumentos de tipos inteiros assinados e não assinados coagim todos os argumentos a serem de um tipo inteiro com sinal.

Expressões lógicas

Combinar condições com operadores lógicos:

• AND (ambas as condições são verdadeiras)
• OR (qualquer condição verdadeira)
• NOT (condição nega)
• XOR (disjunção exclusiva – true quando exatamente um operando é verdadeiro)

Example:

MATCH (p:Person)
FILTER WHERE p.birthday <= 20050915 AND p.firstName = 'John'
RETURN p.firstName || ' ' || p.lastName AS fullName

Predicados de existência de propriedade

Para verificar se existem propriedades, use estes predicados:

p.locationIP IS NOT NULL
p.browserUsed IS NULL

Listar predicados de associação

Teste se os valores estão em listas:

p.firstName IN ['Alice', 'Bob', 'Charlie']
p.gender NOT IN ['male', 'female']

Predicados de padrão de cadeia de caracteres

Corresponder cadeias de caracteres usando técnicas de correspondência de padrões:

p.firstName CONTAINS 'John'
p.browserUsed STARTS WITH 'Chrome'
p.locationIP ENDS WITH '.1'

Expressões aritméticas

Use operadores aritméticos padrão com valores numéricos:

• + (adição)
• - (subtração)
• * (multiplicação)
• / (divisão)

Operadores aritméticos seguem convenções matemáticas gerais.

Precedência:

Em geral, os operadores seguem regras de precedência de operador estabelecidas, como * antes +. Use parênteses para controlar a ordem de avaliação conforme necessário.

Example:

(p.birthday < 20050915 OR p.birthday > 19651231) AND p.gender = 'male'

Regras de coerção:

Use as seguintes regras em ordem de precedência:

1. Expressões aritméticas que envolvem argumentos de tipos de número aproximados retornam um resultado de um tipo numérico aproximado.
2. Expressões aritméticas que envolvem argumentos de tipos inteiros assinados e não assinados retornam um resultado de um tipo inteiro com sinal.

Example:

LET birth_year = p.birthday / 10000
RETURN birth_year

Acesso à propriedade

Acessar propriedades usando notação de ponto:

p.firstName
edge.creationDate

Listar acesso

Acesse os elementos da lista usando a indexação baseada em zero:

interests[0]    -- first element
interests[1]    -- second element

Funções internas

O GQL dá suporte a várias funções internas para processamento e análise de dados.

Funções de agregação

Use funções de agregação para avaliar uma expressão em um conjunto de linhas e obter um valor de resultado final combinando os valores computados para cada linha. O Graph dá suporte às seguintes funções de agregação:

• count(*) - conta linhas
• sum(expression) – soma valores numéricos
• avg(expression) – médias de valores numéricos
• min(expression) - localiza o valor mínimo
• max(expression) - localiza o valor máximo
• collect_list(expression) – coleta valores em uma lista

Em geral, as funções de agregação ignoram valores nulos e sempre retornam um valor nulo quando nenhum valor de entrada material é fornecido. Você pode usar coalesce para obter um valor padrão diferente: coalesce(sum(expr), 0). A única exceção é a count função de agregação, que sempre conta os valores não nulos fornecidos, retornando 0 se não houver nenhum. Use count(*) para incluir valores nulos na contagem.

Use funções de agregação de três maneiras diferentes:

• Para calcular agregações (verticais) em tabelas inteiras
• Para calcular agregações (verticais) sobre subtables determinadas por uma chave de agrupamento
• Para calcular agregações (horizontais) sobre os elementos de uma lista de grupos

Agregações verticais:

-- Vertical aggregate over whole table
MATCH (p:Person)
RETURN count(*) AS total_people, avg(p.birthday) AS average_birth_year

-- Vertical aggregate with grouping
MATCH (p:Person)-[:isLocatedIn]->(c:City)
RETURN c.name, count(*) AS population, avg(p.birthday) AS average_birth_year
GROUP BY c.name

Agregações horizontais:

A agregação horizontal calcula agregações sobre os elementos de variáveis de lista de grupo de padrões de comprimento variável:

-- Horizontal aggregate over a group list variable
MATCH (p:Person)-[edges:knows]->{1,3}(:Person)
RETURN p.firstName, avg(edges.creationDate) AS avg_connection_date

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

Expressões condicionais

Use expressões condicionais para retornar valores diferentes com base nas condições.

CASO PESQUISADO:

CASE
  WHEN condition1 THEN result1
  WHEN condition2 THEN result2
  ELSE default_result
END

CASO SIMPLES:

CASE expression
  WHEN value1 THEN result1
  WHEN value2 THEN result2
  ELSE default_result
END

NULLIF:

NULLIF(a, b) retorna NULL se a for igual b, caso contrário, retornará a.

Example:

MATCH (p:Person)
RETURN p.firstName,
       CASE
         WHEN p.gender = 'male' THEN 'M'
         WHEN p.gender = 'female' THEN 'F'
         ELSE 'Other'
       END AS gender_code,
       NULLIF(p.browserUsed, 'Unknown') AS browser

Funções de cadeia de caracteres

• char_length(string) – retorna o comprimento da cadeia de caracteres.
• upper(string)– retorna uma variante maiúscula da cadeia de caracteres fornecida (somente US ASCII).
• lower(string)– retorna uma variante minúscula da cadeia de caracteres fornecida (somente US ASCII).
• trim(string) – remove o espaço em branco à esquerda e à direita.
• string_join(list, separator) – une elementos de lista com separador.

Example:

MATCH (p:Person)
WHERE char_length(p.firstName) > 5
RETURN upper(p.firstName) AS name_upper

Funções de grafo

• nodes(path) – retorna nós de um valor de caminho.
• edges(path) – retorna bordas de um valor de caminho.
• elements(path) – retorna todos os nós e bordas de um caminho como uma única lista, em ordem de caminho.
• labels(node_or_edge) – retorna os rótulos de um nó ou borda como uma lista de cadeias de caracteres.
• path_length(path) – retorna o número de bordas em um caminho.

Example:

MATCH p=(:Company)<-[:workAt]-(:Person)-[:knows]-{1,3}(:Person)-[:workAt]->(:Company)
RETURN nodes(p) AS chain_of_colleagues, path_length(p) AS hops

Listar funções

• size(list) – retorna o tamanho de um valor de lista.
• trim(list,n) - aparar uma lista para ter no máximo o tamanho n.

Example:

MATCH (p:Person)-[:hasInterest]->(t:Tag)
WHERE size(collect_list(t)) > 3
RETURN p.firstName, collect_list(t.name) AS interests

Funções temporais

• zoned_datetime() – retorna o datetime zoneado atual.
• zoned_datetime("2025-09-12T10:10:52Z") – retorna o datetime zoneado fornecido pelo argumento no formato ISO 8601.

Example:

RETURN zoned_datetime() AS now

Funções genéricas

• coalesce(value1, value2, ...) – retorna o primeiro valor não nulo.
• to_json_string(value) – converte um valor em sua representação de cadeia de caracteres JSON.

Example:

MATCH (p:Person)
RETURN coalesce(p.firstName, 'Unknown') AS display_name,
       to_json_string(p) AS person_json

Conteúdo relacionado

• Guia de idioma GQL
• Valores e tipos de valor GQL
• Otimizar o desempenho da consulta GQL
• Padrões de grafo
• Experimente o grafo gratuitamente