Referência da Linguagem de Consulta do Graph (GQL) para Microsoft Sentinel grafo (pré-visualização)

Aplica-se a: Microsoft Sentinel Graph

Nota

O suporte do GQL está em pré-visualização. As funcionalidades e a sintaxe podem mudar com base nos comentários e no desenvolvimento contínuo.

Esta referência abrange os conceitos, funções e operadores fundamentais da Linguagem de Consulta Graph (GQL). A Linguagem de Consulta Graph (GQL) baseia-se em conceitos matemáticos de teoria de grafos que fornecem uma base sólida para consultar dados de gráficos. Compreender estes conceitos básicos ajuda-o a escrever consultas mais eficazes e a compreender melhor como a GQL processa os seus dados. A GQL também fornece um conjunto avançado de funções e operadores para trabalhar com padrões de gráficos, nós, arestas e propriedades.

Conceitos fundamentais

Esta secção abrange os principais conceitos que formam a base da análise de dados de grafos com a GQL.

Padrões de gráficos

Os padrões de gráficos são os principais blocos modulares das consultas GQL. Descrevem a estrutura que pretende encontrar nos seus dados de grafos através de uma sintaxe declarativa que espelha a representação visual dos gráficos.

Padrões de nós

Os padrões de nós especificam como corresponder nós individuais no gráfico:

(n)                 -- Any node
(n:Person)          -- Node with Person label
(n:Person&City)     -- Node with Person AND City label
(:Person)           -- Person node, don't bind variable

Conceitos-chave:

Enlace de variável: (n) cria uma variável n que pode referenciar mais tarde na consulta
Nós anónimos: (:Person) corresponde a nós sem criar uma variável
Filtragem de etiquetas: :Person restringe as correspondências aos nós com a etiqueta Pessoa
Combinações de etiquetas: utilizar & para operações E, | para operações OR

Padrões edge

Os padrões edge definem a forma como os nós se ligam entre si:

-[e]->                  -- Directed outgoing edge, any label 
-[e:works_at]->         -- Directed edge, works_at label
-[e:knows|likes]-->    -- knows OR likes edge
<-[e]-                  -- Directed incoming edge
-[e]-                   -- Undirected (any direction)

Conceitos-chave:

Direção: -> para saída, <- para entrada, - para qualquer direção
Tipos de arestas: utilize etiquetas como :works_at para filtrar por tipo de relação
Vários tipos: knows|likes corresponde a qualquer um dos tipos de relação

Expressões de etiqueta

As etiquetas fornecem um significado semântico aos nós e arestas. A GQL suporta expressões de etiqueta complexas:

:Person&amp;Company     -- Both Person AND Company labels 
:Person|Company        -- Person OR Company labels
:!Company               -- NOT Company label
:(Person|!Company)&City -- Complex expressions with parentheses

Operadores

& (E): O nó tem de ter todas as etiquetas especificadas
| (OU): O nó tem de ter, pelo menos, uma etiqueta especificada
! (NÃO): O nó não pode ter a etiqueta especificada
() : Parênteses para agrupar expressões complexas

Padrões de caminho

Os padrões de caminho descrevem relações de vários saltos no gráfico:

(a)-[e1]->;(b)-[e2]->(c)     -- 2-hop path 
(a)-[e]->;{2,4}(b)              -- 2 to 4 hops
(a)-[e]->{1,}(b)             -- 1 to maximum of 8 hops
(a)-[:knows|likes]->;{1,3}(b)  -- 1-3 hops via knows/likes 
p=()-[:works_at]->()         -- Binding a path variable

Caminhos de comprimento variável:

{2,4}: Exatamente 2 a 4 saltos
{1,}: 1 ou mais saltos (não vinculados). As consultas de caminho não vinculadas estão limitadas a 8 saltos.
{,5}: até 5 saltos
{5}: Exatamente 5 saltos

Variáveis de caminho

p=()->(): captura todo o caminho para análise posterior
Acesso com NODES(p), , RELATIONSHIPS(p)PATH_LENGTH(p)

Múltiplos padrões

A GQL suporta estruturas de gráficos complexas e não lineares:

(a)->(b), (a)->(c)          -- Multiple edges from same node
(a)->(b)<-(c), (b)->(d)     -- Non-linear structures

Composição do padrão:

Utilizar vírgulas , para separar múltiplos padrões
Todos os padrões têm de corresponder em simultâneo
As variáveis podem ser partilhadas entre padrões

Modos de correspondência

A GQL suporta diferentes modos de correspondência de caminhos que controlam a forma como os padrões são correspondidos com os dados de gráficos. Estes modos afetam o desempenho, a conclusão dos resultados e os tipos de caminhos que são devolvidos.

Os modos de correspondência controlam a forma como os elementos do grafo podem ser reutilizados em variáveis de padrão numa única cláusula MATCH.

ARESTAS DIFERENTES (predefinição)

O modo predefinido. Um limite correspondente não pode vincular-se a mais do que uma variável de limite, mas os nós podem ser reutilizados livremente.

MATCH (a)-[r1]->(b)-[r2]->(c) 
-- r1 and r2 must be different edges
-- a, b, c can be the same or different nodes

ELEMENTOS REPETÍVEIS

Permite que as arestas e os nós sejam reutilizados em variáveis de padrão sem restrições.

MATCH REPEATABLE ELEMENTS (a)-[r1]->(b)-[r2]->(c)
-- r1 and r2 can be the same edge
-- a, b, c can be the same or different nodes

Modos de caminho

Os modos de caminho controlam os tipos de caminhos incluídos nos resultados com base em restrições de repetição.

TRAIL

Filtra caminhos com arestas repetidas. Os nós podem repetir-se, mas cada aresta só pode aparecer uma vez por caminho.

MATCH TRAIL (a)-[]->{1,3}(b)
-- No edge can appear twice in the same path
-- Nodes may repeat

Referência de funções e operadores

A Linguagem de Consulta Graph (GQL) fornece um conjunto avançado de funções e operadores para trabalhar com padrões de gráficos, nós, arestas e propriedades.

Funções e operadores DE GQL principais

A tabela seguinte lista os principais operadores e funções GQL e exemplos.

Função GQL/Operador	Descrição	Exemplo de GQL
MATCH	Localizar padrões de gráficos	CORRESP (a)-[r]->(b)
CORRESPONDÊNCIA OPCIONAL	Localizar padrões que podem não existir	CORRESP OPCIONAL (p)->(c:Cidade)
WHERE	Filtrar padrões e propriedades	WHERE person.age > 25
FILTRAR	Equivalente a WHERE, mas utilizado sem cláusulas MATCH	FILTER p.name = 'Carol' OR c.name = 'Seattle'
É NULO	Verificar se existem valores nulos	WHERE person.age IS NULL
NÃO É NULO	Verificar se existem valores não nulos	WHERE person.age IS NOT NULL
ENTER	Resultados do projeto	DEVOLVER person.name, pessoa.idade
DISTINCT	Devolver valores exclusivos	DEVOLVER PERSON.NAME DISTINCT
CONTAR(*)	Contar todas as linhas	CONTAGEM DE DEVOLUÇÕES(*)
CONTAR()	Contar valores não nulos	CONTAGEM DE DEVOLUÇÕES(person.name)
SOMA()	Somar valores numéricos	DEVOLVER SOMA(pessoa.idade)
MIN()	Valor mínimo	DEVOLVER MÍN(pessoa.idade)
MÁX.()	Valor máximo	DEVOLVER MÁXIMO(pessoa.idade)
AVG()	Valor médio	DEVOLVER MÉDIA(pessoa.idade)
COLLECT_LIST()	Recolher valores na matriz	COLLECT_LIST RETURN (person.name)
TAMANHO()	Comprimento da matriz	TAMANHO DA DEVOLUÇÃO(COLLECT_LIST(n.firstName))
labels()	Mostrar etiquetas para um nó ou limite	Return labels(entity)
MAIÚSCULA()	Converter em maiúsculas	DEVOLVER MAIÚSCULA(person.name)
LOWER()	Converter em minúsculas	DEVOLVER INFERIOR(person.name)
COMEÇA COM	Cadeia começa com padrão	WHERE person.name STARTS WITH 'Tom'
TERMINA COM	Cadeia termina com padrão	ONDE PERSON.NAME TERMINA COM 'Hanks'
CONTÉM	Cadeia contém padrão	WHERE person.name CONTÉM 'Tom'
\|\|	Concatenação de cadeias	RETURN n.firstName \|\| ' ' \|\| n.lastName
COMPACTAR()	Remover espaço em branco de ambas as extremidades	RETURN TRIM(' abc ')
STRING_JOIN()	Associar elementos de matriz com delimitador	DEVOLVER STRING_JOIN(["a", "b" \|\| "c"], "-")
CAST()	Converter tipos de dados	CAST(person.age AS STRING)
ZONED_DATETIME()	Criar datetime a partir da cadeia	ZONED_DATETIME('2024-01-01')
PATH_LENGTH()	Obter o comprimento de um caminho	ENTER PATH_LENGTH(path_variable)
ORDENAR POR	Ordenar resultados	ORDER BY person.age DESC
LIMITE	Limitar contagem de resultados	LIMITE 10
& (E)	Interseção de etiquetas	CORRESP (p:Pessoa & Homem)
\| (OU)	União de etiquetas	CORRESP (n:Pessoa \| Filme)
! (NÃO)	Negação de etiquetas	CORRESP (p:! Mulher)

Best practices

A GQL não define claramente como os tipos dinâmicos devem ser processados. Para evitar erros de runtime, cast explicitamente campos aninhados para o tipo esperado (veja CAST).

Otimização do desempenho

Utilize estas estratégias para otimizar o desempenho de consultas GQL em ambientes de produção:

Sugestão

Comece com padrões simples e, em seguida, aumente a complexidade, se necessário. Monitorize o desempenho das consultas e ajuste os comprimentos e filtros do caminho para melhorar os resultados.

Limite o âmbito de correspondência de caminhos:

Utilize filtros de etiqueta específicos para reduzir o espaço de pesquisa: CORRESP (início:SpecificType) em vez de CORRESP (início)
Limitar caminhos de comprimento variáveis com limites razoáveis: CORRESP (a)-[]->{1,3}(b) em vez de caminhos não vinculados
Aplique as cláusulas WHERE mais cedo para filtrar os resultados antes de operações dispendiosas.

Utilize COUNT(*) para verificações de existência:

Se apenas precisar de verificar se existe um padrão, utilize CONTAR(*) em vez de devolver os resultados completos.

MATCH (user:User)-[:SUSPICIOUS_ACTIVITY]->(target)
WHERE user.id = 'user123'
RETURN COUNT(*) > 0 AS HasSuspiciousActivity

Limitações

Estrutura de consulta: todas as consultas GQL têm de começar com uma instrução CORRESP.
Palavras-chave reservadas: algumas palavras-chave GQL não podem ser utilizadas como identificadores em consultas. Algumas palavras-chave reservadas não são imediatamente óbvias (por exemplo, DATA é uma palavra-chave reservada). Se os dados do gráfico tiverem nomes de propriedades que entrem em conflito com palavras-chave reservadas do GQL, utilize nomes de propriedades diferentes no esquema do gráfico ou mude o nome dos mesmos para evitar conflitos de análise.

Importante

Quando estrutura o esquema de gráfico, alguns nomes de propriedades comuns podem entrar em conflito com palavras-chave reservadas do GQL. Evite ou mude o nome destes nomes de propriedade.

Sem suporte INSERT/CREATE: as operações para alterar as estruturas de gráficos não são suportadas.
Correspondências opcionais: suportadas apenas para padrões de nós (não arestas).
As verificações de equivalência de entidades não são suportadas: as GQL não são suportadas.(MATCH (n)-[]-(n2) WHERE n1 <> n2) Em vez disso, utilize comparações de campos explícitas, por exemplo n.id <> n2.id
Hora e fuso horário: o motor funciona em UTC. Os literais datetime têm de utilizar datetime com zona; apenas a zona UTC é suportada através de ZONED_DATETIME("2011-12-31 23:59:59.9").
Granularidade da duração: as durações suportam até dias e unidades mais pequenas até nanossegundos. As unidades maiores do que o dia (por exemplo, semanas, meses, anos) não são suportadas.

Etiquetas() função GQL personalizada

A labels() função mostra as etiquetas de um nó ou limite como uma matriz.

Sintaxe:

labels(entity)

Parâmetros:entity: uma variável de nó ou limite de um padrão correspondente.

Devolve:

Devolve uma matriz de cadeias com todas as etiquetas para a entidade especificada.

Exemplos:

Mostrar etiquetas para nós correspondentes:

MATCH (entity)
RETURN entity.name, labels(entity)

Saída

Esta consulta mostra o nome e todas as etiquetas de cada nó no gráfico.

entity.name	labels(entity)
john.doe	["Utilizador"]
admin.user	["Utilizador"]
servidor Web	["Sistema"]
base de dados	["Sistema"]
controlador de domínio	["Sistema"]

Mostrar etiquetas em projeções com aliases:

MATCH (n)-[e]->(target)
RETURN n.name, labels(n) AS n_labels, labels(e) AS edge_labels, target.name

Esta consulta mostra os nomes dos nós, as respetivas etiquetas e as etiquetas das arestas de ligação.

n.name	n_labels	edge_labels	target.name
john.doe	["Utilizador"]	["CAN_ACCESS"]	servidor Web
admin.user	["Utilizador"]	["CAN_ACCESS"]	controlador de domínio
servidor Web	["Sistema"]	["CAN_ACCESS"]	base de dados
controlador de domínio	["Sistema"]	["CAN_ACCESS"]	base de dados

Comentários

Esta página foi útil?

Last updated on 2026-04-23