Microsoft Fabric のグラフの GQL 言語ガイド

GQL (Graph クエリ言語) は、グラフ データベースの ISO で標準化されたクエリ言語です。 GQL を使用して、Microsoft Fabric のグラフを使用してグラフ データのクエリ、分析、操作を効率的に行います。

SQL を標準化する同じ ISO 作業グループが GQL を開発します。 その結果、GQL は、式、述語、データ型など、多くの概念を SQL と共有します。 SQL の経験がある場合は、その知識の多くを GQL に適用できます。

この記事では、グラフ内の GQL の包括的なリファレンスを提供します。 以下が対象です。

• コア概念: グラフ データ構造、パターン、クエリの基礎
• 重要なステートメント: MATCH、 FILTER、 LET、 ORDER BY、 LIMIT、および RETURN
• データ型と式: 値型、演算子、および組み込み関数
• 高度な手法: 複数ステートメント構成、変数スコープ、集計戦略

完全な言語リファレンスではなく、タスク指向のガイダンスをお探しの場合は、ハウツー ガイドを参照してください。

• 一般的な GQL クエリ (ネイバー、マルチホップ トラバーサル、共有接続、エンティティの存在チェック) を記述する
• グラフ データのフィルター処理と集計 - FILTER、WHERE、GROUP BY、集計関数
• グラフ パターン クエリの記述 — マルチホップ パターン、パス モード、変数の再利用、および省略可能な MATCH
• GQL クエリのパフォーマンスの最適化 - フィルター戦略、トラバーサル制限、およびキー制約の推奨事項

[前提条件]

開始する前に、次の概念を理解していることを確認してください。

• データベースの基本理解 - リレーショナル (SQL)、NoSQL、グラフなどのデータベース システムを使用した経験が役立ちます。
• グラフの概念 - 接続されたデータ内のノード、エッジ、リレーションシップの理解。
• クエリの基礎 - フィルター処理、並べ替え、集計などの基本的なクエリの概念に関する知識。

推奨される背景:

• SQL または openCypher 言語の経験により、GQL 構文の学習が容易になります (これらは GQL のルートです)。
• データ モデリングに関する知識は、グラフ スキーマの設計に役立ちます。
• グラフ データの特定のユース ケースについて理解します。

必要なもの:

• クエリ機能を持つグラフ ワークスペースへのアクセス。
• ソーシャル ネットワークの例を使用するサンプル データまたは意欲。
• クエリを記述するための基本的なテキスト エディター。

GQL を特別なものにするもの

GQL は、グラフ データ専用に設計されています。 この設計により、自然で直感的に接続された情報を操作できます。

テーブル結合を使用してリレーションシップを表現する SQL とは異なり、GQL では視覚的なグラフ パターンが使用されます。 これらのパターンは、エンティティの接続方法を直接反映しているため、クエリの読み取りが容易になり、推論が容易になります。

たとえば、1999 年より前に生まれた人とその友人 (お互いを知っている人) を見つけたいとします。 ビジュアル グラフ パターンを使用して GQL でその条件を表す方法を次に示します。

MATCH (person:Person)-[:knows]-(friend:Person)
WHERE person.birthday < 19990101 
  AND friend.birthday < 19990101
RETURN person.firstName || ' ' || person.lastName AS person_name, 
       friend.firstName || ' ' || friend.lastName AS friend_name

このクエリは、1999 年より前に生まれた友人 (お互いを知っている人) を検索します。 (person:Person)-[:knows]-(friend:Person)パターンは、探しているリレーションシップ構造を視覚的に示します。これは、データの図を描画するのと同様です。

GQL の基礎

クエリに進む前に、GQL の基盤となる次の主要な概念を理解してください。

• グラフでは、 データがノード (エンティティ) とエッジ (リレーションシップ) として格納され、それぞれにラベルとプロパティが含まれます。
• グラフの種類 はスキーマのように動作し、グラフに存在できるノードとエッジを定義します。
• 制約 は、グラフの種類がデータの整合性を強制するためにグラフに課すその他の規則と制限です。
• クエリ では、 MATCH、 FILTER、 RETURN などのステートメントを使用してデータを処理し、結果を表示します。
• パターンは、 直感的なビジュアル構文を使用して検索するグラフ構造を表します。
• 式は、SQL 式 と同様に、データに対して計算と比較を実行します。
• 述語は、 クエリ内の結果をフィルター処理するブール値式です。
• 値型 は、処理して格納できる値の種類を定義します。

グラフ データについて

GQL を効果的に操作するには、グラフ データの構造を理解する必要があります。 この基盤は、より優れたクエリを記述し、データを効果的にモデル化するのに役立ちます。

ノードとエッジ: 構成要素

GQL では、ラベル付けされたプロパティ グラフを操作します。 グラフは、次の 2 種類の要素で構成されます。

• ノード は、通常、システム内のエンティティ ("名詞") を表します(人、組織、投稿、製品など)。 これらは、ドメインに存在する独立したオブジェクトです。 場合によっては、ノードの頂点も呼び出します。

• エッジは 、エンティティ間のリレーションシップ ("動詞") を表します。エンティティの接続方法と相互作用方法です。

例えば、人々は互いに知り合い(:knows)、特定の地域で活動する組織(:operates)、または製品を購入した顧客(:purchased)です。
エッジ リレーションシップとも呼ばれます。

すべてのグラフ要素には、次の特性があります。

• それを一意に識別する内部 ID
• 1 つ以上のラベル - Person や knowsなどのわかりやすい名前。 グラフでは、エッジには常に 1 つのラベルが付きます。
• プロパティ - 要素に関するデータ ( firstName: "Alice" や birthday: "19730108"など) を格納する名前と値のペア。

グラフの構造

各辺は、原点とターゲットの2つのノードを正確に接続します。 この接続により、グラフの構造が作成され、エンティティが相互にどのように関連付けられているかを示します。 エッジの方向は重要です。別のPersonをfollowsPersonは、有向リレーションシップを作成します。

グラフでサポートされているプロパティ グラフは常に整形式であり、すべてのエッジが 2 つの有効なノードを接続します。 グラフにエッジが表示される場合は、両方のエンドポイントが同じグラフに存在します。

グラフ モデルとグラフの種類

グラフ モデルは、グラフの構造を記述します。 これは、アプリケーション ドメインのデータベース スキーマのように機能します。 グラフ モデルは次を定義します。

• 存在できるノードとエッジ
• どのようなラベルとプロパティを持つことができますか
• ノードとエッジの接続方法

グラフ モデルでは、制約、特に各ノードを一意に識別するプロパティを指定する ノード キー制約 によって、データの整合性も確保されます。

実際の例: ソーシャル ネットワーク

このドキュメント全体を通して、ソーシャル ネットワークの例で GQL の概念を示します。 このドメインを理解すると、例に従って、独自のデータに同様のパターンを適用できます。

ソーシャル ネットワーク エンティティ

ソーシャル ネットワークには、ドメインのエンティティを表す、次の主要な種類のノードが含まれています。

ユーザー は、名前、誕生日、性別などの個人情報を持っています。 彼らは都市に住み、社会的なつながりを形成します。

地理的 階層を形成する場所:

• "ニューヨーク" や "ロンドン" のような都市
• Countries/regions "米国" や "United Kingdom" のような
• "北米" や "ヨーロッパ" のような大陸

ユーザー が時間を費やす組織:

• 人が学ぶ大学
• 人が 働く会社

コンテンツとディスカッション:

• 投稿を含むタイトルを含むフォーラム
• コンテンツ、言語、およびオプションの画像を含む投稿
• 投稿 やその他のコメントに返信するコメント
• コンテンツを分類し、関心を表すタグ

すべての接続方法

エンティティ間の接続により、ネットワークは興味深いものになります。

• 人々は互いを知っている (友情, :knows).
• 企業(:workAt)や大学(:studyAt)で働く人。
• ユーザーが投稿とコメントを作成する (:hasCreator)。
• 投稿やコメントが好きな人 (:likes)。
• 投稿、フォーラム、コメントにはタグ (:hasTag) を付けることができます。
• ユーザーは特定のタグ (:hasInterest) に関心があります。
• フォーラムには投稿 (:containerOf) が含まれており、メンバー (:hasMember) とモデレーター (:hasModerator) が含まれます。

グラフエッジはドメインリレーションシップを表します。 この豊富なネットワークにより、興味深いクエリや分析を行う機会が多数生まれます。

最初の GQL クエリ

グラフの基本を理解したので、GQL を使用してグラフ データのクエリを実行する方法を見てみましょう。 これらの例は単純なものから複雑なものまで構築されており、GQL のアプローチによってグラフ クエリが直感的かつ強力になるしくみがわかります。

シンプルなスタート:すべての人を見つける

可能な限り最も基本的なクエリから始めます。 グラフ内のすべてのユーザー (:Person) の名前 (名、姓) を見つけます。

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

このクエリは次のように実行されます。

1. MATCH は、 Personラベルが付いたすべてのノードを検索します。
2. RETURN 名と姓が表示されます。

フィルター処理の追加: 特定のユーザーを検索する

次に、特定の特性を持つユーザーを見つけます。 この場合は、Alice という名前の全員を見つけて、名前と誕生日を表示します。

MATCH (p:Person)
FILTER p.firstName = 'Alice'
RETURN p.firstName, p.lastName, p.birthday

このクエリは次のように実行されます。

1. MATCH は、Person というラベルが付いたすべてのノード (p) を検索します。
2. FILTER 名が Alice であるノード (p)。
3. RETURN には、名、姓、誕生日が表示されます。

基本的なクエリ構造

基本的な GQL クエリはすべて一貫したパターンに従います。これは、データを検索、フィルター処理、および返すために連携する一連のステートメントです。 ほとんどのクエリは、グラフ内のパターンを見つけるための MATCH で始まり、出力を指定するために RETURN で終わります。

こちらは、知り合いで同じ誕生日の人たちのペアを見つけて、その友達ペアの合計数を返すシンプルなクエリです。

MATCH (n:Person)-[:knows]-(m:Person)
FILTER n.birthday = m.birthday
RETURN count(*) AS same_age_friends

このクエリは次のように実行されます。

1. MATCH は、相互に認識 Person ノードのすべてのペアを検索します。
2. FILTER は、両方の人が同じ誕生日を持つペアのみを保持します。
3. RETURN は、そのようなフレンド ペアの数をカウントします。

GQL では、C スタイルの // 行コメント、SQL スタイルの -- 行コメント、および C スタイルの /* */ ブロック コメントがサポートされています。

一般的な表現

• MATCH検索すべきグラフパターンを特定します。ここで関心のあるデータの構造を定義します。
• LET: マッチしたデータに基づいて新しい変数や計算値を割り当て、結果に導出列を追加します。
• FILTER条件を適用して結果を絞り込み、条件に合わない行を削除します。
• ORDER BY:フィルタリングされたデータをソートし、1つ以上のフィールドに基づいて出力を整理するのに役立ちます。
• OFFSET LIMIT:返される行数を制限する—ページ付けやトップkクエリに有用です。
• RETURN: 最終出力を指定し、結果セットに含まれるべきデータを定義し、集計を行います。

ステートメントの連携方法

GQL文はパイプラインを形成し、各文は前の文の出力を処理します。 この逐次実行により、クエリの読み取りやデバッグが容易になります。なぜなら、実行順序が読み取り順と一致しているからです。

重要なポイント:

• 文は実質的に連続して実行されます。
• 各文はデータを変換し、次の文に渡します。
• このプロセスにより、複雑なクエリを簡略化する、明確で予測可能なデータ フローが作成されます。

ステートメント構成の例

以下のGQLクエリは、名前に「Air」が入っている企業で働く最初の10人を見つけ、氏名順に並べ替え、氏名と会社名を返します。

-- Data flows: Match → Let → Filter → Order → Limit → Return
MATCH (p:Person)-[:workAt]->(c:Company)           -- Input: unit table, Output: (p, c) table
LET fullName = p.firstName || ' ' || p.lastName   -- Input: (p, c) table, Output: (p, c, fullName) table
FILTER c.name CONTAINS 'Air'                      -- Input: (p, c, fullName) table, Output: filtered table
ORDER BY fullName                                 -- Input: filtered table, Output: sorted table
LIMIT 10                                          -- Input: sorted table, Output: top 10 rows table
RETURN fullName, c.name AS companyName            -- Input: top 10 rows table
                                                  -- Output: projected (fullName, companyName) result table

このクエリは次のように実行されます。

1. MATCH 企業で働く人を見つけます。
2. LET は、姓と家族名を組み合わせてフルネームを作成します。
3. FILTER 会社名に「Air」が入っている会社の従業員のみを雇用します。
4. ORDER BY は完全な名前で並べ替えられます。
5. LIMIT は最初の 10 件の結果を受け取ります。
6. RETURN 氏名と会社名を返送します。

変数を使用してデータを接続する

前の例の p、 c、 fullName などの変数は、ステートメント間でデータを伝達します。 変数名を再利用すると、GQL は自動的に同じデータを参照し、強力な結合条件を作成します。 変数はバインド変数とも呼ばれます。

変数は、さまざまな方法で分類できます。

ソースをバインドする方法:

• パターン変数 - 一致するグラフ パターンによってバインドされます
• 標準変数 - 他の言語コンストラクトによってバインドされます

パターン変数の型:

• 要素変数 - グラフ要素参照値へのバインド
  • ノード変数 - 個々のノードにバインドする
  • エッジ変数 - 個々のエッジにバインド
• パス変数 - 一致したパスを表すパス値にバインドする

参照の次数:

• シングルトン変数 - パターンから個々の要素参照値にバインドする
• グループ変数 - 可変長パターンからの要素参照値のリストにバインドします ( 高度な集計手法を参照)

実行の結果と結果

クエリを実行すると、次の要素で構成される 実行結果 が返されます。

• ステートメントのデータを含む RETURN。
• クエリが成功したかどうかを示す状態情報。

結果テーブル

結果テーブル (存在する場合) は、クエリ実行の実際の結果です。

結果テーブルには、その列の名前と型、結果の表示に使用する推奨される列名シーケンス、テーブルの順序、 、および実際の行自体に関する情報が含まれます。

状態情報

クエリの実行中、プロセスはエラーや警告など、注目すべきさまざまな条件を検出します。 各条件は、実行結果の状態情報に状態オブジェクトによって記録されます。

ステータス情報は、プライマリ ステータス オブジェクトと、他のステータス オブジェクトの (空の可能性がある) リストで構成されます。 プライマリ 状態オブジェクトは常に存在し、クエリの実行が成功したか失敗したかを示します。

すべての状態オブジェクトには、記録された条件を識別する 5 桁の状態コード (GQLSTATUS と呼ばれます) と、それを説明するメッセージが含まれています。

成功状態コード:

その他の状態コードは、クエリ実行プロセスで検出された追加のエラーまたは警告を示します。

さらに、ステータス オブジェクトには、基になる原因ステータス オブジェクトと、記録された条件を特徴付けた詳細情報を含む診断レコードを含めることができます。

基本的な概念とステートメント

このセクションでは、効果的な GQL クエリを記述するために必要な主要な構成要素について説明します。 各概念は、実用的なクエリ作成スキルに向けて構築されています。

グラフ パターン: 構造の検索

グラフ パターンは、GQL クエリの中心です。 検索するリレーションシップのような直感的で視覚的な構文を使用して、探しているデータ構造を記述できます。

単純なパターン:

基本的なリレーションシップ パターンから始めます。

-- Find direct friendships
(p:Person)-[:knows]->(f:Person)

-- Find people working at any company
(p:Person)-[:workAt]->(c:Company)

-- Find cities in any country/region
(ci:City)-[:isPartOf]->(co:Country)  

特定のデータを含むパターン:

-- Find employees named Alice
(p:Person)-[:workAt]->(c:Company)
WHERE p.firstName = 'Alice'

-- Find friends who both have birthdays after December 31, 1999
(p:Person)-[:knows]->(f:Person)  
WHERE p.birthday > 19991231 AND f.birthday > 19991231

柔軟なエンティティ選択のラベル式:

(:Person|Company)-[:isLocatedIn]->(p:City|Country)  -- OR with |
(:Place&City)                                       -- AND with &  
(:Person&!Company)                                  -- NOT with !

ラベル式を使用すると、1 つのパターンでさまざまな種類のノードを照合できるため、クエリの柔軟性が高まります。

変数の再利用により、強力な結合が作成されます。

-- Find coworkers: people who work at the same company
(c:Company)<-[:workAt]-(x:Person)-[:knows]-(y:Person)-[:workAt]->(c)

変数 c を再利用することで、両方のユーザーが 同じ 会社で作業し、自動結合制約が作成されます。 このパターンは、"同じエンティティ" リレーションシップを表す重要なパターンです。

WHERE を使用したパターン レベルのフィルター処理:

-- Filter during pattern matching (more efficient)
(p:Person WHERE p.birthday < 19940101)-[:workAt]->(c:Company WHERE c.id > 1000)

-- Filter edges during matching  
(p:Person)-[w:workAt WHERE w.workFrom >= 2000]->(c:Company)

境界付き可変長パターン:

(:Person)-[:knows]->{1,3}(:Person)  -- Friends up to 3 degrees away

トラバーサルを制御するためのパス モード:

パス モードは、可変長トラバーサル中にクエリ エンジンが繰り返し要素を処理する方法を制御します。

TRAIL パターンを使用して、グラフ トラバーサル中のサイクルを防ぎ、各エッジが最大 1 回訪問されるようにします。

-- Find paths without visiting the same :knows edge twice
MATCH TRAIL (src:Person)-[:knows]->{1,4}(dst:Person)
WHERE src.firstName = 'Alice' AND dst.firstName = 'Bob'
RETURN count(*) AS num_connections

-- Find acyclic paths in social networks
MATCH TRAIL (p:Person)-[e:knows]->{,3}(celebrity:Person)
RETURN 
  p.firstName || ' ' || p.lastName AS person_name, 
  celebrity.firstName || ' ' || celebrity.lastName AS celebrity_name, 
  count(e) AS distance
LIMIT 1000

ノードが 2 回アクセスされていないことを保証する必要がある場合は、 ACYCLIC を使用します。

-- Find paths where no person appears more than once
MATCH ACYCLIC (src:Person)-[:knows]->{1,4}(dst:Person)
WHERE src.firstName = 'Alice'
RETURN dst.firstName, dst.lastName
LIMIT 100

可変長エッジ バインド:

可変長パターンでは、エッジ変数はコンテキストに基づいて異なる情報をキャプチャします。

-- Edge variable 'e' binds to a single edge for each result row
MATCH (p:Person)-[e:knows]->(friend:Person)
RETURN p.firstName, e.creationDate, friend.firstName  -- e refers to one specific relationship
LIMIT 1000

-- Edge variable 'e' binds to a group list of all edges in the path
MATCH (p:Person)-[e:knows]->{2,4}(friend:Person)  
RETURN 
  p.firstName || ' ' || p.lastName AS person_name, 
  friend.firstName || ' ' || friend.lastName AS friend_name, 
  -- e is a list
  size(e) AS num_edges
LIMIT 1000

この区別は、エッジ変数を正しく使用するために重要です。

複数のリレーションシップを持つ複雑なパターン:

MATCH (p:Person), (p)-[:workAt]->(c:Company), (p)-[:isLocatedIn]->(city:City)
RETURN p.firstName, p.lastName, c.name AS company_name, city.name AS city_name
LIMIT 1000

このパターンでは、1 人のユーザーが複数の他のエンティティに接続する方法を示す、職場と住居の両方と共にユーザーを見つけます。

コア ステートメント

GQL には、グラフ データを段階的に処理するために連携する特定のステートメントの種類が用意されています。 これらのステートメントを理解することは、効果的なクエリを構築するために不可欠です。

MATCH ステートメント

構文 :

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

MATCH ステートメントは入力データを受け取り、グラフ パターンを検索します。 入力変数をパターン変数と結合し、一致したすべての組み合わせを出力します。

入力変数と出力変数:

-- Input: unit table (no columns, one row)
-- Pattern variables: p, c  
-- Output: table with (p, c) columns for each person-company match
MATCH (p:Person)-[:workAt]->(c:Company)

WHERE を使用したステートメント レベルのフィルター処理:

-- Filter pattern matches
MATCH (p:Person)-[:workAt]->(c:Company) WHERE p.lastName = c.name

WHEREを使用して、すべての一致を後でフィルター処理できます。 この方法では、別の FILTER ステートメントを回避できます。

入力変数を使用した結合:

MATCHが最初のステートメントでない場合は、入力データをパターン一致と結合します。

...
-- Input: table with 'targetCompany' column
-- Implicit join: targetCompany (equality join)
-- Output: table with (targetCompany, p, r) columns
MATCH (p:Person)-[r:workAt]->(targetCompany)

主な結合動作:

MATCHがデータ結合を処理する方法:

• 変数の等価性: 等価一致を使用した入力変数とパターン変数の結合
• 内部結合: パターン一致のない入力行は破棄されます。 左外部結合の動作には OPTIONAL MATCH を使用します。
• フィルター処理の順序: パターン マッチングが完了した後のステートメント レベルの WHERE フィルター
• パターン接続: 適切な結合を行うには、複数のパターンで少なくとも 1 つの変数を共有する必要があります
• パフォーマンス: 共有変数によって効率的な結合制約が作成される

複数のパターンでは、共有変数が必要です。

-- Shared variable 'p' joins the two patterns
-- Output: people with both workplace and residence data
MATCH (p:Person)-[:workAt]->(c:Company), 
      (p)-[:isLocatedIn]->(city:City)

OPTIONAL MATCH ステートメント

構文 :

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

OPTIONAL MATCH は MATCH と同様に機能しますが、左外部結合セマンティクスを使用します。 パターンで入力行に一致するものが見つからない場合、クエリでは、一致しない変数の NULL 値を持つ行が破棄されるのではなく保持されます。

Example:

-- Find all people and, if available, their workplace
MATCH (p:Person)
OPTIONAL MATCH (p)-[:workAt]->(c:Company)
RETURN p.firstName, p.lastName, c.name AS company_name

どの会社で働いていないユーザーも、NULLのcompany_nameを使用して結果に表示されます。

LET ステートメント

構文 :

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

LET ステートメントは、計算された変数を作成し、クエリ パイプライン内でデータ変換を有効にします。

基本的な変数の作成:

MATCH (p:Person)
LET fullName = p.firstName || ' ' || p.lastName
RETURN *
LIMIT 1000

複雑な計算:

MATCH (p:Person)
LET adjustedAge = 2000 - (p.birthday / 10000),
    fullProfile = p.firstName || ' ' || p.lastName || ' (' || p.gender || ')'
RETURN *
LIMIT 1000

主な動作:

• クエリ エンジンは、すべての入力行の式を評価します。
• 結果は出力テーブルの新しい列になります。
• 変数は、前のステートメントの既存の変数のみを参照できます。
• クエリ エンジンは、1 つの LET ステートメントで複数の割り当てを並列で評価します (相互参照はありません)。

FILTER ステートメント

構文 :

FILTER [ WHERE ] <predicate>

FILTER ステートメントを使用すると、クエリ パイプラインを通過するデータを正確に制御できます。

基本的なフィルター処理:

MATCH (p:Person)
FILTER p.birthday < 19980101 AND p.gender = 'female'
RETURN *

複雑な論理条件:

MATCH (p:Person)
FILTER (p.gender = 'male' AND p.birthday < 19940101) 
  OR (p.gender = 'female' AND p.birthday < 19990101)
  OR p.browserUsed = 'Edge'
RETURN *

Null 対応のフィルター処理パターン:

null 値を安全に処理するには、次のパターンを使用します。

• 値を確認する: p.firstName IS NOT NULL - 名が付けられます
• データの検証: p.id > 0 - 有効な ID
• 不足しているデータを処理する: NOT coalesce(p.locationIP, '10.x.x.x') STARTS WITH '10.x.x.x' - ローカル ネットワークから接続しませんでした
• 条件の組み合わせ: 複雑なロジックの明示的な null チェックで AND/OR を使用する

ORDER BY ステートメント

構文 :

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

計算式を使用した複数レベルの並べ替え:

MATCH (p:Person)
RETURN *
ORDER BY p.firstName DESC,               -- Primary: by first name (Z-A)
         p.birthday ASC,                 -- Secondary: by age (oldest first)
         p.id DESC                       -- Tertiary: by ID (highest first)

並べ替え時の NULL 処理:

ORDER BY coalesce(p.gender, 'not specified') DESC -- Treat NULL as 'not specified'

並べ替え動作の詳細:

ORDER BYのしくみを理解する:

• クエリ エンジンは各行の式を評価し、結果によって行の順序が決まります。
• 複数の並べ替えキーによって階層的な順序 (プライマリ、セカンダリ、3 次など) が作成されます。
• NULL は常に比較で最も小さい値です。
• ASC (昇順) は既定の順序であり、 DESC (降順) を明示的に指定する必要があります。
• 格納されたプロパティだけでなく、計算値で並べ替えることができます。

MATCH (a:Person)-[r:knows]->(b:Person)
LET aName = a.firstName || ' ' || a.lastName
LET bName = b.firstName || ' ' || b.lastName
ORDER BY r.creationDate DESC
/* intermediary result _IS_ guaranteed to be ordered here */
RETURN aName, bName, r.creationDate AS since
/* final result _IS_ _NOT_ guaranteed to be ordered here  */

MATCH (a:Person)-[r:knows]->(b:Person)
LET aName = a.firstName || ' ' || a.lastName
LET bName = b.firstName || ' ' || b.lastName
/* intermediary result _IS_ _NOT_ guaranteed to be ordered here */
RETURN aName, bName, r.creationDate AS since
ORDER BY r.creationDate DESC
/* final result _IS_ guaranteed to be ordered here              */

OFFSET と LIMIT のステートメント

構文 :

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

一般的なパターン:

-- Basic top-N query
MATCH (p:Person)
RETURN *
ORDER BY p.id DESC
LIMIT 10                                 -- Top 10 by ID

RETURN: 基本的な結果予測

構文 :

RETURN [ DISTINCT ] <expression> [ AS <alias> ], <expression> [ AS <alias> ], ...
[ ORDER BY <expression> [ ASC | DESC ], <expression> [ ASC | DESC ], ... ]
[ OFFSET <offset> ]
[ LIMIT <limit> ]

RETURN ステートメントは、結果テーブルに表示されるデータを指定して、クエリの最終的な出力を生成します。

基本的な出力:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName || ' ' || p.lastName AS name, 
       p.birthday, 
       c.name

わかりやすくするためにエイリアスを使用する:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName AS first_name, 
       p.lastName AS last_name,
       c.name AS company_name

並べ替えと top-k を組み合わせる:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName || ' ' || p.lastName AS name, 
       p.birthday AS birth_year, 
       c.name AS company
ORDER BY birth_year ASC
LIMIT 10

DISTINCT を使用した重複処理:

-- Remove duplicate combinations
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN DISTINCT p.gender, p.browserUsed, p.birthday AS birth_year
ORDER BY p.gender, p.browserUsed, birth_year

集計と組み合わせる:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN count(DISTINCT p) AS employee_count

RETURN GROUP BY: グループ化された結果プロジェクション

構文 :

RETURN [ DISTINCT ] <expression> [ AS <alias> ], <expression> [ AS <alias> ], ...
GROUP BY <variable>, <variable>, ...
[ ORDER BY <expression> [ ASC | DESC ], <expression> [ ASC | DESC ], ... ]
[ OFFSET <offset> ]
[ LIMIT <limit> ]

GROUP BYを使用して、共有値で行をグループ化し、各グループ内の集計関数を計算します。

集計を使用した基本的なグループ化:

MATCH (p:Person)-[:workAt]->(c:Company)
LET companyName = c.name
RETURN companyName, 
       count(*) AS employeeCount,
       avg(p.birthday) AS avg_birth_year
GROUP BY companyName
ORDER BY employeeCount DESC

複数列のグループ化:

MATCH (p:Person)
LET gender = p.gender
LET browser = p.browserUsed
RETURN gender,
       browser,
       count(*) AS person_count,
       avg(p.birthday) AS avg_birth_year,
       min(p.creationDate) AS first_joined,
       max(p.id) AS highest_id
GROUP BY gender, browser
ORDER BY avg_birth_year DESC
LIMIT 10

データ型: 値の操作

GQL では、さまざまな種類の情報をグラフに格納および操作するための豊富なデータ型がサポートされています。

基本的な値の型

• 数値: 計算と測定の INT64、 UINT64、 FLOAT64 ( DOUBLEとも呼ばれます)
• テキスト: 名前、説明、テキスト データのSTRING
• ロジック: 3 つの値を持つ BOOL : TRUE、FALSE、UNKNOWN (null 処理の場合)
• 時刻: タイムゾーン情報を含むタイムスタンプのZONED DATETIME
• コレクション:同じタイプの複数の値に対してLIST<T>T、グラフのトラバーサル結果に対してPATH
• グラフ要素: グラフ データを参照するためのNODEとEDGE

リテラルの例

42                                     -- Integer literal
"Hello, graph!"                        -- String  literal
TRUE                                   -- Boolean literal
ZONED_DATETIME('2024-01-15T10:30:00Z') -- DateTime with timezone literakl
[1, 2, 3]                              -- Literal list of integers

重大な null 処理パターン

-- Equality predicates with NULL always returns UNKNOWN
5 = NULL                              -- Evaluates to UNKNOWN (not FALSE!)
NULL = NULL                           -- Evaluates to UNKNOWN (not TRUE!)

-- Use IS NULL predicates for explicit null testing
p.nickname IS NULL                    -- Evaluates to TRUE if nickname is null
p.nickname IS NOT NULL                -- Evaluates to TRUE if nickname has a value

-- Use the COALESCE function for null-safe value selection
coalesce(p.nickname, p.firstName, '???')  -- Evaluates to first non-null value

3 つの値を持つロジックへの影響

-- In FILTER statements, only TRUE values pass through
FILTER p.birthday > 0        -- Removes rows where birthday is null or missing or zero

-- It's important to understand that NOT UNKNOWN = UNKNOWN
FILTER NOT (p.birthday > 0)  -- Removes rows where birthday is null or missing or positive

-- Use explicit null handling for inclusive filtering
FILTER p.birthday < 19980101 OR p.birthday IS NULL -- Includes null birthdays

式: データの変換と分析

式を使用すると、クエリ内のデータを計算、比較、変換できます。 これらは SQL の式に似ていますが、グラフ データを処理するための追加の機能があります。

一般的な式の型

p.birthday < 19980101   -- Birth year comparison  
p.firstName || ' ' || p.lastName               -- String concatenation
count(*)                                       -- Aggregation
p.firstName IN ['Alice', 'Bob']                -- List membership
coalesce(p.firstName, p.lastName)              -- Null handling

複合述語の構成

-- Combine conditions with proper precedence
FILTER (p.birthday > 19560101 AND p.birthday < 20061231) 
  AND ((p.gender IN ['male', 'female']) OR (p.browserUsed IS NOT NULL))

-- Use parentheses for clarity and correctness
FILTER p.gender = 'female' AND (p.firstName STARTS WITH 'A' OR p.id > 1000)

文字列パターンマッチング

-- Pattern matching with different operators
p.locationIP CONTAINS '192.168'      -- Substring search
p.firstName STARTS WITH 'John'       -- Prefix matching  
p.lastName ENDS WITH 'son'           -- Suffix matching

-- Case-insensitive operations
upper(p.firstName) = 'ALICE'         -- Convert to uppercase for comparison

カテゴリ別の組み込み関数

GQL には、さまざまなデータ処理ニーズに対して次の関数カテゴリが用意されています。

• 集計関数: データを集計するためのcount()、sum()、avg()、min()、max()

• 条件式: 条件付きロジックの CASE/WHEN/THEN/ELSE/END と NULLIF() 。 例えば次が挙げられます。

  MATCH (p:Person)
  RETURN p.firstName,
    CASE WHEN p.birthday < 20000101 THEN 'Before 2000' ELSE '2000 or later' END AS era,
    NULLIF(p.gender, 'unknown') AS gender
  

• 文字列関数: テキスト処理用の char_length()、 upper()、 lower()、 trim() (大文字と小文字のマッピングの場合のみ US ASCII)

• グラフ関数: グラフ構造を分析するためのnodes()、edges()、elements()、labels()、path_length()

• 一般的な関数: null 値とシリアル化を処理するためのcoalesce()、to_json_string()

複雑な式の演算子の優先順位

1. プロパティ アクセス (.)
2. 乗算と除算 (*、/)
3. 加算と減算 (+、-)
4. 比較 (=、 <>、 <、 >、 <=、 >=)
5. 論理否定 ( NOT )
6. 論理結合 (AND)
7. 論理排他結合 (XOR)
8. 論理和演算 (OR)

上記の一覧では、数値が小さい演算子は、数値が大きい演算子よりも "厳密にバインドされます" です。 たとえば、 NOT n.prop OR m.prop は (NOT n.prop) OR m.prop ですが、 NOT (n.prop OR m.prop).

高度なクエリ手法

このセクションでは、複雑で効率的なグラフ クエリを構築するための高度なパターンと手法について説明します。 これらのパターンは、強力な分析クエリを作成するのに役立つ基本的なステートメントの使用を超えています。

複雑な複数ステートメント構成

高度なグラフ クエリでは、複雑なクエリを効率的に作成する方法を理解することが重要です。

UNION ALL

UNION ALLを使用して、2 つ以上の線形クエリ ブロックの結果を結合します。

-- Combine results from two separate pattern matches
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName AS name, c.name AS affiliation
UNION ALL
MATCH (p:Person)-[:studyAt]->(u:University)
RETURN p.firstName AS name, u.name AS affiliation

UNION ALL では、重複を含むすべての行が保持されます。 UNION DISTINCT (重複を削除する) はまだサポートされていません。

マルチステップ パターンの進行

複数のステートメントを連結して、複雑な分析を段階的に構築します。

-- Build complex analysis step by step
MATCH (company:Company)<-[:workAt]-(employee:Person)
LET companyName = company.name
MATCH (employee)-[:isLocatedIn]->(city:City)
FILTER employee.birthday < 19850101
LET cityName = city.name
RETURN companyName, cityName, avg(employee.birthday) AS avgBirthday, count(employee) AS employeeCount
GROUP BY companyName, cityName
ORDER BY avgBirthday DESC

このクエリは徐々に複雑さを増します。企業、その従業員、従業員の所在地、1985年以前に生まれた従業員の企業を絞り込み、平均誕生日を計算し、結果をまとめて並べ替えることができます。

水平集計の使用

水平方向の集計は、1 つの行内の可変長パターンに対して集計されます。

-- Find people and their minimum distance to people working at Microsoft
MATCH TRAIL (p:Person)-[e:knows]->{,5}(:Person)-[:workAt]->(:Company { name: 'Microsoft'})
LET p_name = p.lastName || ', ' || p.firstName
RETURN p_name, min(count(e)) AS minDistance 
GROUP BY p_name
ORDER BY minDistance DESC

可変範囲と高度なフロー制御

変数はクエリ ステートメント間でデータを接続し、複雑なグラフ トラバーサルを有効にします。 高度なスコープ 規則を理解することは、高度なマルチステートメント クエリを記述するのに役立ちます。

変数バインドとスコープ パターン

-- Variables flow forward through subsequent statements 
MATCH (p:Person)                                    -- Bind p 
LET fullName = p.firstName || ' ' || p.lastName     -- Bind concatenation of p.firstName and p.lastName as fullNume
FILTER fullName CONTAINS 'Smith'                    -- Filter for fullNames with “Smith” substring (p is still bound)
RETURN p.id, fullName                               -- Only return p.id and fullName (p is dropped from scope) 

ステートメント間の結合に対する変数の再利用

-- Multi-statement joins using variable reuse
MATCH (p:Person)-[:workAt]->(:Company)          -- Find people with jobs
MATCH (p)-[:isLocatedIn]->(:City)               -- Same p: people with both job and residence
MATCH (p)-[:knows]->(friend:Person)             -- Same p: their social connections
RETURN *

重大なスコープの規則と制限事項

-- ✅ Backward references work
MATCH (p:Person)
LET adult = p.birthday < 20061231  -- Can reference p from previous statement
RETURN *

-- ❌ Forward references don't work  
LET adult = p.birthday < 20061231  -- Error: p not yet defined
MATCH (p:Person)
RETURN *

-- ❌ Variables in same LET statement can't reference each other
MATCH (p:Person)
LET name = p.firstName || ' ' || p.lastName,
    greeting = 'Hello, ' || name     -- Error: name not visible yet
RETURN *

-- ✅ Use separate statements for dependent variables
MATCH (p:Person)
LET name = p.firstName || ' ' || p.lastName
LET greeting = 'Hello, ' || name     -- Works: name now available
RETURN *

複雑なクエリでの変数の可視性

-- Variables remain visible until overridden or query ends
MATCH (p:Person)                     -- p available from here
LET gender = p.gender                -- gender available from here  
MATCH (p)-[:knows]->(e:Person)       -- p still refers to original person
                                     -- e is new variable for managed employee
RETURN p.firstName AS manager, e.firstName AS friend, gender

高度な集計手法

GQL では、グループとコレクション間でデータを分析するための 2 種類の集計がサポートされています。 GROUP BY を使用した垂直集計と可変長パターンに対する水平方向の集計です。

GROUP BY を使用した垂直方向の集計

垂直集計 (RETURNでGROUP BYで説明) は、共有値によって行をグループ化し、各グループ内の集計を計算します。

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN c.name AS companyName, 
       count(*) AS employee_count, 
       avg(p.birthday) AS avg_birth_year
GROUP BY companyName

この方法では、会社ごとに 1 つの結果行が作成され、各グループ内のすべての従業員が集計されます。

グループ リスト変数を使用した水平集計

水平方向の集計では、可変長パターンによってバインドされたコレクションに対する集計が計算されます。 可変長エッジを使用すると、エッジ変数は、一致した各パス内のすべてのエッジを保持する グループ リスト変数 になります。

-- Group list variable 'edges' enables horizontal aggregation
MATCH (p:Person)-[edges:knows]->{2,4}(friend:Person)
RETURN p.firstName || ' ' || p.lastName AS person_name, 
       friend.firstName || ' ' || friend.lastName AS friend_name,
       size(edges) AS degrees_of_separation,
       avg(edges.creationDate) AS avg_connection_age,
       min(edges.creationDate) AS oldest_connection

垂直集計と水平集計の主な違いは次のとおりです。

• 垂直方向の集計 は、行間またはグループ行間で集計され、各グループの行間で集計されます。
• 水平集計 は、個々のエッジ コレクション内の要素を集計します。
• グループ リスト変数は、可変長エッジ パターンからのみ取得されます。

可変長エッジ バインド コンテキスト

可変長パターンでのエッジ変数のバインド方法を理解することは非常に重要です。

パターン マッチング中 (シングルトン コンテキスト):

-- Edge variable 'e' refers to each individual edge during filtering
MATCH (p:Person)-[e:knows WHERE e.creationDate > zoned_datetime('2000-01-01T00:00:00Z')]->{2,4}(friend:Person)
-- 'e' is evaluated for each edge in the path during matching
RETURN *

結果式 (グループ コンテキスト):

-- Edge variable 'edges' becomes a list of all qualifying edges
MATCH (p:Person)-[e:knows]->{2,4}(friend:Person)
RETURN size(e) AS num_edges,                    -- Number of edges in path
       e[0].creationDate AS first_edge,         -- First edge in path
       avg(e.creationDate) AS avg_age           -- Horizontal aggregation

垂直集計と水平集計の組み合わせ

高度な分析パターンでは、両方の集計の種類を組み合わせることができます。

-- Find average connection age by city pairs
MATCH (p1:Person)-[:isLocatedIn]->(c1:City)
MATCH (p2:Person)-[:isLocatedIn]->(c2:City)
MATCH (p1)-[e:knows]->{1,3}(p2)
RETURN c1.name AS city1,
       c2.name AS city2,
       count(*) AS connection_paths,                  -- Vertical: count paths per city pair
       avg(size(e)) AS avg_degrees,                   -- Horizontal then vertical: path lengths
       avg(avg(e.creationDate)) AS avg_connection_age -- Horizontal then vertical: connection ages
GROUP BY city1, city2

エラー処理戦略

一般的なエラー パターンを理解することは、堅牢なクエリを記述するのに役立ちます。

不足しているデータを適切に処理する:

MATCH (p:Person)
-- Use COALESCE for missing properties
LET displayName = coalesce(p.firstName, p.lastName, 'Unknown')
LET contact = coalesce(p.locationIP, p.browserUsed, 'No info')
RETURN *

明示的な null チェックを使用します。

MATCH (p:Person)
-- Be explicit about null handling
FILTER p.id IS NOT NULL AND p.id > 0
-- Instead of just: FILTER p.id > 0
RETURN *

追加情報

GQLSTATUS コード

クエリ結果のセクションで説明したように、GQL は実行の成功または潜在的な失敗に関連する豊富な状態情報を報告します。 完全な一覧については、 GQL 状態コードのリファレンスを参照 してください。

予約語

GQL は、変数、プロパティ名、ラベル名などの識別子として使用できない特定のキーワードを予約します。 完全な一覧については、 GQL 予約語のリファレンス を参照してください。

予約語を識別子として使用する必要がある場合は、バッククォーク ( `match`、 `return`) でエスケープします。

予約語をエスケープしないようにするには、次の名前付け規則を使用します。

• 単一単語識別子の場合は、アンダースコアを追加します。 :Product_
• 複数単語の識別子の場合は、camelCase または PascalCase を使用します。 :MyEntity、 :hasAttribute、 textColor

次のステップ

GQL の基礎を理解したら、推奨されるラーニング パスを次に示します。

GQL スキルの構築を続ける

初心者向け:

• クイック スタートを試す - 実践的な クイックスタート と チュートリアル に従って、実用的なエクスペリエンスを得る
• 基本的なクエリを練習 する - このガイドの例を独自のデータで試す
• グラフ パターンについて - 包括的なパターン構文を調べる
• データ型の探索 - GQL の値と値の型について

経験豊富なユーザーの場合:

• 高度な式 - GQL の式と関数について学習する
• スキーマの設計 - GQL グラフの種類 と制約について学習する
• データ型の探索 - GQL の値と値の型について

参考資料

これらの参照は、簡単な検索に便利な状態に保ちます。

• GQL クイック リファレンス - 構文クイック リファレンス
• GQL 状態コード - 完全なエラー コード リファレンス
• GQL 予約語 - 予約 済みキーワードの完全な一覧

グラフを探索する

プラットフォームについて説明します。

• グラフ データ モデル - グラフの概念とモデリングについて
• グラフ データベースとリレーショナル データベース - 適切なアプローチを選択する
• 無料でMicrosoft Fabric - 実践的なエクスペリエンスを得る
• エンド ツー エンドのチュートリアル - 完全な学習シナリオ

参加する

• フィードバックの共有 - ドキュメントとツールの改善に役立つ
• コミュニティに参加する - 他のグラフ データベースの専門家と接続する
• 最新情報 - 新機能に関するグラフのお知らせをフォローする

関連コンテンツ

ハウツー ガイド:

• 一般的な GQL クエリを記述 する - 近隣ノード、マルチホップ、共有接続などの実用的なクエリ パターン。
• グラフ データのフィルター処理と集計 - FILTER 関数、WHERE 関数、GROUP BY 関数、集計関数。
• グラフ パターン クエリを記述 する - マルチホップ トラバーサル、パス モード、変数の再利用、およびオプションの照合。
• GQL クエリのパフォーマンスを最適化 する - 効率的な GQL クエリを記述するためのベスト プラクティス。

主要なトピックの詳細:

• ソーシャル ネットワーク スキーマの例 - グラフ スキーマの完全な作業例。
• GQL グラフ パターン - 包括的なパターン構文と高度な照合手法。
• GQL 式と関数 - すべての式の型と組み込み関数。
• GQL グラフの種類 - グラフの種類と制約。
• GQL の値と値の型 - 完全な型システム参照と値の処理。

クイック リファレンス:

• GQL abridged リファレンス - 構文クイック リファレンス。
• GQL 状態コード - 完全なエラー コード リファレンス。
• GQL 予約語 - 予約 キーワードの完全な一覧。

グラフ：

• グラフ データ モデル - グラフの概念とモデリングについて説明します。
• グラフ データベースとリレーショナル データベース - 相違点と、それぞれを使用するタイミング。
• 無料でMicrosoft Fabric。
• Microsoft Fabric。