{"id":"2cd96362-1157-4370-b64a-4230f4aa9ee2","shortId":"YZ9XkL","kind":"skill","title":"azure-cosmos-py","tagline":"Azure Cosmos DB SDK for Python (NoSQL API). Use for document CRUD, queries, containers, and globally distributed data.","description":"# 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.\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.","tags":["azure","cosmos","antigravity","awesome","skills","sickn33","agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows"],"capabilities":["skill","source-sickn33","skill-azure-cosmos-py","topic-agent-skills","topic-agentic-skills","topic-ai-agent-skills","topic-ai-agents","topic-ai-coding","topic-ai-workflows","topic-antigravity","topic-antigravity-skills","topic-claude-code","topic-claude-code-skills","topic-codex-cli","topic-codex-skills"],"categories":["antigravity-awesome-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/sickn33/antigravity-awesome-skills/azure-cosmos-py","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add sickn33/antigravity-awesome-skills","source_repo":"https://github.com/sickn33/antigravity-awesome-skills","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 34928 github stars · SKILL.md body (6,958 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-24T18:50:29.874Z","embedding":null,"createdAt":"2026-04-18T21:32:18.616Z","updatedAt":"2026-04-24T18:50:29.874Z","lastSeenAt":"2026-04-24T18:50:29.874Z","tsv":"'-001':167,208,226,277 '-002':258 '/category':148 '/customer_id':451 '/pk':489 '/tenant_id':468 '/user_id':469 '1':553,562,637 '1000':511 '2':647 '3':657 '4':665 '400':492 '404':610 '429':618 '499.99':264 '5':672 '500':308,352 '6':681 '7':689 '899.99':232 '999.99':180 'account':93 'account-level':92 'action':746 'aggreg':718 'alway':424,638 'api':12,36 'applic':740 'ask':784 'async':512,523,529,567,674 'asyncio':583 'asyncio.run':584 'authent':65 'avoid':658 'await':548,558 'azur':2,5,23,32,48,51 'azure-cosmo':47 'azure-cosmos-pi':1 'azure-ident':50 'azure.cosmos':72,433 'azure.cosmos.aio':516 'azure.cosmos.exceptions':591 'azure.identity':68 'azure.identity.aio':520 'bash':44,55 'basic':282 'best':635 'bodi':187,243,268,551 'boundari':792 'c':293,337,374,417,576 'c.category':376 'c.id':370 'c.name':371 'c.price':295,339,372 'cach':656 'categori':172,259,377,385 'chang':721 'clarif':786 'clear':759 'cli':724 'client':29,79,85,87,103,109,154,159,513,536,540,545,675 'client.create':122 'client.get':101,152,538 'code':609,617 'comput':182 'contain':18,63,108,115,132,136,138,156,158,439,441,456,458,473,477,479,542,544,728 'container.create':185,549 'container.delete':273 'container.query':299,343,379,412,571 'container.read':204,222,401,498,559,596 'container.replace':238,508 'container.upsert':266 'container/item':105 'containerproxi':104 'content':703 'core':110 'cosmos':3,6,24,33,49,56,59,62,525,585 'cosmoscli':74,80,91,518,531 'cosmoshttpresponseerror':593,604 'creat':119,131,161,184,191,192,248,472,547,727 'credenti':75,83,84,527,533,534 'criteria':795 'critic':423 'cross':323,328,354,405,660 'cross-partit':322,327,404,659 'crud':16 'current':495 'data':22,687 'databas':42,60,99,102,113,120,121,123,151,153,537,539 'database.create':137,440,457,478 'database.get':107,157,543 'databaseproxi':98 'db':7,25,34 'def':524 'defaultazurecredenti':70,76,522,528 'delet':270 'describ':747,763 'design':682 'detect':712 'direct':96 'distribut':21,38,688 'document':15,698 'documents.azure.com:443':58,78 'e':606 'e.headers.get':625 'e.status':608,616 'effici':289,429 'electron':173,211,229,260,280,311,387,390,420 'elif':615 'els':633 'enabl':353 'endpoint':57,77,82,532 'environ':53,775 'environment-specif':774 'error':587 'even':686 'event':463 'except':603 'execut':742 'exist':126,141,150,251,254,444,461,482 'expens':331 'expert':780 'f':190,213,317,501,620 'feed':722 'file':701,702 'found':614 'get':89,117,129,149 'global':20,37 'handl':588 'hierarch':452,708 'hierarchi':86 'high':678 'high-throughput':677 'hot':710 'id':127,142,165,193,199,242,256,445,462,483,552 'idempot':670 'ident':52 'import':69,73,434,517,521,582,592 'improv':655 'includ':425 'index':733 'inject':653 'input':789 'instal':43,46 'instanti':97 'instead':693 'item':162,164,166,186,188,195,203,205,206,207,215,218,221,223,224,225,230,233,239,240,241,244,246,255,257,267,269,271,274,275,276,298,300,313,315,318,320,342,344,359,361,363,378,380,393,400,403,411,413,550,557,560,561,569,572,581,595,597,598,612,668,692 'key':135,145,175,202,210,228,279,310,389,410,419,422,427,438,448,454,465,486,564,578,601,641,684,706,709 'laptop':178 'level':94 'librari':30 'limit':622,751 'match':760 'max':296,305,340,349 'miss':797 'mitig':714 'model':41 'ms':628,631,632 'multi':40 'multi-model':39 'mycontain':64,143,160,484,546 'mydb':61,128,155,541 'name':177,214,216,261,304,319,348,384 'nonexist':599 'nosql':11,35 'offer':490,497,499 'offer.offer':503 'oper':95,100,106,430,526,586 'optim':717 'order':446 'output':769 'overview':750 'pagin':719 'paramet':303,347,383 'parameter':649 'partit':134,144,171,174,201,209,227,278,288,309,324,329,355,388,399,406,409,418,421,426,437,447,453,464,485,563,577,600,640,661,683,705,711,730 'partitionkey':146,435,449,466,487 'path':147,450,467,488 'permiss':790 'pip':45 'pk':554,602 'point':643 'portabl':183 'possibl':664 'practic':636 'prevent':652 'preview':455 'price':179,231,263,297,306,321,341,350 'print':189,212,316,362,500,580,611,619 'project':366 'provis':475 'purpos':88 'py':4 'python':10,28,66,116,163,196,220,247,272,284,326,367,394,431,471,514,589 'queri':17,281,283,285,290,301,302,325,334,345,346,356,364,368,381,382,414,566,573,646,650,662,695,716 'rais':634 'rate':621 'read':194,197,391,395,494,556,644,691 'refer':700 'references/partitioning.md':704 'references/query-patterns.md':715 'replac':219,252 'requir':168,198,788 'result':265 'retri':623,629 'retriev':699 'review':781 'ru/s':493,505 'safeti':791 'sale':235 'scenario':680 'scope':762 'scripts/setup_cosmos_container.py':723 'sdk':8,26 'select':291,335,369,415,574 'setup':112 'singl':436,697 'skill':738,754 'skill-azure-cosmos-py' 'source-sickn33' 'spare':333 'specif':776 'specifi':639 'stop':782 'strategi':707 'substitut':772 'success':794 'tablet':262 'tag':181 'task':758 'test':555,565,579,778 'throughput':470,476,491,496,502,504,507,509,510,679,731 'tool':725 'topic-agent-skills' 'topic-agentic-skills' 'topic-ai-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-ai-workflows' 'topic-antigravity' 'topic-antigravity-skills' 'topic-claude-code' 'topic-claude-code-skills' 'topic-codex-cli' 'topic-codex-skills' 'transact':720 'treat':767 'tri':594 'true':236,357 'uniqu':169 'updat':217,237,506 'upsert':245,667 'url':81 'use':13,332,648,666,673,690,736,752 'valid':777 'valu':176,307,351,386 'variabl':54 'within':170,286 'workflow':111,744 'write':671 'x':627 'x-ms-retry-after-m':626","prices":[{"id":"d4b8b29b-c80c-4d5b-8979-45c0f22a4e29","listingId":"2cd96362-1157-4370-b64a-4230f4aa9ee2","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"sickn33","category":"antigravity-awesome-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T21:32:18.616Z"}],"sources":[{"listingId":"2cd96362-1157-4370-b64a-4230f4aa9ee2","source":"github","sourceId":"sickn33/antigravity-awesome-skills/azure-cosmos-py","sourceUrl":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/azure-cosmos-py","isPrimary":false,"firstSeenAt":"2026-04-18T21:32:18.616Z","lastSeenAt":"2026-04-24T18:50:29.874Z"}],"details":{"listingId":"2cd96362-1157-4370-b64a-4230f4aa9ee2","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"sickn33","slug":"azure-cosmos-py","github":{"repo":"sickn33/antigravity-awesome-skills","stars":34928,"topics":["agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows","antigravity","antigravity-skills","claude-code","claude-code-skills","codex-cli","codex-skills","cursor","cursor-skills","developer-tools","gemini-cli","gemini-skills","kiro","mcp","skill-library"],"license":"mit","html_url":"https://github.com/sickn33/antigravity-awesome-skills","pushed_at":"2026-04-24T06:41:17Z","description":"Installable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.","skill_md_sha":"4f775672ad19d25006de5507654c6fcd4fb3a817","skill_md_path":"skills/azure-cosmos-py/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/azure-cosmos-py"},"layout":"multi","source":"github","category":"antigravity-awesome-skills","frontmatter":{"name":"azure-cosmos-py","description":"Azure Cosmos DB SDK for Python (NoSQL API). Use for document CRUD, queries, containers, and globally distributed data."},"skills_sh_url":"https://skills.sh/sickn33/antigravity-awesome-skills/azure-cosmos-py"},"updatedAt":"2026-04-24T18:50:29.874Z"}}