{
  "schema": "https://ai-atoms.com/schemas/skill-v1.json",
  "type": "skill",
  "id": "skill/azure-cosmos-ts",
  "version": "1.0.1",
  "name": "Azure Cosmos Ts",
  "description": "Azure Cosmos DB JavaScript/TypeScript SDK (@azure/cosmos) for data plane operations. Use for CRUD operations on documents, queries, bulk operations, and container management. Triggers: \"Cosmos DB\", \"@azure/cosmos\", \"CosmosClient\", \"document CRUD\", \"NoSQL queries\", \"bulk operations\", \"partition key\", \"container.items\".",
  "system_prompt_fragment": "# @azure/cosmos (TypeScript/JavaScript)\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/cosmos)**: CRUD operations on documents, queries, stored procedures\n> - **Management SDK (@azure/arm-cosmosdb)**: Create accounts, databases, containers via ARM\n\n## Installation\n\n```bash\nnpm install @azure/cosmos @azure/identity\n```\n\n**Current Version**: 4.9.0  \n**Node.js**: >= 20.0.0\n\n## Environment Variables\n\n```bash\nCOSMOS_ENDPOINT=https://<account>.documents.azure.com:443/\nCOSMOS_DATABASE=<database-name>\nCOSMOS_CONTAINER=<container-name>\n# For key-based auth only (prefer AAD)\nCOSMOS_KEY=<account-key>\n```\n\n## Authentication\n\n### AAD with DefaultAzureCredential (Recommended)\n\n```typescript\nimport { CosmosClient } from \"@azure/cosmos\";\nimport { DefaultAzureCredential } from \"@azure/identity\";\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/cosmos\";\n\n// Option 1: Endpoint + Key\nconst client = new CosmosClient({\n  endpoint: process.env.COSMOS_ENDPOINT!,\n  key: process.env.COSMOS_KEY!,\n});\n\n// 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: [\"/partitionKey\"] },\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<Product>(item);\n```\n\n### Read Document\n\n```typescript\nconst { resource } = await container\n  .item(\"product-1\", \"electronics\") // id, partitionKey\n  .read<Product>();\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<Product>();\n\nif (existing) {\n  existing.price = 899.99;\n  const { resource: updated } = await container\n    .item(\"product-1\", \"electronics\")\n    .replace<Product>(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<Product>(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/cosmos\";\n\nconst operations: PatchOperation[] = [\n  { op: \"replace\", path: \"/price\", value: 799.99 },\n  { op: \"add\", path: \"/discount\", value: true },\n  { op: \"remove\", path: \"/oldField\" },\n];\n\nconst { resource } = await container\n  .item(\"product-1\", \"electronics\")\n  .patch<Product>(operations);\n```\n\n## Queries\n\n### Simple Query\n\n```typescript\nconst { resources } = await container.items\n  .query<Product>(\"SELECT * FROM c WHERE c.price < 1000\")\n  .fetchAll();\n```\n\n### Parameterized Query (Recommended)\n\n```typescript\nimport { SqlQuerySpec } from \"@azure/cosmos\";\n\nconst querySpec: SqlQuerySpec = {\n  query: \"SELECT * FROM c WHERE c.partitionKey = @category AND c.price < @maxPrice\",\n  parameters: [\n    { name: \"@category\", value: \"electronics\" },\n    { name: \"@maxPrice\", value: 1000 },\n  ],\n};\n\nconst { resources } = await container.items\n  .query<Product>(querySpec)\n  .fetchAll();\n```\n\n### Query with Pagination\n\n```typescript\nconst queryIterator = container.items.query<Product>(querySpec, {\n  maxItemCount: 10, // Items per page\n});\n\nwhile (queryIterator.hasMoreResults()) {\n  const { resources, continuationToken } = await queryIterator.fetchNext();\n  console.log(`Page with ${resources?.length} items`);\n  // Use continuationToken for next page if needed\n}\n```\n\n### Cross-Partition Query\n\n```typescript\nconst { resources } = await container.items\n  .query<Product>(\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/cosmos\";\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: \"/name\", 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 < 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: [\"/category\"] },\n});\n```\n\n### Hierarchical Partition Key (MultiHash)\n\n```typescript\nimport { PartitionKeyDefinitionVersion, PartitionKeyKind } from \"@azure/cosmos\";\n\nconst { container } = await database.containers.createIfNotExists({\n  id: \"orders\",\n  partitionKey: {\n    paths: [\"/tenantId\", \"/userId\", \"/sessionId\"],\n    version: PartitionKeyDefinitionVersion.V2,\n    kind: PartitionKeyKind.MultiHash,\n  },\n});\n\n// 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// 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/cosmos\";\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// Read with ETag\nconst { resource, etag } = await container\n  .item(\"product-1\", \"electronics\")\n  .read<Product>();\n\nif (resource && etag) {\n  resource.price = 899.99;\n  \n  try {\n    // 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  // Client & Resources\n  CosmosClient,\n  Database,\n  Container,\n  Item,\n  Items,\n  \n  // Operations\n  OperationInput,\n  BulkOperationType,\n  PatchOperation,\n  \n  // Queries\n  SqlQuerySpec,\n  SqlParameter,\n  FeedOptions,\n  \n  // Partition Keys\n  PartitionKeyDefinition,\n  PartitionKeyDefinitionVersion,\n  PartitionKeyKind,\n  \n  // Responses\n  ItemResponse,\n  FeedResponse,\n  ResourceResponse,\n  \n  // Errors\n  ErrorResponse,\n} from \"@azure/cosmos\";\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<Product | null> {\n    try {\n      const { resource } = await this.container\n        .item(id, category)\n        .read<Product>();\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<Product, \"id\">): Promise<Product> {\n    const item = { ...product, id: crypto.randomUUID() };\n    const { resource } = await this.container.items.create<Product>(item);\n    return resource!;\n  }\n\n  async findByCategory(category: string): Promise<Product[]> {\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<Product>(querySpec)\n      .fetchAll();\n    return resources;\n  }\n}\n```\n\n## Related SDKs\n\n| SDK | Purpose | Install |\n|-----|---------|---------|\n| `@azure/cosmos` | Data plane (this SDK) | `npm install @azure/cosmos` |\n| `@azure/arm-cosmosdb` | Management plane (ARM) | `npm install @azure/arm-cosmosdb` |\n| `@azure/identity` | Authentication | `npm install @azure/identity` |\n\n## When to Use\nThis skill is applicable to execute the workflow or actions described in the overview.",
  "applicable_domains": [
    "devops"
  ],
  "category": "devops",
  "invocation": [
    "/azure-cosmos-ts"
  ],
  "authored_by": "claudeskills.in community",
  "source_url": "https://claudeskills.in/skill/azure-cosmos-ts",
  "provenance": {
    "source": "claudeskills.in",
    "source_url": "https://claudeskills.in/skill/azure-cosmos-ts",
    "license": "unknown",
    "imported_at": "2026-09-03",
    "notes": "Aggregated by claudeskills.in from community GitHub lists."
  },
  "tags": [
    "claudeskills",
    "devops"
  ],
  "lifecycle": "draft"
}