GQL 式、述語、および関数

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

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

リテラル

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

Example:

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

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

Predicates

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

比較述語

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

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

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

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

Example:

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

両方のオペランドが数値の場合、GQLはそれらを数値値で比較します。

論理式

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

• 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

存在部分クエリ

ネストされたクエリが少なくとも1行を返すかどうかをテストするために、手続きフォーム EXISTS サブクエリを使用します。

EXISTS {
  <query statements>
  RETURN <columns>
}

その結果は、nullでないブール値となります:

• TRUE もしサブクエリが1行以上を返す場合、
• FALSE もしサブクエリが行を返さない場合、

すでにスコープ内の変数はサブクエリ内で暗黙的に利用可能です。 サブクエリ内でのみ導入された変数は、サブクエリの外では利用できません。

フィルターで EXISTS を活用してください:

MATCH (p:Person)
WHERE EXISTS {
  MATCH (p)-[:knows]->(friend:Person)
  RETURN friend
}
RETURN p.firstName, p.lastName

NOT EXISTS を使って、サブクエリが行を返さない行を保持します。 EXISTSはLET、RETURN、ORDER BY、集計フィルターやソース式でも使用できます。 EXISTS リスト述語フィルター内ではサポートされていません。

相関するサブクエリの詳細については、GQL言語ガイドの CALL 文 を参照してください。

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

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

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

述語関数のリスト

リスト述語関数を使ってリストの要素に対するブール式を評価する:

ALL(element IN list WHERE predicate)
ANY(element IN list WHERE predicate)
NONE(element IN list WHERE predicate)
SINGLE(element IN list WHERE predicate)

ソースはリストリテラル、リスト値プロパティ、変数、または可変長パターンのグループリストのいずれかです。

これらの関数は以下の意味を持ちます:

以下の例は、動的に構成されたリスト上で4つの関数すべてを評価するものです。

LET items = [1, 2, 3]
RETURN ALL(x IN items WHERE x > 0) AS all_match,
       ANY(x IN items WHERE x = 2) AS any_match,
       NONE(x IN items WHERE x < 0) AS none_match,
       SINGLE(x IN items WHERE x = 2) AS single_match

返された4つの値はすべて TRUEです。

また、リストから要素の特性を評価することもできます。 この例では、 connections は可変長辺パターンによって作成されたグループリストです。

MATCH (person:Person)-[connections:knows]->{1,4}(friend:Person)
WHERE ALL(connection IN connections WHERE connection.creationDate IS NOT NULL)
RETURN person.firstName, friend.firstName

リスト述語は三値論理を用います。 表は、リスト要素のフィルター式によって生成される値の観点から結果を説明しています。

ソースリストがnullの場合、各関数は UNKNOWNを返します。 nullリスト要素は、その要素がnullにバインドされた状態でフィルターを評価した結果をもたらします。関数の結果を自動的に未知にするわけではありません。

要素変数はリスト述語のフィルター式内でのみ利用可能です。 フィルターは囲むクエリの変数を参照することもできます。 要素変数が外側変数と同じ名前の場合、ローカル要素変数が優先されます。 ネストされたリスト述語も同様に外部要素変数をシャドウ化することができます。

集約関数は囲むグループリストを参照できますが、ローカルにバウンドされた要素変数を集約することはできません。 EXISTS リスト述語フィルター内ではサブクエリもサポートされていません。

ANY(...) はリスト述語関数です。 ANY SHORTESTパスサーチのプレフィックスやANY動的価値タイプと混同しないでください。

文字列パターン述語

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

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

RE2の正規表現マッチングには MSFT.REGEXP_LIKEを用います。

算術式

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

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

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

順位：

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

Example:

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

強制型規則:

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

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

「プロパティ アクセス」

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

p.firstName
edge.creationDate

アクセスを一覧表示する

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

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

組み込み関数

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

数値関数

数値関数を使って数値変換、三角関数の計算、整数範囲の作成を行います。

絶対値とパワー

両方の関数は数値を受け入れます。 null 引数は null を生成します。 POWER結果が溢れ出すなど無効な数値演算はエラーを引き起こします。

RETURN ABS(-1) AS absoluteValue, POWER(2, -2) AS reciprocalSquare

結果は次のとおりです。

三角関数

三角関数は1つの数値を受け入れ、 DOUBLEを返します。 null 引数は null を生成します。

関数の数学的領域外の引数は誤りを生じさせます。

RETURN COS(0) AS cosine, RADIANS(180) AS angle

結果は次のとおりです。

整数範囲

RANGE(start, end) startからendまでの整数リストを1ステップで返します。 RANGE(start, end, step) 指定されたゼロでないステップを使用します。 start、 end、 step は非零整数でなければなりません。 ゼロは start または endに対して有効であり、ゼロでない step のみである必要があります。

この範囲には startが含まれます。 正確に正確にリリーチを繰り返し加えた場合にのみendstepend含まれます。 startがendより大きい正のステップ、またはstartがend未満の負のステップは空のリストを返します。 ゼロステップはエラーを生み出します。

RETURN RANGE(0, 10, 3) AS ascending, RANGE(5, 0, -2) AS descending

結果は次のとおりです。

すべての引数が符号なし整数であれば、 RANGE は LIST<UINT64> を返します。 そうでなければ、 LIST<INT64> を返し、符号付き整数として安全に表現できない値は拒否します。

集計関数

集約関数は、入力行間または可変長パターンで区切られたグループリスト内で値を組み合わせます。

集計クエリにグルーピング列がなく入力行も受け取らない場合、 COUNT は 0を返し、 COLLECT_LIST と COLLECT_ELEMENTS は空のリストを返し、他の集計関数はnullを返します。 コレクションの集約で返される値の順序に頼らないでください。 グループ化列では、入力行がなければグループが生まれず、結果行もありません。

集合量化子

重複する値を含めるには ALL を使い、削除するには DISTINCT してください。 ALL は式集約のデフォルトです。 COUNT(*) 集合量化子は受け入れません。

MATCH (person:Person)
RETURN COUNT(person) AS personCount,
       COUNT(DISTINCT person.browserUsed) AS browserCount

COLLECT_LISTの場合、DISTINCT重複値を除去し、最大1つのnullを保持します。 COLLECT_ELEMENTSの場合、入力リストが連結された後の要素に適用DISTINCT。 DISTINCT だからといって COLLECT_ONE 決定論的というわけではありません。

集約特有のフィルターと制限

集計の後に FILTER (WHERE predicate) を加え、 predicate が真である値のみを含めるようにします。 偽および未知の述語結果は除外します。 このフィルターはその集約体にのみ影響し、同じ RETURN内の他の式が利用可能な入力行には影響しません。

集計フィルター内に LIMIT n を加えて、最大で n の条件を満たす入力行まで考慮します。 フィルタリングは集計特異的限界の前に行われ、 DISTINCT は限界の後に適用されます。

MATCH (person:Person)
RETURN COUNT(*) AS allPeople,
       COUNT(*) FILTER (WHERE person.birthday < 19900101 LIMIT 5) AS sampleBornBefore1990

行間の集約

集約は通常、入力行間で値を垂直に組み合わせます。 GROUP BYを使って各グループごとに1つずつの結果を計算してください。

MATCH (p:Person)
RETURN count(*) AS total_people, avg(p.birthday) AS average_birth_year

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

同じクエリブロック内で、垂直アグリゲートを直接別のアグリゲート内に置かないでください。 たとえば、 SUM(COUNT(*)) は無効です。 集計結果を集約する必要があるときは、 NEXT を使って集約ステップを分けてください。

マッチング経路内の集約

可変長パターンで囲まれた辺変数はグループリストとなります。 その変数上の集約は水平的で、異なる入力行を組み合わせるのではなく、マッチングされた各パスに対してリスト内の1つの結果を計算します。

MATCH (person:Person)-[knows:knows]->{1,5}(friend:Person)
RETURN COUNT(knows) AS pathLength

ここで、 COUNT(knows) はマッチングされた各経路の辺の数を返します。 COUNT、SUM、AVG、MIN、MAX、COLLECT_LIST、COLLECT_ONE、COLLECT_ELEMENTSの水平型が支えられています。 COUNT(*) そして、骨材特化の FILTER や LIMIT は水平型ではありません。

水平アグリゲートは、1つの外側の垂直アグリゲートへの入力となることができます。

MATCH (person:Person)-[knows:knows]->{1,5}(friend:Person)
RETURN MIN(COUNT(knows)) AS shortestMatchedPath

このクエリでは、 COUNT(knows) 一致したパスごとに1つの長さを計算し、 MIN 入力行間でその長さを組み合わせます。

タスク指向の例については、「 フィルタおよびグラフ集約データ」を参照してください。

条件式

単純な CASE 式を使って、1つ以上の値を持つ1つの式を比較し、最初の等しい値に関連付けられた結果を返します:

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 p.gender
         WHEN 'male' THEN 'M'
         WHEN 'female' THEN 'F'
         ELSE 'Other'
       END AS gender_code,
       NULLIF(p.browserUsed, 'Unknown') AS browser

検索済み CASE WHEN <predicate> 表現はサポートされていません。 述語で行をルーティングし、選択した分岐に対してクエリ文やネスト手続きを実行するには、 WHEN 条件文を使用します。

文字列関数

文字列関数を使って文字列を測定、変換、検索、比較、組み合わせできます。

文字の長さと格

以下の関数を使って文字列を測定または変更します:

Unicodeのマッピングは文字列の長さや表現を変更することができます:

RETURN UPPER('straße') AS uppercase,
       LOWER('İ') AS lowercase,
       CASEFOLD('Straße') AS folded

結果はそれぞれ STRASSE、 i̇、 strasseです。 CASEFOLD LOWERと同等ではありません。 例えば、格折りたたみはssにß、ギリシャのシグマ形Σ、σ、ςをσに写します。

文字列の正規化

GQLは4つのUnicode正規化形式を定義しています:

• 正規化形式C(NFC)、正準合成。
• 正規化形式D(NFD)、標準分解。
• 正規化形式KC(NFKC)、適合性の合成。
• 正規化形式 KD(NFKD)、適合分解。

NORMALIZE(string) デフォルトでNFCに切り替えます。 2つ目の引数として正規化形式を指定します。

RETURN NORMALIZE('cafe\u0301') AS composed,
       NORMALIZE('café', NFD) AS decomposed

引数は文字列でなければなりません。

トリム弦

TRIMを使って文字列の両端、始まり、または末尾からスペース文字または指定文字を一つ削除します:

RETURN TRIM('  text  ') AS both_ends,
       TRIM(BOTH FROM '  text  ') AS explicit_both,
       TRIM(LEADING FROM '  text  ') AS beginning,
       TRIM(TRAILING FROM '  text  ') AS ending,
       TRIM(LEADING 'f' FROM 'foobar') AS custom_character

カスタムトリム値は正確に1バイトでなければなりません。 マルチバイトのUnicode文字や複数文字を含む文字列はカスタムトリム値としてサポートされていません。 nullソースやカスタムトリム値はnullを返します。

結合文字列

STRING_JOIN(list [, delimiter]) 文字列のリストに加わります。 デフォルトの区切り符は、コンマの後にスペースが続くものです:

RETURN STRING_JOIN(['foo', 'bar', 'baz']) AS default_delimiter,
       STRING_JOIN(['foo', 'bar', 'baz'], '-') AS custom_delimiter

その結果は foo, bar, baz で foo-bar-baz。 空のリストは空文字列を返します。 nullリスト、null区切り符、またはnullリスト要素はnullを返します。 すべてのnullでないリスト要素は文字列でなければなりません。

正規表現関数

グラフはGQLの拡張として以下の正則表現関数を提供します:

MSFT.REGEXP_LIKE

パターンがソース文字列の任意の部分と一致したときに TRUE 返します。 一致するものが見つからない場合は、 FALSEを返します。

source は検索する文字列です。 pattern は、 source の任意の部分文字列に対してマッチングされます。ただし、式自体が ^ や $のようなアンカーを用いない限りは。 flags マッチングの動作は 「マッチングルールとオプション」で説明されているように変化します。

RETURN MSFT.REGEXP_LIKE('HELLO', 'hello', 'i') AS matches

結果は TRUE になります。

MSFT.REGEXP_COUNT

マッチ数を返します。 一致するものが見つからない場合は、 0を返します。

source は検索する文字列であり、 pattern はカウントすべきマッチを特定します。 start はマッチングが開始できるゼロベースのUnicodeコードポイント位置です。 試合はこの位置から開始されなければなりません。 アンカーパターンの新しい出発点には、その位置が弦の新しい始まりにはなりません。 flags マッチングの動作は 「マッチングルールとオプション」で説明されているように変化します。

RETURN MSFT.REGEXP_COUNT('1a2a3a4', '[0-9]', 3) AS match_count

検索は位置 3、すなわち2番目の aから開始するため、 3 と 4 の数字のみがカウントされます。 結果は 2 になります。

MSFT.REGEXP_INSTR

選択されたマッチまたは捕獲グループのゼロベースの位置を返します。

source は探索する文字列であり、 pattern はマッチを特定します。 start はマッチングが開始できるゼロベースのUnicodeコードポイント位置です。 マッチはこの位置から開始されなければならず、アンカーパターンの新しいストリングの始まりにはなりません。

occurrence startから見つけた最初の、2番目の、またはその後の重複しない一致を選択します。 group その一致の中に何を見つけるかを選択します: 0 は完全な一致を選び、正の値がその番号付き捕獲グループを選択します。 return_option 選択されたマッチまたはグループの境界を返す。 0 は開始位置を返し、 1 は終了直後の位置を返す。 flags マッチングの動作は 「マッチングルールとオプション」で説明されているように変化します。

一致する発生が見つからなかったり、選択した捕獲グループがその発生に参加しない場合、関数は返 -1を返します。

RETURN MSFT.REGEXP_INSTR('banana', 'a', 0, 2) AS match_position

2試合目は 3番からスタートするため、結果は 3です。

MSFT.REGEXP_SUBSTR

選択されたマッチや捕獲グループのテキストを返します。

source は探索する文字列であり、 pattern はマッチを特定します。 start はマッチングが開始できるゼロベースのUnicodeコードポイント位置です。 マッチはこの位置から開始されなければならず、アンカーパターンの新しいストリングの始まりにはなりません。

occurrence startから見つけた最初の、2番目の、またはその後の重複しない一致を選択します。 group その一致から返すテキストを選択し、 0 は完全な一致を選び、正の値がその番号付き捕獲グループを選択します。 flags マッチングの動作は 「マッチングルールとオプション」で説明されているように変化します。

一致する出現が見つからなかったり、選択したキャプチャグループがその発生に参加しない場合、関数はnullを返します。

RETURN MSFT.REGEXP_SUBSTR(
  '12-345',
  '([0-9]+)-([0-9]+)',
  0,
  1,
  '',
  2
) AS matched_text

最初の出現は完全文字列であり、捕獲群 2 は 345なので、結果は 345となります。

MSFT.REGEXP_REPLACE

一致するテキストを置き換えます。 デフォルトでは、すべてのマッチを置き換え、置き換えテキストを文字通り挿入します。

source は修正する文字列であり、 pattern はマッチを特定します。 replacement は選択されたマッチに挿入されたテキストです。 EXACT 文字通り挿入します; TEMPLATE キャプチャ参照を解釈します。

start は置換が始まるゼロベースのUnicodeコードポイント位置です。 試合はこの位置から開始されなければなりません。 start前のテキストは変わらず保存され、位置がアンカーパターンの新しい始まりになることはありません。 occurrenceをstartのすべてのマッチを置き換える0に設定するか、重複しない番号付けのマッチのみを置き換えるには正の値に設定します。 start以降の試合は特定のイベントが選ばれても変更されません。 flags マッチングの動作は 「マッチングルールとオプション」で説明されているように変化します。

RETURN MSFT.REGEXP_REPLACE('a1b2c3', '[0-9]', '#', 0, 2) AS replaced

2桁目の一致のみが置き換えられるため、結果は a1b#c3となります。

一致しなければ、ソース文字列は変更せずに返されます。

マッチングテキストを再利用するには、 TEMPLATEを指定してください。 このモードでは、 \0 から \9 は完全マッチと捕獲グループを示し、 \\ は文字通りのバックスラッシュを挿入します。 これらの参照をエスケープせずに、 @で接頭辞を付けた生の文字列リテラルを使いましょう:

RETURN MSFT.REGEXP_REPLACE(
  'John Smith',
  @'([A-Za-z]+) ([A-Za-z]+)',
  TEMPLATE @'\2 \1'
) AS reordered_name

結果は Smith John になります。

マッチングルールとオプション

パターンは RE2正則表現構文 を使用し、Unicode文字列をマッチングします。 ソースは任意の文字列式でいることができます。 パターン、フラグ、置換は文字列リテラルでなければならず、数値オプションは符号なし整数リテラルでなければなりません。

マッチは左から右へ重なり合わずに見つかります。 0長マッチの後、マッチングはUnicodeコードポイント1ポイント分進みます。

開始位置と戻された位置は、ゼロベースのUnicodeコードポイントオフセットです。 発生数は1基元ですが、MSFT.REGEXP_REPLACEの出現0手段がすべての出現に代わるものです。

以下の表は、省略された任意の引数のデフォルトを示しています。

オプションの旗は以下の通りです:

'ims'のような旗を一本の文字列で組み合わせます。 nullソースはnullを返します。 サポートされていないフラグ、無効な正規表現、無効な返還オプション、または無効な発生やグループ番号はエラーを返します。

グラフ関数

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

ELEMENT_ID ノードまたはエッジ参照を受け入れ、null入力に対してnullを返します。 返された文字列は不透明として扱いましょう。

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)
LET personId = p.id, personName = p.firstName
RETURN personId, personName, collect_list(t.name) AS interests
GROUP BY personId, personName
FILTER size(interests) > 3

テンポラル関数

• CURRENT_TIMESTAMP - 現在のゾーン化された datetime を返します。
• ZONED_DATETIME(string) - ISO 8601文字列で表されるゾーンの日付時間を返します。
• DURATION(string) - ISO 8601の持続時間文字列で表される日中の時間の長さを返します。

Example:

RETURN CURRENT_TIMESTAMP AS now,
       DURATION('PT2H') AS twoHours

減算演算子を使って、2つのゾーン化された日付時間間の持続時間を導出します:

RETURN ZONED_DATETIME('2026-09-17T12:00:00Z')
       - ZONED_DATETIME('2026-09-17T10:00:00Z') AS elapsed

ジェネリック関数

• 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

関連コンテンツ

• GQL 言語ガイド
• GQL 値と値型
• グラフ パターン
• グラフ データのフィルター処理と集計