Partilhar via

Expressões, predicados e funções GQL

Observação

Esta funcionalidade está atualmente em pré-visualização pública. Essa visualização é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

As expressões GQL permitem realizar cálculos, comparações e transformações em dados dentro de suas consultas. Em combinação com funções integradas, as expressões fornecem ferramentas poderosas para processamento, filtragem e análise de dados em consultas gráficas.

Literais

Literais são expressões simples que avaliam diretamente o valor declarado. Os 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 sintaxe literal detalhada para cada tipo de dados, consulte Valores GQL e tipos de valor.

Predicates

Predicados são expressões booleanas, que são comumente usadas para filtrar resultados em consultas GQL. Eles avaliam para TRUE, FALSEou UNKNOWN (nulo).

Atenção

Quando usados como filtro, os predicados retêm apenas os itens para os quais o predicado é avaliado como TRUE.

Predicados de comparação

Compare valores usando estes operadores:

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

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

Para 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érica:

Por ordem de precedência:

  1. Expressões de comparação envolvendo argumentos de tipos numéricos aproximados coagem todos os argumentos a serem de um tipo numérico aproximado.
  2. Expressões de comparação envolvendo argumentos de tipos inteiros assinados e não assinados coagem todos os argumentos a serem de um tipo inteiro assinado.

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)

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

p.locationIP IS NOT NULL
p.browserUsed IS NULL

Observação

Tentar aceder a uma propriedade conhecida como inexistente resulta num 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 do nó ou aresta acedida.

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 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 as regras estabelecidas de precedência do operador, 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:

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.

Example:

LET birth_year = p.birthday / 10000
RETURN birth_year

Acesso à propriedade

Acesse as propriedades usando a notação de pontos:

p.firstName
edge.creationDate

Acesso à lista

Acessar elementos da lista usando 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

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 calculados para cada linha. As seguintes funções de agregação são suportadas para gráfico no Microsoft Fabric:

  • 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. Você 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 também incluir valores nulos na contagem.

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

  • Para calcular agregados (verticais) em tabelas inteiras
  • Para calcular agregados (verticais) em subtabelas determinadas por uma chave de agrupamento
  • Para agregações computacionais (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).

Observação

Para obter uma cobertura abrangente das técnicas de agregação, incluindo a ligação de arestas de comprimento variável e a 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 a variante maiúscula da string fornecida (somente ASCII dos EUA)
  • lower(string)- retorna a variante minúscula da string fornecida (somente ASCII dos EUA)
  • trim(string) - remove espaços em branco à esquerda e à direita
  • string_join(list, separator) - junta elementos da lista com separador

Example:

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

Funções gráficas

  • nodes(path) - retorna nós de um valor de caminho
  • edges(path) - Devolve arestas 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) - Devolve o tamanho de um valor de lista
  • trim(list,n) - cortar uma lista para ser no máximo de 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() - Devolve datetime zoneado atual
  • zoned_datetime("2025-09-12T10:10:52Z") - retorna datetime zoneado dado pelo argumento no formato ISO 8601

Example:

RETURN zoned_datetime() AS now

Funções genéricas

  • coalesce(value1, value2, ...) - Devolve o primeiro valor não nulo

Example:

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

Conteúdo relacionado

  • Last updated on