[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-9f07315c-da90-4ebc-bcb3-a567e09331eb":3,"$f9F3ru50MnHX2xGheIAdfaTtSomDxLznntG2TvkSMndA":42},{"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":33},"9f07315c-da90-4ebc-bcb3-a567e09331eb","azure-cosmos-py","Azure Cosmos DB Python SDK（NoSQL API）。用于文档CRUD、查询、容器和全球分布式数据。","cat_coding_backend","mod_coding","sickn33,coding","---\nname: azure-cosmos-py\ndescription: Azure Cosmos DB SDK for Python (NoSQL API). Use for document CRUD, queries, containers, and globally distributed data.\nrisk: unknown\nsource: community\ndate_added: '2026-02-27'\n---\n\n# 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:\u002F\u002F\u003Caccount>.documents.azure.com:443\u002F\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:\u002F\u002F\u003Caccount>.documents.azure.com:443\u002F\"\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\u002Fitem 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=\"\u002Fcategory\")\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 \u003C @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 \u003C @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=\"\u002Fcustomer_id\")\n)\n\n# Hierarchical partition key (preview)\ncontainer = database.create_container_if_not_exists(\n    id=\"events\",\n    partition_key=PartitionKey(path=[\"\u002Ftenant_id\", \"\u002Fuser_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=\"\u002Fpk\"),\n    offer_throughput=400  # RU\u002Fs\n)\n\n# Read current throughput\noffer = container.read_offer()\nprint(f\"Throughput: {offer.offer_throughput} RU\u002Fs\")\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\u002Fpartitioning.md | Partition key strategies, hierarchical keys, hot partition detection and mitigation |\n| references\u002Fquery-patterns.md | Query optimization, aggregations, pagination, transactions, change feed |\n| scripts\u002Fsetup_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.\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,221,1197,"2026-05-16 13:06:07",{"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":25,"skillCount":32,"createdAt":26},"后端开发","backend","mdi-server","API、数据库、服务端架构",296,[34],{"id":35,"skillId":4,"version":36,"fileName":37,"fileSize":38,"filePath":39,"fileHash":40,"manifest":41,"createdAt":19},"fba760a5-869c-4325-8ee1-86b1b745da66","1.0.0","azure-cosmos-py.zip",2593,"uploads\u002Fskills\u002F9f07315c-da90-4ebc-bcb3-a567e09331eb\u002Fazure-cosmos-py.zip","a9b569e4f3e33aec9af3314e307be55c6f2f8b46cf473b662c6ffb21f4a5eff4","[{\"path\":\"SKILL.md\",\"isDirectory\":false,\"size\":7181}]",{"code":43,"message":44,"data":45},200,"success",{"items":46,"stats":47,"page":50},[],{"averageRating":48,"totalRatings":48,"ratingCounts":49},0,[48,48,48,48,48],{"limit":51,"offset":48,"hasMore":52,"nextOffset":51,"ratedOnly":16},15,false]