GQL クイック リファレンス

この記事は、Microsoft Fabric のグラフの GQL (Graph クエリ言語) 構文のクイック リファレンスです。 構文やデフォルトを思い出すのに使うのが良いでしょう。 エンドツーエンドの説明については、 GQL言語ガイドをご覧ください。各セクションは詳細を所有する焦点のある参考文献へリンクしています。

クエリ構造

GQL クエリでは、グラフから取得するデータ、その処理方法、結果を表示する方法を定義する一連のステートメントが使用されます。 各ステートメントには特定の目的があり、一緒にグラフのデータと一致する線形パイプラインを作成し、段階的に変換します。

一般的なクエリ フロー:
GQL クエリは、通常、一致するグラフ パターンを指定することから始まります。 次に、変数の作成、フィルター処理、並べ替え、改ページ、結果の出力に省略可能なステートメントを使用します。

Example:

MATCH (n:Person)-[:knows]->(m:Person) 
LET fullName = n.firstName || ' ' || n.lastName 
FILTER m.gender = 'female' 
ORDER BY fullName ASC 
OFFSET 10
LIMIT 5 
RETURN fullName, m.firstName

ステートメントの構成:

• MATCH – 検索するグラフ パターンを指定します。
• LET – 式から変数を定義します。
• FOR – リストを行に展開する。
• CALL – インラインのサブクエリを実行し、その返された列を追加します。
• FILTER – 条件に一致する行を保持します。
• WHEN – 各入力行を最初の一致する条件分岐にルーティングします。
• ORDER BY – 結果を並べ替えます。
• OFFSET – 多数の行をスキップします。
• LIMIT – 行数を制限します。
• RETURN – 最終的な結果を出力します。
• NEXT – 前の段階で返された列を使って別のクエリステージを開始します。

各ステートメントは前のステートメントに基づいて構築されるため、クエリの出力を段階的に調整して整形します。 完全なクエリブロックを組み合わせるために UNION、 UNION DISTINCT、または UNION ALL を使いましょう。 各ステートメントの詳細については、次のセクションを参照してください。

クエリ ステートメント

MATCH

データ内のグラフ パターンを見つけます。

構文 :

MATCH <graph pattern> [ WHERE <predicate> ]
...

Example:

MATCH (n:Person)-[:knows]-(m:Person) WHERE n.birthday > 2000
RETURN *

MATCH ステートメントの詳細については、Graph パターンを参照してください。

させる

式を使用して変数を作成します。

構文 :

LET <variable> = <expression>, <variable> = <expression>, ...
...

Example:

MATCH (n:Person)
LET fullName = n.firstName || ' ' || n.lastName
RETURN fullName

LETステートメントの詳細については、GQL 言語ガイドを参照してください。

FOR

リストを行に展開し、各要素の位置をオプションで返します。

構文 :

FOR <variable> IN <list_expression>
  [ WITH OFFSET <offset_variable> | WITH ORDINALITY <ordinality_variable> ]
...

Example:

FOR value IN [10, 20] WITH OFFSET index
RETURN value, index

WITH OFFSET 0から始まる。 WITH ORDINALITY 1から始まる。

FORステートメントの詳細については、GQL 言語ガイドを参照してください。

CALL

各入力行ごとにインラインのサブクエリを実行します。 すでにスコープ内の変数はサブクエリ内で暗黙的に利用可能です。

構文 :

[ OPTIONAL ] CALL {
  <query statements>
  RETURN <columns>
}
...

サブクエリ内で作成された変数のうち、外部で利用可能なのは最終的な RETURN 文の列のみです。 通常の CALL は、サブクエリが行を返さない場合に外側の行をドロップし、複数の行を返す場合はその行を掛け算します。 OPTIONAL CALL サブクエリが行を返さない場合、 NULL 列の外側行を保持します。

MATCH (p:Person)
CALL {
  MATCH (p)-[:knows]->(friend:Person)
  RETURN count(*) AS friendCount
}
RETURN p.firstName, friendCount

インラインサブクエリの詳細については、 GQL言語ガイドをご覧ください。

フィルター

条件に一致する行を保持します。

構文 :

FILTER [ WHERE ] <predicate>
...

Example:

MATCH (n:Person)-[:knows]->(m:Person)
FILTER WHERE n.birthday > m.birthday
RETURN *

FILTERステートメントの詳細については、GQL 言語ガイドを参照してください。

ORDER BY（並び替え）

結果を並べ替えます。

構文 :

ORDER BY <expression> [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ], ...
...

Example:

MATCH (n:Person)
RETURN *
ORDER BY n.lastName ASC NULLS LAST, n.firstName ASC

ヌル配置はソート方向に依存しません。 デフォルトはASCとDESCの両方でNULLS LASTされており、null値を非null値の前に置くNULLS FIRSTを指定します。

ORDER BYステートメントの詳細については、GQL 言語ガイドを参照してください。

OFFSET/LIMIT

行をスキップし、結果の数を制限します。

構文 :

OFFSET <offset> [ LIMIT <limit> ]
LIMIT <limit>
...

Example:

MATCH (n:Person)
ORDER BY n.birthday
OFFSET 10 LIMIT 20
RETURN n.firstName || ' ' || n.lastName AS name, n.birthday

OFFSETステートメントと LIMIT ステートメントの詳細については、GQL 言語ガイドを参照してください。

RETURN

最終的な結果を出力します。

構文 :

RETURN [ DISTINCT ] <expression> [ AS <alias> ], ...

Example:

MATCH (n:Person)
RETURN n.firstName, n.lastName

RETURNステートメントの詳細については、GQL 言語ガイドを参照してください。

NEXT

次のクエリ段階が始まります。 NEXT後は前の段階で返された列のみが利用可能です。

構文 :

<query stage>
RETURN <columns>
NEXT
<query stage>

Example:

RETURN 1 AS value
NEXT
RETURN value + 1 AS nextValue

どちらの段階でもクエリブロックのユニオンを含めることができます。 その段階内で、出力が NEXT 境界を越える前に、和集合が評価されます。

NEXTの詳細については、GQL言語ガイドをご覧ください。

条件付きステートメント

各入力行を、述語が TRUE に値する最初のWHEN分岐へルーティングします。

構文 :

WHEN <predicate> THEN <linear query statement or { query statements }>
[ WHEN <predicate> THEN <linear query statement or { query statements }> ... ]
[ ELSE <linear query statement or { query statements }> ]

述語はブール型でなければならず、順序通りに評価されます。 FALSE そして UNKNOWN 次の枝へと落ちていく。 分岐が一致せず ELSEもない場合は、入力行は省略されます。 最初のマッチ以降の述語や選択されなかった分岐ボディは評価されません。

RETURN 'Alice' AS name, 19900101u AS birthday
NEXT
WHEN birthday < 20000101u THEN
  RETURN name, 'Before 2000' AS era
ELSE
  RETURN name, '2000 or later' AS era

すべてのブランチは、互換性のあるデータ型を持つ同じ列名を返す必要があります。 枝にネスト手続きが含まれている場合は、ブレースで囲みましょう。

詳細については、 条件文を参照してください。

UNION

完全なクエリブロックの出力を組み合わせます。

構文 :

<query block>
UNION [ DISTINCT | ALL ]
<query block>

UNIONを素で、重複する行を削除UNION DISTINCT。 UNION ALL 重複行を保持します。 各クエリブロックは、互換性のあるデータ型を持つ同じ列名の集合を返さなければなりません。

労働組合に関する詳細は GQLの言語ガイドをご覧ください。

グラフ パターン

グラフ パターンは、一致するグラフの構造を表します。

ノード パターン

グラフ データベースでは、ノードを使用して、人、製品、場所などのエンティティを表します。

ノード パターンは、グラフ内のノードを照合する方法を記述します。 ラベルまたはバインド変数でフィルター処理できます。

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

ノード パターンの詳細については、「 グラフ パターン」を参照してください。

エッジ パターン

エッジ パターンでは、方向やエッジの種類など、ノード間のリレーションシップを指定します。 グラフ データベースでは、エッジは 2 つのノード間の接続またはリレーションシップを表します。

<-[e]-             -- Incoming edge
-[e]->             -- Outgoing edge
-[e]-              -- Any edge
-[e:knows]->       -- Edge with label ("relationship type")
-[e:knows|likes]-> -- Edges with different labels
-[:knows]->        -- :knows edge, don't bind variable

エッジ パターンの詳細については、「 グラフ パターン」を参照してください。

ラベル式

ラベル式を使用すると、論理演算子を使用して特定のラベルの組み合わせでノードを照合できます。

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

ラベル式の詳細については、 グラフ パターンを参照してください。

パス パターン

パス パターンは、ホップ数や変数バインドなど、グラフを介したトラバーサルを記述します。

(a)-[:knows|likes]->{1,3}(b)        -- 1-3 hops via knows/likes
p=()-[:knows]->()                   -- Bind a path variable
MATCH REPEATABLE ELEMENTS (a)->(b)  -- Explicit default match mode
MATCH DIFFERENT EDGES (a)->(b), (a)->(c)
MATCH ALL TRAIL (a)->{1,4}(b)       -- Every edge-unique path
MATCH p = ANY SHORTEST (a)->{1,4}(b) -- One shortest path per endpoint pair

WALK はデフォルトのパスモードであり、繰り返しノードやエッジを許可しています。 TRAIL 繰り返しのエッジを防ぎます。 SIMPLE 終了した最初から最後までのサイクルを除き、 ACYCLIC はすべての繰り返しノードを防ぎます。 両ノード固有のモードは、エッジの再利用がエンドポイントノードを繰り返し行うため、繰り返しエッジも防止します。 ALL はデフォルトの経路探索です。 ANY SHORTEST 各送信先-宛先ペアに対して最短パスを1つ返し、同列のパスの中から決定論的に選択しません。

サポートされる量化子には、固定 {n}、有界の量化子、 {m,n} ・ {,n}、無界の量化子 {m,}、 *、 +が含まれます。 無制限 ALL WALK パターンはサポートされていません。終了経路モードを使いましょう。 無界 ANY SHORTEST WALK には追加の形状と経路値の制限があります。 詳細は GQLグラフパターンを参照してください。

パス パターンの詳細については、「 グラフ パターン」を参照してください。

複数のパターン

1 つのクエリで複雑な非線形グラフ構造を照合するには、複数のパターンを使用します。

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

複数のパターンの詳細については、「 グラフ パターン」を参照してください。

値と値の型

基本型

基本型は、文字列、数値、ブール値、datetime などのプリミティブ データ値です。

STRING           -- 'hello', "world"
INT64            -- 42, -17
FLOAT64          -- 3.14, -2.5e10, -17d
BOOL             -- TRUE, FALSE, UNKNOWN
ZONED DATETIME   -- ZONED_DATETIME('2023-01-15T10:30:00Z')

dまたはD接尾辞は、文字通りのおおよその大FLOAT64を作り出します。 接尾辞のない指数も FLOAT64 値を生み出します。 fとFの文字通りの接尾辞は現在サポートされていません。

基本型の詳細については、「 GQL の値と値の型」を参照してください。

参照値の型

参照値の種類は、クエリで値として使用するノードとエッジです。

NODE             -- Node reference values
EDGE             -- Edge reference values

参照値型の詳細については、「 GQL 値と値型」を参照してください。

コレクション型

コレクション型は、リストやパスなど、複数の値をグループ化します。

LIST<INT64>      -- [1, 2, 3]
LIST<STRING>     -- ['a', 'b', 'c']
PATH             -- Path values

コレクション型の詳細については、「 GQL の値と値の型」を参照してください。

マテリアル型とヌル可能型

すべての値型は null 許容 (null 値を含む) またはマテリアル (それを除外) のいずれかです。 既定では、 NOT NULLを明示的に指定しない限り、型は null 許容です。

STRING NOT NULL  -- Material (Non-nullable) string type
INT64            -- Nullable (default) integer type

式と演算子

Conditional

単純な CASE 式は、ある式と1つ以上の値を比較します。

CASE expr WHEN val THEN val ELSE val END -- Simple CASE
NULLIF(a, b)                           -- NULL if a = b

検索済み CASE WHEN <predicate> 表現はサポートされていません。 条件 文 を使って述語に基づいて行をルーティングします。

条件式の詳細については、 GQL の式と関数を参照してください。

Comparison

比較演算子は値を比較し、等値、順序付け、または null を確認します。

=, <>, <, <=, >, >=              -- Standard comparison
IS NULL, IS NOT NULL             -- Null checks

比較述語の詳細については、 GQL の式と関数を参照してください。

Logical

論理演算子は、クエリでブール条件を結合または否定します。

AND, OR, NOT, XOR               -- Boolean logic

論理式の詳細については、 GQL 式と関数を参照してください。

EXISTS

プロシージャフォームのサブクエリが少なくとも1行を返すかどうかをテストします。

EXISTS {
  MATCH (p)-[:knows]->(friend:Person)
  RETURN friend
}

EXISTS nullでないブール値を返します。 NOT EXISTSを使って、サブクエリが行を返さないことをテストします。 結果は WHERE または FILTER、 LET、 RETURN、 ORDER BY、集計フィルターやソース式に利用できます。 EXISTS リスト述語フィルター内ではサポートされていません。

EXISTSの詳細については、存在性のサブクエリを参照してください。

Arithmetic

算術演算子は、数値に対して計算を実行します。

+, -, *, /                       -- Basic arithmetic operations
1.00m / 8.00m                    -- Exact result: 0.1250m

算術式の詳細については、 GQL 式と関数を参照してください。

文字列パターン

文字列パターン述語は、文字列内の部分文字列、プレフィックス、またはサフィックスと一致します。

n.firstName CONTAINS 'John'          -- Has substring
n.browserUsed STARTS WITH 'Chrome'   -- Starts with prefix
n.locationIP ENDS WITH '.1'          -- Ends with suffix
MSFT.REGEXP_LIKE(n.firstName, '^jo', 'i') -- RE2 regular expression

文字列パターン述語の詳細については、 GQL の式と関数を参照してください。

リスト操作

リスト操作のテスト メンバーシップ、アクセス要素、メジャー リストの長さ。

n.gender IN ['male', 'female']    -- Membership test
n.tags[0]                        -- First element
size(n.tags)                     -- List length
ALL(x IN n.tags WHERE x <> '')   -- Every element matches
ANY(x IN n.tags WHERE x = 'gql') -- At least one element matches
NONE(x IN n.tags WHERE x = '')   -- No element matches
SINGLE(x IN n.tags WHERE x = 'gql') -- Exactly one element matches

述語関数のリストは、フィルター結果に応じて TRUE、 FALSE、または UNKNOWN を返します。 空のリストの場合、 ALL と NONE は TRUEを返し、 ANY と SINGLE は FALSE返します。 nullソースリストは UNKNOWNを返します。

要素のバインディングはフィルターに局所的で、外側の変数をシャドウすることがあります。 そのローカルバインディング上の集約やフィルター内の EXISTS サブクエリはサポートされていません。

詳細については、 List 述語関数を参照してください。

「プロパティ アクセス」

プロパティ アクセスは、ノードまたはエッジからプロパティの値を取得します。

n.firstName                      -- Property access

プロパティ アクセスの詳細については、 GQL の式と関数を参照してください。

Functions

組み込み関数を使って値を変換し、グラフ要素を検査し、行を集約できます。

数値関数

数値関数は数値値を計算したり、整数の範囲を生成したりします。

abs(value)                       -- Absolute value; preserves the numeric type
power(base, exponent)            -- Exponentiation; returns DOUBLE
sin(radians), cos(radians)       -- Trigonometric functions
asin(value), acos(value)         -- Inverse functions; value must be in [-1, 1]
degrees(radians)                 -- Convert radians to degrees
radians(degrees)                 -- Convert degrees to radians
range(start, end)                -- Integer range with step 1
range(start, end, step)          -- Integer range with a nonzero step

その他、サポートされている三角関数には TAN、 COT、 ATAN、 SINH、 COSH、 TANHがあります。 ABSとRANGEを除き、これらの数値関数はDOUBLEを返します。

GQLの式や関数における数値関数についてさらに学びましょう。

集計関数

集計関数は、行のグループ (垂直集計) またはグループ リストの要素 (水平集計) の集計値を計算します。

count(*)                         -- Count all rows
count(expr)                      -- Count non-null values
sum(p.birthday)                  -- Sum values
avg(p.birthday)                  -- Average
min(p.birthday), max(p.birthday) -- Minimum and maximum values
collect_list(p.firstName)        -- Collect inputs, including nulls
collect_one(p.firstName)         -- Select one non-null value
collect_elements(p.roles)        -- Concatenate list-valued inputs
count(DISTINCT expr)             -- Remove duplicate expression values
count(*) FILTER (WHERE predicate LIMIT 10) -- Filter and limit this aggregate

列をグループ化しない場合、入力行のない集計クエリはCOUNTに対して0、COLLECT_LISTとCOLLECT_ELEMENTSに対して空のリスト、SUM、AVG、MIN、MAX、COLLECT_ONEに対してnullを返します。 グループリストの引数は集約を水平にします。

GQL 式と関数の集計関数の詳細について説明します。

文字列関数

文字列関数を使用すると、文字列値を操作および分析できます。

char_length(s)                   -- String length
upper(s), lower(s)               -- Unicode case mapping
casefold(s)                      -- Unicode caseless form
normalize(s)                     -- Normalize a string to NFC
normalize(s, NFD)                -- Normalize a string to NFD
trim(s)                          -- Trim spaces
trim(leading '_' from s)         -- Trim one custom byte
string_join(list)                -- Join with ", "
string_join(list, delimiter)     -- Join with a custom delimiter
MSFT.REGEXP_COUNT(s, pattern)    -- Count RE2 matches
MSFT.REGEXP_INSTR(s, pattern)    -- Find a zero-based match position
MSFT.REGEXP_SUBSTR(s, pattern)   -- Return matching text
MSFT.REGEXP_REPLACE(s, pattern, replacement) -- Replace matches

正則表現パターン、置換、オプションはリテラルでなければなりません。 署名、フラグ、nullの挙動については、 文字列関数を参照してください。

関数を一覧表示する

リスト関数を使用すると、長さの確認やサイズのトリミングなど、リストを操作できます。

size(list)                       -- List length
trim(list, n)                    -- Trim a list to at most n elements

リスト関数の詳細については、「 GQL 式と関数」を参照してください。

グラフ関数

グラフ関数を使用すると、ノード、パス、エッジから情報を取得できます。

labels(node)                     -- Get node labels
element_id(node_or_edge)         -- Get an opaque element identifier
nodes(path)                      -- Get path nodes
edges(path)                      -- Get path edges
elements(path)                   -- Get all path nodes and edges
path_length(path)                -- Get number of edges in a path

グラフ関数の詳細については、「 GQL 式と関数」を参照してください。

テンポラル関数

テンポラル関数を使用すると、日付と時刻の値を操作できます。

CURRENT_TIMESTAMP                -- Get the current zoned datetime
ZONED_DATETIME(string)           -- Parse an ISO 8601 zoned datetime
DURATION(string)                 -- Parse an ISO 8601 day-time duration

テンポラル関数の詳細については、「 GQL 式と関数」を参照してください。

ジェネリック関数

汎用関数を使用すると、一般的な方法でデータを操作できます。

coalesce(expr1, expr2, ...)    -- Get the first non-null value
to_json_string(value)          -- Convert value to JSON string
nullif(a, b)                   -- NULL if a = b, else a

ジェネリック関数の詳細については、「 GQL 式と関数」を参照してください。

タスク指向の例

完成したすぐに適応できるクエリパターンが必要なときは、ハウツー記事を活用してください:

• 隣接ノード、マルチホップ経過、共有接続、存在チェックに関する共通のGQLクエリを書きます。
• 行およびパターンのフィルタリング、グループ化、コレクション集約、条件付きルーティングのためのグラフデータをフィルタリングおよび集約します。
• パスモード、パスサーチ、パターン合成、オプションマッチングのためのグラフパターンクエリを書きます。

関連コンテンツ

• GQL 言語ガイド
• GQL グラフ パターン
• GQL 式、述語、および関数
• GQL 値と値型