explain_query
Analyze MongoDB query execution plans to identify indexes used, documents examined, and execution stages. Optimize slow queries by understanding query performance and behavior.
Instructions
Get the execution plan for a query.
Helps understand:
How MongoDB will execute the query
Which indexes will be used
Number of documents examined
Execution stages and timing
Use this to optimize slow queries.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name | |
| database | No | Database name (optional if default database is configured) | |
| filter | Yes | MongoDB query filter to explain | |
| projection | No | MongoDB projection (optional) | |
| sort | No | MongoDB sort specification (optional) |
Implementation Reference
- src/index.ts:1241-1277 (handler)The handler function for the 'explain_query' tool. It constructs a MongoDB find query based on the provided filter, projection, and sort parameters, then calls .explain() to get the query execution plan, and returns it as JSON.case 'explain_query': { const { database, collection, filter, projection, sort } = request.params .arguments as { database?: string; collection: string; filter: object; projection?: object; sort?: Sort; }; const dbName = database || this.defaultDatabase; if (!dbName) { throw new McpError( ErrorCode.InvalidRequest, 'Database name is required when no default database is configured' ); } const db = client.db(dbName); let query = db.collection(collection).find(filter); if (projection) { query = query.project(projection); } if (sort) { query = query.sort(sort); } const explanation = await query.explain(); return { content: [ { type: 'text', text: JSON.stringify(explanation, null, 2), }, ], }; }
- src/index.ts:611-636 (schema)The input schema definition for the 'explain_query' tool, specifying parameters like database, collection, filter, projection, and sort with types and requirements.inputSchema: { type: 'object', properties: { database: { type: 'string', description: 'Database name (optional if default database is configured)', }, collection: { type: 'string', description: 'Collection name', }, filter: { type: 'object', description: 'MongoDB query filter to explain', }, projection: { type: 'object', description: 'MongoDB projection (optional)', }, sort: { type: 'object', description: 'MongoDB sort specification (optional)', }, }, required: ['collection', 'filter'], },
- src/index.ts:600-637 (registration)The registration of the 'explain_query' tool in the list of available tools returned by ListToolsRequestSchema, including name, description, and input schema.{ name: 'explain_query', description: `Get the execution plan for a query. Helps understand: - How MongoDB will execute the query - Which indexes will be used - Number of documents examined - Execution stages and timing Use this to optimize slow queries.`, inputSchema: { type: 'object', properties: { database: { type: 'string', description: 'Database name (optional if default database is configured)', }, collection: { type: 'string', description: 'Collection name', }, filter: { type: 'object', description: 'MongoDB query filter to explain', }, projection: { type: 'object', description: 'MongoDB projection (optional)', }, sort: { type: 'object', description: 'MongoDB sort specification (optional)', }, }, required: ['collection', 'filter'], }, },