Microsoft Sentinel グラフの Graph クエリ言語 (GQL) リファレンス (プレビュー)

適用対象: Microsoft Sentinel Graph

注:

GQL のサポートはプレビュー段階です。機能と構文は、フィードバックと進行中の開発に基づいて変更できます。

このリファレンスでは、Graph クエリ言語 (GQL) の基本的な概念、関数、演算子について説明します。 Graph Query Language (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 ラベルを持つノードに一致を制限します
ラベルの組み合わせ: AND に & を使用し、OR 操作に | します

エッジパターン

エッジパターンは、ノードが相互に接続する方法を定義します。

-[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): ノードには、少なくとも 1 つの指定されたラベルが必要です
! (NOT): ノードに指定されたラベルを含めてはなりません
() : 複雑な式をグループ化するためのかっこ

パスパターン

パスパターンは、グラフ内のマルチホップリレーションシップを表します。

(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 では、グラフデータに対するパターンの照合方法を制御するさまざまなパスマッチングモードがサポートされています。これらのモードは、パフォーマンス、結果の完全性、および返されるパスの種類に影響します。

一致モードは、1 つの MATCH 句内のパターン変数間でグラフ要素を再利用する方法を制御します。

異なるエッジ (既定値)

既定のモード。一致したエッジを複数のエッジ変数にバインドすることはできませんが、ノードは自由に再利用できます。

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

REPEATABLE 要素

エッジとノードの両方を、制限なしでパターン変数間で再利用できるようにします。

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

パスモード

パスモードは、繰り返し制約に基づいて結果に含めるパスの種類を制御します。

トレイル

繰り返しエッジを持つパスをフィルター処理します。ノードは繰り返すことができますが、各エッジはパスごとに 1 回だけ表示できます。

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)
省略可能な一致	存在しない可能性があるパターンを検索する	OPTIONAL MATCH (p)->(c:City)
WHERE	パターンとプロパティをフィルター処理する	WHERE person.age > 25
FILTER	WHERE と同等ですが、MATCH 句なしで使用されます	FILTER p.name = 'Carol' OR c.name = 'Seattle'
IS NULL	null 値を確認する	WHERE person.age IS NULL
IS NOT NULL	null 以外の値を確認する	WHERE person.age IS NOT NULL
Return	プロジェクトの結果	return person.name, person.age
DISTINCT	一意の値を返す	DISTINCT person.name を返す
COUNT(*)	すべての行をカウントする	RETURN COUNT(*)
Count()	null 以外の値をカウントする	RETURN COUNT(person.name)
SUM()	数値の合計	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)
で始まる	文字列はパターンで始まります	where person.name STARTS WITH 'Tom'
で終わる	文字列はパターンで終わる	where person.name ends with 'Hanks'
CONTAINS	文字列にはパターンが含まれます	WHERE person.name CONTAINS 'Tom'
\|\|	文字列の結合	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()	文字列から datetime を作成する	ZONED_DATETIME('2024-01-01')
PATH_LENGTH()	パスの長さを取得する	RETURN PATH_LENGTH(path_variable)
ORDER BY	結果の並べ替え	ORDER BY person.age DESC
制限	結果の数を制限する	LIMIT 10
& (AND)	ラベルの交差部分	MATCH (p:Person & Male)
\|(OR)	ラベル共用体	MATCH (n:Person \|ムービー)
! (NOT)	ラベルの否定	MATCH (p:!女性)

ベストプラクティス

GQL では、動的型の処理方法が明確に定義されていません。ランタイムエラーを回避するには、入れ子になったフィールドを予期される型に明示的にキャストします (CAST を参照してください)。

パフォーマンスの最適化

運用環境で GQL クエリのパフォーマンスを最適化するには、次の戦略を使用します。

ヒント

単純なパターンから始めて、必要に応じて複雑さを増します。クエリのパフォーマンスを監視し、パスの長さとフィルターを調整して結果を改善します。

パスマッチングスコープを制限する:

特定のラベルフィルターを使用して、MATCH (開始) ではなく MATCH (start:SpecificType) という検索領域を減らす
適切な境界を持つ可変長パスを制限する: 無制限パスではなく 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 は予約済みキーワード (keyword))。グラフデータに GQL 予約キーワードと競合するプロパティ名がある場合は、グラフスキーマで異なるプロパティ名を使用するか、競合を解析しないように名前を変更します。

重要

グラフスキーマを設計するときに、一般的なプロパティ名の一部が GQL 予約キーワードと競合する可能性があります。これらのプロパティ名は避けるか、名前を変更してください。

INSERT/CREATE のサポートなし: グラフ構造を変更する操作はサポートされていません。
オプションの一致: ノードパターン (エッジではなく) でのみサポートされます。
エンティティ等価性チェックはサポートされていません:GQL の (MATCH (n)-[]-(n2) WHERE n1 <> n2) はサポートされていません。たとえば、明示的なフィールド比較を代わりに使用する n.id <> n2.id
時刻とタイムゾーン: エンジンは UTC で動作します。 Datetime リテラルでは、ゾーン化された datetime を使用する必要があります。 ZONED_DATETIME("2011-12-31 23:59:59.9")を使用してサポートされているのは UTC ゾーンのみです。
期間の細分性: 期間では、最大日数とナノ秒までの小さな単位がサポートされます。 1 日を超える単位 (週、月、年など) はサポートされていません。

Labels() カスタム GQL 関数

labels()関数は、ノードまたはエッジのラベルを配列として表示します。

構文:

labels(entity)

Parameters:entity: 一致するパターンのノードまたはエッジ変数。

返します：

指定したエンティティのすべてのラベルを持つ文字列の配列を返します。

例:

一致したノードのラベルを表示します。

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

出力

このクエリでは、グラフ内の各ノードの名前とすべてのラベルが表示されます。

entity.name	labels(entity)
john.doe	["User"]
admin.user	["User"]
web-server	["System"]
データベース	["System"]
domain-controller	["System"]

エイリアスを使用してプロジェクションにラベルを表示する:

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	["User"]	["CAN_ACCESS"]	web-server
admin.user	["User"]	["CAN_ACCESS"]	domain-controller
web-server	["System"]	["CAN_ACCESS"]	データベース
domain-controller	["System"]	["CAN_ACCESS"]	データベース

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-04-23