GQL クエリ API リファレンス

RESTful HTTP API を使用して、Microsoft Fabric のグラフ内のプロパティグラフに対して GQL クエリを実行します。このリファレンスでは、HTTP コントラクト (要求と応答の形式、認証、JSON 結果のエンコード、エラー処理) について説明します。

Important

この記事では、ソーシャルネットワークのグラフデータセットの例のみを使用します。

概要

GQL Query APIは、GQLクエリをJSONペイロードとして受け入れ、構造化かつ型付きの結果を返すRESTエンドポイントを公開します。初回リクエスト中に完了しないクエリに対して継続ポーリングをサポートしています。

主な機能

単一エンドポイント - すべての操作で HTTP POST を 1 つの URL に使用します。
JSON ベース - 要求と応答のペイロードでは、型指定された GQL 値の豊富なエンコードで JSON が使用されます。
継続ポーリング - 長期間実行されるクエリは複数のHTTPリクエストにまたがって継続可能です。
型セーフ - 値表現の判別共用体を使用した厳密な GQL 互換型指定。

[前提条件]

ノードとエッジ (リレーションシップ) を含むデータを含むグラフが必要です。サンプルグラフを作成して読み込むには、グラフのクイックスタートを参照してください。
実行結果と結果の構造など、プロパティグラフと GQL の基本的な理解を理解している必要があります。
組織にサインインするには、Azure CLI ツール az をインストールしてセットアップする必要があります。この記事のコマンドラインの例では、bash などの POSIX と互換性のあるコマンドラインシェルを使用することを前提としています。

Authentication

GQL クエリ API には、ベアラートークンを使用した認証が必要です。

すべての要求の Authorization ヘッダーにアクセストークンを含めます。

Authorization: Bearer <your-access-token>

一般に、Microsoft Authentication Library (MSAL) またはMicrosoft Entraと互換性のあるその他の認証フローを使用してベアラートークンを取得できます。

ベアラートークンは、通常、次の 2 つの主要なパスを通じて取得されます。

ユーザー委任アクセス

Azure CLI ツール az を使用して、コマンドラインからユーザー委任サービス呼び出しのベアラートークンを取得できます。

次の方法で、コマンドラインからユーザー委任呼び出しのベアラートークンを取得します。

az login を実行します。
アクション: az account get-access-token --resource https://api.fabric.microsoft.com

これにより、Azure CLI ツール az が使用されます。

az restを使用して要求を実行すると、ベアラートークンが自動的に取得されます。

アプリケーションアクセス

Microsoft Entraに登録されているアプリケーションのベアラートークンを取得できます。詳細については、 Fabric API のクイックスタートを参照してください。

API エンドポイント

API は、すべてのクエリ操作を受け入れる単一のエンドポイントを使用します。

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/graphModels/{graphModelId}/executeQuery?beta=true

クエリAPIはベータ版で、本番環境での使用は推奨されていません。必要な beta クエリパラメータを trueに設定します。古い preview=true パラメータは後方互換性のためにサポートされていますが、新しい統合には beta=true を使用します。

ワークスペースの {workspaceId} を取得するには、 az restを使用して使用可能なすべてのワークスペースを一覧表示できます。

az rest --method get --resource "https://api.fabric.microsoft.com" --url "https://api.fabric.microsoft.com/v1/workspaces"

{graphModelId}を取得するには、az restを使用して、ワークスペース内で使用可能なすべてのグラフを一覧表示できます。

az rest --method get --resource "https://api.fabric.microsoft.com" --url "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/graphModels"

Azure CLIの出力オプションを使って、これらのリストリクエストからの応答をフィルタリングまたはフォーマットできます。これらのオプションはAzure CLIクライアントで動作します。クエリAPIパラメータではありません:

--query "value[?displayName=='My Workspace']" displayNameがMy Workspaceの項目のみをリストアップします。
--query "value[?starts_with(displayName, 'My')]" displayNameがMyで始まるアイテムのみをリストアップします。
--query "{query}" 提供されたJMESPath {query}に一致する項目のみをリストアップします。サポートされた構文については Query Azure CLI コマンドの結果を参照してください。
-o table テーブルの結果を生成します。

注

コマンドラインシェルから API エンドポイントを使用してクエリを実行する方法については、 az-rest の使用に関するセクション、または curl の使用に関するセクションを参照してください。

クエリパラメーター

パラメーター	タイプ	必須	Description
`beta`	boolean	イエス	ベータ版クエリAPIを使用するために `true` に設定してください。
`continuationToken`	文字列	いいえ	クエリがまだ実行中の `result.nextPage` からトークンを取得できます。トークンを使う際には同じクエリテキストを送信してください。

要求ヘッダー

Header	価値	必須
`Content-Type`	`application/json`	イエス
`Accept`	`application/json`	イエス
`Authorization`	`Bearer <token>`	イエス

要求の形式

すべての要求では、JSON ペイロードと共に HTTP POST が使用されます。

基本的な要求構造

{
  "query": "MATCH (n) RETURN n LIMIT 100"
}

要求フィールド

フィールド	タイプ	必須	Description
`query`	文字列	イエス	実行する GQL クエリ

応答形式

成功した要求のすべての応答では、実行状態と結果を含む JSON ペイロードで HTTP 200 状態が使用されます。

応答構造

{
  "status": {
    "code": "00000",
    "description": "note: successful completion",
    "diagnostics": {
      "OPERATION": "query",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/",
      "_graphaneGqlStatus": {
        "gqlType": "STRING",
        "value": "00000"
      }
    }
  },
  "result": {
    "kind": "TABLE",
    "columns": [...],
    "data": [...]
  }
}

Status オブジェクト

すべての応答には、実行情報を含む状態オブジェクトが含まれます。

フィールド	タイプ	Description
`code`	文字列	5文字の公開APIステータスコード。
`description`	文字列	人間が読みやすい状態説明。
`diagnostics`	オブジェクト	詳細な診断記録、利用可能な場合は標準的なクエリエンジンGQLSTATUSも含まれます。
`cause`	オブジェクト	オプションの基礎原因ステータスオブジェクト。

状態コード

主要な status.code は以下の公開APIカテゴリを使用しています:

00000 - 少なくとも1行の成功。
00001 - 結果が省略されたものの成功裏に完了した場合。将来のDDLおよびDMLサポート用に予約されています。
01000 - 警告または情報条件。
02000 - 現在、行を生成するクエリから利用可能な行が存在しない。
42000 - 構文、アクセスルール、またはその他のユーザーが訂正可能なクエリエラー。
50000 - システムエラーまたは非機密エラー。

詳細については、 GQL ステータスコードリファレンスを参照してください。

診断レコード

診断レコードには、状態オブジェクトをさらに詳しく説明する他のキーと値のペアを含めることができます。アンダースコア (_) で始まるキーはグラフに固有です。 GQL 標準では、他のすべてのキーが規定されています。

注

_graphaneGqlStatus診断にはクエリエンジンが報告する標準的な5文字のGQLSTATUSが含まれています。すべてのアンダースコア接頭辞付き診断メンバーは、 null またはJSONでエンコードされたGQL値のいずれかを含みます。例えば、 _graphaneGqlStatus は STRINGを使い、エラー分類診断では BOOLを使用します。「値の型とエンコード」を参照してください。

原因

基になる原因がわかっている場合、状態オブジェクトにはオプションの cause フィールドが含まれます。

その他の状態オブジェクト

一部の結果は、オプションの additionalStatuses フィールドで他のステータスオブジェクトをリストとして報告できます。

プライマリー状態は最も重大な記録状態です。追加のステータスおよびネスト原因にはそれぞれ独自の公開APIコードと標準的なGQLSTATUS診断があります。

結果の種類

結果では、 kind フィールドで判別共用体パターンが使用されます。

テーブルの結果

表形式のデータを返すクエリの場合:

{
  "kind": "TABLE",
  "columns": [
    {
      "name": "name",
      "gqlType": "STRING",
      "jsonType": "string"
    },
    {
      "name": "age",
      "gqlType": "INT64",
      "jsonType": "number|string"
    }
  ],
  "isOrdered": false,
  "isDistinct": false,
  "data": [
    {
      "name": "Alice",
      "age": 30
    },
    {
      "name": "Bob",
      "age": 25
    }
  ]
}

実行時間の長いクエリ

現在のHTTPリクエスト中にクエリが完了しない場合、APIはHTTP 200を返します。公開ステータスコード 02000、空のテーブル、 nextPage トークンが表示されます。

{
  "status": {
    "code": "02000",
    "description": "No data available, retry with continuation token"
  },
  "result": {
    "kind": "TABLE",
    "columns": [],
    "data": [],
    "nextPage": "{continuationToken}"
  }
}

同じリクエスト本体を送信し、トークンをURLに追加して完了を行います:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/graphModels/{graphModelId}/executeQuery?beta=true&continuationToken={continuationToken}

nextPageは不透明な価値として扱いましょう。 RFC 3986に従って正確に一度だけパーセンテージエンコードを行い、その後 continuationToken クエリパラメータ値として使用してください。トークンをデコードしたり、検査したり、改変したりしないでください。

回答に nextPageが含まれなくなるまで続けてください。クエリの実行は最初のリクエストから最大20分間継続可能です。その総時間を超えると、APIはHTTP 408をエラーコード QueryTimeout返します。

短縮された結果

グラフは、クエリ応答の内部バイナリ表現が64MBを超えると切り詰められます。 APIは適合する行を返し、その行にステータスを追加 additionalStatuses。追加ステータスはパブリックコード01000を使用し、_graphaneGqlStatus正典のGQLSTATUS 01M11を保持しています。

切断は省略された行に対して nextPage トークンを生成しません。フィルターや特定の予測、または LIMITでクエリを絞り込み、再度実行します。

省略された結果

レスポンススキーマは、データや評価結果に依存しない文が行を生成しない操作を表現することができます。この結果はステータスコード 00001を使用します:

{
  "kind": "NOTHING"
}

この省略された結果は、行のないテーブルとは異なります。空テーブルは、現在返すべき行がない行を生成するクエリを評価した結果です。

グラフはこの結果形状およびステータスコードを将来のデータ定義言語(DDL)およびデータ操作言語(DML)文のサポートのために保留しています。現在のクエリ文は常にテーブルの結果を返します。

値の型とエンコード

API では、リッチ型システムを使用して、正確なセマンティクスで GQL 値を表します。 GQL 値の JSON 形式は、判別共用体パターンに従います。

注

表形式の結果の JSON 形式では、 gqlType と value を分離して判別共用体パターンを実現し、よりコンパクトな表現を実現します。テーブルのシリアル化の最適化を参照してください。

値の構造

{
  "gqlType": "TYPE_NAME",
  "value": <type-specific-value>
}

プリミティブ型

GQL 型	Example	Description
`BOOL`	`{"gqlType": "BOOL", "value": true}`	ネイティブ JSON ブール値
`STRING`	`{"gqlType": "STRING", "value": "Hello"}`	UTF-8 文字列

数値型

整数型

GQL 型	範囲	JSON シリアル化	Example
`INT64`	-2⁶ 2⁶ ²-1	数値または文字列*	`{"gqlType": "INT64", "value": -9237}`
`UINT64`	0 から 2⁶⁴-1	数値または文字列*	`{"gqlType": "UINT64", "value": 18467}`

JavaScript の安全範囲外の大きな整数 (-9,007,199,254,740,991 ~ 9,007,199,254,740,991) は文字列としてシリアル化されます。

{"gqlType": "INT64", "value": "9223372036854775807"}
{"gqlType": "UINT64", "value": "18446744073709551615"}

浮動小数点型

GQL 型	範囲	JSON シリアル化	Example
`FLOAT64`	IEEE 754 binary64	JSON 番号または文字列	`{"gqlType": "FLOAT64", "value": 3.14}`

浮動小数点値は、IEEE 754 の特殊な値をサポートします。

{"gqlType": "FLOAT64", "value": "Inf"}
{"gqlType": "FLOAT64", "value": "-Inf"}
{"gqlType": "FLOAT64", "value": "NaN"}
{"gqlType": "FLOAT64", "value": "-0"}

テンポラル型

サポートされているテンポラル型では、ISO 8601 文字列形式が使用されます。

GQL 型	Format	Example
`ZONED DATETIME`	YYYY-MM-DDTHH:MM:SS[.ffffff]±HH:MM	`{"gqlType": "ZONED DATETIME", "value": "2023-12-25T14:30:00+02:00"}`

Graph 要素の参照型

GQL 型	Description	Example
`NODE`	グラフノードリファレンス	`{"gqlType": "NODE", "value": "node-123"}`
`EDGE`	グラフエッジリファレンス	`{"gqlType": "EDGE", "value": "edge_abc#def"}`

複合型

複合型は、他の GQL 値で構成されます。

Lists

リストには、一貫性のある要素型を持つ null 許容値の配列が含まれています。

{
  "gqlType": "LIST<INT64>",
  "value": [1, 2, null, 4, 5]
}

特殊なリストの種類:

LIST<ANY> - 混合型 (各要素には完全な型情報が含まれます)
LIST<NULL> - 許容される null 値のみ
LIST<NOTHING> - 常に空の配列

経路

パスは、グラフ要素の参照値のリストとしてエンコードされます。

{
    "gqlType": "PATH",
    "value": ["node1", "edge1", "node2"]
}

テーブルのシリアル化の最適化を参照してください。

テーブルのシリアル化の最適化

テーブルの結果の場合、値のシリアル化は列の型情報に基づいて最適化されます。

既知の型 - 生の値のみがシリアル化されます
ANY 列 - 型識別子を持つ完全な値オブジェクト

{
  "kind": "TABLE",
  "columns": [
    {"name": "name", "gqlType": "STRING", "jsonType": "string"},
    {"name": "amount", "gqlType": "INT64", "jsonType": "number|string"},
    {"name": "mixed", "gqlType": "ANY", "jsonType": "object"}
  ],
  "data": [
    {
      "name": "Alice",
      "amount": "123",
      "mixed": {"gqlType": "INT64", "value": "1"}
    }
  ]
}

エラー処理

トランスポートエラー

HTTPステータスとGQLステータスは応答の異なる層を表しています:

HTTP 状態	Meaning
200	APIがリクエストを処理しました。 `status.code`検査してください。結果は成功、行なし、クエリが進行中、またはユーザーが訂正可能なクエリエラーを示すことがあります。
408	クエリ実行は合計20分のタイムアウトを超えました。エラーコードは `QueryTimeout`。
429	サービスレートの制限を超えました。 `Retry-After`ヘッダーの持続時間が終わるまで待ってから再挑戦してください。
499	発信者はリクエストをキャンセルしました。エラーコードは `ClientCancelled`。
その他の4xxまたは5xx	リクエストまたはサービスが失敗し、GQL実行結果が返される前に。 HTTPエラー応答を確認しましょう。

アプリケーションエラー

アプリケーションレベルのエラーは、状態オブジェクトにエラー情報を含むHTTP 200を返すことがあります。例えば、ゼロでの割り算は公開APIコード 42000 を使用し、診断レコードの標準的なGQLSTATUS 22012 を保持します。

{
  "status": {
    "code": "42000",
    "description": "error: data exception - division by zero",
    "diagnostics": {
      "OPERATION": "query",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/",
      "_graphaneGqlStatus": {
        "gqlType": "STRING",
        "value": "22012"
      },
      "_graphaneIsUserError": {
        "gqlType": "BOOL",
        "value": true
      },
      "_graphaneIsTransientError": {
        "gqlType": "BOOL",
        "value": false
      }
    }
  }
}

状態チェック

広範な結果を判断するには、公衆の資料 status.codeを確認してください。 _graphaneGqlStatusは、数値オーバーフロー(22003)とゼロ除算(22012)など、特定のクエリエンジン条件を区別する必要がある場合に使います。

az rest を使用した完全な例

次のように、ベアラートークンを手動で取得する必要がないように、 az rest コマンドを使用してクエリを実行します。

az rest --method post --url "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/graphModels/{graphModelId}/executeQuery?beta=true" \
--headers "Content-Type=application/json" "Accept=application/json" \
--resource "https://api.fabric.microsoft.com" \
--body '{ 
  "query": "MATCH (n:Person) WHERE n.birthday > 19800101 RETURN n.firstName, n.lastName, n.birthday ORDER BY n.birthday LIMIT 100" 
}'

curl を使用した完全な例

このセクションの例では、シェルからの HTTPS 要求を実行するために curl ツールを使用します。

次のように、シェル変数に格納されている有効なアクセストークンがあることを前提としています。

export ACCESS_TOKEN="your-access-token-here"

ヒント

有効なベアラートークンを取得する方法については、認証に関するセクションを参照してください。

次のようなクエリを実行します。

curl -X POST "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/graphModels/{graphModelId}/executeQuery?beta=true" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "query": "MATCH (n:Person) WHERE n.birthday > 19800101 RETURN n.firstName, n.lastName, n.birthday ORDER BY n.birthday LIMIT 100" 
  }'

ベストプラクティス

GQL クエリ API を使用する場合は、次のベストプラクティスに従ってください。

エラー処理

常に状態コードを確認 する - HTTP 200 に基づいて成功を想定しないでください。
エラーの詳細を解析 する - デバッグに診断と原因チェーンを使用します。

セキュリティ

HTTPS を使用する - 暗号化されていない接続を介して認証トークンを送信しないでください。
トークンのローテーション - 適切なトークン更新と有効期限処理を実装します。
入力の検証 - ユーザーがクエリテキストに挿入する値を検証し、正しくエスケープします。

値表現

大きな整数値を処理 する - 整数は、JSON 数値としてネイティブに表現できない場合、文字列としてエンコードされます。
特殊な浮動小数点値を扱う - APIは正無限大、負無限大、非数値、負0を "Inf"、 "-Inf"、 "NaN"、 "-0"としてシリアライズします。
null 値の処理 - JSON null は GQL null を表します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-09-29

GQL クエリ API リファレンス

概要

主な機能

[前提条件]

Authentication

ユーザー委任アクセス

アプリケーション アクセス

API エンドポイント

クエリ パラメーター

要求ヘッダー

要求の形式

基本的な要求構造

要求フィールド

応答形式

応答構造

Status オブジェクト

状態コード

診断レコード

原因

その他の状態オブジェクト

結果の種類

テーブルの結果

実行時間の長いクエリ

短縮された結果

省略された結果

値の型とエンコード

値の構造

プリミティブ型

数値型

整数型

浮動小数点型

テンポラル型

Graph 要素の参照型

複合型

Lists

経路

テーブルのシリアル化の最適化

エラー処理

トランスポート エラー

アプリケーション エラー

状態チェック

az rest を使用した完全な例

curl を使用した完全な例

ベスト プラクティス

エラー処理

セキュリティ

値表現

関連コンテンツ

フィードバック

その他のリソース

アプリケーションアクセス

クエリパラメーター

トランスポートエラー

アプリケーションエラー

ベストプラクティス