mongodb-query-optimizer

MongoDB 查询优化器

何时调用此技能

仅当用户希望：

• 获得查询/索引优化或性能方面的帮助
• 了解查询为什么运行缓慢，或如何加快查询速度
• 了解其集群上的慢查询和/或如何优化慢查询

除非用户请求优化、慢查询或索引方面的帮助，否则不要在常规查询编写任务中调用此技能。

高层工作流

常规性能帮助

如果用户想检查慢查询，或想获取常规性能建议（不针对任何特定查询）：

• 使用 MongoDB MCP 服务的 atlas-get-performance-advisor 工具获取慢查询日志和性能顾问输出
• 基于这些信息提出建议

如果未配置 Atlas MCP Server for Atlas，或者你没有足够的信息通过 atlas-get-performance-advisor 查询正确的集群，请告知用户，常规性能分析需要配置带有 API 凭据的 Atlas MCP Server，并建议他们进行配置，或改为询问特定查询。

特定查询方面的帮助

如果用户询问某个特定查询：

• 使用 collection-indexes、explain 和 find MCP 工具，获取该集合上现有的索引、该查询的 explain() 输出以及集合中的示例文档
• 使用 atlas-get-performance-advisor MCP 工具获取慢查询日志和性能顾问输出

然后根据收集到的信息、MongoDB 最佳实践以及参考文件中的示例提出优化建议。如果可能，优先创建能完全覆盖查询的索引。如果无法使用 MongoDB MCP Server，仍应尝试提出建议。

MCP：可用工具

调用方式。 使用准确的工具名称作为 toolName，并将单个参数对象作为 arguments，调用 MongoDB MCP 服务。不要将工具名称作为选项、查询参数或嵌套键传入；应将其作为 MCP 工具名称传入，并将参数作为参数对象传入。完整的 MCP Server 工具参考：MongoDB MCP Server Tools。

数据库工具（MCP 集群连接正常时）：

工具名称（准确名称）	参数对象
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 凭据时）：

工具名称（准确名称）	参数对象
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 value	适用场景
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. 检查现有集合索引：

   • 调用 collection-indexes，参数为 database=store、collection=orders
   • 结果显示：{_id: 1}、{status: 1}、{date: -1}

2. 运行 explain：

   • 调用 explain，参数为 method=find、filter={status: 'shipped', region: 'US'}、sort={date: -1}、verbosity=queryPlanner 和 executionStats
   • 结果：使用 {status: 1} 索引，随后执行内存排序（SORT），totalKeysExamined: 50000，nReturned: 100

3. 运行 find：

   • 调用 find，并设置 limit=1，获取样本文档以推断架构。

如果已配置 MCP Atlas 连接，请执行步骤 4。否则跳到步骤 5。

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

   • 尝试从 MCP 连接字符串中获取集群名称，或向用户询问 projectId/clusterName
   • 使用 slowQueryLogs 获取过去 24 小时内 database=store、collection=orders 的慢查询日志
   • 使用 suggestedIndexes 检查该查询的索引建议

5. 诊断： 根据 explain 输出和慢查询日志，该查询需要返回 100 个文档，却扫描了 50K 个索引条目（选择性较差：0.002）。内存排序增加了开销。索引无法同时支持两个筛选字段和排序。

6. 建议： 按照 ESR 原则创建复合索引 {status: 1, region: 1, date: -1}（先放两个相等条件字段，再放排序字段）。这样可消除内存排序，并通过同时筛选 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 创建索引