Compartilhar via

Expressões, predicados e funções 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.

As expressões GQL permitem que você execute cálculos, comparações e transformações em dados em suas consultas. Em combinação com funções internas, as expressões fornecem ferramentas avançadas para processamento, filtragem e análise de dados em consultas de grafo.

Literals

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

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 geralmente são usadas para filtrar resultados em consultas GQL. Eles são avaliados como TRUE, FALSEou UNKNOWN (nulo).

Cuidado

Quando usados como um filtro, os predicados retêm apenas esses itens, para os quais o predicado é TRUEavaliado como .

Predicados de comparação

Compare os valores usando estes operadores:

  • = (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 :

Expression Resultado
5 = 5 TRUE
5 = 3 FALSE
5 = NULL UNKNOWN
NULL = NULL UNKNOWN

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:

Em ordem de precedência:

  1. Expressões de comparação envolvendo 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)

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, você pode usar:

p.locationIP IS NOT NULL
p.browserUsed IS NULL

Observação

Tentar acessar uma propriedade conhecida como inexistente resulta em um erro de sintaxe. O acesso a uma propriedade potencialmente inexistente avalia para null. A determinação de se uma propriedade é conhecida ou potencialmente inexistente é feita com base no tipo de nó ou aresta acessada.

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

Geralmente, 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:

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

Elementos da lista de acesso usando 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

As funções de agregação são usadas para avaliar uma expressão em um conjunto de linhas e obter um valor de resultado final combinando os valores computados para cada linha. As seguintes funções de agregação têm suporte para grafo no Microsoft Fabric:

  • 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(*) também para incluir valores nulos na contagem.

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

  • Para agregações de computação (vertical) em tabelas inteiras
  • Para agregações de computação (vertical) sobre subtables determinadas por uma chave de agrupamento
  • Para agregações de computação (horizontal) 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).

Observação

Para obter uma cobertura abrangente de técnicas de agregação, incluindo associação de borda de comprimento variável e combinação de agregação horizontal/vertical, consulte Técnicas avançadas de agregação.

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
  • labels(node_or_edge) – retorna os rótulos de um nó ou borda como uma lista de cadeias de caracteres

Example:

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

Listar funções

  • size(list) - retorna o tamanho de um valor de lista
  • trim(list,n) - cortar uma lista para ter a maior parte do 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 datetime zoneado atual
  • zoned_datetime("2025-09-12T10:10:52Z") – retorna 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

Example:

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

Conteúdo relacionado

  • Last updated on