dataflows-consumption-cli

更新の確認 — セッションごとに1回（必須） このスキルをセッション内で初めて使用する際は、先に check-updates スキルを実行してください。

• GitHub Copilot CLI / VS Code：check-updates スキルを呼び出してください。
• Claude Code / Cowork / Cursor / Windsurf / Codex：ローカルの package.json のバージョンとリモートのバージョンを比較してください。
• このセッションですでに確認済みの場合はスキップしてください。

重要な注意事項

1. ワークスペース名からワークスペースの詳細（IDを含む）を調べるには、すべてのワークスペースを一覧表示してから、JMESPath フィルタリングを使用してください。
2. 名前からデータフローを調べるには、ワークスペース内のすべてのデータフローを一覧表示し、クライアント側で displayName によるフィルタリングを行ってください。サーバー側での名前フィルタリングには対応していません。
3. getDefinition は GET ではなく POST です。データを読み取る操作であっても同様です。

スコープの境界 — 読み取り専用（必須） このスキルは厳密に読み取り専用です。データフローやその定義を作成、更新、削除してはなりません。つまり、Delete Dataflow、Create Dataflow、updateDefinition、その他の変更・破壊的な呼び出し（データフローに対する az rest --method delete/put/patch や、作成・上書きを行う POST など）は禁止です。許可される POST は、以下に記載されている読み取り用の getDefinition および executeQuery 操作のみです。 ユーザーからデータフローの削除、作成、変更、または永続化を依頼された場合は、最終回答でその変更操作を明示的に拒否し、将来の引き継ぎ先として dataflows-authoring-cli の名前のみを提示してください。そのスキルを呼び出したり、書き込みに備えた探索を行ったり、同じターンで書き込みワークフローを続行したりしてはなりません。変更操作を開始できるのは、ユーザーが別の作成依頼を明示的に確認した後に限られます。

dataflows-consumption-cli — CLI による Dataflows Gen2 の利用

目次

タスク	参照	備考
Fabric でワークスペースとアイテムを検索する	COMMON-CLI.md § Fabric でワークスペースとアイテムを検索する	必須 — まずリンクを読む
Fabric のトポロジと主要な概念	COMMON-CORE.md § Fabric のトポロジと主要な概念
環境 URL	COMMON-CORE.md § 環境 URL
認証とトークンの取得	COMMON-CORE.md § 認証とトークンの取得	audience が間違っていると 401 が発生します。認証の問題が発生した場合は、まずお読みください
コアのコントロールプレーン REST API	COMMON-CORE.md § コアのコントロールプレーン REST API	ページネーション、LRO のポーリング、レート制限のパターンを含みます
ジョブの実行	COMMON-CORE.md § ジョブの実行
注意事項、ベストプラクティス、トラブルシューティング	COMMON-CORE.md § 注意事項、ベストプラクティス、トラブルシューティング
ツール選択の根拠	COMMON-CLI.md § ツール選択の根拠
認証のレシピ	COMMON-CLI.md § 認証のレシピ	az login のフローとトークンの取得
az rest による Fabric コントロールプレーン API	COMMON-CLI.md § az rest による Fabric コントロールプレーン API	必ず --resource を指定してください。ページネーションと LRO のヘルパーを含みます
ジョブの実行（CLI）	COMMON-CLI.md § ジョブの実行
注意事項とトラブルシューティング（CLI 固有）	COMMON-CLI.md § 注意事項とトラブルシューティング（CLI 固有）	az rest の audience、シェルのエスケープ、トークンの有効期限
クイックリファレンス	COMMON-CLI.md § クイックリファレンス	az rest のテンプレートとトークン audience／ツールの対応表
使用機能の対応表	DATAFLOWS-CONSUMPTION-CORE.md § 使用機能の対応表	最初に読む — 利用可能な操作を確認できます
REST API の範囲（使用）	DATAFLOWS-CONSUMPTION-CORE.md § REST API の範囲	List、Get、Parameters、getDefinition、Jobs
Dataflow 定義の調査	DATAFLOWS-CONSUMPTION-CORE.md § Dataflow 定義の調査	mashup.pq、queryMetadata.json、.platform をデコードします
パラメーターの検出と分析	DATAFLOWS-CONSUMPTION-CORE.md § パラメーターの検出と分析	型、形式、M コードのパターン
更新とジョブの監視	DATAFLOWS-CONSUMPTION-CORE.md § 更新とジョブの監視	LRO パターン、ジョブインスタンス、ポーリングのベストプラクティス
エージェントによる探索パターン	DATAFLOWS-CONSUMPTION-CORE.md § エージェントによる探索パターン	6 ステップの検出手順
セキュリティと権限のモデル	DATAFLOWS-CONSUMPTION-CORE.md § セキュリティと権限のモデル	操作ごとの権限マトリックス
よくあるエラー	DATAFLOWS-CONSUMPTION-CORE.md § よくあるエラー	エラーコードと解決方法
注意事項とトラブルシューティングのリファレンス	DATAFLOWS-CONSUMPTION-CORE.md § 注意事項とトラブルシューティング	原因と解決方法を示した 12 件の番号付き項目
クイックリファレンス：一行コマンド	consumption-cli-quickref.md	使用に関するすべての操作に対応した az rest の一行コマンド
検出パターン	discovery-queries.md	定義のデコード、パラメーターの抽出、接続の分析
スクリプトテンプレート	script-templates.md	コピーして使える bash および PowerShell のテンプレート
プレビュー データの可視化	chart-visualization.md	executeQuery の結果を ASCII の折れ線／棒／円グラフとして表示します（依存関係なし）
ツールスタック	SKILL.md § ツールスタック
接続	SKILL.md § 接続
エージェントによる探索（「自分の Dataflow とチャット」）	SKILL.md § エージェントによる探索	Dataflow の探索はここから開始してください
クエリの実行	SKILL.md § クエリ評価	個々のクエリを実行します。応答は Apache Arrow バイナリです

---

ツールスタック

ツール	役割	インストール
az CLI	主要：認証（az login）、az rest を介した Fabric REST API	ほとんどの開発環境にプリインストール済み
curl	REST 呼び出し用の代替 HTTP クライアント	プリインストール済み
jq	JSON レスポンスの解析、フィールドの抽出、出力の整形	プリインストール済み、または簡単にインストール可能
base64	定義パーツを base64 からデコード	bash に組み込み済み。PowerShell では [Convert]::FromBase64String を使用
bash/pwsh	スクリプトの実行	プリインストール済み

エージェントによる確認 — 最初の操作の前に確認してください。

az account show >/dev/null 2>&1 || echo "RUN: az login"
command -v jq >/dev/null 2>&1 || echo "INSTALL: apt-get install jq OR brew install jq"

---

接続

ワークスペース ID とデータフロー ID の解決

Fabric のワークスペースとアイテムの検索については、COMMON-CLI.md を参照してください。

# Find workspace ID by name
WS_ID=$(az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces" \
  --query "value[?displayName=='My Workspace'].id" --output tsv)

# Find dataflow ID by name within workspace
DF_ID=$(az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/dataflows" \
  --query "value[?displayName=='Sales Data Pipeline'].id" --output tsv)

再利用可能な接続変数

# Set once at script top
WS_ID="<workspaceId>"
DF_ID="<dataflowId>"
API="https://api.fabric.microsoft.com/v1"
AZ="az rest --resource https://api.fabric.microsoft.com"

---

エージェントによる探索（「データフローとチャットする」）

検出手順

ワークスペースのデータフローをすべて探索するには、以下を順番に実行します。拡張パターンについては、references/discovery-queries.md を参照してください。

# 1. List workspaces → find target
az rest --method get --resource "https://api.fabric.microsoft.com" \
  --url "$API/workspaces" --query "value[].{name:displayName, id:id}" -o table

# 2. List dataflows → enumerate all
az rest --method get --resource "https://api.fabric.microsoft.com" \
  --url "$API/workspaces/$WS_ID/dataflows" \
  --query "value[].{name:displayName, id:id, desc:description}" -o table

# 3. Get dataflow properties
az rest --method get --resource "https://api.fabric.microsoft.com" \
  --url "$API/workspaces/$WS_ID/dataflows/$DF_ID"

# 4. Discover parameters
#    Note: the /parameters endpoint returns DataflowNotParametricError (an HTTP 4xx)
#    for a non-parametric dataflow (no Power Query parameters). Treat that as
#    "this dataflow has no parameters" and report it plainly — do NOT surface the
#    raw error. Optionally confirm by checking mashup.pq for `IsParameterQuery`.
az rest --method get --resource "https://api.fabric.microsoft.com" \
  --url "$API/workspaces/$WS_ID/dataflows/$DF_ID/parameters" \
  --query "value[].{name:name, type:type, required:isRequired, default:defaultValue}" -o table

# 5. Get definition → decode mashup.pq
RESPONSE=$(az rest --method post --resource "https://api.fabric.microsoft.com" \
  --url "$API/workspaces/$WS_ID/dataflows/$DF_ID/getDefinition")
echo "$RESPONSE" | jq -r '.definition.parts[] | select(.path=="mashup.pq") | .payload' | base64 --decode

# 6. Check job history
az rest --method get --resource "https://api.fabric.microsoft.com" \
  --url "$API/workspaces/$WS_ID/dataflows/$DF_ID/jobs/instances" \
  --query "value[].{status:status, type:invokeType, start:startTimeUtc, end:endTimeUtc, error:failureReason}" -o table

エージェントワークフロー

1. 検出 → ステップ 1～3 を実行して、データフローを一覧表示し、特定します。
2. パラメーター → ステップ 4 で入力と既定値を確認します。
3. 定義 → ステップ 5 で M クエリ、接続、ステージング構成を調べます。
4. 監視 → ステップ 6 で更新履歴とエラーパターンを確認します。
5. 反復 → 特定のクエリや接続の詳細を詳しく調べます。
6. 提示 → 調査結果を要約するか、再利用可能なスクリプトを生成します（script-templates.md を参照）。

---

注意点、ルール、トラブルシューティング

プラットフォーム全般の注意点については、DATAFLOWS-CONSUMPTION-CORE.md の「注意点とトラブルシューティングのリファレンス」と、COMMON-CLI.md の「注意点とトラブルシューティング（CLI 固有）」を参照してください。

必ず行うこと

• 必ず最初に az login を実行する — az rest はアクティブなセッションを使用します。セッションがない場合、原因の分かりにくいエラーが発生します。
• 必ず --resource "https://api.fabric.microsoft.com" を指定する — 対象の指定が間違っていると 401 が返されます。
• ページネーションを処理する — continuationToken が存在しなくなるか null になるまで、リクエストを繰り返します。
• getDefinition の LRO を処理する — Location ヘッダーを伴う 202 Accepted が返される場合があります。完了するまでポーリングしてください。
• 調査の前に base64 をデコードする — 定義パーツは base64 でエンコードされています。
• getDefinition には POST を使用する — GET エンドポイントではありません。

避けること

• GUID のハードコード — 常に一覧取得後にフィルターするパターンで検索してください。
• getDefinition が GET だと思い込むこと — POST です（よくある間違い）。
• ページネーションを無視すること — 一覧エンドポイントは部分的な結果を返す場合があります。
• 過度に頻繁なポーリング — 429 の場合は Retry-After ヘッダーに従ってください。
• Viewer ロールで getDefinition が使えると期待すること — Read+Write（Contributor 以上）が必要です。

推奨事項

• 生の curl より az rest を優先する — 認証を自動的に処理します。
• 一覧取得後にフィルターするパターンを使う — データフローにはサーバー側の名前フィルターがありません。
• ジョブのポーリングには指数バックオフを使う — 5 秒 → 10 秒 → 20 秒 → 最大 30 秒。
• レスポンスの解析には jq を使う — シェル文字列操作よりも簡潔です。
• az rest 内での単純なフィールド抽出には JMESPath の --query を使う。
• スクリプトの再利用には環境変数（WS_ID、DF_ID、API）を使う。

トラブルシューティング

症状	原因	対処方法
401 Unauthorized	トークンの有効期限切れ、またはオーディエンスの誤り	az login を実行し、--resource "https://api.fabric.microsoft.com" を指定してください
getDefinition で 403 Forbidden	ビューアーのロール（読み取り専用）	コントリビューター以上のロール（読み取りと書き込み）が必要です
404 Not Found	ワークスペースまたはデータフロー ID の誤り	List Dataflows API で再検出してください
getDefinition が 202 を返す	定義が大きい、またはサーバーが高負荷	処理が完了するまで Location ヘッダーの URL をポーリングしてください
/parameters で DataflowNotParametricError（4xx）	データフローに Power Query パラメーターがない（パラメーター化されていない）	想定どおりです。「このデータフローにはパラメーターがありません」と報告し、生のエラーは表示しないでください。必要に応じて mashup.pq の IsParameterQuery で確認してください
queryMetadata.json の connections 配列が空、または存在しない	クエリがインライン／リテラルソース（例：#table()）を使用しているため、バインドする外部接続がありません	想定どおりです。「外部データソース接続はありません（インラインソース）」と報告し、存在しないバインドを捏造しないでください
Base64 デコード後のテキストが文字化けする	エンコードされたコンテンツに BOM が含まれている	デコード時に UTF-8 BOM（\xEF\xBB\xBF）を除去してください
429 TooManyRequests	レート制限	Retry-After ヘッダーに従い、指数バックオフを実装してください
リストに重複した結果がある	古い continuationToken を再利用している	常に最新のレスポンスから取得したトークンを使用してください
OperationNotSupportedForItem	アイテムの種類が違う	Get Item を使用して、アイテムの種類が Dataflow であることを確認してください

---

例

例 1：ワークスペース内のすべてのデータフローを一覧表示する

プロンプト：「このワークスペース内のすべてのデータフローを一覧表示してください。」

エージェントの応答：

az rest --method get \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/dataflows" \
  --resource "https://api.fabric.microsoft.com" \
  --query "value[].{Name:displayName, Id:id, Type:type}" -o table

例 2：データフロー定義をデコードする

プロンプト：「このデータフロー内の Power Query M コードを表示してください。」

エージェントの応答：

# Step 1: Request definition (POST returns 202 with Location header).
# az rest cannot expose response headers, so capture Location via curl + az-acquired token.
TOKEN=$(az account get-access-token --resource "https://api.fabric.microsoft.com" --query accessToken -o tsv)
LOCATION=$(curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" -H "Content-Length: 0" \
  "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/dataflows/${DF_ID}/getDefinition" \
  -o /dev/null -D - | tr -d '\r' | grep -i "^location:" | awk '{print $2}')

# Step 2: Poll until definition is ready
DEF=$(az rest --method get --url "${LOCATION}" \
  --resource "https://api.fabric.microsoft.com")

# Step 3: Decode mashup.pq to see the Power Query M code
echo "$DEF" | python3 -c "
import json, base64, sys
parts = json.load(sys.stdin)['definition']['parts']
for p in parts:
    if p['path'] == 'mashup.pq':
        print(base64.b64decode(p['payload']).decode('utf-8'))
"

例 3：更新ジョブの履歴を確認する

プロンプト：「このデータフローの最近の更新履歴を表示してください。」

エージェントの応答：

# Get recent job instances for a dataflow
az rest --method get \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/dataflows/${DF_ID}/jobs/instances?limit=5" \
  --resource "https://api.fabric.microsoft.com" \
  --query "value[].{Status:status, Start:startTimeUtc, End:endTimeUtc, Id:id}" -o table

例 4：定義からパラメーターを検出する

プロンプト：「このデータフローで受け付けるパラメーターを教えてください。」

エージェントの応答：

# After decoding the definition (see Example 2), extract parameters:
echo "$DEF" | python3 -c "
import json, base64, sys
parts = json.load(sys.stdin)['definition']['parts']
for p in parts:
    if p['path'] == 'queryMetadata.json':
        meta = json.loads(base64.b64decode(p['payload']).decode('utf-8'))
        for qname, qmeta in meta.get('queriesMetadata', {}).items():
            if qmeta.get('queryGroupId') == 'parameters' or 'IsParameterQuery' in str(qmeta):
                print(f'Parameter: {qname}')
"

---

クエリの評価

データフローから個別のクエリを実行し、結果を確認します。レスポンスは Apache Arrow IPC の生ストリームであり、Content-Type: application/vnd.apache.arrow.stream です。JSON エンベロープではありません。 有効なストリームの先頭4バイトは、IPC 継続マーカー ff ff ff ff です。pyarrow.ipc.open_stream() で解析してください。

ワイヤ形式：executeQuery は Apache Arrow IPC の生バイトストリーム（Content-Type: application/vnd.apache.arrow.stream）を返します。JSON ではありません。 jq で解析しようとしないでください。抽出する JSON エンベロープはありません。--output-file を使ってバイトを保存し、Arrow として解析してください（例5～7を参照）。

失敗時も HTTP 200 が返されます：基盤となるソースクエリが失敗しても（Kusto SEM0100、T-SQL の構文エラー、列の欠落など）、executeQuery は application/vnd.apache.arrow.stream とともに 200 OK を返します。エラーはストリームの PQ Arrow Metadata セクションに {"Error":"..."} として埋め込まれています。検出用スニペットについては、dataflows-authoring-cli § mashup-preview.md → Arrow 本文内の失敗を検出するを参照してください。単純な HTTP ステータスチェックでは、失敗を成功として扱ってしまいます。

用途の区分（executeQuery の正式なリファレンスは mashup-preview.md です）：同じ executeQuery エンドポイントは、異なる2つの用途に対応しています。このスキルでは、データの取得を扱います。

• (a) 保存済みクエリの実行 — 本文は {"QueryName":"<saved-shared>"} のみ（customMashupDocument なし）。
• (b) アドホックな読み取り専用の customMashupDocument — updateDefinition で保存する意図なしに、候補となる section Section1; ... ドキュメントをプレビューします（例7）。

M を保存する場合は、dataflows-authoring-cli § ワークフロー C（プレビュー駆動の作成ループ）を使用してください。ここでは、ブートストラップバインドルール（新しい認証情報付きデータフローに必要な、コネクションバインドの先行設定）、自動ラップルール、上限のないプレビューを厳禁とするルール、およびプレビュー後の保存手順を扱います。

自動ラップに関する注意：Fabric REST API では、customMashupDocument は完全な section Section1; ... shared X = ...; ドキュメントである必要があります。let ... in ... の式はサーバー側で自動ラップされません。完全なセクションドキュメントを送信し、QueryName リクエストフィールドが、その中で宣言されている shared メンバーと一致するようにしてください。

本文の形式：最上位に QueryName を持つフラットなオブジェクトを送信してください（ワイヤ上ではフィールド名の大文字と小文字は区別されません。正式な形式は PascalCase です）。{"queries":[{...}]} 配列形式は、内側の大文字と小文字にかかわらず、常に 400 DataflowExecuteQueryError: Invalid query name を返します。QueryName の値が誤っている場合は、別のエラーコードである QueryNotFound が返されます。dataflows-authoring-cli § mashup-preview.md → リクエスト本文を参照してください。

処理の重い保存済みクエリで TimedOut が発生した場合の復旧方法：保存済みの shared <Q> メンバーの処理コストがサーバー側の executeQuery の制限（観測上は約90秒。400 DataflowExecuteQueryError → InternalErrorCode: EvaluationError, Message: Evaluation result error code: TimedOut として表面化）を超える場合、同じ本文を再試行しないでください。結果は決定的です。代わりに、customMashupDocument に保存済みの mashup.pq 全体（例2でデコード）を設定し、さらに shared __PreviewCap = Table.FirstN(<Q>, 10); というプローブを追加して、QueryName: "__PreviewCap" を指定して再送信してください。この上限は、ほとんどのコネクター（Kusto、SQL、OData、Web テーブル）でソース側にプッシュダウンされるため、ソースはサンプルのみを返します。dataflows-authoring-cli § mashup-preview.md → 観測された InternalErrorCode の値を参照してください。

前提条件

• Dataflow が存在していること（上記の例 1 で確認してください）
• dataflow 内にクエリ名が存在していること（例 2 に従って mashup.pq で確認してください）
• ユーザーが dataflow に対する Contributor ロール以上（読み取り＋書き込み権限）を持っていること
• 任意：クエリパラメーターとカスタム M コードの変更

例 5：クエリを実行して結果を保存する

プロンプト：「この dataflow で SalesData クエリを実行し、結果を保存してください。」

エージェントの応答：

# Step 1: Identify the query to execute (must be a `shared` member of the dataflow's mashup)
QUERY_NAME="SalesData"  # Replace with your query name

# Step 2: Build the request body. To execute the persisted query as-is, send ONLY
#   QueryName — omit customMashupDocument. (Do NOT pass a self-referential
#   `shared X = let Source = #shared[X] in Source` — that recurses on itself
#   inside the candidate document.) For custom M, see Example 7.
jq -n --arg q "$QUERY_NAME" '{QueryName: $q}' > req.json

# Step 3: Execute the query (raw Apache Arrow IPC stream is written directly to disk)
az rest --method post \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/dataflows/${DF_ID}/executeQuery" \
  --resource "https://api.fabric.microsoft.com" \
  --body "@req.json" \
  --output-file "${QUERY_NAME}_results.arrow"

# Step 4: Check for embedded source errors (HTTP 200 does NOT mean success)
if grep -q '"Error":"' "${QUERY_NAME}_results.arrow"; then
  echo "Query execution failed (embedded in Arrow body):"
  python3 -c "import re,sys; raw=open(sys.argv[1],'rb').read().decode('utf-8','replace'); m=re.search(r'\\{\"Error\":\"[^\"]+\"\\}', raw); print(m.group(0) if m else '(marker present, JSON not parsed)')" "${QUERY_NAME}_results.arrow"
  exit 1
fi

echo "Query results saved to ${QUERY_NAME}_results.arrow"

--output-file を使う理由：指定しない場合、az rest は生のバイトを標準出力に出力し、警告 Not a json response, outputting to stdout. For binary data suggest use "--output-file" to write to a file を表示します。Arrow IPC ストリームを適切に保存するため、executeQuery には必ず --output-file を指定してください。以前のドキュメントにある jq -r '.data' | base64 --decode のパターンは、az rest では誤りです。抽出対象となる JSON エンベロープはありません。

例 5b：クエリ結果を Markdown テーブルとして表示する

プロンプト：「その結果の先頭 10 行を表示してください。」

エージェントの応答 — 保存した Arrow ファイルを読み込み、head(N) をチャット内に Markdown テーブルとして表示します。executeQuery の実行後は必ずこれを行ってください（デフォルトの N=10）。視覚的なプレビューにより、埋め込みエラー検出器では見逃される サイレント成功 のバグを検出できます。フィルターによってすべての行が除外された、誤った列を参照した、誤った型変換を行った、フィルターの境界が 1 つずれた、結合キーに誤字がある、といった問題です。

N=${N:-10}; ARROW_FILE="${QUERY_NAME}_results.arrow"
python3 - <<EOF
import json, sys, pyarrow as pa, pyarrow.ipc as ipc

with open("$ARROW_FILE", "rb") as f:
    try:
        reader = ipc.open_stream(f)
    except pa.lib.ArrowInvalid:
        f.seek(0); reader = ipc.open_file(f)
    # Surface any embedded engine error before rendering (mirrors mashup-preview.md § Error handling — A)
    for v in (reader.schema.metadata or {}).values():
        s = v.decode("utf-8", errors="replace")
        if '"Error"' in s:
            try:
                msg = json.loads(s)["Error"]
            except (ValueError, KeyError):
                msg = s[:200]
            sys.exit(f"Preview failed: {msg}")
    table = reader.read_all()

rows, cols = table.num_rows, table.num_columns
print(f"**{rows} rows × {cols} columns** · {', '.join(table.schema.names)}\n")
if rows == 0:
    sys.exit(0)

# Slice at the Arrow level before converting — avoids materialising the whole result.
df = table.slice(0, $N).to_pandas().copy()
# Truncate long string cells so the chat table stays readable.
for c in df.select_dtypes(include=["object", "string"]).columns:
    df[c] = df[c].astype(str).str.slice(0, 50)
try:
    print(df.to_markdown(index=False))           # requires the `tabulate` package
except ImportError:
    print(df.to_string(index=False))             # fallback: fixed-width text
EOF

任意の依存関係：pandas.DataFrame.to_markdown() には tabulate パッケージが必要です。例 6 で pyarrow／pandas をインストールしたのと同様に、お使いの環境の標準的な Python ツールを使って一度インストールしてください。tabulate がない場合、スニペットは固定幅の to_string() にフォールバックするため、引き続き表示できます。

表示を省略する場合：デフォルトでは head(N) を表示してください。省略するのは、（a）ユーザーがプレビューなしで Arrow ファイルそのものを明示的に求めた場合、（b）結果の行数が約 1000 行を超える場合（この場合も head(N) を表示し、合計行数について 1 行の注記を追加してください）、または（c）Arrow ファイルを直接処理する別のツールに結果をそのままストリーミングする場合に限ります。それ以外の場合はすべて、表示してください。保存されたファイルだけでは、チャット内でユーザーから見えません。

例 6：Arrow の結果を CSV に変換する

プロンプト：「Excel で開けるように、Arrow クエリの結果を CSV に変換してください。」

エージェントの応答：

前提条件（初回のみのクライアント側セットアップ）：この例では、Arrow IPC ストリームのデコードに pyarrow を、CSV の書き出しに pandas を使用します。お使いの環境の標準的な Python ツールを使って、一度インストールしてください。これらはローカルのクライアント依存関係であり、Fabric のレシピには含まれません。

python3 <<EOF
import pyarrow as pa
import pandas as pd
import sys

ARROW_FILE = "${QUERY_NAME}_results.arrow"
CSV_FILE = "${QUERY_NAME}_results.csv"

# Open the Arrow IPC stream directly (raw on the wire, no envelope)
with open(ARROW_FILE, "rb") as f:
    reader = pa.ipc.open_stream(f)

    # Defensive: surface any error embedded in the stream's PQ Arrow Metadata
    md = reader.schema.metadata or {}
    for k, v in md.items():
        s = v.decode("utf-8", errors="replace")
        if '"Error"' in s:
            print(f"Preview failed: {s}", file=sys.stderr)
            sys.exit(1)

    table = reader.read_all()

# Convert to pandas and export as CSV
df = table.to_pandas()
df.to_csv(CSV_FILE, index=False)

print(f"Converted {len(df)} rows to CSV")
print("Columns:", list(df.columns))
EOF

例 7：カスタム M コードでクエリを実行する

プロンプト：「この dataflow に対して、保存せずに一度限りのアドホックな M クエリを実行してください。」

意図：アドホックな読み取り専用の実行です。customMashupDocument は永続化されません。updateDefinition を使って M を保存する場合は、代わりに dataflows-authoring-cli § Workflow C を使用してください。bootstrap-bind、自動ラップ、プレビュー後の永続化ルールが追加されます。

エージェントの応答：

# Execute a query with custom M code (e.g., filter, aggregate, transform).
# The customMashupDocument must be a complete `section` document; az rest does NOT auto-wrap raw expressions.
CUSTOM_M='section Section1;

shared CustomQuery = let
    Source = Table.FromRecords({[id=1, name="Alice"], [id=2, name="Bob"]}),
    Filtered = Table.SelectRows(Source, each [id] > 0)
in
    Filtered;'

jq -n --arg m "$CUSTOM_M" '{QueryName: "CustomQuery", customMashupDocument: $m}' > req.json

az rest --method post \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/dataflows/${DF_ID}/executeQuery" \
  --resource "https://api.fabric.microsoft.com" \
  --body "@req.json" \
  --output-file custom_results.arrow

# Always check for embedded errors before treating the file as a success
if grep -q '"Error":"' custom_results.arrow; then
    echo "Custom query failed; inspect custom_results.arrow for the embedded {\"Error\":...} block."
    exit 1
fi

---

出力の形式

このスキルがタスクを完了したとき、エージェントは次の形式で返答します。

フィールド	規約
詳細度	ステータスは簡潔な要約（3～10行）、一覧表示や検査の結果は Markdown テーブルにします。
デフォルトの形式	list 形式のクエリには Markdown テーブル、単一リソースの結果にはフェンス付き JSON コードブロック、デコード済みの mashup.pq にはフェンス付きの ```m ブロックを使います。executeQuery の場合は、Arrow ストリーム全体をファイルに保存し、head(N)（デフォルトの N=10）をチャット内で Markdown テーブルとして表示します。Example 5b を参照してください。表示を抑制できるのは、ユーザーが明示的にリクエストした場合、rows > 1000 の場合（先頭の行と合計件数の注記を表示）、または結果を別のツールにストリーミングする場合のみです。
副作用の開示	このスキルは読み取り専用です。変更を行うと示唆してはならず、作成・更新・削除のリクエストは拒否し（dataflows-authoring-cli に案内してください）。
検証	ユーザーが呼び出しを再現できるよう、応答にソース URL（例：az rest --url の値）を含めます。
エラーの提示	executeQuery が {"Error":"..."} を埋め込んだ Arrow を返した場合は、エラーをそのまま提示し、部分的な結果を成功として示してはなりません。