Справочник по языку запросов Graph (GQL) для Microsoft Sentinel graph (предварительная версия)

Область применения: Microsoft Sentinel Graph

Примечание.

Поддержка GQL доступна в предварительной версии. Функции и синтаксис могут изменяться в зависимости от отзывов и текущей разработки.

В этом справочнике рассматриваются основные понятия, функции и операторы языка запросов Graph (GQL). Язык запросов графа (GQL) основан на концепциях математической теории графов, которые обеспечивают надежную основу для запроса данных графа. Понимание этих основ помогает создавать более эффективные запросы и лучше понимать, как GQL обрабатывает данные. GQL также предоставляет широкий набор функций и операторов для работы с шаблонами графов, узлами, ребрами и свойствами.

Основные принципы

В этом разделе рассматриваются основные понятия, которые формируют основу анализа данных графа с помощью GQL.

Шаблоны графов

Шаблоны графов являются основными стандартными блоками запросов GQL. Они описывают структуру, которую вы хотите найти в данных графа, используя декларативный синтаксис, который отражает визуальное представление графов.

Шаблоны узлов

Шаблоны узлов указывают, как сопоставлять отдельные узлы в графе:

(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

Основные понятия:

Привязка переменных. (n) Создает переменную n, на которую можно будет ссылаться позже в запросе.
Анонимные узлы: (:Person) соответствует узлам без создания переменной
Фильтрация меток: :Person совпадения ограничиваются узлами с меткой Person
Сочетания меток: используйте & для и для | операций OR

Шаблоны ребер

Шаблоны edge определяют, как узлы соединяются друг с другом:

-[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)

Основные понятия:

Направление: -> для исходящего, <- для входящего, - для любого направления
Типы ребер: используйте метки, например :works_at , для фильтрации по типу связи
Несколько типов: knows|likes соответствует одному из типов связей

Выражения меток

Метки обеспечивают семантическое значение узлов и ребер. GQL поддерживает сложные выражения меток:

: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

Операторы

& (AND): Узел должен иметь все указанные метки.
| (OR): Узел должен иметь по крайней мере одну указанную метку.
! (НЕ): узел не должен иметь указанную метку.
() : круглые скобки для группирования сложных выражений

Шаблоны путей

Шаблоны путей описывают связи с несколькими прыжками в графе:

(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

Пути переменной длины:

{2,4}: ровно от 2 до 4 прыжков
{1,}: 1 или более прыжков (без ограничений). Запросы неограниченного пути ограничены 8 прыжками.
{,5}: до 5 прыжков
{5}: ровно 5 прыжков

Переменные пути

p=()->(): записывает весь путь для последующего анализа.
Доступ с помощью NODES(p), RELATIONSHIPS(p)PATH_LENGTH(p)

Несколько шаблонов

GQL поддерживает сложные нелинейные структуры графов:

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

Состав шаблона:

Использование запятых , для разделения нескольких шаблонов
Все шаблоны должны совпадать одновременно
Переменные можно совместно использовать в разных шаблонах

Режимы сопоставления

GQL поддерживает различные режимы сопоставления путей, которые определяют, как шаблоны сопоставляются с данными графа. Эти режимы влияют на производительность, полноту результатов и типы возвращаемых путей.

Режимы сопоставления управляют тем, как элементы графа можно повторно использовать между переменными шаблона в рамках одного предложения MATCH.

РАЗНЫЕ РЕБРА (по умолчанию)

Режим по умолчанию. Совпадающее ребро не может быть привязано к нескольким переменным ребер, но узлы можно использовать повторно.

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

ПОВТОРЯЕМЫЕ ЭЛЕМЕНТЫ

Позволяет повторно использовать ребра и узлы в переменных шаблона без ограничений.

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

Режимы пути

Режимы пути определяют, какие типы путей включаются в результаты на основе ограничений повторения.

СЛЕД

Фильтрует пути с повторяющимися ребрами. Узлы могут повторяться, но каждый ребро может отображаться только один раз для каждого пути.

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

Справочник по функциям и операторам

Язык запросов Graph (GQL) предоставляет широкий набор функций и операторов для работы с шаблонами графов, узлами, ребрами и свойствами.

Основные функции и операторы GQL

В следующей таблице перечислены основные функции и операторы GQL, а также примеры.

Функция или оператор GQL	Описание	Пример GQL
MATCH	Поиск шаблонов графов	MATCH (a)-[r]-(>b)
НЕОБЯЗАТЕЛЬНОЕ СООТВЕТСТВИЕ	Поиск шаблонов, которые могут не существовать	НЕОБЯЗАТЕЛЬНОЕ СОПОСТАВЛЕНИЕ (p)->(c:City)
WHERE	Шаблоны и свойства фильтра	WHERE person.25 >
ФИЛЬТР	Эквивалент WHERE, но используется без предложений MATCH	FILTER p.name = "Кэрол" ИЛИ c.name = "Сиэтл"
ЯВЛЯЕТСЯ NULL	Проверка значений NULL	WHERE person.age IS NULL
НЕ ИМЕЕТ ЗНАЧЕНИЯ NULL	Проверка значений, отличных от NULL	WHERE person.age IS NOT NULL
RETURN	Результаты проекта	RETURN person.name, person.age
РАЗЛИЧНЫХ	Возвращение уникальных значений	RETURN DISTINCT person.name
COUNT(*)	Подсчет всех строк	RETURN COUNT(*)
COUNT()	Подсчет значений, отличных от NULL	RETURN COUNT(person.name)
СУММ()	Суммирование числовых значений	RETURN SUM(person.age)
MIN()	Минимальное значение	RETURN MIN(person.age)
MAX()	Максимальное значение	RETURN MAX(person.age)
AVG()	Среднее значение	RETURN AVG(person.age)
COLLECT_LIST()	Сбор значений в массив	RETURN COLLECT_LIST(person.name)
SIZE()	Длина массива	RETURN SIZE(COLLECT_LIST(n.firstName))
labels()	Отображение меток для узла или ребра	Return labels (entity)
UPPER()	Преобразование в верхний регистр	RETURN UPPER(person.name)
LOWER()	Преобразование в нижний регистр	RETURN LOWER(person.name)
НАЧИНАЕТСЯ С	Строка начинается с шаблона	ГДЕ person.name НАЧИНАЕТСЯ С "Том"
ЗАКАНЧИВАЕТСЯ НА	Строка заканчивается шаблоном	ГДЕ person.name ЗАКАНЧИВАЕТСЯ С "Хэнкс"
CONTAINS	Строка содержит шаблон	WHERE person.name СОДЕРЖИТ "Том"
\|\|	Объединение строк	RETURN n.firstName \|\| ' ' \|\| n.lastName
TRIM()	Удаление пробелов с обоих концов	RETURN TRIM(' abc ')
STRING_JOIN()	Объединение элементов массива с разделителем	RETURN STRING_JOIN(["a", "b" \|\| "c"], "-")
CAST()	Преобразование типов данных	CAST(person.age AS STRING)
ZONED_DATETIME()	Создание даты и времени из строки	ZONED_DATETIME('2024-01-01')
PATH_LENGTH()	Получение длины пути	RETURN PATH_LENGTH(path_variable)
конструкция ORDER BY	Сортировать результаты	ORDER BY person.age DESC
ПРЕДЕЛ	Ограничение числа результатов	ОГРАНИЧЕНИЕ 10
& (AND)	Пересечение меток	MATCH (p:Person и Male)
\| (ИЛИ)	Объединение меток	MATCH (n:Person \| Фильм)
! (НЕ)	Отрицание метки	MATCH (p:! Женский)

Лучшие методики

GQL не определяет, как следует обрабатывать динамические типы. Чтобы избежать ошибок среды выполнения, явно приведите вложенные поля к их ожидаемому типу (см. cast).

Оптимизация производительности

Используйте следующие стратегии для оптимизации производительности запросов GQL в рабочих средах:

Совет

Начните с простых шаблонов, а затем повысьте сложность при необходимости. Отслеживайте производительность запросов и настраивайте длину пути и фильтры для улучшения результатов.

Ограничение область сопоставления путей:

Использование определенных фильтров меток для сокращения пространства поиска: MATCH (start:SpecificType) вместо MATCH (start)
Ограничение путей переменной длины с разумными границами: MATCH (a)-[]->{1,3}(b) вместо неограниченных путей
Применяйте предложения WHERE на ранней стадии, чтобы фильтровать результаты перед дорогостоящими операциями.

Используйте COUNT(*) для проверок существования:

Если вам нужно проверка только если шаблон существует, используйте COUNT(*) вместо возврата полных результатов.

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

Ограничения

Структура запроса. Все запросы GQL должны начинаться с инструкции MATCH.
Зарезервированные ключевые слова. Некоторые ключевые слова GQL не могут использоваться в качестве идентификаторов в запросах. Некоторые зарезервированные ключевые слова не сразу очевидны (например, DATE является зарезервированным ключевое слово). Если данные графа имеют имена свойств, конфликтующие с зарезервированными ключевыми словами GQL, используйте в схеме графа разные имена свойств или переименуйте их, чтобы избежать конфликтов синтаксического анализа.

Важно!

При разработке схемы графа некоторые общие имена свойств могут конфликтовать с зарезервированными ключевыми словами GQL. Избегайте или переименуйте имена этих свойств.

Нет поддержки INSERT/CREATE: операции по изменению структур графа не поддерживаются.
Необязательные совпадения: поддерживается только для шаблонов узлов (не ребер).
Проверки эквивалентности сущностей не поддерживаются: GQL (MATCH (n)-[]-(n2) WHERE n1 <> n2) не поддерживается. Используйте явное сравнение полей, например n.id <> n2.id
Время и часовой пояс: двигатель работает в формате UTC. Литералы Datetime должны использовать zoned datetime; Только зона UTC поддерживается через ZONED_DATETIME("2011-12-31 23:59:59.9").
Детализация длительности. Продолжительность поддерживает до дней и меньшие единицы до наносекунд. Единицы, превышающие день (например, недели, месяцы, годы), не поддерживаются.

Пользовательская функция GQL Labels()

Функция labels() отображает метки для узла или ребра в виде массива.

Синтаксис:

labels(entity)

Параметры:entity переменная узла или ребер из соответствующего шаблона.

Возвращает:

Возвращает массив строк со всеми метками для указанной сущности.

Примеры.

Отображение меток для сопоставленных узлов:

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

Вывести

Этот запрос показывает имя и все метки для каждого узла графа.

entity.name	labels(entity)
john.doe	["Пользователь"]
admin.user	["Пользователь"]
веб-сервер	["Система"]
Базы данных	["Система"]
контроллер домена	["Система"]

Отображение меток в проекциях с псевдонимами:

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

В этом запросе отображаются имена узлов, их метки и метки соединительных ребер.

n.name	n_labels	edge_labels	target.name
john.doe	["Пользователь"]	["CAN_ACCESS"]	веб-сервер
admin.user	["Пользователь"]	["CAN_ACCESS"]	контроллер домена
веб-сервер	["Система"]	["CAN_ACCESS"]	Базы данных
контроллер домена	["Система"]	["CAN_ACCESS"]	Базы данных

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-04-23