Azure Cosmos DB Shell 快速入门

只需几分钟即可通过这些实践示例开始使用 Azure Cosmos DB Shell。

先决条件

• 已安装 Azure Cosmos DB Shell （Installation Guide）
• Azure Cosmos DB 帐户
• 配置了身份验证（Microsoft Entra ID、托管标识或帐户密钥）

启动 shell

cosmosdbshell

你将看到提示：

CS >

连接您的账户

在没有连接参数的情况下启动时，Azure Cosmos DB Shell 以断开连接状态启动。 connect使用命令进行身份验证并连接到帐户。

使用 Microsoft Entra ID（建议）：

CS > connect https://<account-name>.documents.azure.cn:443/ --auth-method entra-id

这会启动浏览器登录流。

使用托管标识 （生产）：

CS > connect https://<account-name>.documents.azure.cn:443/ --auth-method managed-identity

使用帐户密钥 （开发/测试）：

CS > connect DefaultEndpointProtocol=https;AccountName=<account-name>;AccountKey=<account-key>; --auth-method key

基本导航

查看帐户终结点

CS > endpoint

列出数据库

CS > ls

输出：

database1
database2
mydb

导航至某个数据库

CS > cd mydb
CS >

列出数据库中的容器

CS > ls

输出：

users
products
orders

导航到容器

CS > cd users
CS >

显示当前路径

CS > pwd

输出：

/mydb/users

基本操作

创建数据库

CS > mkdb mynewdb

创建容器

CS > mkcon mycontainer -pk /id

（使用分区键 /id创建容器）

查询文档

CS > query "SELECT * FROM c WHERE c.status = 'active'"

输出：

{
  "id": "user1",
  "name": "Alice",
  "status": "active"
}
{
  "id": "user2", 
  "name": "Bob",
  "status": "active"
}

对文档进行计数

CS > query "SELECT COUNT(*) FROM c"

插入文档

CS > create item {"id": "user3", "name": "Charlie", "status": "active"}

更新文档

CS > update {"id": "user1", "name": "Alice", "status": "inactive"}

删除文档

CS > rm user1

删除容器

CS > rmcon users

删除数据库

CS > rmdb mydb

管道命令

合并命令以创建功能强大的工作流。

查询与计数

CS > query "SELECT * FROM c" | jq 'length'

使用 jq 筛选结果

CS > query "SELECT * FROM c" | jq '.[] | select(.status == "active")'

提取特定字段

CS > query "SELECT * FROM c" | jq '.[] | {id, name}'

转换和输出

CS > query "SELECT * FROM c" | jq '.[] | .name' | tr '\n' ','

Shell 脚本

为自动化操作创建脚本文件。

示例脚本： batch_operations.sh

#!/bin/bash

# Connect to Cosmos DB Shell
cosmosdbshell << 'EOF'
cd mydb
cd users

# Insert multiple documents
create item {"id": "user10", "name": "David", "status": "active"}
create item {"id": "user11", "name": "Eve", "status": "inactive"}
create item {"id": "user12", "name": "Frank", "status": "active"}

# Query and count
query "SELECT COUNT(*) as count FROM c"

# Exit
exit
EOF

运行脚本

bash batch_operations.sh

筛选和搜索

查找具有特定条件的文档

CS > query "SELECT * FROM c WHERE c.age > 30 AND c.status = 'active'"

在数组中搜索

CS > query "SELECT * FROM c WHERE ARRAY_CONTAINS(c.tags, 'vip')"

聚合结果

CS > query "SELECT c.status, COUNT(*) as count FROM c GROUP BY c.status"

导出再导入

将数据导出到 JSON

CS > query "SELECT * FROM c" > users_export.json

导出的文件将文档包装在信封中 items ：

{
  "items": [
    { "id": "user1", "pk": "tenantA", "name": "Alice", "status": "active",
      "_rid": "...", "_self": "...", "_etag": "...", "_attachments": "...", "_ts": 1730000000 },
    { "id": "user2", "pk": "tenantA", "name": "Bob", "status": "active",
      "_rid": "...", "_self": "...", "_etag": "...", "_attachments": "...", "_ts": 1730000001 }
  ]
}

导出到类似于 CSV 的格式

CS > query "SELECT * FROM c" | jq -r '.id, .name, .status' | paste -sd, > users.csv

导入裸 JSON 数组

命令 create item （别名 mkitem）接受单个 JSON 对象或顶级 JSON 数组。 在控制输入文件时使用此表单，并可以生成干净的文档数组。

示例 users_import.json：

[
  { "id": "user10", "pk": "tenantA", "name": "David", "status": "active" },
  { "id": "user11", "pk": "tenantA", "name": "Eve",   "status": "inactive" },
  { "id": "user12", "pk": "tenantB", "name": "Frank", "status": "active" }
]

通过将文件经管道传入 mkitem 来导入它：

CS > cat users_import.json | mkitem

添加 --force（别名 --upsert），以替换现有项，而不是在出现 id 冲突时失败：

CS > cat users_import.json | mkitem --force

导入以前导出的查询结果

由 query "SELECT * FROM c" > users_export.json 生成的文件不是裸数组——它带有上文所示的 { "items": [ ... ] } 包装器，而且文档仍然包含 Cosmos 系统字段（_rid、_self、_etag、_attachments、_ts），这些字段在插入时不得回传。

使用 jq 解包数组并去除系统字段，然后再通过管道传递给 mkitem：

CS > cat users_export.json \
  | jq '[.items[] | del(._rid, ._self, ._etag, ._attachments, ._ts)]' \
  | mkitem --force --db=mydb --con=users

每个步骤的作用：

• .items[] 解包信封并流式传输每个文档。
• del(...) 移除 Cosmos 系统中的只读字段。
• [ ... ] 将结果重新收集到 mkitem 所期望的顶层数组中。
• --force 使导入操作具有幂等性（重新运行时会替换现有项）。
• --db / --con 以显式目标为目标，以便无论当前 shell 位置如何，导入都有效。

mkitem 依次遍历数组，并打印摘要，其中包含已创建或替换的项数以及总 RU 费用。 各项失败（例如，没有 id 的 --force 冲突）会以内联方式报告，但不会中断导入。

技巧与最佳做法

对常用命令使用别名

# Add to your shell profile
alias cosmosdb='cosmosdbshell'

Tab 键补全

• 使用 Tab 键自动补全数据库和容器名称
• 按 Tab 两次以查看所有可用选项

命令历史记录

• 按向上/向下箭头键浏览命令历史记录
• 按 Ctrl+R 搜索命令历史记录

设置输出格式

# Pretty-print JSON
CS > query "SELECT * FROM c" | jq .

# Compact output
CS > query "SELECT * FROM c" | jq -c .

性能提示

• 在查询中使用分区键 以更快地获得结果：

  CS > query "SELECT * FROM c WHERE c.id = 'user1'"
  

• 限制结果集以用于大型查询：

  CS > query "SELECT TOP 100 * FROM c"
  

• 使用投影 减少数据传输：

  CS > query "SELECT c.id, c.name FROM c"
  

常见工作流

从文件批量插入

CS > jq -r '.[]' data.json | while read line; do
  create $line
done

备份容器

CS > query "SELECT * FROM c" > backup_users.json

验证数据迁移

CS > query "SELECT COUNT(*) FROM c" 
CS > query "SELECT COUNT(*) FROM c"

后续步骤

• 完整命令参考 - 了解所有可用的命令
• MCP 服务器设置 - 启用 AI 集成
• 故障排除指南 - 解决问题
• 安全最佳做法 - 保护设置

另请参阅

• Azure Cosmos DB Shell 概述
• 安装指南
• Azure Cosmos DB查询参考