mongodb-query-optimizer

MongoDB 查詢最佳化工具

何時呼叫此技能

僅在使用者想要以下內容時呼叫：

• 查詢/索引的最佳化或效能協助
• 查詢為何很慢或如何加速
• 叢集上的慢查詢及/或如何最佳化它們

除非使用者要求最佳化、慢查詢或索引協助，否則不要為例行查詢撰寫而呼叫。

高階工作流程

一般效能協助

如果使用者想要檢查慢查詢，或尋找一般效能建議（非針對特定查詢）：

• 使用 MongoDB MCP 伺服器的 atlas-get-performance-advisor 工具來擷取慢查詢日誌與效能顧問輸出
• 根據這些資訊提出建議

如果 Atlas MCP 伺服器未設定，或你沒有足夠資訊對正確叢集執行 atlas-get-performance-advisor，請告知使用者一般效能分析需要設定 Atlas MCP 伺服器並提供 API 憑證，並建議他們設定或改為詢問特定查詢。

特定查詢協助

如果使用者詢問特定查詢：

• 使用 collection-indexes、explain 和 find MCP 工具來取得集合的現有索引、查詢的 explain() 輸出以及集合中的一份樣本文件
• 使用 atlas-get-performance-advisor MCP 工具來擷取慢查詢日誌與效能顧問輸出

然後根據收集到的資訊以及參考檔案中的 MongoDB 最佳實務與範例，提出最佳化建議。如果可能，優先建立能完全涵蓋查詢的索引。如果無法使用 MongoDB MCP 伺服器，仍應嘗試提出建議。

MCP：可用工具

如何呼叫。 以確切的工具名稱作為 toolName，並以單一 arguments 物件作為 arguments 來呼叫 MongoDB MCP 伺服器。不要將工具名稱作為選項、查詢參數或巢狀鍵傳遞；請將其作為 MCP 工具名稱，並將參數作為 arguments 物件傳遞。完整的 MCP 伺服器工具參考：MongoDB MCP Server Tools。

資料庫工具（當 MCP 叢集連線正常時）：

工具名稱（確切）	Arguments 物件
collection-indexes	{ "database": "<db>", "collection": "<coll>" } — 兩者皆為必要字串。
explain	{ "database": "<db>", "collection": "<coll>", "method": [ { "name": "find", "arguments": { "filter": {...}, "sort": {...}, "limit": N } } ], "verbosity": "executionStats" }。method 是包含一個物件的陣列：name 為 "find"、"aggregate" 或 "count"；arguments 存放該方法的參數（例如 find：filter、sort、limit；aggregate：pipeline；count：query）。可選的 verbosity："queryPlanner"（預設）、"executionStats"、"queryPlannerExtended"、"allPlansExecution"。
find	{ "database": "<db>", "collection": "<coll>", "filter": {...}, "projection": {...}, "sort": {...}, "limit": N } — database、collection 和 filter 為必要。可選：projection、sort、limit。

Atlas 工具（當 Atlas API 憑證已設定時）：

工具名稱（確切）	Arguments 物件
atlas-list-projects	{} 或 { "orgId": "<24-char hex>" }。回傳專案及其 ID；用於取得 Performance Advisor 所需的 projectId。
atlas-get-performance-advisor	必要： "projectId"（24 字元十六進位字串）、"clusterName"（字串，1–64 字元，英數字/底線/連字號）。可選： "operations" — 字串陣列，可包含 "suggestedIndexes"、"dropIndexSuggestions"、"slowQueryLogs"、"schemaSuggestions"（僅請求你需要的）；僅用於 slowQueryLogs："since"（ISO 8601 日期時間）、"namespaces"（"db.coll" 字串的陣列）。

針對使用者的問題，嘗試從連線字串和 Atlas API 兩方面取得與你要最佳化的查詢相關的資訊。

1. DB 連線字串適用於 MongoDB MCP

典型流程：呼叫 collection-indexes → explain → find（樣本文件）。

• collection-indexes — 使用結果中的 classicIndexes（每個有 name、key）來檢查查詢是否已可使用現有索引。
• explain — 先以 "queryPlanner" 模式執行以檢查 COLLSCAN。如果查詢使用了索引或集合非常小，再以 "executionStats"（10 秒逾時）執行以取得掃描與回傳的文件數。

2. Atlas API 存取適用於 MongoDB MCP

如果你需要專案 ID，先呼叫 atlas-list-projects。然後呼叫 atlas-get-performance-advisor，僅包含你需要的 operations：

Operation 值	使用時機
slowQueryLogs	擷取慢查詢—優先處理最慢且最頻繁的。可選：namespaces 以限定集合範圍；since 指定時間視窗。
suggestedIndexes	擷取叢集索引建議
dropIndexSuggestions	使用者詢問要移除或減少索引開銷時
schemaSuggestions	使用者詢問與索引相關的綱要/查詢結構建議時

不要將 MCP 工具名稱作為 operations 值傳遞—operations 是列出要擷取哪些資料的獨立參數。

範例工作流程 1（特定查詢協助）

使用者：「為什麼這個查詢很慢？db.orders.find({status: 'shipped', region: 'US'}).sort({date: -1})」

如果 MCP 資料庫連線已設定且資料庫與集合名稱已知，執行步驟 1–3。否則跳到步驟 4。

1. 檢查現有集合索引：

   • 以 database=store、collection=orders 呼叫 collection-indexes
   • 結果顯示：{_id: 1}、{status: 1}、{date: -1}

2. 執行 explain：

   • 以 method=find、filter={status: 'shipped', region: 'US'}、sort={date: -1}、verbosity=queryPlanner 和 executionStats 呼叫 explain
   • 結果：使用 {status: 1} 索引，然後進行記憶體內排序，totalKeysExamined: 50000、nReturned: 100

3. 執行 find：

   • 以 limit=1 呼叫 find 來擷取一份樣本文件以推斷綱要。

如果 MCP Atlas 連線已設定，執行步驟 4。否則跳到步驟 5。

4. 執行 atlas-get-performance-advisor：

   • 嘗試從 MCP 連線字串取得叢集名稱，或詢問使用者 projectId/clusterName
   • 使用 slowQueryLogs 從 database=store、collection=orders 擷取過去 24 小時的慢查詢日誌
   • 使用 suggestedIndexes 檢查該查詢的索引建議

5. 診斷： 根據 explain 輸出和慢查詢日誌，此查詢目標為 100 份文件，但掃描了 50K 個索引條目（選擇性差：0.002）。記憶體內排序增加了開銷。索引不支援兩個篩選欄位或排序。

6. 建議： 建立複合索引 {status: 1, region: 1, date: -1}，遵循 ESR（兩個等值欄位，然後排序）。這消除了記憶體內排序，並透過同時篩選 status 和 region 來改善選擇性。

如果 MongoDB MCP 伺服器未設定，請遵循最佳索引實務。

範例工作流程 2（一般資料庫效能協助）

使用者：「可以幫我最佳化叢集上的慢查詢嗎？」

1. 執行 atlas-get-performance-advisor：
   • 嘗試從連線字串取得叢集名稱，並推斷 atlas-list-projects 中所需的專案名稱；如果不確定，則詢問使用者叢集名稱和專案 ID。
   • 使用 slowQueryLogs 擷取過去 24 小時的慢查詢日誌
   • 使用 suggestedIndexes
   • 使用 dropIndexSuggestions
   • 使用 schemaSuggestions
2. 診斷與建議： 根據慢查詢日誌和效能顧問建議，你可以在 db.orders 集合上建立複合索引 {status: 1, region: 1, date: -1}，以最佳化如 find({status: 'shipped', region: 'US'}).sort({date: -1}) 的查詢。

檢查所有效能顧問輸出以及慢查詢日誌。提供正在改善的內容及其原因，並專注於可能產生最大影響的建議（例如，影響最多查詢的索引，或效能最差的查詢）。

載入參考資料

在開始診斷與建議之前，載入參考檔案。

總是載入：

• references/core-indexing-principles.md
• references/antipattern-examples.md

條件式載入以下檔案：

• 如果正在診斷聚合管線 → references/aggregation-optimization.md
• 如果正在診斷會變更文件的查詢，例如 replaceOne、findOneAndUpdate 等 → references/update-query-examples.md，以取得 oplog 有效率的更新和常見更新反模式

輸出

• 保持答案簡短清晰：幾句話說明索引和最佳化建議，以及背後的理由（例如一般索引原則、觀察叢集中的慢查詢日誌，或在 Performance Advisor 中看到的建議）
• 專注於影響最大的索引或最佳化—如果你省略了一些最佳化，請告知使用者，並在使用者詢問時提出。
• 不要使用強烈語氣，例如說「你應該建立這些索引，它們一定會改善應用程式效能」—請說明這些是針對某些查詢的建議，並給出背後的理由。
• 考慮集合上已存在的索引數量（如果已知）—通常不應超過 20 個
• 僅在建議來自 Atlas Performance Advisor 時才建議移除索引
• 除非使用者同意，否則不要直接透過 MCP 建立索引