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

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

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

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 retornar uma ou mais linhas.
• FALSE se a subconsulta não retorna linhas.

Variáveis já no escopo estão implicitamente disponíveis dentro da subconsulta. Variáveis introduzidas apenas dentro da subconsulta não estão disponíveis fora dela.

Use EXISTS em um 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 retorna linhas. Você também pode usar EXISTS em LET, RETURN, ORDER BY, e agregar filtros ou expressões de fonte. EXISTS não é suportado dentro de um filtro de predicados de lista.

Para mais informações sobre subconsultas correlacionadas, veja a CALL declaração no guia da 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 de um padrão de comprimento variável.

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

O exemplo a seguir avalia todas as quatro funções sobre uma lista construída dinamicamente:

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 retornados são TRUE.

Você 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

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 retorna UNKNOWN. Um elemento de lista nulo contribui com o resultado de avaliar o filtro com esse elemento vinculado a nulo; ele 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 da consulta anexada. Se a variável elemento tiver o mesmo nome de uma variável externa, a variável local de elemento tem precedência. Predicados de lista aninhada podem igualmente sombrear uma variável de elemento externo.

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

ANY(...) é uma função de lista de predicados. Não confunda com o prefixo ANY SHORTEST de busca de caminho ou o ANY tipo de valor dinâmico.

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'

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)

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

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 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 transbordando 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) retorna uma lista de inteiros de start em direção enda , 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 alcance inclui start. Só inclui end quando adicionam step repetidamente os alcances end exatos. Um passo positivo com start maior que end, ou um passo negativo com start menor que end, retorna 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, retorna a LIST<INT64> e rejeita valores que não podem ser representados com segurança como inteiros com sinal.

Funções de agregação

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 possui colunas de agrupamento e não recebe linhas de entrada, COUNT retorna 0, COLLECT_LIST e COLLECT_ELEMENTS retorna uma lista vazia, e as outras funções agregadas retornam nula. Não confie na ordem dos valores retornados por um agregado de coleção. Com agrupamento de colunas, nenhuma linha de entrada produz grupo e, portanto, nenhuma linha de resultado.

Quantificadores de conjuntos

Use ALL para incluir valores duplicados ou DISTINCT removê-los. 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 não faz COLLECT_ONE com que seja determinística.

Filtros e limites específicos de agregados

Adicione FILTER (WHERE predicate) após um agregado para incluir apenas valores para que predicate seja verdadeiro. Resultados falsos e de predicados desconhecidos são excluídos. Esse 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 as linhas de entrada qualificadas. A filtragem ocorre antes do limite específico do agregado e DISTINCT é aplicada após esse 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 as etapas de agregação quando precisar agregar um resultado agregado.

Agregação dentro de um caminho pareado

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: ele 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) retorna 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 para agregados ou LIMIT não são formas horizontais.

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

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

Nesta consulta, COUNT(knows) calcula um comprimento por caminho pareado 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 retorne 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 igual b, caso contrário, retornará a.

Example:

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 rotear linhas por predicados e executar uma instrução de consulta ou procedimento aninhado para o desvio selecionado, 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 caractere e caso

Use estas funções para medir ou alterar as sequências de caracteres:

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, respectivamente. CASEFOLD não é equivalente a LOWER. Por exemplo, a dobragem de casos mapeia ß para ss e mapeia as formas Σsigma gregas , σ, e ς para σ.

Normalizar cordas

O GQL define quatro formulários 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) O padrão é NFC. Especifique uma forma de normalização como segundo argumento:

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

O argumento deve ser um fio.

Cordas de corte

Use TRIM para remover caracteres de espaço ou um caractere 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 de trim personalizado 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 retorna nulo.

Join strings

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 retorna uma cadeia vazia. Uma lista nula, delimitador nulo ou elemento de lista nula retorna nula. Todo elemento de lista não nulo deve ser uma string.

Funções de expressão regular

O Graph fornece essas 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 sequência de origem. Se nenhuma correspondência for encontrada, retorna FALSE.

source é a cadeia para pesquisar. pattern é pareado com qualquer substring de source , a menos que a expressão em si use âncoras como ^ ou $. flags muda 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

Retorna o número de correspondências. Se nenhuma correspondência for encontrada, retorna 0.

source é a cadeia a ser pesquisada e pattern identifica as correspondências a serem contadas. start é a posição de ponto de código Unicode baseada em zero na qual o emparelhamento pode começar. Uma partida deve começar nessa posição ou após ela. A posição não se torna um novo começo da corda para padrões ancorados. flags muda 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 busca começa na posição 3, a segunda a, então apenas os dígitos 3 e 4 são contados. O resultado é 2.

MSFT.REGEXP_INSTR

Retorna 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 na qual o emparelhamento pode começar. Uma partida deve começar nessa posição ou depois, o que não se torna um novo começo da corda para padrões ancorados.

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

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

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

A segunda partida começa na posição 3, então o resultado é 3.

MSFT.REGEXP_SUBSTR

Retorna 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 na qual o emparelhamento pode começar. Uma partida deve começar nessa posição ou depois, o que não se torna um novo começo da corda para padrões ancorados.

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

Se nenhuma ocorrência correspondente for encontrada, ou se o grupo de captura selecionado não participar dessa ocorrência, a função retorna 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, então o resultado é 345.

MSFT.REGEXP_REPLACE

Substitui o texto correspondente. Por padrão, ele substitui cada correspondência e insere o texto de substituição literalmente.

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

start é a posição de ponto de código Unicode baseada em zero na qual a substituição pode começar. Uma partida deve começar nessa posição ou após ela. O texto antes start é preservado inalterado, e a posição não se torna um novo começo da sequência para padrões ancorados. Defina occurrence para 0 substituir toda correspondência de start, ou para um valor positivo para substituir apenas aquela correspondência numerada não sobreposta. Partidas anteriores permanecem start inalteradas quando uma ocorrência específica é selecionada. flags muda 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, então o resultado é a1b#c3.

Se nenhuma correspondência for encontrada, a cadeia de origem é retornada inalterada.

Para reutilizar texto correspondente no substituto, especifique TEMPLATE. Neste modo, \0 por meio \9 de referência, ao conjunto completo de partidas e captura, insere \\ uma barra inversa literal. Use um literal de string bruto, prefixado com @, para passar essas 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

Padrões usam sintaxe de expressões regulares do RE2 e combinam com strings Unicode. A fonte pode ser qualquer expressão de string. O padrão, as 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 em 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 toda ocorrência em MSFT.REGEXP_REPLACE.

A tabela a seguir lista os padrões para argumentos opcionais omitidos:

As bandeiras opcionais são:

Combine flags em uma única string, como 'ims'. Uma fonte nula retorna 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 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.
• element_id(node_or_edge) - retorna o identificador de nó ou aresta como uma string opaca.

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

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

Example:

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 – retorna o datetime zoneado atual.
• ZONED_DATETIME(string) - retorna a data-hora zonificada representada por uma cadeia ISO 8601.
• DURATION(string) - retorna a duração diurna representada por uma string de duração ISO 8601.

Example:

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

Use o operador de subtração para derivar uma duração entre dois datas zonificadas:

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

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
• Padrões de grafo
• Filtrar e agregar dados de grafo