azure-cosmos-py

azure-cosmos-py 技能總覽

azure-cosmos-py 技能可協助你用 Python 連接 Azure Cosmos DB，處理文件 CRUD、分割區感知的容器設計、查詢，以及驗證設定，而不用靠猜 SDK 的使用方式。它特別適合正在建置或維護資料庫程式碼的工程師，尤其是 Azure-first 技術棧，以及重視分割與查詢成本、屬於 azure-cosmos-py for Database Engineering 的情境。

這個 azure-cosmos-py 技能適合做什麼

當你的工作是為 Cosmos DB NoSQL API 建立穩定的 Python 整合，而不只是「讓 client 連得上」時，就該用 azure-cosmos-py 技能。這個 repo 的設計偏向實務任務：安裝、環境變數、驗證選擇、client 階層、容器設定、分割，以及查詢模式。

為什麼值得安裝 azure-cosmos-py

它最大的價值在於決策指引。這個技能會告訴你先設定什麼、查詢時要避開什麼，以及在寫應用程式之前該怎麼思考 partition key。當真正的卡點是資料模型或效能適配，而不是語法時，它比通用提示更有幫助。

最適合與不適合的情境

如果你需要 azure-cosmos-py usage 指引，處理 NoSQL API 的容器、讀取、寫入或查詢，這個技能很適合。若你要的是關聯式建模、大量分析，或非 Python 的 SDK，它就不那麼合適。如果你的專案不是 Azure Cosmos DB NoSQL，這個技能就不是正確的起點。

如何使用 azure-cosmos-py 技能

先安裝並檢查對的檔案

進行 azure-cosmos-py install 時，先從 repo 的 skill 路徑開始，接著閱讀會影響實作決策的支援檔案：

• SKILL.md：主流程與驗證設定
• references/partitioning.md：partition key 的選擇
• references/query-patterns.md：查詢成本與參數化
• scripts/setup_cosmos_container.py：容器建立模式

技能中顯示的安裝指令是：

pip install azure-cosmos azure-identity

把粗略需求改寫成可用的提示

這個技能在你提供資料庫形狀與操作目標時最有效，而不是只說「幫我處理 Cosmos」。好的輸入應該包含：

• container name
• item 範例結構
• partition key path
• 目標是 read、write、query 還是 container creation
• 本機開發還是 production auth
• 是否接受 cross-partition query

提示範例：
「用 azure-cosmos-py 建立一個以 /customer_id 分割的 orders 容器，然後示範用 CosmosClient 做 Python 讀寫，以及查詢同一個 customer partition 內的所有 orders，並使用參數化查詢。」

使用符合任務的工作流程

做容器設定時，先照腳本與 partitioning reference 走，再寫應用程式碼。處理查詢時，優先使用 point reads 和 parameterized queries，不要用臨時的字串拼接。處理 auth 時，要先決定是用 key、DefaultAzureCredential 還是 ManagedIdentityCredential，因為這會改變設定方式與環境變數。

實務上的品質建議

通常品質提升最大的地方，是把 partition key 和最常用的查詢一開始就提供給技能。如果這兩個資訊不清楚，輸出就容易變得很泛，最後可能做出成本高或容器設計彆扭的結果。另外，也要說明你需要的是單一 partition 讀取、cross-partition 搜尋，還是 point reads，因為這些選擇都會影響程式碼與成本。

azure-cosmos-py 技能 FAQ

azure-cosmos-py 只是 Azure Cosmos DB Python SDK 用途嗎？

是的，azure-cosmos-py 技能的重心就是 Azure Cosmos DB 的 Python SDK 與 NoSQL API。它不是通用的 Azure 資料技能，也不應拿來取代 SQL 資料庫指引或其他語言的 SDK。

如果我已經熟悉 SDK 文件，還需要這個技能嗎？

如果你已經很熟 SDK，當你需要更快做出設定決策時，這個技能仍然有價值：要安裝什麼、在你的環境中如何驗證、以及如何組織查詢才能有更好的效能。它是在原始 API 表面之外，多加了一層導引。

這個技能適合初學者嗎？

如果你的目標只是像建立 client、讀取文件、或設定容器這類小而具體的任務，那它很適合。若你直接跳過資料模型細節，它就沒那麼友善，因為 Cosmos DB 的決策很依賴 partitioning 與存取模式。

什麼情況下不該用這個技能？

如果你不是要做 Cosmos DB NoSQL、你的應用程式主要是關聯式、或你需要的是更廣泛的架構建議而不是 Python SDK 實作，就不要用 azure-cosmos-py。如果你只是想要一段快速範例，且不在意 partitioning 或 query cost，它也不是最佳選擇。

如何改進 azure-cosmos-py 技能

先提供 partition key 和查詢模式

對 azure-cosmos-py 來說，最有價值的改進，是先告訴它 partition key path 和最常見的查詢。這樣它就能建議真正符合存取模式的容器設計，而不是套用泛用模板。如果你省略這些資訊，可能會得到一份可用但效能不佳的程式碼。

明確說明 auth 與環境

要清楚指出目標是本機開發、production，還是兩者都要。例如，說明你想用 DefaultAzureCredential、managed identity，或 key-based auth，並帶上相關環境變數，例如 COSMOS_ENDPOINT、COSMOS_DATABASE 和 COSMOS_CONTAINER。這能減少來回溝通，也更容易產出可部署的結果。

直接要求精確的操作形式

當你指定明確的工作流程時，這個技能表現最好：

• 建立帶 partition key 的容器
• 插入或 upsert 文件
• 根據 id 與 partition key 讀取
• 執行 parameterized query
• 比較 single-partition 與 cross-partition 選項

這比直接問「Cosmos 範例」更有效，因為 SDK 指引會依照你需要的是 point reads、查詢，還是 provisioning 而改變。

用成本與正確性訊號持續調整

如果第一次輸出太寬泛，可以要求技能優先優化三件事中的一項：更少的 RU、更簡單的程式碼，或更安全的查詢處理。例如，直接要求「改寫這段以避免 cross-partition queries」或「把這個字串拼接查詢改成 parameterized query」。這類後續提示，通常比再要一個泛用範例更能改善 azure-cosmos-py usage。