GQL 式、述語、および関数

この記事では、Microsoft Fabric クエリのグラフで使用できる GQL 式、述語、および組み込み関数の包括的なリファレンスを提供します。 この参照を使用して、グラフ クエリで計算を実行し、結果をフィルター処理し、データを変換する方法を理解します。

GQL クエリ言語とエンド ツー エンドクエリの例の概要については、 GQL 言語ガイドを参照してください。 サポートされているデータ型とリテラル構文の詳細については、 GQL 値と値型に関するページを参照してください。

リテラル

リテラルは、指定された値に直接評価される単純な式です。 GQL 値と値型に関する記事では、各種類の値のリテラルについて詳しく説明します。

Example:

1
1.0d
TRUE
"Hello, graph!"
[ 1, 2, 3 ]
NULL

各データ型のリテラル構文の詳細については、 GQL 値と値型に関するページを参照してください。

Predicates

述語は、GQL クエリで結果をフィルター処理するために一般的に使用されるブール式です。 これらは、 TRUE、 FALSE、または UNKNOWN (null) と評価されます。

注意事項

フィルターとして述語を使用すると、述語が TRUEに評価される項目のみが保持されます。

比較述語

これらの演算子を使用して値を比較します。

  • = (等しい)
  • <> (等しくない)
  • < (より小さい)
  • > (より大きい)
  • <= (以下)
  • >= (以上)

GQL では 3 つの値を持つロジックが使用され、null との比較では次の UNKNOWNが返されます。

Expression 結果
5 = 5 TRUE
5 = 3 FALSE
5 = NULL UNKNOWN
NULL = NULL UNKNOWN

特定の比較動作については、 GQL 値と値型の各値型のドキュメントを参照してください。

Example:

MATCH (p:Person)
FILTER WHERE p.birthday <= 20050915
RETURN p.firstName

数値強制ルール:

次の規則を優先順位に従って使用します。

  1. 近似数値型の引数を含む比較式では、すべての引数が近似数値型であることが強制されます。
  2. 符号付き整数型と符号なし整数型の両方の引数を含む比較式では、すべての引数が符号付き整数型であることが強制されます。

論理式

条件を論理演算子と組み合わせる:

  • AND (両方の条件が true)
  • OR (いずれかの条件が true)
  • NOT (条件を否定)
  • XOR (排他的和演算 — 1 つのオペランドが true の場合は true)

Example:

MATCH (p:Person)
FILTER WHERE p.birthday <= 20050915 AND p.firstName = 'John'
RETURN p.firstName || ' ' || p.lastName AS fullName

プロパティの存在述語

プロパティが存在するかどうかを確認するには、次の述語を使用します。

p.locationIP IS NOT NULL
p.browserUsed IS NULL

注

既知の非存在プロパティにアクセスしようとすると構文エラーが発生します。 潜在的に存在しない物件へのアクセスは、 null評価されます。 プロパティが既知か、または存在しない可能性があるかの判断は、アクセスされたノードまたはエッジの種類に基づいています。

メンバーシップ述語を一覧表示する

値がリスト内にあるかどうかをテストします。

p.firstName IN ['Alice', 'Bob', 'Charlie']
p.gender NOT IN ['male', 'female']

文字列パターン述語

パターン マッチング手法を使用して文字列を照合する:

p.firstName CONTAINS 'John'
p.browserUsed STARTS WITH 'Chrome'
p.locationIP ENDS WITH '.1'

算術式

数値で標準の算術演算子を使用します。

  • + (追加)
  • - (減算)
  • * (乗算)
  • / (除算)

算術演算子は、一般的な数学規則に従います。

順位：

一般に、演算子は、*前の+など、確立された演算子の優先順位規則に従います。 必要に応じて評価順序を制御するには、かっこを使用します。

Example:

(p.birthday < 20050915 OR p.birthday > 19651231) AND p.gender = 'male'

強制型規則:

次の規則を優先順位に従って使用します。

  1. 概数型の引数を含む算術式は、近似数値型の結果を返します。
  2. 符号付き整数型と符号なし整数型の両方の引数を含む算術式は、符号付き整数型の結果を返します。

Example:

LET birth_year = p.birthday / 10000
RETURN birth_year

「プロパティ アクセス」

ドット表記を使用してプロパティにアクセスする:

p.firstName
edge.creationDate

アクセスを一覧表示する

0 から始まるインデックス作成を使用してリスト要素にアクセスする:

interests[0]    -- first element
interests[1]    -- second element

組み込み関数

GQL では、データ処理と分析のためのさまざまな組み込み関数がサポートされています。

集計関数

集計関数を使用して、一連の行に対して式を評価し、各行に対して計算された値を組み合わせて最終的な結果値を取得します。 Graph では、次の集計関数がサポートされています。

  • count(*) - 行をカウントします
  • sum(expression) - 数値の合計
  • avg(expression) - 数値を平均する
  • min(expression) - 最小値を検索します
  • max(expression) - 最大値を検索します
  • collect_list(expression) - リストに値を収集します

一般に、集計関数は null 値を無視し、マテリアル入力値が指定されていない場合は常に null 値を返します。 coalesceを使用して、別の既定値 (coalesce(sum(expr), 0)) を取得できます。 唯一の例外は、指定された null 以外の値を常にカウントし、存在しない場合は 0 を返す、 count 集計関数です。 count(*)を使用して、カウントに null 値を含めます。

集計関数は、次の 3 つの方法で使用します。

  • テーブル全体の集計を計算 (垂直) するには
  • グループ化キーによって決定されたサブテーブルに対する集計を計算 (垂直) するには
  • グループ リストの要素に対する集計を計算 (水平) するには

垂直集計:

-- Vertical aggregate over whole table
MATCH (p:Person)
RETURN count(*) AS total_people, avg(p.birthday) AS average_birth_year

-- Vertical aggregate with grouping
MATCH (p:Person)-[:isLocatedIn]->(c:City)
RETURN c.name, count(*) AS population, avg(p.birthday) AS average_birth_year
GROUP BY c.name

水平集計:

水平方向の集計では、可変長パターンのグループ リスト変数の要素に対する集計が計算されます。

-- Horizontal aggregate over a group list variable
MATCH (p:Person)-[edges:knows]->{1,3}(:Person)
RETURN p.firstName, avg(edges.creationDate) AS avg_connection_date

水平集計は、常に垂直集計よりも優先されます。 グループ リストを通常のリストに変換するには、 collect_list(edges)を使用します。

注

可変長エッジ バインドや水平/垂直集計の組み合わせなど、集計手法の包括的な範囲については、「 高度な集計手法」を参照してください。

条件式

条件式を使用して、条件に基づいて異なる値を返します。

検索されたケース:

CASE
  WHEN condition1 THEN result1
  WHEN condition2 THEN result2
  ELSE default_result
END

単純な CASE:

CASE expression
  WHEN value1 THEN result1
  WHEN value2 THEN result2
  ELSE default_result
END

NULLIF:

NULLIF(a, b)は、NULLがaと等しい場合はbを返し、それ以外の場合はaを返します。

Example:

MATCH (p:Person)
RETURN p.firstName,
       CASE
         WHEN p.gender = 'male' THEN 'M'
         WHEN p.gender = 'female' THEN 'F'
         ELSE 'Other'
       END AS gender_code,
       NULLIF(p.browserUsed, 'Unknown') AS browser

文字列関数

  • char_length(string) - 文字列の長さを返します。
  • upper(string)- 指定された文字列の大文字のバリアントを返します (US ASCII のみ)。
  • lower(string)- 指定された文字列の小文字のバリアントを返します (US ASCII のみ)。
  • trim(string) - 先頭と末尾の空白を削除します。
  • string_join(list, separator) - リスト要素を区切り記号で結合します。

Example:

MATCH (p:Person)
WHERE char_length(p.firstName) > 5
RETURN upper(p.firstName) AS name_upper

グラフ関数

  • nodes(path) - パス値からノードを返します。
  • edges(path) - パス値からエッジを返します。
  • elements(path) - パスからすべてのノードとエッジを 1 つのリストとしてパス順に返します。
  • labels(node_or_edge) - ノードまたはエッジのラベルを文字列のリストとして返します。
  • path_length(path) - パス内のエッジの数を返します。

Example:

MATCH p=(:Company)<-[:workAt]-(:Person)-[:knows]-{1,3}(:Person)-[:workAt]->(:Company)
RETURN nodes(p) AS chain_of_colleagues, path_length(p) AS hops

関数を一覧表示する

  • size(list) - リスト値のサイズを返します。
  • trim(list,n) - リストをトリミングして、最大サイズの nにします。

Example:

MATCH (p:Person)-[:hasInterest]->(t:Tag)
WHERE size(collect_list(t)) > 3
RETURN p.firstName, collect_list(t.name) AS interests

テンポラル関数

  • zoned_datetime() - 現在のゾーン化された datetime を返します。
  • zoned_datetime("2025-09-12T10:10:52Z") - 引数によって指定されたゾーン化された datetime を ISO 8601 形式で返します。

Example:

RETURN zoned_datetime() AS now

ジェネリック関数

  • coalesce(value1, value2, ...) - null 以外の最初の値を返します。
  • to_json_string(value) - 値を JSON 文字列形式に変換します。

Example:

MATCH (p:Person)
RETURN coalesce(p.firstName, 'Unknown') AS display_name,
       to_json_string(p) AS person_json

関連コンテンツ

  • Last updated on