GQL 言語ガイド

GQL Graph クエリ言語は、グラフ データベースの ISO で標準化されたクエリ言語です。 これは、グラフ データのクエリと操作を効率的に行うのに役立ちます。

SQL を標準化する同じ ISO 作業グループが GQL を開発するため、一貫性と厳格性が維持されます。 SQL に慣れている場合は、式、述語、型など、GQL に多くの類似点があります。 これらの類似点により、GQL の使用を簡単に開始できます。

このガイドは、GQL の基礎を学ぶ新人と、高度な手法と包括的な参照情報を求める経験豊富なユーザーの両方に役立ちます。

[前提条件]

GQL に取り組む前に、次の概念を理解しておいてください。

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

推奨される背景:

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

必要なもの:

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

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などのわかりやすい名前。 Microsoft Fabricでは、グラフエッジは常に正確に1つのラベルを持ちます。
• プロパティ - 要素に関するデータ ( firstName: "Alice" や birthday: "19730108"など) を格納する名前と値のペア。

グラフの構造

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

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

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

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

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

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

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

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

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

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

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

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

• "ニューヨーク" や "ロンドン" のような都市
• "米国" や "英国" などの国/地域
• "北米" や "ヨーロッパ" のような大陸

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

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

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

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

すべての接続方法

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

• 人々は互いを知っている (友情, :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 = 'Annemarie'
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 は、名前に "Air" を持つ企業で働くユーザーを検索します。
2. LET は、姓と家族名を組み合わせてフルネームを作成します。
3. FILTER は Contoso の従業員のみを保持します。
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 who works at Microsoft specifically
(p:Person)-[:workAt]->(c:Company)
WHERE p.firstName = 'Annemarie'

-- Find friends who are both young
(p:Person)-[:knows]->(f:Person)  
WHERE p.birthday > 19950101 AND f.birthday > 19950101

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

(: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 パターン:

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

可変長エッジ バインド:

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

-- 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がデータ結合を処理する方法:

• 変数の等価性: 等価一致を使用した入力変数とパターン変数の結合
• 内部結合: パターン一致のない入力行は破棄されます (左結合または右結合なし)
• フィルター処理の順序: パターン マッチングが完了した後のステートメント レベルの 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)

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, '127.0.0.1') STARTS WITH '127.0.0' - ローカル ネットワークから接続しませんでした
• 条件の組み合わせ: 複雑なロジックの明示的な 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 処理: 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、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()
• 文字列関数: テキスト処理用のchar_length()、upper()、lower()、trim()
• グラフ関数: グラフ構造を分析するためのnodes()、edges()、labels()
• 一般的な関数: null 値を正常に処理するためのcoalesce()

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

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

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

高度なクエリ手法

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

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

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

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

-- 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年以前に生まれた従業員の企業を絞り込み、平均誕生日を計算し、結果をまとめて並べ替えることができます。

水平集計の使用

-- 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 を調べる

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

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

参加する

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

関連コンテンツ

主要なトピックの詳細:

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

クイック リファレンス:

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

Microsoft Fabric のグラフ:

• グラフ データ モデル - グラフの概念とモデリングについて。
• グラフ データベースとリレーショナル データベース - 相違点と、それぞれを使用するタイミング。
• Microsoft Fabric を無料で試す。
• Microsoft Fabric のエンド ツー エンドのチュートリアル。