[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M69AVRA5MPEFJZ5ZJE5PBBYC":3,"skill-same:01M69AVRA5MPEFJZ5ZJE5PBBYC":84},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":41,"linkOnly":42,"markdownContent":43,"markdownBody":44,"frontMatter":45,"refName":50,"commitSha":51,"skillDirectory":52,"forksCount":53,"repositoryHtmlUrl":54,"repositoryHomepageUrl":55,"ownerHtmlUrl":56,"ownerBlogUrl":57,"ownerDescription":58,"updatedAt":59,"install":60,"resources":73},"01M69AVRA5MPEFJZ5ZJE5PBBYC","azure-cosmos-ts",null,"Azure Cosmos DB JavaScript\u002FTypeScript SDK (@azure\u002Fcosmos) for data plane operations. Use for CRUD operations on documents, queries, bulk operations, and container management. Triggers: \"Cosmos DB\", \"@azure\u002Fcosmos\", \"CosmosClient\", \"document CRUD\", \"NoSQL queries\", \"bulk operations\", \"partition key\", \"container.items\".","microsoft\u002Fskills","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M69AJYYW4E1RMSYCQDJ4FJSH",3204,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fplugins\u002Fazure-sdk-typescript\u002Fskills\u002Fazure-cosmos-ts\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,9,39,40],"azure","azure cosmos ts","cosmos","partition","for","plane","container management","bulk","triggers","db","bulk operations","document","container","use","typescript","crud","nosql","data","azure cosmos db","documents","javascript","sdk","2026-11-10 10:12:30",false,"---\nname: azure-cosmos-ts\ndescription: |\n  Azure Cosmos DB JavaScript\u002FTypeScript SDK (@azure\u002Fcosmos) for data plane operations. Use for CRUD operations on documents, queries, bulk operations, and container management. Triggers: \"Cosmos DB\", \"@azure\u002Fcosmos\", \"CosmosClient\", \"document CRUD\", \"NoSQL queries\", \"bulk operations\", \"partition key\", \"container.items\".\nlicense: MIT\nmetadata:\n  author: Microsoft\n  version: \"1.0.0\"\n  package: '@azure\u002Fcosmos'\n---\n\n# @azure\u002Fcosmos (TypeScript\u002FJavaScript)\n\nData plane SDK for Azure Cosmos DB NoSQL API operations — CRUD on documents, queries, bulk operations.\n\n> **⚠️ Data vs Management Plane**\n> - **This SDK (@azure\u002Fcosmos)**: CRUD operations on documents, queries, stored procedures\n> - **Management SDK (@azure\u002Farm-cosmosdb)**: Create accounts, databases, containers via ARM\n\n## Installation\n\n```bash\nnpm install @azure\u002Fcosmos @azure\u002Fidentity\n```\n\n**Current Version**: 4.9.0  \n**Node.js**: >= 20.0.0\n\n## Environment Variables\n\n```bash\nCOSMOS_ENDPOINT=https:\u002F\u002F\u003Caccount>.documents.azure.com:443\u002F\nCOSMOS_DATABASE=\u003Cdatabase-name>\nCOSMOS_CONTAINER=\u003Ccontainer-name>\n# For key-based auth only (prefer AAD)\nCOSMOS_KEY=\u003Caccount-key>\nAZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production\n```\n\n## Authentication\n\n### Microsoft Entra Token Credential (Recommended)\n\n```typescript\nimport { CosmosClient } from \"@azure\u002Fcosmos\";\nimport { DefaultAzureCredential, ManagedIdentityCredential } from \"@azure\u002Fidentity\";\n\n\u002F\u002F Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=\u003Cspecific_credential>\nconst credential = new DefaultAzureCredential({requiredEnvVars: [\"AZURE_TOKEN_CREDENTIALS\"]});\n\u002F\u002F Or use a specific credential directly in production:\n\u002F\u002F See https:\u002F\u002Flearn.microsoft.com\u002Fjavascript\u002Fapi\u002Foverview\u002Fazure\u002Fidentity-readme?view=azure-node-latest#credential-classes\n\u002F\u002F const credential = new ManagedIdentityCredential();\n\nconst client = new CosmosClient({\n  endpoint: process.env.COSMOS_ENDPOINT!,\n  aadCredentials: credential,\n});\n```\n\n### Key-Based Authentication\n\n```typescript\nimport { CosmosClient } from \"@azure\u002Fcosmos\";\n\n\u002F\u002F Option 1: Endpoint + Key\nconst client = new CosmosClient({\n  endpoint: process.env.COSMOS_ENDPOINT!,\n  key: process.env.COSMOS_KEY!,\n});\n\n\u002F\u002F Option 2: Connection String\nconst client = new CosmosClient(process.env.COSMOS_CONNECTION_STRING!);\n```\n\n## Resource Hierarchy\n\n```\nCosmosClient\n└── Database\n    └── Container\n        ├── Items (documents)\n        ├── Scripts (stored procedures, triggers, UDFs)\n        └── Conflicts\n```\n\n## Core Operations\n\n### Database & Container Setup\n\n```typescript\nconst { database } = await client.databases.createIfNotExists({\n  id: \"my-database\",\n});\n\nconst { container } = await database.containers.createIfNotExists({\n  id: \"my-container\",\n  partitionKey: { paths: [\"\u002FpartitionKey\"] },\n});\n```\n\n### Create Document\n\n```typescript\ninterface Product {\n  id: string;\n  partitionKey: string;\n  name: string;\n  price: number;\n}\n\nconst item: Product = {\n  id: \"product-1\",\n  partitionKey: \"electronics\",\n  name: \"Laptop\",\n  price: 999.99,\n};\n\nconst { resource } = await container.items.create\u003CProduct>(item);\n```\n\n### Read Document\n\n```typescript\nconst { resource } = await container\n  .item(\"product-1\", \"electronics\") \u002F\u002F id, partitionKey\n  .read\u003CProduct>();\n\nif (resource) {\n  console.log(resource.name);\n}\n```\n\n### Update Document (Replace)\n\n```typescript\nconst { resource: existing } = await container\n  .item(\"product-1\", \"electronics\")\n  .read\u003CProduct>();\n\nif (existing) {\n  existing.price = 899.99;\n  const { resource: updated } = await container\n    .item(\"product-1\", \"electronics\")\n    .replace\u003CProduct>(existing);\n}\n```\n\n### Upsert Document\n\n```typescript\nconst item: Product = {\n  id: \"product-1\",\n  partitionKey: \"electronics\",\n  name: \"Laptop Pro\",\n  price: 1299.99,\n};\n\nconst { resource } = await container.items.upsert\u003CProduct>(item);\n```\n\n### Delete Document\n\n```typescript\nawait container.item(\"product-1\", \"electronics\").delete();\n```\n\n### Patch Document (Partial Update)\n\n```typescript\nimport { PatchOperation } from \"@azure\u002Fcosmos\";\n\nconst operations: PatchOperation[] = [\n  { op: \"replace\", path: \"\u002Fprice\", value: 799.99 },\n  { op: \"add\", path: \"\u002Fdiscount\", value: true },\n  { op: \"remove\", path: \"\u002FoldField\" },\n];\n\nconst { resource } = await container\n  .item(\"product-1\", \"electronics\")\n  .patch\u003CProduct>(operations);\n```\n\n## Queries\n\n### Simple Query\n\n```typescript\nconst { resources } = await container.items\n  .query\u003CProduct>(\"SELECT * FROM c WHERE c.price \u003C 1000\")\n  .fetchAll();\n```\n\n### Parameterized Query (Recommended)\n\n```typescript\nimport { SqlQuerySpec } from \"@azure\u002Fcosmos\";\n\nconst querySpec: SqlQuerySpec = {\n  query: \"SELECT * FROM c WHERE c.partitionKey = @category AND c.price \u003C @maxPrice\",\n  parameters: [\n    { name: \"@category\", value: \"electronics\" },\n    { name: \"@maxPrice\", value: 1000 },\n  ],\n};\n\nconst { resources } = await container.items\n  .query\u003CProduct>(querySpec)\n  .fetchAll();\n```\n\n### Query with Pagination\n\n```typescript\nconst queryIterator = container.items.query\u003CProduct>(querySpec, {\n  maxItemCount: 10, \u002F\u002F Items per page\n});\n\nwhile (queryIterator.hasMoreResults()) {\n  const { resources, continuationToken } = await queryIterator.fetchNext();\n  console.log(`Page with ${resources?.length} items`);\n  \u002F\u002F Use continuationToken for next page if needed\n}\n```\n\n### Cross-Partition Query\n\n```typescript\nconst { resources } = await container.items\n  .query\u003CProduct>(\n    \"SELECT * FROM c WHERE c.price > 500\",\n    { enableCrossPartitionQuery: true }\n  )\n  .fetchAll();\n```\n\n## Bulk Operations\n\n### Execute Bulk Operations\n\n```typescript\nimport { BulkOperationType, OperationInput } from \"@azure\u002Fcosmos\";\n\nconst operations: OperationInput[] = [\n  {\n    operationType: BulkOperationType.Create,\n    resourceBody: { id: \"1\", partitionKey: \"cat-a\", name: \"Item 1\" },\n  },\n  {\n    operationType: BulkOperationType.Upsert,\n    resourceBody: { id: \"2\", partitionKey: \"cat-a\", name: \"Item 2\" },\n  },\n  {\n    operationType: BulkOperationType.Read,\n    id: \"3\",\n    partitionKey: \"cat-b\",\n  },\n  {\n    operationType: BulkOperationType.Replace,\n    id: \"4\",\n    partitionKey: \"cat-b\",\n    resourceBody: { id: \"4\", partitionKey: \"cat-b\", name: \"Updated\" },\n  },\n  {\n    operationType: BulkOperationType.Delete,\n    id: \"5\",\n    partitionKey: \"cat-c\",\n  },\n  {\n    operationType: BulkOperationType.Patch,\n    id: \"6\",\n    partitionKey: \"cat-c\",\n    resourceBody: {\n      operations: [{ op: \"replace\", path: \"\u002Fname\", value: \"Patched\" }],\n    },\n  },\n];\n\nconst response = await container.items.executeBulkOperations(operations);\n\nresponse.forEach((result, index) => {\n  if (result.statusCode >= 200 && result.statusCode \u003C 300) {\n    console.log(`Operation ${index} succeeded`);\n  } else {\n    console.error(`Operation ${index} failed: ${result.statusCode}`);\n  }\n});\n```\n\n## Partition Keys\n\n### Simple Partition Key\n\n```typescript\nconst { container } = await database.containers.createIfNotExists({\n  id: \"products\",\n  partitionKey: { paths: [\"\u002Fcategory\"] },\n});\n```\n\n### Hierarchical Partition Key (MultiHash)\n\n```typescript\nimport { PartitionKeyDefinitionVersion, PartitionKeyKind } from \"@azure\u002Fcosmos\";\n\nconst { container } = await database.containers.createIfNotExists({\n  id: \"orders\",\n  partitionKey: {\n    paths: [\"\u002FtenantId\", \"\u002FuserId\", \"\u002FsessionId\"],\n    version: PartitionKeyDefinitionVersion.V2,\n    kind: PartitionKeyKind.MultiHash,\n  },\n});\n\n\u002F\u002F Operations require array of partition key values\nconst { resource } = await container.items.create({\n  id: \"order-1\",\n  tenantId: \"tenant-a\",\n  userId: \"user-123\",\n  sessionId: \"session-xyz\",\n  total: 99.99,\n});\n\n\u002F\u002F Read with hierarchical partition key\nconst { resource: order } = await container\n  .item(\"order-1\", [\"tenant-a\", \"user-123\", \"session-xyz\"])\n  .read();\n```\n\n## Error Handling\n\n```typescript\nimport { ErrorResponse } from \"@azure\u002Fcosmos\";\n\ntry {\n  const { resource } = await container.item(\"missing\", \"pk\").read();\n} catch (error) {\n  if (error instanceof ErrorResponse) {\n    switch (error.code) {\n      case 404:\n        console.log(\"Document not found\");\n        break;\n      case 409:\n        console.log(\"Conflict - document already exists\");\n        break;\n      case 412:\n        console.log(\"Precondition failed (ETag mismatch)\");\n        break;\n      case 429:\n        console.log(\"Rate limited - retry after:\", error.retryAfterInMs);\n        break;\n      default:\n        console.error(`Cosmos error ${error.code}: ${error.message}`);\n    }\n  }\n  throw error;\n}\n```\n\n## Optimistic Concurrency (ETags)\n\n```typescript\n\u002F\u002F Read with ETag\nconst { resource, etag } = await container\n  .item(\"product-1\", \"electronics\")\n  .read\u003CProduct>();\n\nif (resource && etag) {\n  resource.price = 899.99;\n  \n  try {\n    \u002F\u002F Replace only if ETag matches\n    await container.item(\"product-1\", \"electronics\").replace(resource, {\n      accessCondition: { type: \"IfMatch\", condition: etag },\n    });\n  } catch (error) {\n    if (error instanceof ErrorResponse && error.code === 412) {\n      console.log(\"Document was modified by another process\");\n    }\n  }\n}\n```\n\n## TypeScript Types Reference\n\n```typescript\nimport {\n  \u002F\u002F Client & Resources\n  CosmosClient,\n  Database,\n  Container,\n  Item,\n  Items,\n  \n  \u002F\u002F Operations\n  OperationInput,\n  BulkOperationType,\n  PatchOperation,\n  \n  \u002F\u002F Queries\n  SqlQuerySpec,\n  SqlParameter,\n  FeedOptions,\n  \n  \u002F\u002F Partition Keys\n  PartitionKeyDefinition,\n  PartitionKeyDefinitionVersion,\n  PartitionKeyKind,\n  \n  \u002F\u002F Responses\n  ItemResponse,\n  FeedResponse,\n  ResourceResponse,\n  \n  \u002F\u002F Errors\n  ErrorResponse,\n} from \"@azure\u002Fcosmos\";\n```\n\n## Best Practices\n\n1. **Use Microsoft Entra Token Credential** — Use `DefaultAzureCredential` for local development; use `ManagedIdentityCredential` or `WorkloadIdentityCredential` for production\n2. **Always use parameterized queries** — Prevents injection, improves plan caching\n3. **Specify partition key** — Avoid cross-partition queries when possible\n4. **Use bulk operations** — For multiple writes, use `executeBulkOperations`\n5. **Handle 429 errors** — Implement retry logic with exponential backoff\n6. **Use ETags for concurrency** — Prevent lost updates in concurrent scenarios\n7. **Close client on shutdown** — Call `client.dispose()` in cleanup\n\n## Common Patterns\n\n### Service Layer Pattern\n\n```typescript\nexport class ProductService {\n  private container: Container;\n\n  constructor(client: CosmosClient) {\n    this.container = client\n      .database(process.env.COSMOS_DATABASE!)\n      .container(process.env.COSMOS_CONTAINER!);\n  }\n\n  async getById(id: string, category: string): Promise\u003CProduct | null> {\n    try {\n      const { resource } = await this.container\n        .item(id, category)\n        .read\u003CProduct>();\n      return resource ?? null;\n    } catch (error) {\n      if (error instanceof ErrorResponse && error.code === 404) {\n        return null;\n      }\n      throw error;\n    }\n  }\n\n  async create(product: Omit\u003CProduct, \"id\">): Promise\u003CProduct> {\n    const item = { ...product, id: crypto.randomUUID() };\n    const { resource } = await this.container.items.create\u003CProduct>(item);\n    return resource!;\n  }\n\n  async findByCategory(category: string): Promise\u003CProduct[]> {\n    const querySpec: SqlQuerySpec = {\n      query: \"SELECT * FROM c WHERE c.partitionKey = @category\",\n      parameters: [{ name: \"@category\", value: category }],\n    };\n    const { resources } = await this.container.items\n      .query\u003CProduct>(querySpec)\n      .fetchAll();\n    return resources;\n  }\n}\n```\n\n## Related SDKs\n\n| SDK | Purpose | Install |\n|-----|---------|---------|\n| `@azure\u002Fcosmos` | Data plane (this SDK) | `npm install @azure\u002Fcosmos` |\n| `@azure\u002Farm-cosmosdb` | Management plane (ARM) | `npm install @azure\u002Farm-cosmosdb` |\n| `@azure\u002Fidentity` | Authentication | `npm install @azure\u002Fidentity` |\n","# @azure\u002Fcosmos (TypeScript\u002FJavaScript)\n\nData plane SDK for Azure Cosmos DB NoSQL API operations — CRUD on documents, queries, bulk operations.\n\n> **⚠️ Data vs Management Plane**\n> - **This SDK (@azure\u002Fcosmos)**: CRUD operations on documents, queries, stored procedures\n> - **Management SDK (@azure\u002Farm-cosmosdb)**: Create accounts, databases, containers via ARM\n\n## Installation\n\n```bash\nnpm install @azure\u002Fcosmos @azure\u002Fidentity\n```\n\n**Current Version**: 4.9.0  \n**Node.js**: >= 20.0.0\n\n## Environment Variables\n\n```bash\nCOSMOS_ENDPOINT=https:\u002F\u002F\u003Caccount>.documents.azure.com:443\u002F\nCOSMOS_DATABASE=\u003Cdatabase-name>\nCOSMOS_CONTAINER=\u003Ccontainer-name>\n# For key-based auth only (prefer AAD)\nCOSMOS_KEY=\u003Caccount-key>\nAZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production\n```\n\n## Authentication\n\n### Microsoft Entra Token Credential (Recommended)\n\n```typescript\nimport { CosmosClient } from \"@azure\u002Fcosmos\";\nimport { DefaultAzureCredential, ManagedIdentityCredential } from \"@azure\u002Fidentity\";\n\n\u002F\u002F Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=\u003Cspecific_credential>\nconst credential = new DefaultAzureCredential({requiredEnvVars: [\"AZURE_TOKEN_CREDENTIALS\"]});\n\u002F\u002F Or use a specific credential directly in production:\n\u002F\u002F See https:\u002F\u002Flearn.microsoft.com\u002Fjavascript\u002Fapi\u002Foverview\u002Fazure\u002Fidentity-readme?view=azure-node-latest#credential-classes\n\u002F\u002F const credential = new ManagedIdentityCredential();\n\nconst client = new CosmosClient({\n  endpoint: process.env.COSMOS_ENDPOINT!,\n  aadCredentials: credential,\n});\n```\n\n### Key-Based Authentication\n\n```typescript\nimport { CosmosClient } from \"@azure\u002Fcosmos\";\n\n\u002F\u002F Option 1: Endpoint + Key\nconst client = new CosmosClient({\n  endpoint: process.env.COSMOS_ENDPOINT!,\n  key: process.env.COSMOS_KEY!,\n});\n\n\u002F\u002F Option 2: Connection String\nconst client = new CosmosClient(process.env.COSMOS_CONNECTION_STRING!);\n```\n\n## Resource Hierarchy\n\n```\nCosmosClient\n└── Database\n    └── Container\n        ├── Items (documents)\n        ├── Scripts (stored procedures, triggers, UDFs)\n        └── Conflicts\n```\n\n## Core Operations\n\n### Database & Container Setup\n\n```typescript\nconst { database } = await client.databases.createIfNotExists({\n  id: \"my-database\",\n});\n\nconst { container } = await database.containers.createIfNotExists({\n  id: \"my-container\",\n  partitionKey: { paths: [\"\u002FpartitionKey\"] },\n});\n```\n\n### Create Document\n\n```typescript\ninterface Product {\n  id: string;\n  partitionKey: string;\n  name: string;\n  price: number;\n}\n\nconst item: Product = {\n  id: \"product-1\",\n  partitionKey: \"electronics\",\n  name: \"Laptop\",\n  price: 999.99,\n};\n\nconst { resource } = await container.items.create\u003CProduct>(item);\n```\n\n### Read Document\n\n```typescript\nconst { resource } = await container\n  .item(\"product-1\", \"electronics\") \u002F\u002F id, partitionKey\n  .read\u003CProduct>();\n\nif (resource) {\n  console.log(resource.name);\n}\n```\n\n### Update Document (Replace)\n\n```typescript\nconst { resource: existing } = await container\n  .item(\"product-1\", \"electronics\")\n  .read\u003CProduct>();\n\nif (existing) {\n  existing.price = 899.99;\n  const { resource: updated } = await container\n    .item(\"product-1\", \"electronics\")\n    .replace\u003CProduct>(existing);\n}\n```\n\n### Upsert Document\n\n```typescript\nconst item: Product = {\n  id: \"product-1\",\n  partitionKey: \"electronics\",\n  name: \"Laptop Pro\",\n  price: 1299.99,\n};\n\nconst { resource } = await container.items.upsert\u003CProduct>(item);\n```\n\n### Delete Document\n\n```typescript\nawait container.item(\"product-1\", \"electronics\").delete();\n```\n\n### Patch Document (Partial Update)\n\n```typescript\nimport { PatchOperation } from \"@azure\u002Fcosmos\";\n\nconst operations: PatchOperation[] = [\n  { op: \"replace\", path: \"\u002Fprice\", value: 799.99 },\n  { op: \"add\", path: \"\u002Fdiscount\", value: true },\n  { op: \"remove\", path: \"\u002FoldField\" },\n];\n\nconst { resource } = await container\n  .item(\"product-1\", \"electronics\")\n  .patch\u003CProduct>(operations);\n```\n\n## Queries\n\n### Simple Query\n\n```typescript\nconst { resources } = await container.items\n  .query\u003CProduct>(\"SELECT * FROM c WHERE c.price \u003C 1000\")\n  .fetchAll();\n```\n\n### Parameterized Query (Recommended)\n\n```typescript\nimport { SqlQuerySpec } from \"@azure\u002Fcosmos\";\n\nconst querySpec: SqlQuerySpec = {\n  query: \"SELECT * FROM c WHERE c.partitionKey = @category AND c.price \u003C @maxPrice\",\n  parameters: [\n    { name: \"@category\", value: \"electronics\" },\n    { name: \"@maxPrice\", value: 1000 },\n  ],\n};\n\nconst { resources } = await container.items\n  .query\u003CProduct>(querySpec)\n  .fetchAll();\n```\n\n### Query with Pagination\n\n```typescript\nconst queryIterator = container.items.query\u003CProduct>(querySpec, {\n  maxItemCount: 10, \u002F\u002F Items per page\n});\n\nwhile (queryIterator.hasMoreResults()) {\n  const { resources, continuationToken } = await queryIterator.fetchNext();\n  console.log(`Page with ${resources?.length} items`);\n  \u002F\u002F Use continuationToken for next page if needed\n}\n```\n\n### Cross-Partition Query\n\n```typescript\nconst { resources } = await container.items\n  .query\u003CProduct>(\n    \"SELECT * FROM c WHERE c.price > 500\",\n    { enableCrossPartitionQuery: true }\n  )\n  .fetchAll();\n```\n\n## Bulk Operations\n\n### Execute Bulk Operations\n\n```typescript\nimport { BulkOperationType, OperationInput } from \"@azure\u002Fcosmos\";\n\nconst operations: OperationInput[] = [\n  {\n    operationType: BulkOperationType.Create,\n    resourceBody: { id: \"1\", partitionKey: \"cat-a\", name: \"Item 1\" },\n  },\n  {\n    operationType: BulkOperationType.Upsert,\n    resourceBody: { id: \"2\", partitionKey: \"cat-a\", name: \"Item 2\" },\n  },\n  {\n    operationType: BulkOperationType.Read,\n    id: \"3\",\n    partitionKey: \"cat-b\",\n  },\n  {\n    operationType: BulkOperationType.Replace,\n    id: \"4\",\n    partitionKey: \"cat-b\",\n    resourceBody: { id: \"4\", partitionKey: \"cat-b\", name: \"Updated\" },\n  },\n  {\n    operationType: BulkOperationType.Delete,\n    id: \"5\",\n    partitionKey: \"cat-c\",\n  },\n  {\n    operationType: BulkOperationType.Patch,\n    id: \"6\",\n    partitionKey: \"cat-c\",\n    resourceBody: {\n      operations: [{ op: \"replace\", path: \"\u002Fname\", value: \"Patched\" }],\n    },\n  },\n];\n\nconst response = await container.items.executeBulkOperations(operations);\n\nresponse.forEach((result, index) => {\n  if (result.statusCode >= 200 && result.statusCode \u003C 300) {\n    console.log(`Operation ${index} succeeded`);\n  } else {\n    console.error(`Operation ${index} failed: ${result.statusCode}`);\n  }\n});\n```\n\n## Partition Keys\n\n### Simple Partition Key\n\n```typescript\nconst { container } = await database.containers.createIfNotExists({\n  id: \"products\",\n  partitionKey: { paths: [\"\u002Fcategory\"] },\n});\n```\n\n### Hierarchical Partition Key (MultiHash)\n\n```typescript\nimport { PartitionKeyDefinitionVersion, PartitionKeyKind } from \"@azure\u002Fcosmos\";\n\nconst { container } = await database.containers.createIfNotExists({\n  id: \"orders\",\n  partitionKey: {\n    paths: [\"\u002FtenantId\", \"\u002FuserId\", \"\u002FsessionId\"],\n    version: PartitionKeyDefinitionVersion.V2,\n    kind: PartitionKeyKind.MultiHash,\n  },\n});\n\n\u002F\u002F Operations require array of partition key values\nconst { resource } = await container.items.create({\n  id: \"order-1\",\n  tenantId: \"tenant-a\",\n  userId: \"user-123\",\n  sessionId: \"session-xyz\",\n  total: 99.99,\n});\n\n\u002F\u002F Read with hierarchical partition key\nconst { resource: order } = await container\n  .item(\"order-1\", [\"tenant-a\", \"user-123\", \"session-xyz\"])\n  .read();\n```\n\n## Error Handling\n\n```typescript\nimport { ErrorResponse } from \"@azure\u002Fcosmos\";\n\ntry {\n  const { resource } = await container.item(\"missing\", \"pk\").read();\n} catch (error) {\n  if (error instanceof ErrorResponse) {\n    switch (error.code) {\n      case 404:\n        console.log(\"Document not found\");\n        break;\n      case 409:\n        console.log(\"Conflict - document already exists\");\n        break;\n      case 412:\n        console.log(\"Precondition failed (ETag mismatch)\");\n        break;\n      case 429:\n        console.log(\"Rate limited - retry after:\", error.retryAfterInMs);\n        break;\n      default:\n        console.error(`Cosmos error ${error.code}: ${error.message}`);\n    }\n  }\n  throw error;\n}\n```\n\n## Optimistic Concurrency (ETags)\n\n```typescript\n\u002F\u002F Read with ETag\nconst { resource, etag } = await container\n  .item(\"product-1\", \"electronics\")\n  .read\u003CProduct>();\n\nif (resource && etag) {\n  resource.price = 899.99;\n  \n  try {\n    \u002F\u002F Replace only if ETag matches\n    await container.item(\"product-1\", \"electronics\").replace(resource, {\n      accessCondition: { type: \"IfMatch\", condition: etag },\n    });\n  } catch (error) {\n    if (error instanceof ErrorResponse && error.code === 412) {\n      console.log(\"Document was modified by another process\");\n    }\n  }\n}\n```\n\n## TypeScript Types Reference\n\n```typescript\nimport {\n  \u002F\u002F Client & Resources\n  CosmosClient,\n  Database,\n  Container,\n  Item,\n  Items,\n  \n  \u002F\u002F Operations\n  OperationInput,\n  BulkOperationType,\n  PatchOperation,\n  \n  \u002F\u002F Queries\n  SqlQuerySpec,\n  SqlParameter,\n  FeedOptions,\n  \n  \u002F\u002F Partition Keys\n  PartitionKeyDefinition,\n  PartitionKeyDefinitionVersion,\n  PartitionKeyKind,\n  \n  \u002F\u002F Responses\n  ItemResponse,\n  FeedResponse,\n  ResourceResponse,\n  \n  \u002F\u002F Errors\n  ErrorResponse,\n} from \"@azure\u002Fcosmos\";\n```\n\n## Best Practices\n\n1. **Use Microsoft Entra Token Credential** — Use `DefaultAzureCredential` for local development; use `ManagedIdentityCredential` or `WorkloadIdentityCredential` for production\n2. **Always use parameterized queries** — Prevents injection, improves plan caching\n3. **Specify partition key** — Avoid cross-partition queries when possible\n4. **Use bulk operations** — For multiple writes, use `executeBulkOperations`\n5. **Handle 429 errors** — Implement retry logic with exponential backoff\n6. **Use ETags for concurrency** — Prevent lost updates in concurrent scenarios\n7. **Close client on shutdown** — Call `client.dispose()` in cleanup\n\n## Common Patterns\n\n### Service Layer Pattern\n\n```typescript\nexport class ProductService {\n  private container: Container;\n\n  constructor(client: CosmosClient) {\n    this.container = client\n      .database(process.env.COSMOS_DATABASE!)\n      .container(process.env.COSMOS_CONTAINER!);\n  }\n\n  async getById(id: string, category: string): Promise\u003CProduct | null> {\n    try {\n      const { resource } = await this.container\n        .item(id, category)\n        .read\u003CProduct>();\n      return resource ?? null;\n    } catch (error) {\n      if (error instanceof ErrorResponse && error.code === 404) {\n        return null;\n      }\n      throw error;\n    }\n  }\n\n  async create(product: Omit\u003CProduct, \"id\">): Promise\u003CProduct> {\n    const item = { ...product, id: crypto.randomUUID() };\n    const { resource } = await this.container.items.create\u003CProduct>(item);\n    return resource!;\n  }\n\n  async findByCategory(category: string): Promise\u003CProduct[]> {\n    const querySpec: SqlQuerySpec = {\n      query: \"SELECT * FROM c WHERE c.partitionKey = @category\",\n      parameters: [{ name: \"@category\", value: category }],\n    };\n    const { resources } = await this.container.items\n      .query\u003CProduct>(querySpec)\n      .fetchAll();\n    return resources;\n  }\n}\n```\n\n## Related SDKs\n\n| SDK | Purpose | Install |\n|-----|---------|---------|\n| `@azure\u002Fcosmos` | Data plane (this SDK) | `npm install @azure\u002Fcosmos` |\n| `@azure\u002Farm-cosmosdb` | Management plane (ARM) | `npm install @azure\u002Farm-cosmosdb` |\n| `@azure\u002Fidentity` | Authentication | `npm install @azure\u002Fidentity` |\n",{"name":5,"license":15,"metadata":46,"description":49},{"author":12,"package":47,"version":48},"@azure\u002Fcosmos","1.0.0","Azure Cosmos DB JavaScript\u002FTypeScript SDK (@azure\u002Fcosmos) for data plane operations. Use for CRUD operations on documents, queries, bulk operations, and container management. Triggers: \"Cosmos DB\", \"@azure\u002Fcosmos\", \"CosmosClient\", \"document CRUD\", \"NoSQL queries\", \"bulk operations\", \"partition key\", \"container.items\".\n","main","3f5b461b2314e01c400564051e92469114c5b68f",".github\u002Fplugins\u002Fazure-sdk-typescript\u002Fskills\u002Fazure-cosmos-ts",368,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills","https:\u002F\u002Fmicrosoft.github.io\u002Fskills\u002F","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-14 06:48:25",{"source":8,"skillName":5,"commands":61,"prompt":71,"zipAvailable":72},[62,65,68],{"tool":63,"command":64},"npx","npx skills add microsoft\u002Fskills --skill azure-cosmos-ts",{"tool":66,"command":67},"bunx","bunx skills add microsoft\u002Fskills --skill azure-cosmos-ts",{"tool":69,"command":70},"pnpm","pnpm dlx skills add microsoft\u002Fskills --skill azure-cosmos-ts","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fplugins\u002Fazure-sdk-typescript\u002Fskills\u002Fazure-cosmos-ts\u002FSKILL.md",true,[74,80],{"path":75,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":78,"sourceHtmlUrl":79},"references\u002Fbulk-operations.md","REFERENCE","参考文档",11431,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fplugins\u002Fazure-sdk-typescript\u002Fskills\u002Fazure-cosmos-ts\u002Freferences\u002Fbulk-operations.md",{"path":81,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":82,"sourceHtmlUrl":83},"references\u002Fquery-patterns.md",8916,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fplugins\u002Fazure-sdk-typescript\u002Fskills\u002Fazure-cosmos-ts\u002Freferences\u002Fquery-patterns.md",[85,112,150,177,196,234],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":96,"publishedAt":41},"01M69B4JCRQV5SPXAFCKXQRV0H","skill-creator","Guide for creating effective skills for AI coding agents working with Azure SDKs and Microsoft Foundry services. Use when creating new skills or updating existing skills.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fskill-creator\u002FSKILL.md",[91],{"categoryNo":92,"categoryName":93,"taxonomyType":94,"taxonomyTypeDesc":95},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[97,98,99,9,100,101,102,19,103,104,105,32,106,107,108,23,109,110,111],"skill creator","creator","coding agents","foundry","microsoft foundry","ai coding agents","services","coding","guide","ai coding","with","sdks","Existing","when","new",{"skillNo":113,"name":114,"nameZh":6,"description":115,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":116,"categories":117,"keywords":128,"publishedAt":41},"01M69B4FD57V1MYKRWAJJECTZ7","podcast-generation","Generate AI-powered podcast-style audio narratives using Azure OpenAI's GPT Realtime Mini model via WebSocket. Use when building text-to-speech features, audio narrative generation, podcast creation from content, or integrating with Azure OpenAI Realtime API for real audio output. Covers full-stack implementation from React frontend to Python FastAPI backend with WebSocket streaming.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fpodcast-generation\u002FSKILL.md",[118,121,124,127],{"categoryNo":119,"categoryName":120,"taxonomyType":94,"taxonomyTypeDesc":95},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":122,"categoryName":123,"taxonomyType":94,"taxonomyTypeDesc":95},"01JBSEEDCAT000000000000010","后端与接口",{"categoryNo":125,"categoryName":126,"taxonomyType":94,"taxonomyTypeDesc":95},"01JBSEEDCAT000000000000016","图像与多媒体",{"categoryNo":92,"categoryName":93,"taxonomyType":94,"taxonomyTypeDesc":95},[129,130,131,132,133,134,135,19,136,137,138,139,140,141,142,143,144,145,146,147,148,110,149],"podcast generation","podcast","generation","frontend","python","react","realtime","azure openai","generate","streaming","api","Audio","stack","text","model","fastapi","creation","python fastapi","narrative","features","fastapi backend",{"skillNo":151,"name":152,"nameZh":6,"description":153,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":154,"categories":155,"keywords":157,"publishedAt":41},"01M69B4CYPM5SESY5ZWEFDXEQZ","microsoft-docs","Understand Microsoft technologies by querying official documentation. Use whenever the user asks how something works, wants tutorials, needs configuration options, limits, quotas, or best practices for any Microsoft technology (Azure, .NET, M365, Windows, Power Platform, etc.)—even if they don't mention \"docs.\" If the question is about understanding a concept rather than writing code, this is the right skill.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fmicrosoft-docs\u002FSKILL.md",[156],{"categoryNo":92,"categoryName":93,"taxonomyType":94,"taxonomyTypeDesc":95},[158,9,159,160,161,162,163,164,165,166,167,19,168,169,170,32,171,63,172,173,174,175,176,23],"docs","microsoft docs","MCP","writing","cli","mcp server","windows","power platform","official","documentation","learn","best practices","question","power","back","technology","platform","learn mcp","concept",{"skillNo":178,"name":179,"nameZh":6,"description":180,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":181,"categories":182,"keywords":184,"publishedAt":41},"01M69B49C3YPD1ZJ3NC0HPCY58","mcp-builder","Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP), Node\u002FTypeScript (MCP SDK), or C#\u002F.NET (Microsoft MCP SDK).","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fmcp-builder\u002FSKILL.md",[183],{"categoryNo":92,"categoryName":93,"taxonomyType":94,"taxonomyTypeDesc":95},[160,185,186,33,133,187,40,188,9,189,190,143,191,192,105,32,193,194,195,107,23,110],"mcp builder","builder","llms","model context protocol","fastmcp","Tools","node","context","integrate","mcp sdk","building mcp servers",{"skillNo":197,"name":198,"nameZh":6,"description":199,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":200,"categories":201,"keywords":214,"publishedAt":41},"01M69B467A7CDMFQ0T6Q0ZA12Q","kql","KQL language expertise for writing correct, efficient Kusto Query Language queries. Covers syntax gotchas, join patterns, dynamic types, datetime pitfalls, regex patterns, serialization, memory management, result-size discipline, and advanced functions (geo, vector, graph). USE THIS SKILL whenever writing, debugging, or reviewing KQL queries — even simple ones — because the gotchas section prevents the most common errors that waste tool calls and cause expensive retry cascades. Trigger on: KQL, Kusto, ADX, Azure Data Explorer, Fabric Real-Time Intelligence, EventHouse, Log Analytics, log analysis, data exploration, time series, anomaly detection, summarize, where clause, join, extend, project, let statement, parse operator, extract function, any mention of pipe-forward query syntax.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fkql\u002FSKILL.md",[202,205,206,211],{"categoryNo":203,"categoryName":204,"taxonomyType":94,"taxonomyTypeDesc":95},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":92,"categoryName":93,"taxonomyType":94,"taxonomyTypeDesc":95},{"categoryNo":207,"categoryName":208,"taxonomyType":209,"taxonomyTypeDesc":210},"01JBSEEDCAT000000000000033","数据分析师","PROFESSION","适用职业",{"categoryNo":212,"categoryName":213,"taxonomyType":209,"taxonomyTypeDesc":210},"01JBSEEDCAT000000000000036","内容创作者",[198,161,215,216,217,19,218,219,220,221,222,223,224,225,226,227,228,229,230,23,231,232,233],"summarize","memory","analytics","vector","time series","tool","discipline","log","geo","exploration","pipe","time","project","regex","join","datetime","section","anomaly","parse",{"skillNo":235,"name":236,"nameZh":6,"description":237,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":238,"categories":239,"keywords":240,"publishedAt":41},"01M69B44HJQ7897EZ7NE7DWQX3","github-issue-creator","Convert raw notes, error logs, voice dictation, or screenshots into crisp GitHub-flavored markdown issue reports. Use when the user pastes bug info, error messages, or informal descriptions and wants a structured GitHub issue. Supports images\u002FGIFs for visual evidence.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fgithub-issue-creator\u002FSKILL.md",[],[241,242,243,244,98,245,246,247,248,249,250,251,32,252,253,254,255,256,257,23,110],"github","github issue creator","github issue","issue","issue creator","screenshots","notes","logs","error messages","messages","convert","evidence","reports","images","info","visual","error"]