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
1.00m
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

Se ambos os operandos forem números, o GQL compara-os pelos seus valores numéricos.

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

Subconsultas de existência

Use uma subconsulta de formulário EXISTS de procedimento para testar se uma consulta aninhada retorna pelo menos uma linha:

EXISTS {
  <query statements>
  RETURN <columns>
}

O resultado é um valor booleano não nulo:

• TRUE se a subconsulta devolver uma ou mais linhas.
• FALSE se a subconsulta não devolver linhas.

As variáveis já no âmbito estão implicitamente disponíveis dentro da subconsulta. Variáveis introduzidas apenas dentro da subquery não estão disponíveis fora dela.

Utilização EXISTS num filtro:

MATCH (p:Person)
WHERE EXISTS {
  MATCH (p)-[:knows]->(friend:Person)
  RETURN friend
}
RETURN p.firstName, p.lastName

Use NOT EXISTS para reter linhas para as quais a subconsulta não devolve linhas. Também pode usar EXISTS em LET, RETURN, ORDER BY, e agregar filtros ou expressões de origem. EXISTS não é suportado dentro de um filtro de predicados de lista.

Para mais informações sobre subconsultas correlacionadas, consulte a CALL afirmação no guia de linguagem GQL.

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']

Funções predicadas de lista

Use uma função de predicado de lista para avaliar uma expressão booleana para os elementos de uma lista:

ALL(element IN list WHERE predicate)
ANY(element IN list WHERE predicate)
NONE(element IN list WHERE predicate)
SINGLE(element IN list WHERE predicate)

A fonte pode ser um literal de lista, uma propriedade de valor de lista, uma variável ou uma lista de grupo a partir de um padrão de comprimento variável.

As funções têm os seguintes significados:

O exemplo seguinte avalia as quatro funções ao longo de uma lista dinamicamente construída:

LET items = [1, 2, 3]
RETURN ALL(x IN items WHERE x > 0) AS all_match,
       ANY(x IN items WHERE x = 2) AS any_match,
       NONE(x IN items WHERE x < 0) AS none_match,
       SINGLE(x IN items WHERE x = 2) AS single_match

Todos os quatro valores devolvidos são TRUE.

Também pode avaliar propriedades de elementos a partir de uma lista. Neste exemplo, connections é a lista de grupos criada pelo padrão de arestas de comprimento variável:

MATCH (person:Person)-[connections:knows]->{1,4}(friend:Person)
WHERE ALL(connection IN connections WHERE connection.creationDate IS NOT NULL)
RETURN person.firstName, friend.firstName

Os predicados de lista usam lógica de três valores. A tabela descreve o resultado em termos dos valores produzidos pela expressão do filtro para os elementos da lista:

Se a lista de origem for nula, cada função devolve UNKNOWN. Um elemento da lista nula contribui para o resultado da avaliação do filtro com esse elemento ligado a nulo; não torna automaticamente o resultado da função desconhecido.

A variável elemento está disponível apenas dentro da expressão de filtro do predicado da lista. O filtro também pode referenciar variáveis a partir da consulta anexa. Se a variável elemento tiver o mesmo nome que uma variável exterior, a variável local tem precedência. Predicados de lista aninhada podem igualmente sombrear uma variável de elemento externo.

As funções agregadas podem referenciar uma lista de grupos que o encerra, mas não podem agregar a variável de elemento localmente limitada. EXISTS Subconsultas também não são suportadas dentro de um filtro de predicados de lista.

ANY(...) é uma função predicado de lista. Não confundas com o prefixo ANY SHORTEST de path search ou o ANY tipo de valor dinâmico.

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'

Para correspondência de expressões regulares do RE2, use MSFT.REGEXP_LIKE.

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 que envolvem um tipo numérico aproximado devolvem um tipo numérico aproximado.
2. Expressões aritméticas que envolvem tanto tipos inteiros com e sem sinal devolvem um tipo inteiro com assinatura.

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 numéricas

Use funções numéricas para transformar valores numéricos, calcular valores trigonométricos e criar intervalos inteiros.

Valor absoluto e poder

Ambas as funções aceitam valores numéricos. Um argumento nulo produz nulo. Uma operação numérica inválida, como um resultado a transbordar POWER , produz um erro.

RETURN ABS(-1) AS absoluteValue, POWER(2, -2) AS reciprocalSquare

O resultado é:

Funções trigonométricas

As funções trigonométricas aceitam um valor numérico e retornam um DOUBLE. Um argumento nulo produz nulo.

Um argumento fora do domínio matemático de uma função produz um erro.

RETURN COS(0) AS cosine, RADIANS(180) AS angle

O resultado é:

Intervalos inteiros

RANGE(start, end) devolve uma lista de inteiros de start para end, usando um passo de 1. RANGE(start, end, step) usa o passo não nulo especificado. start, end, e step devem ser inteiros não nulos. Zero é válido para start ou end; apenas step deve ser diferente de zero.

O intervalo inclui start. Inclui end apenas quando se adicionam step repetidamente os limites end exatos. Um passo positivo com start maior que end, ou um passo negativo com start menor que end, devolve uma lista vazia. Um passo zero produz um erro.

RETURN RANGE(0, 10, 3) AS ascending, RANGE(5, 0, -2) AS descending

O resultado é:

Se todos os argumentos forem inteiros sem sinal, RANGE retorna um LIST<UINT64>. Caso contrário, devolve a LIST<INT64> e rejeita valores que não podem ser representados de forma segura como inteiros com sinal.

Funções agregadas

As funções agregadas combinam valores entre linhas de entrada ou dentro de uma lista de grupos limitada por um padrão de comprimento variável.

Quando uma consulta agregada não tem colunas de agrupamento e não recebe linhas de entrada, COUNT devolve 0, COLLECT_LIST e COLLECT_ELEMENTS devolve uma lista vazia, e as outras funções agregadas devolvem nula. Não confie na ordem dos valores devolvidos por um agregado de coleções. Com o agrupamento de colunas, nenhuma linha de entrada não produz grupo e, portanto, não produz linha de resultados.

Quantificadores de conjuntos

Use ALL para incluir valores duplicados ou DISTINCT para os remover. ALL é o padrão para agregados de expressão. COUNT(*) não aceita um quantificador conjunto.

MATCH (person:Person)
RETURN COUNT(person) AS personCount,
       COUNT(DISTINCT person.browserUsed) AS browserCount

Para COLLECT_LIST, DISTINCT remove valores duplicados e mantém no máximo um nulo. Para COLLECT_ELEMENTS, DISTINCT aplica-se aos elementos após a concatenação das listas de entrada. DISTINCT isso não torna COLLECT_ONE determinístico.

Filtros e limites específicos de agregados

Adicionar FILTER (WHERE predicate) após um agregado para incluir apenas valores para os quais predicate é verdadeiro. Resultados falsos e de predicados desconhecidos são excluídos. Este filtro afeta apenas esse agregado, não as linhas de entrada disponíveis para outras expressões na mesma RETURN.

Adicione LIMIT n dentro do filtro agregado para considerar, no máximo n , linhas de entrada qualificadas. A filtragem ocorre antes do limite específico do agregado e DISTINCT é aplicada depois desse limite.

MATCH (person:Person)
RETURN COUNT(*) AS allPeople,
       COUNT(*) FILTER (WHERE person.birthday < 19900101 LIMIT 5) AS sampleBornBefore1990

Agregação entre linhas

Um agregado normalmente combina valores verticalmente entre as linhas de entrada. Use GROUP BY para calcular um resultado para cada grupo.

MATCH (p:Person)
RETURN count(*) AS total_people, avg(p.birthday) AS average_birth_year

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

Não coloque um agregado vertical diretamente dentro de outro no mesmo bloco de consulta. Por exemplo, SUM(COUNT(*)) é inválido. Use NEXT para separar os passos de agregação quando precisar de agregar um resultado agregado.

Agregação dentro de um caminho emparelhado

Uma variável de aresta limitada por um padrão de comprimento variável torna-se uma lista de grupos. Um agregado sobre essa variável é horizontal: calcula um resultado dentro da lista para cada caminho correspondente, em vez de combinar diferentes linhas de entrada.

MATCH (person:Person)-[knows:knows]->{1,5}(friend:Person)
RETURN COUNT(knows) AS pathLength

Aqui, COUNT(knows) devolve o número de arestas em cada caminho correspondente. As formas horizontais de COUNT, SUM, AVG, MIN, MAX, COLLECT_LIST, COLLECT_ONE, e COLLECT_ELEMENTS são suportadas. COUNT(*) e específicas FILTER de agregados ou LIMIT não são formas horizontais.

Um agregado horizontal pode ser a entrada de um agregado vertical exterior:

MATCH (person:Person)-[knows:knows]->{1,5}(friend:Person)
RETURN MIN(COUNT(knows)) AS shortestMatchedPath

Nesta consulta, COUNT(knows) calcula um comprimento por cada caminho emparelhado e MIN combina esses comprimentos nas linhas de entrada.

Para exemplos orientados a tarefas, veja Filtrar e agregar dados de grafos.

Expressões condicionais

Use uma expressão simples CASE para comparar uma expressão com um ou mais valores e devolve o resultado associado ao primeiro valor igual:

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 p.gender
         WHEN 'male' THEN 'M'
         WHEN 'female' THEN 'F'
         ELSE 'Other'
       END AS gender_code,
       NULLIF(p.browserUsed, 'Unknown') AS browser

Expressões pesquisadas CASE WHEN <predicate> não são suportadas. Para encaminhar linhas por predicados e executar uma instrução de consulta ou procedimento aninhado para a ramificação selecionada, use uma WHEN instrução condicional.

Funções de cadeia de caracteres

Use funções de cadeia para medir, transformar, pesquisar, comparar e combinar cadeias de caracteres.

Comprimento do carácter e caso

Use estas funções para medir ou alterar cadeias de caracteres:

Os mapeamentos Unicode podem alterar o comprimento ou a representação de uma cadeia:

RETURN UPPER('straße') AS uppercase,
       LOWER('İ') AS lowercase,
       CASEFOLD('Straße') AS folded

Os resultados são STRASSE, i̇, e strasse, respetivamente. CASEFOLD não é equivalente a LOWER. Por exemplo, a dobragem de casos mapeia ß para ss e mapeia as formas Σsigma gregas , σ, e ς para σ.

Normalizar cadeias

O GQL define quatro formas de normalização Unicode:

• Forma de normalização C (NFC), composição canónica.
• Forma de normalização D (NFD), decomposição canónica.
• Forma de normalização KC (NFKC), composição de compatibilidade.
• Forma de normalização KD (NFKD), decomposição de compatibilidade.

NORMALIZE(string) por defeito é NFC. Especifique uma forma de normalização como segundo argumento:

RETURN NORMALIZE('cafe\u0301') AS composed,
       NORMALIZE('café', NFD) AS decomposed

O argumento tem de ser uma corda.

Cordas de corte

Use TRIM para remover caracteres de espaço ou um carácter especificado de ambas as extremidades, do início ou do fim de uma sequência:

RETURN TRIM('  text  ') AS both_ends,
       TRIM(BOTH FROM '  text  ') AS explicit_both,
       TRIM(LEADING FROM '  text  ') AS beginning,
       TRIM(TRAILING FROM '  text  ') AS ending,
       TRIM(LEADING 'f' FROM 'foobar') AS custom_character

O valor personalizado do trim deve ser exatamente um byte. Caracteres Unicode multibyte e strings contendo múltiplos caracteres não são suportados como valores de trim personalizados. Uma fonte nula ou valor de trim personalizado devolve nulo.

Cordas de junção

STRING_JOIN(list [, delimiter]) junta-se a uma lista de cordas. O delimitador padrão é uma vírgula seguida de um espaço:

RETURN STRING_JOIN(['foo', 'bar', 'baz']) AS default_delimiter,
       STRING_JOIN(['foo', 'bar', 'baz'], '-') AS custom_delimiter

Os resultados são foo, bar, baz e foo-bar-baz. Uma lista vazia devolve uma cadeia vazia. Uma lista nula, delimitador nulo ou elemento de lista nula devolve nula. Todo elemento de lista não nulo deve ser uma cadeia.

Funções de expressão regular

O Graph fornece estas funções de expressão regular como extensões do GQL:

MSFT.REGEXP_LIKE

Retorna TRUE quando o padrão corresponde a qualquer parte da cadeia de origem. Se nenhuma correspondência for encontrada, ela retornará FALSE.

source é a cadeia a pesquisar. pattern é comparado com qualquer subcadeia de source , a menos que a própria expressão use âncoras como ^ ou $. flags altera o comportamento de correspondência conforme descrito nas regras e opções de correspondência.

RETURN MSFT.REGEXP_LIKE('HELLO', 'hello', 'i') AS matches

O resultado é TRUE.

MSFT.REGEXP_COUNT

Devolve o número de correspondências. Se nenhuma correspondência for encontrada, ela retornará 0.

source é a cadeia a pesquisar, e pattern identifica as correspondências a contar. start é a posição de ponto de código Unicode baseada em zero onde o emparelhamento pode começar. Um jogo deve começar nesta posição ou depois dela. A posição não se torna um novo começo da corda para padrões ancorados. flags altera o comportamento de correspondência conforme descrito nas regras e opções de correspondência.

RETURN MSFT.REGEXP_COUNT('1a2a3a4', '[0-9]', 3) AS match_count

A pesquisa começa na posição 3, a segunda a, ou seja, 3 apenas os dígitos e 4 são contados. O resultado é 2.

MSFT.REGEXP_INSTR

Devolve a posição baseada em zero de um grupo selecionado de correspondência ou captura.

source é a cadeia a pesquisar e pattern identifica as correspondências. start é a posição de ponto de código Unicode baseada em zero onde o emparelhamento pode começar. Uma partida deve começar nesta posição ou depois, o que não se torna um novo início da corda para padrões ancorados.

occurrence seleciona a primeira, segunda ou subsequente correspondência não sobreposta encontrada a partir de start. group Seleciona o que localizar dentro dessa correspondência: 0 seleciona a correspondência completa, e um valor positivo seleciona o grupo de captura numerado. return_option determina qual o limite do jogo ou grupo selecionado que é devolvido: 0 devolve a sua posição inicial e 1 retorna a posição imediatamente após o seu fim. flags altera o comportamento de correspondência conforme descrito nas regras e opções de correspondência.

Se não for encontrada ocorrência correspondente, ou se o grupo de captura selecionado não participar nessa ocorrência, a função devolve -1.

RETURN MSFT.REGEXP_INSTR('banana', 'a', 0, 2) AS match_position

O segundo jogo começa na posição 3, pelo que o resultado é 3.

MSFT.REGEXP_SUBSTR

Devolve o texto de uma correspondência ou grupo de captura selecionado.

source é a cadeia a pesquisar e pattern identifica as correspondências. start é a posição de ponto de código Unicode baseada em zero onde o emparelhamento pode começar. Uma partida deve começar nesta posição ou depois, o que não se torna um novo início da corda para padrões ancorados.

occurrence seleciona a primeira, segunda ou subsequente correspondência não sobreposta encontrada a partir de start. group seleciona o texto a devolver dessa correspondência: 0 seleciona a correspondência completa, e um valor positivo seleciona esse grupo de captura numerado. flags altera o comportamento de correspondência conforme descrito nas regras e opções de correspondência.

Se não for encontrada nenhuma ocorrência correspondente, ou se o grupo de captura selecionado não participar nessa ocorrência, a função devolve nulo.

RETURN MSFT.REGEXP_SUBSTR(
  '12-345',
  '([0-9]+)-([0-9]+)',
  0,
  1,
  '',
  2
) AS matched_text

A primeira ocorrência é a cadeia completa, e o grupo 2 de captura é 345, pelo que o resultado é 345.

MSFT.REGEXP_REPLACE

Substitui o texto correspondente. Por defeito, substitui todas as correspondências e insere literalmente o texto de substituição.

source é a cadeia a modificar e pattern identifica as correspondências. replacement é o texto inserido para uma partida selecionada. EXACT insere-a literalmente; TEMPLATE interpreta referências de captura.

start é a posição de ponto de código Unicode baseada em zero onde a substituição pode começar. Um jogo deve começar nesta posição ou depois dela. O texto anterior start mantém-se inalterado, e a posição não se torna um novo início da cadeia para padrões ancorados. Defina occurrence para 0 substituir todas as correspondências de start, ou para um valor positivo para substituir apenas essa correspondência numerada não sobreposta. As partidas anteriores depois start mantêm-se inalteradas quando uma ocorrência específica é selecionada. flags altera o comportamento de correspondência conforme descrito nas regras e opções de correspondência.

RETURN MSFT.REGEXP_REPLACE('a1b2c3', '[0-9]', '#', 0, 2) AS replaced

Apenas a correspondência do segundo dígito é substituída, pelo que o resultado é a1b#c3.

Se não for encontrada correspondência, a cadeia de origem é devolvida inalterada.

Para reutilizar texto correspondente na substituição, especifique TEMPLATE. Neste modo, \0\9 através de referir-se ao jogo completo e aos grupos de captura, insere \\ uma barra diagonal literal. Use um literal de string bruto, prefixado com @, para passar estas referências sem escape adicional:

RETURN MSFT.REGEXP_REPLACE(
  'John Smith',
  @'([A-Za-z]+) ([A-Za-z]+)',
  TEMPLATE @'\2 \1'
) AS reordered_name

O resultado é Smith John.

Regras e opções de correspondência

Os padrões usam a sintaxe de expressões regulares do RE2 e correspondem às strings Unicode. A fonte pode ser qualquer expressão de cadeia. O padrão, os flags e a substituição devem ser literais de string, e as opções numéricas devem ser literais inteiros sem sinal.

As correspondências são encontradas da esquerda para a direita sem sobreposição. Após uma correspondência de comprimento zero, a correspondência avança um ponto de código Unicode.

As posições iniciais e as posições retornadas são deslocamentos de pontos de código Unicode baseados em zero. Os números de ocorrência são baseados em um, exceto que ocorrência 0 significa substituir todas as ocorrências em MSFT.REGEXP_REPLACE.

A tabela seguinte lista os valores predefinidos para argumentos opcionais omitidos:

As bandeiras opcionais são:

Combinar flags numa única cadeia, como 'ims'. Uma fonte nula devolve nula. Uma flag não suportada, expressão regular inválida, opção de retorno inválida ou ocorrência inválida ou número de grupo retornam um erro.

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.
• element_id(node_or_edge) - devolve o identificador de nó ou aresta como uma cadeia opaca.

ELEMENT_ID aceita uma referência de nó ou aresta e devolve nulo para uma entrada nula. Trate a corda devolvida como opaca.

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) - reduz uma lista para no máximo n elementos.

Exemplo:

MATCH (p:Person)-[:hasInterest]->(t:Tag)
LET personId = p.id, personName = p.firstName
RETURN personId, personName, collect_list(t.name) AS interests
GROUP BY personId, personName
FILTER size(interests) > 3

Funções temporais

• CURRENT_TIMESTAMP - devolve a data-hora zoneada atual.
• ZONED_DATETIME(string) - devolve a data-hora zoneada representada por uma cadeia ISO 8601.
• DURATION(string) - devolve a duração diurna, representada por uma cadeia de duração ISO 8601.

Exemplo:

RETURN CURRENT_TIMESTAMP AS now,
       DURATION('PT2H') AS twoHours

Use o operador de subtração para obter uma duração entre dois datas-horários zonados:

RETURN ZONED_DATETIME('2026-09-17T12:00:00Z')
       - ZONED_DATETIME('2026-09-17T10:00:00Z') AS elapsed

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
• Padrões gráficos
• Filtrar e agregar dados de grafos