sqldb-cli

テレメトリ — 必須。 すべての api.fabric.microsoft.com 呼び出しには x-ms-fabric-skill: sqldb-cli を付ける必要があります（az rest の場合は --headers "x-ms-fabric-skill=sqldb-cli"）。 fabric_lro やリトライを含む、すべての LRO ポーリングにも付けてください。スニペットでは省略されていますが、必ず追加してください。

重要な注意事項

1. ワークスペース名から詳細（ID を含む）を見つけるには、すべてのワークスペースを一覧表示してから、JMESPath で絞り込みます
2. ワークスペース ID、アイテムの種類、アイテム名からアイテムの詳細（ID を含む）を見つけるには、そのワークスペース内にある該当する種類のアイテムをすべて一覧表示してから、JMESPath で絞り込みます
3. スキルの使い分け：sqldb-cli は Fabric SQL データベースのアイテム（OLTP、SQL Server エンジン）にのみ使用してください。Warehouse、Lakehouse SQL エンドポイント、Mirrored Database には sqldw-cli を、ノートブックのセルには spark-cli を使用します。

Fabric SQL Database (OLTP) -- CLI スキル

このスキルは、Fabric SQL データベースの T-SQL スキーマ作成、読み取り専用クエリ、OLTP パフォーマンス診断を担当します。

これはモードディスパッチャーであり、手順は一切含まれていません。以下の表からリクエストに合ったモードを選び、コマンドを一つでも実行する前に、ファイル読み取りツールを使って該当する references/<mode>.md ファイルを最初から最後まで読んでください。そのファイルにはエンドポイント、ペイロードの形式、テンプレート、注意点が記載されています。読まずに実行すると、誤ったペイロードや結果につながります。

モードの選択

モード	リクエストの内容	例	最初に読むファイル
authoring	既存のデータベース内でスキーマやデータを作成・変更する場合：テーブル、制約、インデックス、ベクトル列、プロシージャ、dacpac のデプロイ、INSERT/UPDATE/DELETE/MERGE。また、リクエストで新しいデータベースを求められている場合に限り、SQL データベースのアイテム自体を作成します	sqldb table の作成、sqldb の外部キー、dacpac のデプロイ、sqldb スキーマの変更、fabric での sql database の作成	references/authoring.md
consumption	sqlcmd を通じて読み取り専用の T-SQL を実行する場合：SELECT、カタログの調査、ベクトル類似性検索、時間軸クエリ	sqldb sys.tables、sqldb のベクトル類似性、sqldb の時間軸クエリ、sql database へのクエリ	references/consumption.md
operations	OLTP パフォーマンスを診断する場合：Query Store、ブロックされたセッション、性能が劣化したプラン、待機統計	sqldb query store、sql database のブロックされたセッション、sqldb の性能が劣化したプラン、sqldb の低速クエリ	references/operations.md

モード境界ルール

consumption で実行するのは読み取り専用の T-SQL のみです。DDL または DML は authoring モードに、パフォーマンスの調査は operations モードに該当します。モードを切り替えることを伝え、該当するリファレンスを読んでから実行してください。

authoring では、リクエストでデータベースの作成が求められていない限り、リクエストに記載されたデータベースはすでに存在するものとして扱います。データベースを特定したら、すぐに T-SQL に進んでください。スキーマやデータの作業を行う前提条件として、SQL データベースのアイテムをプロビジョニングしてはいけません。

リクエストが複数のモードにまたがる場合は、一度に一つずつ処理し、各作業を始める前に該当するリファレンスを読んでください。この表を読んでもモードを判断できない場合は、推測せず、簡潔な確認の質問を一つしてください。

Terminal write（ターミナルへの書き込み） -- 絶対に省略してはいけない手順

リファレンスを読み、変更を計画しただけではタスクを完了したことにはなりません。変更を伴う各モードでは、最後に状態を変更する呼び出しを1回実行します。それを実行していない場合、何も保存されていません。成功したと報告するのではなく、そのことを明示してください。

モード	Terminal write（ターミナルへの書き込み）
authoring	データベースに対して sqlcmd -Q／-i を使って T-SQL を実行してください。CREATE TABLE、ALTER、INSERT INTO、UPDATE、DELETE、MERGE INTO のステートメントを実際に実行する必要があります。DDL または DML を作成してユーザーに見せただけでは、何も変更されません。新しいデータベースを求められた場合に限り、ターミナルへの書き込みは代わりに POST /v1/workspaces/{ws}/sqlDatabases となり、完了するまでポーリングします。
consumption	なし -- このモードは厳密に読み取り専用です
operations	診断の読み取り自体については、なし。リファレンスに記載された唯一の例外は、一時的なブロッキングの調査で Extended Events セッション（CREATE EVENT SESSION ... ON DATABASE、ring_buffer ターゲット）を作成する場合です。この場合、最後の手順で必ずセッションを削除してください。実行中のまま残してはいけません。

タスクの完了を報告する前に、ターミナル呼び出しが成功を返したことを確認してください。また、リファレンスに読み戻しの手順が記載されている場合は、成果物を読み戻して変更が反映されたことを確認してください。

すべてのモードに共通する基本事項

まずワークスペースとアイテムを特定してください。どのモードでもこれが必要です。

タスク	リファレンス	備考
Fabric でワークスペースとアイテムを検索する	COMMON-CLI.md	必須 -- ワークスペースまたはアイテム ID を特定する前に読みます
Fabric のトポロジと主要概念	COMMON-CORE.md	アイテムの種類、ワークスペース、容量
環境 URL	COMMON-CORE.md	ソブリン クラウド／パブリック クラウド以外のホスト
認証とトークンの取得	COMMON-CORE.md	オーディエンスが違うと 401 になります。認証に問題がある場合は事前に読みます
認証の手順	COMMON-CLI.md	az login のフローとトークンの取得
コア コントロール プレーン REST API	COMMON-CORE.md	ページネーション、LRO のポーリング、レート制限
注意点とトラブルシューティング	COMMON-CLI.md	az rest のオーディエンス、シェルのエスケープ、トークンの有効期限

ルール

必須

• 何かをする前に、上の表からモードを1つだけ選択してください。
• モードの最初のコマンドを実行する前に、references/<mode>.md を最初のツール呼び出しで最初から最後まで読みます。一度だけ、全体をまとめて読みます。再度開いたり、もう一度 grep したり、ページごとに読み進めたりしないでください。すでに内容を確認しています。
• 読み込む他のすべてのファイル（ネストされた references/<mode>/*.md のサブリファレンスや共有の common/*.md ファイルを含む）についても、一度だけ読むルールを適用します。実際に必要なファイルだけを開き、それぞれ最初から最後まで一度だけ読み、読み込んだファイルを grep したり再度開いたりしないでください。
• 推測で GUID を選ばず、一覧表示して絞り込むことでワークスペース ID とアイテム ID を特定してください。
• リクエストがモードの境界を越える場合は、モードを切り替えることを明示してください。
• リファレンスは指示として扱い、成果物として扱わないでください。読んだ後は、記載されたコマンドを実際のワークスペースに対して実行し、実際の結果を報告してください。リファレンスの記述を引用するだけで、コマンドを実行しないのでは、リクエストへの回答になりません。

推奨

• リクエストを満たす範囲で、最も限定的なモードを選んでください。
• モードのリファレンスは正確に1つだけ読みます。リクエストが実際に複数のモードにまたがる場合に限り、2つ目を読み、その前にそのことを伝えてください。
• 最初の応答で選択したモードを伝え、ユーザーが訂正できるようにしてください。

避けるべきこと

• このディスパッチャーだけから実行すること -- これは意図的に運用上の詳細を省略しています。
• リファレンスを実行せずに、その要約で答えること。
• すでに読み込んだリファレンスを再度読んだり、再度 grep したりすること。これはターンとトークンを消費します。
• consumption または operations からスキーマやデータを変更すること -- どちらも読み取りで応答します。どちらかが発行できる唯一の書き込みは、operations の断続的ブロッキング調査が設定してから削除する Extended Events セッションです。
• このファミリーがすでに担っている作業に対して、別のスキルを読み込むこと（CRITICAL NOTES 3 を参照）。

例

ユーザーのリクエスト	モード	読み込むリファレンス
「Fabric SQL データベースに、Customers への外部キーを持つ Orders テーブルを作成してください。」	authoring	references/authoring.md
「このワークスペースに sales_oltp という新しい SQL データベースを作成してください。」	authoring	references/authoring.md
「SQL データベース内でこのベクトルに最も近い 5 つの埋め込みを見つけてください。」	consumption	references/consumption.md
「Query Store によると、過去 1 日でどのクエリがリグレッションしましたか？」	operations	references/operations.md