Expressões, predicados e funções GQL

Este artigo fornece uma referência abrangente para expressões, predicados e funções incorporadas GQL disponíveis em grafos nas consultas Microsoft Fabric. Use esta referência para perceber como realizar cálculos, filtrar resultados e transformar dados nas suas consultas de grafos.

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

Literais

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

Exemplo:

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

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

Predicates

Os predicados são expressões booleanas que normalmente se usam para filtrar resultados em consultas GQL. Eles avaliam para TRUE, FALSEou UNKNOWN (nulo).

Predicados de comparação

Use estes operadores para comparar valores:

• = (igual)
• <> (não igual)
• < (menos que)
• > (maior que)
• <= (inferior ou igual)
• >= (maior ou igual)

GQL usa lógica de três valores onde comparações com retorno UNKNOWNnulo :

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

Exemplo:

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

Regras de coerção numérica:

Use as seguintes regras por ordem de precedência:

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

Expressões lógicas

Combine condições com operadores lógicos:

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

Exemplo:

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

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

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

Precedência:

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

Exemplo:

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

Regras de coerção:

Use as seguintes regras por ordem de precedência:

1. Expressões aritméticas envolvendo argumentos de tipos de números aproximados retornam um resultado de um tipo numérico aproximado.
2. Expressões aritméticas envolvendo argumentos de tipos inteiros assinados e não assinados retornam um resultado de um tipo inteiro assinado.

Exemplo:

LET birth_year = p.birthday / 10000
RETURN birth_year

Acesso à propriedade

Aceder às propriedades usando notação de pontos:

p.firstName
edge.creationDate

Acesso à lista

Aceder aos elementos da lista utilizando indexação baseada em zero:

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

Funções incorporadas

GQL suporta várias funções integradas para processamento e análise de dados.

Funções agregadas

Use funções agregadas para avaliar uma expressão sobre um conjunto de linhas e obter um valor final combinando os valores calculados para cada linha. O Graph suporta as seguintes funções agregadas:

• count(*) - conta linhas
• sum(expression) - soma dos valores numéricos
• avg(expression) - valores numéricos médios
• min(expression) - encontra valor mínimo
• max(expression) - encontra valor máximo
• collect_list(expression) - Recolhe valores numa lista

Em geral, as funções agregadas ignoram valores nulos e sempre retornam um valor nulo quando nenhum valor de entrada material é fornecido. Pode usar coalesce para obter um valor padrão diferente: coalesce(sum(expr), 0). A única exceção é a função agregada count , 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 as funções agregadas de três formas diferentes:

• Para calcular agregados (verticais) sobre tabelas inteiras
• Para calcular agregados (verticais) sobre subtabelas determinados por uma chave de agrupamento
• Para calcular agregados (horizontais) sobre os elementos de uma lista de grupos

Agregados 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

Agregados horizontais:

A agregação horizontal calcula agregações sobre os elementos de variáveis de lista de grupos a partir 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 tem sempre 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 devolver diferentes valores 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 bigual a , caso contrário retorna a.

Exemplo:

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) - devolve o comprimento da corda.
• upper(string)- devolve a variante maiúscula da sequência fornecida (apenas ASCII nos EUA).
• lower(string)- devolve a variante minúscula da cadeia fornecida (apenas ASCII nos EUA).
• trim(string) - remove espaços em branco dianteiros e posteriores.
• string_join(list, separator) - junta elementos de lista com separador.

Exemplo:

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

Funções gráficas

• nodes(path) - devolve nós a partir de um valor de caminho.
• edges(path) - devolve arestas a partir de um valor de caminho.
• elements(path) - devolve todos os nós e arestas de um caminho como uma única lista, por ordem de caminho.
• labels(node_or_edge) - devolve as etiquetas de um nó ou aresta como uma lista de cadeias.
• path_length(path) - devolve o número de arestas num caminho.

Exemplo:

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) - devolve o tamanho de um valor de lista.
• trim(list,n) - Cortar uma lista para ser, no máximo, de tamanho n.

Exemplo:

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() - devolve a data-hora zoneada atual.
• zoned_datetime("2025-09-12T10:10:52Z") - devolve a data-hora zoneada dada pelo argumento no formato ISO 8601.

Exemplo:

RETURN zoned_datetime() AS now

Funções genéricas

• coalesce(value1, value2, ...) - devolve o primeiro valor não nulo.
• to_json_string(value) - converte um valor para a sua representação da cadeia JSON.

Exemplo:

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

Conteúdo relacionado

• Guia de idiomas do GQL
• Valores GQL e tipos de valor
• Otimizar o desempenho das consultas GQL
• Padrões gráficos
• Experimenta o Graph gratuitamente