{
  "schema": "https://ai-atoms.com/schemas/skill-v1.json",
  "type": "skill",
  "id": "skill/azure-cosmos-py",
  "version": "1.0.1",
  "name": "Azure Cosmos Py",
  "description": "Azure Cosmos DB SDK for Python (NoSQL API). Use for document CRUD, queries, containers, and globally distributed data.\nTriggers: \"cosmos db\", \"CosmosClient\", \"container\", \"document\", \"NoSQL\", \"partition key\".",
  "system_prompt_fragment": "# Azure Cosmos DB SDK for Python\n\nClient library for Azure Cosmos DB NoSQL API — globally distributed, multi-model database.\n\n## Installation\n\n```bash\npip install azure-cosmos azure-identity\n```\n\n## Environment Variables\n\n```bash\nCOSMOS_ENDPOINT=https://<account>.documents.azure.com:443/\nCOSMOS_DATABASE=mydb\nCOSMOS_CONTAINER=mycontainer\n```\n\n## Authentication\n\n```python\nfrom azure.identity import DefaultAzureCredential\nfrom azure.cosmos import CosmosClient\n\ncredential = DefaultAzureCredential()\nendpoint = \"https://<account>.documents.azure.com:443/\"\n\nclient = CosmosClient(url=endpoint, credential=credential)\n```\n\n## Client Hierarchy\n\n| Client | Purpose | Get From |\n|--------|---------|----------|\n| `CosmosClient` | Account-level operations | Direct instantiation |\n| `DatabaseProxy` | Database operations | `client.get_database_client()` |\n| `ContainerProxy` | Container/item operations | `database.get_container_client()` |\n\n## Core Workflow\n\n### Setup Database and Container\n\n```python\n# Get or create database\ndatabase = client.create_database_if_not_exists(id=\"mydb\")\n\n# Get or create container with partition key\ncontainer = database.create_container_if_not_exists(\n    id=\"mycontainer\",\n    partition_key=PartitionKey(path=\"/category\")\n)\n\n# Get existing\ndatabase = client.get_database_client(\"mydb\")\ncontainer = database.get_container_client(\"mycontainer\")\n```\n\n### Create Item\n\n```python\nitem = {\n    \"id\": \"item-001\",           # Required: unique within partition\n    \"category\": \"electronics\",   # Partition key value\n    \"name\": \"Laptop\",\n    \"price\": 999.99,\n    \"tags\": [\"computer\", \"portable\"]\n}\n\ncreated = container.create_item(body=item)\nprint(f\"Created: {created['id']}\")\n```\n\n### Read Item\n\n```python\n# Read requires id AND partition key\nitem = container.read_item(\n    item=\"item-001\",\n    partition_key=\"electronics\"\n)\nprint(f\"Name: {item['name']}\")\n```\n\n### Update Item (Replace)\n\n```python\nitem = container.read_item(item=\"item-001\", partition_key=\"electronics\")\nitem[\"price\"] = 899.99\nitem[\"on_sale\"] = True\n\nupdated = container.replace_item(item=item[\"id\"], body=item)\n```\n\n### Upsert Item\n\n```python\n# Create if not exists, replace if exists\nitem = {\n    \"id\": \"item-002\",\n    \"category\": \"electronics\",\n    \"name\": \"Tablet\",\n    \"price\": 499.99\n}\n\nresult = container.upsert_item(body=item)\n```\n\n### Delete Item\n\n```python\ncontainer.delete_item(\n    item=\"item-001\",\n    partition_key=\"electronics\"\n)\n```\n\n## Queries\n\n### Basic Query\n\n```python\n# Query within a partition (efficient)\nquery = \"SELECT * FROM c WHERE c.price < @max_price\"\nitems = container.query_items(\n    query=query,\n    parameters=[{\"name\": \"@max_price\", \"value\": 500}],\n    partition_key=\"electronics\"\n)\n\nfor item in items:\n    print(f\"{item['name']}: ${item['price']}\")\n```\n\n### Cross-Partition Query\n\n```python\n# Cross-partition (more expensive, use sparingly)\nquery = \"SELECT * FROM c WHERE c.price < @max_price\"\nitems = container.query_items(\n    query=query,\n    parameters=[{\"name\": \"@max_price\", \"value\": 500}],\n    enable_cross_partition_query=True\n)\n\nfor item in items:\n    print(item)\n```\n\n### Query with Projection\n\n```python\nquery = \"SELECT c.id, c.name, c.price FROM c WHERE c.category = @category\"\nitems = container.query_items(\n    query=query,\n    parameters=[{\"name\": \"@category\", \"value\": \"electronics\"}],\n    partition_key=\"electronics\"\n)\n```\n\n### Read All Items\n\n```python\n# Read all in a partition\nitems = container.read_all_items()  # Cross-partition\n# Or with partition key\nitems = container.query_items(\n    query=\"SELECT * FROM c\",\n    partition_key=\"electronics\"\n)\n```\n\n## Partition Keys\n\n**Critical**: Always include partition key for efficient operations.\n\n```python\nfrom azure.cosmos import PartitionKey\n\n# Single partition key\ncontainer = database.create_container_if_not_exists(\n    id=\"orders\",\n    partition_key=PartitionKey(path=\"/customer_id\")\n)\n\n# Hierarchical partition key (preview)\ncontainer = database.create_container_if_not_exists(\n    id=\"events\",\n    partition_key=PartitionKey(path=[\"/tenant_id\", \"/user_id\"])\n)\n```\n\n## Throughput\n\n```python\n# Create container with provisioned throughput\ncontainer = database.create_container_if_not_exists(\n    id=\"mycontainer\",\n    partition_key=PartitionKey(path=\"/pk\"),\n    offer_throughput=400  # RU/s\n)\n\n# Read current throughput\noffer = container.read_offer()\nprint(f\"Throughput: {offer.offer_throughput} RU/s\")\n\n# Update throughput\ncontainer.replace_throughput(throughput=1000)\n```\n\n## Async Client\n\n```python\nfrom azure.cosmos.aio import CosmosClient\nfrom azure.identity.aio import DefaultAzureCredential\n\nasync def cosmos_operations():\n    credential = DefaultAzureCredential()\n    \n    async with CosmosClient(endpoint, credential=credential) as client:\n        database = client.get_database_client(\"mydb\")\n        container = database.get_container_client(\"mycontainer\")\n        \n        # Create\n        await container.create_item(body={\"id\": \"1\", \"pk\": \"test\"})\n        \n        # Read\n        item = await container.read_item(item=\"1\", partition_key=\"test\")\n        \n        # Query\n        async for item in container.query_items(\n            query=\"SELECT * FROM c\",\n            partition_key=\"test\"\n        ):\n            print(item)\n\nimport asyncio\nasyncio.run(cosmos_operations())\n```\n\n## Error Handling\n\n```python\nfrom azure.cosmos.exceptions import CosmosHttpResponseError\n\ntry:\n    item = container.read_item(item=\"nonexistent\", partition_key=\"pk\")\nexcept CosmosHttpResponseError as e:\n    if e.status_code == 404:\n        print(\"Item not found\")\n    elif e.status_code == 429:\n        print(f\"Rate limited. Retry after: {e.headers.get('x-ms-retry-after-ms')}ms\")\n    else:\n        raise\n```\n\n## Best Practices\n\n1. **Always specify partition key** for point reads and queries\n2. **Use parameterized queries** to prevent injection and improve caching\n3. **Avoid cross-partition queries** when possible\n4. **Use `upsert_item`** for idempotent writes\n5. **Use async client** for high-throughput scenarios\n6. **Design partition key** for even data distribution\n7. **Use `read_item`** instead of query for single document retrieval\n\n## Reference Files\n\n| File | Contents |\n|------|----------|\n| references/partitioning.md | Partition key strategies, hierarchical keys, hot partition detection and mitigation |\n| references/query-patterns.md | Query optimization, aggregations, pagination, transactions, change feed |\n| scripts/setup_cosmos_container.py | CLI tool for creating containers with partitioning, throughput, and indexing |\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-py"
  ],
  "authored_by": "claudeskills.in community",
  "source_url": "https://claudeskills.in/skill/azure-cosmos-py",
  "provenance": {
    "source": "claudeskills.in",
    "source_url": "https://claudeskills.in/skill/azure-cosmos-py",
    "license": "unknown",
    "imported_at": "2026-09-03",
    "notes": "Aggregated by claudeskills.in from community GitHub lists."
  },
  "tags": [
    "claudeskills",
    "devops"
  ],
  "lifecycle": "draft"
}