
关于
Azure Cosmos DB JavaScript/TypeScript SDK(@azure/cosmos),用于数据平面操作。支持文档 CRUD、查询、批量操作和容器管理
name: azure-cosmos-ts description: Azure Cosmos DB JavaScript/TypeScript SDK (@azure/cosmos) 用于数据平面操作。用于文档的 CRUD 操作、查询、批量操作和容器管理。 risk: unknown source: community date_added: '2026-02-27'
@azure/cosmos (TypeScript/JavaScript)
Azure Cosmos DB NoSQL API 操作的数据平面 SDK — 文档的 CRUD 操作、查询、批量操作。
⚠️ 数据平面 vs 管理平面
- 此 SDK (@azure/cosmos):文档的 CRUD 操作、查询、存储过程
- 管理 SDK (@azure/arm-cosmosdb):通过 ARM 创建账户、数据库、容器
安装
npm install @azure/cosmos @azure/identity
当前版本:4.9.0 Node.js:>= 20.0.0
环境变量
COSMOS_ENDPOINT=https://<account>.documents.azure.com:443/
COSMOS_DATABASE=<database-name>
COSMOS_CONTAINER=<container-name>
# For key-based auth only (prefer AAD)
COSMOS_KEY=<account-key>
身份验证
使用 DefaultAzureCredential 的 AAD 认证(推荐)
import { CosmosClient } from "@azure/cosmos";
import { DefaultAzureCredential } from "@azure/identity";
const client = new CosmosClient({
endpoint: process.env.COSMOS_ENDPOINT!,
aadCredentials: new DefaultAzureCredential(),
});
基于密钥的身份验证
import { CosmosClient } from "@azure/cosmos";
// Option 1: Endpoint + Key
const client = new CosmosClient({
endpoint: process.env.COSMOS_ENDPOINT!,
key: process.env.COSMOS_KEY!,
});
// Option 2: Connection String
const client = new CosmosClient(process.env.COSMOS_CONNECTION_STRING!);
资源层次结构
CosmosClient
└── Database
└── Container
├── Items (documents)
├── Scripts (stored procedures, triggers, UDFs)
└── Conflicts
核心操作
数据库和容器设置
const { database } = await client.databases.createIfNotExists({
id: "my-database",
});
const { container } = await database.containers.createIfNotExists({
id: "my-container",
partitionKey: { paths: ["/partitionKey"] },
});
创建文档
interface Product {
id: string;
partitionKey: string;
name: string;
price: number;
}
const item: Product = {
id: "product-1",
partitionKey: "electronics",
name: "Laptop",
price: 999.99,
};
const { resource } = await container.items.create<Product>(item);
读取文档
const { resource } = await container
.item("product-1", "electronics") // id, partitionKey
.read<Product>();
if (resource) {
console.log(resource.name);
}
更新文档(替换)
const { resource: existing } = await container
.item("product-1", "electronics")
.read<Product>();
if (existing) {
existing.price = 899.99;
const { resource: updated } = await container
.item("product-1", "electronics")
.replace<Product>(existing);
}
Upsert 文档
const item: Product = {
id: "product-1",
partitionKey: "electronics",
name: "Laptop Pro",
price: 1299.99,
};
const { resource } = await container.items.upsert<Product>(item);
删除文档
await container.item("product-1", "electronics").delete();
补丁文档(部分更新)
import { PatchOperation } from "@azure/cosmos";
const operations: PatchOperation[] = [
{ op: "replace", path: "/price", value: 799.99 },
{ op: "add", path: "/discount", value: true },
{ op: "remove", path: "/oldField" },
];
const { resource } = await container
.item("product-1", "electronics")
.patch<Product>(operations);
查询
简单查询
const { resources } = await container.items
.query<Product>("SELECT * FROM c WHERE c.price < 1000")
.fetchAll();
参数化查询(推荐)
import { SqlQuerySpec } from "@azure/cosmos";
const querySpec: SqlQuerySpec = {
query: "SELECT * FROM c WHERE c.partitionKey = @category AND c.price < @maxPrice",
parameters: [
{ name: "@category", value: "electronics" },
{ name: "@maxPrice", value: 1000 },
],
};
const { resources } = await container.items
.query<Product>(querySpec)
.fetchAll();
分页查询
const queryIterator = container.items.query<Product>(querySpec, {
maxItemCount: 10, // Items per page
});
while (queryIterator.hasMoreResults()) {
const { resources, continuationToken } = await queryIterator.fetchNext();
console.log(\`Page with \${resources?.length} items\`);
// Use continuationToken for next page if needed
}
跨分区查询
const { resources } = await container.items
.query<Product>(
"SELECT * FROM c WHERE c.price > 500",
{ enableCrossPartitionQuery: true }
)
.fetchAll();
批量操作
执行批量操作
import { BulkOperationType, OperationInput } from "@azure/cosmos";
兼容工具
Claude CodeCursor
标签
后端开发
