この参照を使用して、コマンドと一般的なワークフローを検出します。 インストールされているシェルで help <command> を実行し、正確な引数とオプションを指定します。 この記事の例は、ブロックが明示的に cosmosdbshell で始まる場合を除き、Azure Cosmos DB シェル内で実行されます。
例では、サンプル データベース ShellDemo、コンテナー Items、およびパーティション キー /tenantIdを使用します。 リソース名を目的のターゲットに置き換えます。 データを読み取ったり変更したりする前に、アカウントルートで info アカウントを確認します。
接続とナビゲーション
| Command | Purpose |
|---|---|
connect <endpoint-or-connection-string> |
Microsoft Entra ID、マネージド ID、アカウント キー、または既定の資格情報チェーンを使用して接続します。 |
disconnect |
現在のアカウントを切断します。 |
ls |
選択したスコープのデータベース、コンテナー、または項目を一覧表示します。 |
cd <path> |
データベースまたはコンテナーを選択します。
cdを使用してアカウント ルートに戻り、cd ..を使用して上に移動します。 |
pwd |
現在のAzure Cosmos DBの場所を表示します。 |
info |
選択したスコープで、アカウント、データベース、またはコンテナーの構成と使用状況を調べます。 |
connect https://<account-name>.documents.azure.com/ --tenant=<tenant-id>
info --format=json
ls
cd /ShellDemo/Items
pwd
info --database=ShellDemo --container=Items
pwd は、接続されているアカウントではなく、ナビゲーションを識別します。 アカウント ルートでは、 info --format=json には accountId と uriが含まれます。 他のスコープでは、 info 代わりにデータベースまたはコンテナーについて説明します。
--database (--db) と--container (--con) をサポートするコマンドは、ナビゲーションとは別にリソースをターゲットにすることができます。 前の cdに依存するのではなく、スクリプトと MCP 呼び出しでこれらのオプションを使用します。
ls コンテナーを一覧表示する場合、既定では 100 項目になります。
--maxを正の境界に設定します。
info --partitions クエリ データと消費要求ユニット (RU) を info --detailed します。詳細な分散分析では、コンテナーをスキャンできます。
接続オプション
| Option | Purpose |
|---|---|
--tenant |
このテナントには対話型Microsoft Entra認証を使用します。 |
--hint |
対話型サインインのユーザー名を事前入力します。 |
--managed-identity |
クライアント ID でユーザー割り当てマネージド ID を選択します。 |
--mode |
directまたはgateway接続を選択します。 |
--subscription、--resource-group |
アカウント管理操作Azure Resource Managerコンテキストを指定します。 |
明示的な資格情報オプションのないエンドポイントでは、既定の資格情報チェーンが使用されます。 ローカル エミュレーターの場合は、その localhost エンドポイントを使用します。 セミコロンはそれ以外の場合はシェル コマンドを区切るため、接続文字列を引用符で囲みます。 接続文字列は、再生可能なシェル履歴に保持できます。Microsoft Entra IDを優先します。
診断とスキーマの検出
| Command | Purpose |
|---|---|
doctor |
シェルの状態を変更せずに、バインドされた読み取り専用環境と接続診断を実行します。 |
doctor who |
既知の資格情報とスコープ情報を診断レポートに追加します。 |
whoami |
資格情報の種類と使用可能なMicrosoft Entra ID 情報を調べます。 |
can-i <action> |
データを変更せずに、 read、 query、 write、または manage アクセスをプローブします。 |
schema |
パーティション キーとインデックス作成メタデータを使用して、境界付きサンプルからフィールド名と型を推論します。 |
doctor --no-update-check --format=json
doctor --database=ShellDemo --container=Items --query
whoami --format=json
can-i query --database=ShellDemo --container=Items
schema --database=ShellDemo --container=Items --sample=20
schema --database=ShellDemo --container=Items --fields-only
doctor は切断中に動作します。 既定では、その更新チェックは、境界付きパブリック GitHub リリース参照を実行します。--no-update-checkは、他の要求されたネットワーク チェックではなく、その参照を無効にします。
--query は小さなクエリ プローブを実行し、RU を使用します。
--armは、Azure Resource Manager チェックを明示的に要求します。 結果は、合格、警告、失敗、スキップされたチェックを区別します。スキップされたチェックは成功の証拠ではありません。
can-i は、ロールの割り当ての一覧ではなく、 allow、 deny、または indeterminateをレポートします。 書き込みプローブは、すべての書き込みアクセス許可の証明ではなく、削除アクセスに基づくヒューリスティックです。 このデータ プレーン プローブでは管理アクセスを確立できないため、 indeterminateが返されます。
schema --sample は 1 から 100 個のドキュメントを受け取り、既定値は 20 です。
--fields-only (エイリアス --short)は、読み取られたコンテナー メタデータを省略します。 推論されたフィールドは、完全なスキーマや適用されたスキーマではなく、サンプルを記述します。
クエリコマンドとポイント読み取りコマンド
query
コンテナーに対してAzure Cosmos DB クエリを実行します。
query "SELECT TOP 10 c.id FROM c" --database=ShellDemo --container=Items --max=10
query "SELECT VALUE COUNT(1) FROM c" --database=ShellDemo --container=Items --max=1
| Option | Purpose |
|---|---|
--max、-m |
返された項目をバインドしました。 対話型クエリには、既定の項目制限はありません。 |
--format、-f |
結果のプレゼンテーション json、 table、または csv を選択します。 |
--metrics、-mx |
表示またはファイルのクエリ メトリックを要求します。 |
--explain |
ドキュメントを返す代わりに、最初のページの実行とインデックスのメトリックを検査します。 |
--bucket |
このクエリのスループット バケットを選択します。 |
--database、--container |
クエリ ターゲットを明示的に設定します。 |
query "SELECT c.id FROM c WHERE c.tenantId = 'demo'" --database=ShellDemo --container=Items --explain
この例の tenantId プロパティは、「 はじめに」のサンプル モデルに属しています。 プロパティを使用する前に、 schema を使用して独自のコンテナーを検査します。
--explain は、最初のページ のプローブを実行し、RU を使用し、完全なクエリを測定しません。 インデックス メトリックが見つからないと、スキャンの証明ではなく、不明な評価が生成されます。
--max は explain プローブを制御しません。
MCP を使用して、クエリは continuationTokenを持つ境界付きページを返します。 同じクエリとオプションを使用して、ツールの continuation 引数として変更せずに null 以外のトークンを渡します。
continuation は対話型シェル オプションではありません。
resultIncomplete: trueを持つ null トークンは、再開できない切り捨てを意味し、クエリを絞り込むか、要求されたバインドを増やします。
print
正確な ID と完全なパーティション キーで項目をポイント読み取ります。
print sample-1 demo --database=ShellDemo --container=Items
パーティション キー値は JSON 型を保持します。
| Value | Meaning |
|---|---|
680 |
数値キー。 |
'"680"' |
680数字を含む文字列キー。 |
true または null |
ブール型または null 型のキー。 |
'{}' |
null とは異なる未定義のパーティション キー値。 |
'["tenant-1",680]' |
構成されたパス順の完全な階層キー。 |
print は、アイテムが見つからない場合はクエリにフォールバックしません。 以前のバージョンでは、数値に見えるキーを文字列として扱いました。必要に応じ、明示的な JSON 文字列の引用符を使用します。
アイテムの作成と変更
| Command | Purpose |
|---|---|
mkitem <json> |
項目または項目の配列を作成します。また、パイプされた JSON も受け入れます。 |
create item <json> |
汎用作成コマンドを使用して項目を作成します。 |
replace <json> |
既存のドキュメントを指定されたドキュメントに置き換えます。 |
patch <operation> <id> <pk> <path> [value] |
完全なドキュメントを置き換えずにフィールドを変更します。 |
rm <pattern> |
一致するアイテムを削除するか、 --dry-runで一致をプレビューします。 |
書き込みには、目的のアカウントとコンテナーに対するアクセス許可が必要であり、RU を使用します。
mkitem --force (エイリアス --upsert)は既存の項目を置き換えることができます。 置換には、変更するフィールドだけでなく、完全な目的のドキュメントが含まれている必要があります。
patch
サポートされている操作は、 set、 add、 replace、 remove、および incr (エイリアス increment) です。 値は JSON 型指定を使用します。
patch set sample-1 demo /status reviewed --database=ShellDemo --container=Items
set フィールドを作成できます。 replace は存在する必要があります。
remove は値を受け取っていません。
incr には数値が必要です。 アイテムから読み取られた実際の ETag で --etag を使用して、条件付き更新を保護します。
正確なアイテムを安全に削除する
Warning
項目、コンテナー、またはデータベースを削除すると、データが削除されます。 重要なデータをバックアップし、アカウントとターゲットを確認し、削除を適用する前にドライ ランを確認します。
rm パターンは、項目 ID ではなく、既定でパーティション キーと一致します。 1 つの項目をターゲットにするには、正確な ID、 --key=id、および完全なパーティション キーを使用します。
rm sample-1 --key=id --partition-key=demo --database=ShellDemo --container=Items --dry-run
1 の数を要求し、返された ID、パーティション キー、および ETag を確認します。 レビューされたバージョンのみを削除するには、 --dry-run せずに同じターゲットを繰り返し、実際に返された ETag で --etag を追加し、埋め込まれた二重引用符を保持します。 不一致で停止します。条件なしで再試行しないでください。 削除後、同じ ID とパーティション キーのポイント読み取りを使用して、項目が見つからないことを確認します。 再試行する前に、不確実な結果を調べます。
ワイルドカードまたはスコープ外の一致では、多くの項目をスキャンし、大量の RU を使用できます。
--partition-keyを指定すると、プレビューと削除の両方がその論理パーティションに制限されます。
rmcon、 rmdb、および delete も --dry-runをサポートします。
トランザクションと一括操作
| Capability | batch |
bulk |
|---|---|---|
| 原子性 | すべての操作が成功するか、一緒にロールバックされます。 | 各操作は個別に成功または失敗します。ロールバックなし。 |
| パーティション スコープ | 1 つの完全なパーティション キー。 | 操作では、さまざまなパーティション キーを使用できます。 |
| ワークロード のサイズ | サービスの制限に従って、1 回の実行につき 1 ~ 100 の操作。 | ストリーミングされた入力ファイル。ステートフル ジョブは、10,000 操作と 64 MiB の正規 JSON に制限されます。 |
| 実行 | 1 つのトランザクション。 | 有界同時書き込み。既定のコンカレンシーは 16 です。 |
どちらのコマンドも、create、upsert、replace、delete、またはpatchop値を持つ操作を受け入れます。
bulkさらに、replace、delete、およびpatchの操作ごとのpartitionKeyと条件付きifMatchを受け入れます。
create
ifMatchを受け入れないupsert。
batch
1 回の呼び出しでトランザクションを実行します。
batch run '[{"op":"create","item":{"id":"batch-1","tenantId":"demo","status":"new"}},{"op":"patch","id":"batch-1","operations":[{"op":"set","path":"/status","value":"ready"}]}]' --partition-key=demo --database=ShellDemo --container=Items
対話型の構築には、 begin、 add、 status、 show、 execute、および cancelを使用します。 アクティブなバッチは、そのターゲット キーとパーティション キーを保持します。 MCP を使用すると、ワンショット batch run のみがサポートされます。
bulk
独立した操作には bulk run <json-or-file> を使用します。 JSON 配列、JSON Lines ファイル、またはパイプ操作を受け入れます。 書き込みを許可する前にプランをプレビューします。
bulk run operations.jsonl --database=ShellDemo --container=Items --dry-run
operations.jsonl には、次に例を示す 1 行に 1 つの操作を含めることができます。
{"op":"create","item":{"id":"bulk-1","tenantId":"demo","status":"new"}}
{"op":"create","item":{"id":"bulk-2","tenantId":"other","status":"new"}}
確認後、 --yesで同じファイルを適用します。 再開可能な実行の --journal=<file> を追加します。 ジャーナルは、成功した書き込みをスキップし、失敗した書き込みを再試行し、不確実な結果を伴う操作を保留します。
--retry-uncertainを使用する前に不確かな結果を調べます。べき等でない操作を再生すると、効果が重複する可能性があります。
| Option | Purpose |
|---|---|
--concurrency |
バインドされたインフライト書き込み。 コンカレンシーが高いほど、プロビジョニングされたスループットは増加しません。 |
--continue-on-error |
個々の操作の失敗後に書き込みのスケジュールを続行します。 |
--max-items |
bulk patchまたはbulk deleteのクエリで選択されたバインドされた項目。 |
--max-ru |
正確な請求上限ではなく、観察された RU 予算を設定します。引き続き、実行中の作業が完了する可能性があります。 |
--dry-run |
データベースの書き込みを行わずに入力を検証するか、項目を選択します。 選択では RU を使用できます。 |
--etag |
クエリで選択された修正プログラムまたは削除操作の条件付き ETag をキャプチャします。 |
--save |
クエリで選択したプランを新しいファイルに書き込み、個別のレビューと実行を行います。 |
bulk patch --where <predicate> --operations <json>エイリアスcよりもAzure Cosmos DBクエリ述語を持つ項目を選択bulk delete --where <predicate>。 SQL 更新または削除ステートメントではありません。
--saveでは、実行時に新しい選択を必要とするのではなく、選択によってレビュー可能なスナップショットが生成されます。
対話型ステートフル ジョブでは、 begin、 add、 status、 show、 execute、および cancelが使用されます。 MCP では、 run、 patch、および deleteのみがサポートされます。 部分的なエラーでは、正常な書き込みを元に戻すことはできません。再試行する前に概要を調べます。
インポートとエクスポート
export items.json --database=ShellDemo --container=Items --max=100
export items.csv --database=ShellDemo --container=Items --max=100
import items.json --database=ShellDemo --container=Items --dry-run
export は、宛先名が .csv で終わると、JSON 配列または CSV を書き込みます。 クエリ結果エンベロープまたは JSON 行は書き込まれません。
--query はサブセットを選択し、出力をバインド --max し、 --force はエクスポートが成功した後にのみ既存の宛先を置き換えることを許可します。
import は、JSON 配列、単一オブジェクト、および JSON Lines を含むオブジェクト シーケンスを検出します。
.csv拡張機能は CSV を選択します。値は文字列としてインポートされます。 CSV では、既定でセミコロン区切り記号が使用されます。別の区切り記号が必要な場合は、 COSMOSDB_SHELL_CSVSEP 環境変数を設定します。
--format どちらのコマンドでも、 ファイル形式ではなくサマリー プレゼンテーションが変更されます。
import --dry-run は、ターゲット要求や書き込みなしで、入力構文と項目 ID をオフラインで検証します。 ターゲット パーティション キー、アクセス許可、ID の競合、またはすべてのサービス制約は検証されません。 ドライ ランが成功すると、検証されたレコードと imported: 0が報告されます。
検証済みファイルを適用するには、 --dry-runを削除します。 既定のモードでは、項目が挿入されます。 --mode=upsert は上書きできます。 既定で 16 件の同時書き込みをインポートします。 ファイルの順序が重要な場合は、 --concurrency=1 を使用します。
--continue-on-error は、不正な形式の入力ではなく、個々の書き込みエラーの後に続行されます。 以前の書き込みが成功してもロールバックされず、インフライト書き込みが失敗した後に完了する可能性があります。
対話型インポート、一括、およびパターンベースの削除では、定期的な進行状況が表示されます。 構造化された出力と MCP 応答は、結果の図形をターミナルの進行状況テキストなしで保持します。
データベースとコンテナーの管理
| Command | Purpose |
|---|---|
mkdb <name> |
アカウント ルート スコープでデータベースを作成する。スループット設定に--ruで--scale=manualまたは--scale=autoを使用します。 |
mkcon <name> <partition-key-path> [unique-key-paths] |
コンテナーを作成する。階層パスは、コンマ区切りの位置指定パスです。 |
create database / create container |
汎用作成フォーム。 |
rmdb <name> / rmcon <name> |
データベースまたはコンテナーを削除します。 |
delete database / delete container / delete item |
一般的な削除フォーム。 |
cd
info --format=json
ls
mkdb ShellDemo --scale=auto --ru=1000
cd /ShellDemo
mkcon Items /tenantId --scale=manual --ru=400
mkdbを実行する前に、アカウントを確認し、未使用のデータベース名を選択します。 各作成コマンドを個別に実行し、その結果を確認してから続行します。
mkdbアカウント ルート スコープが必要です。mkconcd /ShellDemoによって選択されたデータベース スコープから実行されます。
これらの設定によってスループットが割り当てられるので、料金が発生する可能性があります。 サーバーレス アカウントでは、 --scale と --ruを省略します。スループット設定はサポートされていません。
バージョン 1.1.295 のプロビジョニング済みアカウントでは、スループット オプションを省略すると、データベースの共有自動スケーリング スループットまたはコンテナーの専用自動スケール スループットが作成され、既定の最大 RU/秒が 1,000 RU/秒になります。 バージョンに依存する既定値に依存するのではなく、目的の設定を指定します。
管理操作は、サポートされているMicrosoft Entra資格情報と使用可能な ARM コンテキストに接続されている場合、Azure Resource Managerを優先します。 キー、エミュレーター、および静的トークン接続では、データ プレーンが使用されます。 ARM の作成結果は、 created: null と outcome: "createdOrUpdated"報告します。リソースが新しく作成されたことは証明されません。
コンテナー ポリシーとスループット
| Command | サブコマンドと目的 |
|---|---|
index(別名 indexpolicy) |
show、 add、 remove、またはインデックス作成のパスとポリシーを set します。 |
throughput |
show、 set / manual、またはプロビジョニングされた RU/秒 autoscale 。 |
ttl |
show、 set <seconds>、既定の有効期限のない on 、または off。 |
conflict |
show または、last-writer-wins またはカスタム競合解決を set します。 |
bucket |
クライアント スループット バケット、 show、 set、および clear コンテナー バケットの制限を選択します。 |
変更する前に構成を読み取ります。
index show --database=ShellDemo --container=Items
throughput show --database=ShellDemo --container=Items
throughput autoscale 1000 --database=ShellDemo --container=Items --dry-run
ttl show --database=ShellDemo --container=Items
conflict show --database=ShellDemo --container=Items
インデックスの変更は、クエリの動作とインデックス作成のコストに影響します。 TTL の変更は、既存の項目の有効期限が切れる可能性があります。 競合解決ポリシーは、複数リージョンの書き込みアカウントに適用されます。
スループットの変更は料金に影響する可能性があります。 データベース共有スループットを使用するサーバーレス アカウントとコンテナーには、変更する専用のコンテナー スループットはありません。 手動/自動スケール モードを切り替える場合は、サポートされているトークンベースの管理が必要です。キーベースの接続では、その移行を実行できません。
bucket <0-5> このクライアントの選択を変更します。 0 はクリアします。 コンテナー バケットの制限には、Entra 管理接続とプロビジョニング済みスループットが必要です。 キー接続またはエミュレーター接続では使用できません。
サーバー側プログラミングと変更フィード
| Command | Purpose |
|---|---|
sproc |
list、 show、 exists、 create、 exec、 edit、または delete ストアド プロシージャ。 |
udf |
list、 show、 exists、 create、 edit、またはユーザー定義関数の delete 。 |
trigger |
list、 show、 exists、 create、 edit、または delete トリガー。 |
watch(別名 tail) |
コンテナーの変更フィードから新しい項目と変更された項目を読み取ります。 |
sproc exec には、完全な --partition-keyが必要です。 作成コマンドは JavaScript ファイルを受け入れます。対話型の作成/編集ワークフローでは、外部エディターを開くことができます。 これらのプログラミング コマンドは、MCP を介して公開されません。
watch --database=ShellDemo --container=Items --max=10
watch は RU を消費し、変更を待つことができます。
Ctrl + C キーを押して停止します。 MCP 経由では使用できません。
パイプライン、スクリプト、および外観
| コマンドまたは機能 | Purpose |
|---|---|
filter <expression> |
パイプされた JSON を組み込みの jq に着想を得たサブセットで変換します。 |
ftab |
パイプされた JSON を書式設定されたテーブルとしてレンダリングします。 |
jq |
インストールされている外部 jq 実行可能ファイルを呼び出します。 |
cat、dir、edit |
ファイルの読み取り、ローカル ファイルの一覧表示、または外部エディターでローカル ファイルを開きます。 |
echo |
パイプラインにテキストまたは JSON を書き込みます。 |
exec |
シェル スクリプトを実行します。 |
theme |
list、 show、 use、 load、 validate、 save、または edit ターミナル テーマ。 |
az |
インストールされているAzure CLI実行可能ファイルを呼び出します。 |
help、 version、 welcome、 cls / clear、 exit |
コマンドを検出し、シェル セッションを制御します。 |
schema --database=ShellDemo --container=Items --fields-only | filter '.fields' | ftab
theme list
theme use dark
filter は完全な jq 実装ではありません。 構造化されたパイプライン データに対して動作します。フィールド パスを選択する前に、コマンドの結果の図形を調べます。
スクリプトでは、変数、条件、ループ、関数がサポートされます。 構文は、Bash や PowerShell ではなく、Azure Cosmos DB シェルに属しています。 閉じていないコンストラクトまたは明示的な末尾の円記号に対して、複数行の入力が続行されます。
CLI のスタートアップ オプション
オペレーティング システムターミナルから次のコマンドを実行します。
cosmosdbshell --version
cosmosdbshell --mcp
cosmosdbshell --mcp 6129
cosmosdbshell --connect https://<account-name>.documents.azure.com/ --connect-tenant=<tenant-id>
接続オプションでは、--connect-managed-identity、--connect-subscription、--connect-resource-groupなど、起動時に--connect- プレフィックスが使用されます。
--otelを使用して OpenTelemetry トレースを有効にします。アップストリーム シェル ガイドに従ってエクスポートを構成します。
AI ツール
これらのアクションを使用して、アシスタントでシェル コマンドを検索します。
ドキュメントのみの取得には、Microsoft Learn MCP サーバーを使用します。 コンパクト ガイド インデックスの場合は、 Shell ドキュメント インデックス (llms.txt) を使用します。 インデックスによってクローラーのアクセス許可が変更されたり、取得が保証されたりすることはありません。
シェル MCP には個別のセットアップが必要であり、構成されたアクセス許可でデータを読み取ったり変更したりできるため、承認する前にツールの呼び出しを確認してください。 資格情報や機密データを共有しないでください。
AI エージェントを接続する
認証されたデータベース操作用にシェル MCP を構成します。Markdown として読み取る
テキスト バージョンを開いてアシスタントにコピーします。ChatGPT に質問する
コマンド構文を検索し、データ変更操作を識別します。クロードに質問する
コマンド構文を検索し、データ変更操作を識別します。
ChatGPT と Claude は、パブリック記事の URL とスターター プロンプトのみを受け取ります。 ここで、サインインを求められる場合があります。 取得に失敗した場合は、Markdown テキストをコピーします。 これらのリンクでは、データベース アクセスは構成されません。