[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6EXHGNE29WSWVW2568JSR5M":3,"skill-same:01M6EXHGNE29WSWVW2568JSR5M":75},{"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":39,"linkOnly":40,"markdownContent":41,"markdownBody":42,"frontMatter":43,"refName":46,"commitSha":47,"skillDirectory":48,"forksCount":49,"repositoryHtmlUrl":50,"repositoryHomepageUrl":51,"ownerHtmlUrl":52,"ownerBlogUrl":6,"ownerDescription":53,"updatedAt":54,"install":55,"resources":68},"01M6EXHGNE29WSWVW2568JSR5M","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\".","ComeOnOliver\u002Fskillshub","ComeOnOliver","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F43215937?v=4","01M6E5JNFECJAAVFE0W7SMWWD2","Haoran Shu","01M6E5JNNDQS7AJZDYFQ8TPZCK",66,"MIT","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Faiskillstore\u002Fmarketplace\u002Fsickn33\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],"azure","azure cosmos ts","cosmos","use","container management","bulk","triggers","db","bulk operations","document","queries","container","typescript","partition","crud","nosql","data","azure cosmos db","documents","javascript","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\".\npackage: \"@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>\n```\n\n## Authentication\n\n### AAD with DefaultAzureCredential (Recommended)\n\n```typescript\nimport { CosmosClient } from \"@azure\u002Fcosmos\";\nimport { DefaultAzureCredential } from \"@azure\u002Fidentity\";\n\nconst client = new CosmosClient({\n  endpoint: process.env.COSMOS_ENDPOINT!,\n  aadCredentials: new DefaultAzureCredential(),\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 AAD authentication** — Prefer `DefaultAzureCredential` over keys\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>\n```\n\n## Authentication\n\n### AAD with DefaultAzureCredential (Recommended)\n\n```typescript\nimport { CosmosClient } from \"@azure\u002Fcosmos\";\nimport { DefaultAzureCredential } from \"@azure\u002Fidentity\";\n\nconst client = new CosmosClient({\n  endpoint: process.env.COSMOS_ENDPOINT!,\n  aadCredentials: new DefaultAzureCredential(),\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 AAD authentication** — Prefer `DefaultAzureCredential` over keys\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,"package":44,"description":45},"@azure\u002Fcosmos","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","def8531e65114c0fca8fb8551c1871ee0eed705c","skills\u002Faiskillstore\u002Fmarketplace\u002Fsickn33\u002Fazure-cosmos-ts",24,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub","https:\u002F\u002Fskillshub.wtf","https:\u002F\u002Fgithub.com\u002FComeOnOliver","AI & Blockchain Engineer\r\n","2026-06-24 22:07:19",{"source":8,"skillName":5,"commands":56,"prompt":66,"zipAvailable":67},[57,60,63],{"tool":58,"command":59},"npx","npx skills add ComeOnOliver\u002Fskillshub --skill azure-cosmos-ts",{"tool":61,"command":62},"bunx","bunx skills add ComeOnOliver\u002Fskillshub --skill azure-cosmos-ts",{"tool":64,"command":65},"pnpm","pnpm dlx skills add ComeOnOliver\u002Fskillshub --skill azure-cosmos-ts","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Faiskillstore\u002Fmarketplace\u002Fsickn33\u002Fazure-cosmos-ts\u002FSKILL.md",true,[69],{"path":70,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":73,"sourceHtmlUrl":74},"skill-report.json","REFERENCE","参考文档",8690,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Faiskillstore\u002Fmarketplace\u002Fsickn33\u002Fazure-cosmos-ts\u002Fskill-report.json",[76,90,100,109,115,122],{"skillNo":77,"name":78,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":86,"publishedAt":39},"01M6FKJN13GMG4KY57J3QD8GY5","model-hierarchy-skill","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzscole\u002Fmodel-hierarchy-skill\u002Fmodel-hierarchy-skill\u002FSKILL.md",[81],{"categoryNo":82,"categoryName":83,"taxonomyType":84,"taxonomyTypeDesc":85},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[87,88,89],"model","model hierarchy","model hierarchy skill",{"skillNo":91,"name":92,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":96,"publishedAt":39},"01M6FKJJJ6GCAMR4PPPRD12M5X","zoom-mcp","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fzoom-mcp\u002FSKILL.md",[95],{"categoryNo":82,"categoryName":83,"taxonomyType":84,"taxonomyTypeDesc":85},[97,98,99],"MCP","zoom","zoom mcp",{"skillNo":101,"name":102,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":39},"01M6FKJE3KYT3KPEZMEEHYKA6K","zoom-apps-sdk","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fzoom-apps-sdk\u002FSKILL.md",[],[106,107,108,98],"sdk","zoom apps sdk","apps",{"skillNo":110,"name":111,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":112,"categories":113,"keywords":114,"publishedAt":39},"01M6FKJ9EDH9Q5VWDF8HAJRSP0","windows","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwindows\u002FSKILL.md",[],[111],{"skillNo":116,"name":117,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":118,"categories":119,"keywords":121,"publishedAt":39},"01M6FKJ666BEEFC3AE9GJ72Q93","whiteboard","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwhiteboard\u002FSKILL.md",[120],{"categoryNo":82,"categoryName":83,"taxonomyType":84,"taxonomyTypeDesc":85},[117],{"skillNo":123,"name":124,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":125,"categories":126,"keywords":127,"publishedAt":39},"01M6FKJ21WFCDGTJQ2Q91T9DVW","websockets","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwebsockets\u002FSKILL.md",[],[124]]