[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-b548c1fa-a606-4a7c-b4f2-ecd3a44c49af":3,"$fCwdoNKL4ve0dtcgOwVHklbQPfpfLaknnV82wg6cpgRo":43},{"id":4,"title":5,"description":6,"categoryId":7,"moduleId":8,"tags":9,"prompt":10,"icon":11,"source":12,"sourceUrl":13,"authorId":14,"authorName":15,"isPublic":16,"stars":17,"runs":18,"createdAt":19,"updatedAt":19,"module":20,"category":27,"packages":34},"b548c1fa-a606-4a7c-b4f2-ecd3a44c49af","azure-cosmos-ts","Azure Cosmos DB JavaScript\u002FTypeScript SDK（@azure\u002Fcosmos）用于数据平面操作。用于对文档、查询、批量操作和容器管理进行CRUD操作。","cat_coding_devops","mod_coding","sickn33,coding","---\nname: azure-cosmos-ts\ndescription: Azure Cosmos DB JavaScript\u002FTypeScript SDK (@azure\u002Fcosmos) for data plane operations. Use for CRUD operations on documents, queries, bulk operations, and container management.\nrisk: unknown\nsource: community\ndate_added: '2026-02-27'\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\n## When to Use\nThis skill is applicable to execute the workflow or actions described in the overview.\n\n## Limitations\n- Use this skill only when the task clearly matches the scope described above.\n- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.\n- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.\n","","imported","https:\u002F\u002Fgithub.com\u002Fsickn33\u002Fantigravity-awesome-skills","user_system_seed","SkillOPIC",true,240,2039,"2026-05-16 13:06:10",{"id":8,"name":21,"slug":22,"icon":23,"description":24,"sort":25,"createdAt":26},"编程开发","coding","mdi-code-braces","代码生成、调试、审查，提升开发效率",2,"2026-05-16 12:53:40",{"id":7,"name":28,"slug":29,"icon":30,"description":31,"moduleId":8,"sort":32,"skillCount":33,"createdAt":26},"DevOps","devops","mdi-cog-outline","CI\u002FCD、容器化、部署运维",3,162,[35],{"id":36,"skillId":4,"version":37,"fileName":38,"fileSize":39,"filePath":40,"fileHash":41,"manifest":42,"createdAt":19},"515b7ffe-d587-4475-845b-878118a92ef9","1.0.0","azure-cosmos-ts.zip",3778,"uploads\u002Fskills\u002Fb548c1fa-a606-4a7c-b4f2-ecd3a44c49af\u002Fazure-cosmos-ts.zip","65070fb44e489ca0e2e55043101083cead6898b64d1270a5fee054169eb762bf","[{\"path\":\"SKILL.md\",\"isDirectory\":false,\"size\":11489}]",{"code":44,"message":45,"data":46},200,"success",{"items":47,"stats":48,"page":51},[],{"averageRating":49,"totalRatings":49,"ratingCounts":50},0,[49,49,49,49,49],{"limit":52,"offset":49,"hasMore":53,"nextOffset":52,"ratedOnly":16},15,false]