{
  "schemaVersion": "1.0",
  "item": {
    "slug": "azure-cosmos-py",
    "name": "Azure Cosmos DB Python",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/thegovind/azure-cosmos-py",
    "canonicalUrl": "https://clawhub.ai/thegovind/azure-cosmos-py",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/azure-cosmos-py",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=azure-cosmos-py",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md",
      "references/partitioning.md",
      "references/query-patterns.md",
      "scripts/setup_cosmos_container.py"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-23T16:43:11.935Z",
      "expiresAt": "2026-04-30T16:43:11.935Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
        "contentDisposition": "attachment; filename=\"4claw-imageboard-1.0.1.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/azure-cosmos-py"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/azure-cosmos-py",
    "agentPageUrl": "https://openagent3.xyz/skills/azure-cosmos-py/agent",
    "manifestUrl": "https://openagent3.xyz/skills/azure-cosmos-py/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/azure-cosmos-py/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Azure Cosmos DB SDK for Python",
        "body": "Client library for Azure Cosmos DB NoSQL API — globally distributed, multi-model database."
      },
      {
        "title": "Installation",
        "body": "pip install azure-cosmos azure-identity"
      },
      {
        "title": "Environment Variables",
        "body": "COSMOS_ENDPOINT=https://<account>.documents.azure.com:443/\nCOSMOS_DATABASE=mydb\nCOSMOS_CONTAINER=mycontainer"
      },
      {
        "title": "Authentication",
        "body": "from 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)"
      },
      {
        "title": "Client Hierarchy",
        "body": "ClientPurposeGet FromCosmosClientAccount-level operationsDirect instantiationDatabaseProxyDatabase operationsclient.get_database_client()ContainerProxyContainer/item operationsdatabase.get_container_client()"
      },
      {
        "title": "Setup Database and Container",
        "body": "# 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\")"
      },
      {
        "title": "Create Item",
        "body": "item = {\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']}\")"
      },
      {
        "title": "Read Item",
        "body": "# Read requires id AND partition key\nitem = container.read_item(\n    item=\"item-001\",\n    partition_key=\"electronics\"\n)\nprint(f\"Name: {item['name']}\")"
      },
      {
        "title": "Update Item (Replace)",
        "body": "item = 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)"
      },
      {
        "title": "Upsert Item",
        "body": "# 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)"
      },
      {
        "title": "Delete Item",
        "body": "container.delete_item(\n    item=\"item-001\",\n    partition_key=\"electronics\"\n)"
      },
      {
        "title": "Basic Query",
        "body": "# 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']}\")"
      },
      {
        "title": "Cross-Partition Query",
        "body": "# 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)"
      },
      {
        "title": "Query with Projection",
        "body": "query = \"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)"
      },
      {
        "title": "Read All Items",
        "body": "# 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)"
      },
      {
        "title": "Partition Keys",
        "body": "Critical: Always include partition key for efficient operations.\n\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)"
      },
      {
        "title": "Throughput",
        "body": "# 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)"
      },
      {
        "title": "Async Client",
        "body": "from 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())"
      },
      {
        "title": "Error Handling",
        "body": "from 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"
      },
      {
        "title": "Best Practices",
        "body": "Always specify partition key for point reads and queries\nUse parameterized queries to prevent injection and improve caching\nAvoid cross-partition queries when possible\nUse upsert_item for idempotent writes\nUse async client for high-throughput scenarios\nDesign partition key for even data distribution\nUse read_item instead of query for single document retrieval"
      },
      {
        "title": "Reference Files",
        "body": "FileContentsreferences/partitioning.mdPartition key strategies, hierarchical keys, hot partition detection and mitigationreferences/query-patterns.mdQuery optimization, aggregations, pagination, transactions, change feedscripts/setup_cosmos_container.pyCLI tool for creating containers with partitioning, throughput, and indexing"
      }
    ],
    "body": "Azure Cosmos DB SDK for Python\n\nClient library for Azure Cosmos DB NoSQL API — globally distributed, multi-model database.\n\nInstallation\npip install azure-cosmos azure-identity\n\nEnvironment Variables\nCOSMOS_ENDPOINT=https://<account>.documents.azure.com:443/\nCOSMOS_DATABASE=mydb\nCOSMOS_CONTAINER=mycontainer\n\nAuthentication\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\nClient Hierarchy\nClient\tPurpose\tGet From\nCosmosClient\tAccount-level operations\tDirect instantiation\nDatabaseProxy\tDatabase operations\tclient.get_database_client()\nContainerProxy\tContainer/item operations\tdatabase.get_container_client()\nCore Workflow\nSetup Database and Container\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\nCreate Item\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\nRead Item\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\nUpdate Item (Replace)\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\nUpsert Item\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\nDelete Item\ncontainer.delete_item(\n    item=\"item-001\",\n    partition_key=\"electronics\"\n)\n\nQueries\nBasic Query\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\nCross-Partition Query\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\nQuery with Projection\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\nRead All Items\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\nPartition Keys\n\nCritical: Always include partition key for efficient operations.\n\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\nThroughput\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\nAsync Client\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\nError Handling\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\nBest Practices\nAlways specify partition key for point reads and queries\nUse parameterized queries to prevent injection and improve caching\nAvoid cross-partition queries when possible\nUse upsert_item for idempotent writes\nUse async client for high-throughput scenarios\nDesign partition key for even data distribution\nUse read_item instead of query for single document retrieval\nReference Files\nFile\tContents\nreferences/partitioning.md\tPartition key strategies, hierarchical keys, hot partition detection and mitigation\nreferences/query-patterns.md\tQuery optimization, aggregations, pagination, transactions, change feed\nscripts/setup_cosmos_container.py\tCLI tool for creating containers with partitioning, throughput, and indexing"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/thegovind/azure-cosmos-py",
    "publisherUrl": "https://clawhub.ai/thegovind/azure-cosmos-py",
    "owner": "thegovind",
    "version": "0.1.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/azure-cosmos-py",
    "downloadUrl": "https://openagent3.xyz/downloads/azure-cosmos-py",
    "agentUrl": "https://openagent3.xyz/skills/azure-cosmos-py/agent",
    "manifestUrl": "https://openagent3.xyz/skills/azure-cosmos-py/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/azure-cosmos-py/agent.md"
  }
}