azure-cosmos-py

azure-cosmos-py 技能概览

azure-cosmos-py 技能帮助你用 Python 操作 Azure Cosmos DB，适合需要文档 CRUD、分区感知的容器设计、查询以及认证配置，又不想靠猜 SDK 结构来推进工作的场景。它最适合正在构建或维护数据库代码的工程师，尤其适用于 Azure 优先技术栈，以及 azure-cosmos-py for Database Engineering 这类对分区和查询成本同样敏感的使用场景。

这个技能适合做什么

当你的任务是为 Cosmos DB NoSQL API 建立可靠的 Python 集成，而不只是“让客户端连上去”，就该用 azure-cosmos-py 技能。这个仓库面向的是实际工作：安装、环境变量、认证方式、客户端层级、容器设置、分区设计和查询模式。

为什么值得安装

它的核心价值在于决策指引。这个技能会告诉你先配什么、查询里要避开什么，以及在写应用代码前该如何考虑 partition key。相比通用提示词，它在真正卡住你的是数据模型还是性能匹配，而不是语法时，明显更有用。

最适合与不适合的情况

如果你需要围绕 NoSQL API 的容器、读取、写入或查询获取 azure-cosmos-py usage 指导，这个技能非常合适。如果你想做关系型建模、批量分析，或者使用非 Python 的 SDK，它就没那么对口。若你的项目并不是 Azure Cosmos DB NoSQL，这个技能也不是正确的起点。

如何使用 azure-cosmos-py 技能

先安装，再优先查看正确的文件

在进行 azure-cosmos-py install 时，先从仓库的 skill 路径开始，然后阅读会影响实现决策的支持文件：

• SKILL.md：主流程和认证配置
• references/partitioning.md：partition key 选择
• references/query-patterns.md：查询成本与参数化
• scripts/setup_cosmos_container.py：容器创建模式

技能里给出的安装命令是：

pip install azure-cosmos azure-identity

把模糊需求变成可用提示词

当你提供的是数据库形态和操作目标，而不是只说“帮我连 Cosmos”，这个技能的效果最好。好的输入应包括：

• 容器名
• 示例 item 结构
• partition key 路径
• 目标是读、写、查询还是创建容器
• 本地开发还是生产环境认证
• 是否可以接受跨分区查询

提示词示例：
“使用 azure-cosmos-py 创建一个按 /customer_id 分区的 orders 容器，然后用 CosmosClient 给出 Python 读写示例，并编写一个参数化查询，查询同一客户分区下的所有订单。”

按照你的任务选择对应流程

做容器设置时，先看脚本和 partitioning 参考，再写应用代码。做查询时，优先使用 point reads 和参数化查询，不要临时用字符串拼接。做认证时，要尽早决定用 key、DefaultAzureCredential 还是 ManagedIdentityCredential，因为这会直接影响环境变量和初始化方式。

实用的质量提示

通常，提升最大的一步是把 partition key 和最常见的查询告诉技能。如果这两点不清楚，输出往往会很泛，甚至设计出一个成本高或不顺手的容器。还要明确你需要的是单分区读取、跨分区搜索，还是 point reads，因为这些选择会同时影响代码和成本。

azure-cosmos-py 技能常见问题

azure-cosmos-py 只适用于 Azure Cosmos DB Python SDK 吗？

是的，azure-cosmos-py 技能的重点就是 Azure Cosmos DB 的 Python SDK 和 NoSQL API。它不是通用的 Azure 数据技能，也不能拿来替代 SQL 数据库指导或其他语言的 SDK。

如果我已经会看 SDK 文档，还需要这个技能吗？

如果你已经熟悉 SDK，这个技能在需要更快做出配置决策时仍然很有用：该安装什么、在你的环境里该怎么认证、以及怎样组织查询才能获得更好的性能。它是在原始 API 之上加了一层决策引导。

它适合新手吗？

如果你的目标是一个小而明确的任务，比如创建客户端、读取文档或搭建容器，那么适合。若你跳过数据模型细节，它就没那么友好，因为 Cosmos DB 的很多决定都高度依赖分区和访问模式。

什么情况下不该用这个技能？

如果你的目标不是 Cosmos DB NoSQL，如果应用主要是关系型，或者你需要的是更广泛的架构建议而不是 Python SDK 实现，就不要用 azure-cosmos-py。如果你只是想要一段快速代码片段，而且并不关心分区或查询成本，这个技能也不是最佳选择。

如何改进 azure-cosmos-py 技能

先给出 partition key 和查询模式

对 azure-cosmos-py 来说，最有价值的改进是直接告诉它 partition key 路径和最常见的查询。这样它才能基于真实访问模式给出容器设计，而不是泛泛而谈。如果省略这些信息，得到的代码可能能跑，但性能不一定好。

明确说明认证方式和环境

要说明你的目标是本地开发、生产环境，还是两者都要。比如，直接说你想用 DefaultAzureCredential、managed identity 还是 key-based auth，并附上相关环境变量，例如 COSMOS_ENDPOINT、COSMOS_DATABASE 和 COSMOS_CONTAINER。这样可以减少来回沟通，也更容易产出可部署的结果。

直接请求具体操作形态

当你明确提出一个具体工作流时，这个技能表现最好：

• 创建带 partition key 的容器
• 插入或 upsert 文档
• 按 id 和 partition key 读取
• 执行参数化查询
• 对比单分区和跨分区方案

这比只问“Cosmos 示例”更有效，因为 SDK 指导会随着你需要 point reads、查询还是预配而变化。

用成本和正确性信号反复打磨

如果第一次输出太宽泛，就让技能围绕三件事之一进行优化：更少的 RU、代码更简单、或者查询处理更安全。比如，你可以要求“重写这段代码，避免跨分区查询”，或者“把这个字符串拼接查询改成参数化查询”。这类后续提示通常比再要一个通用示例，更能提升 azure-cosmos-py usage 的质量。