update_by_query
Modify documents in an Elasticsearch index using a query and script, handling conflicts and refresh options for controlled updates.
Instructions
Update documents in an Elasticsearch index based on a query
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| conflicts | No | What to do when version conflicts occur during the update | |
| index | Yes | Name of the Elasticsearch index to update documents in | |
| maxDocs | No | Limit the number of documents to update | |
| query | Yes | Elasticsearch query to select documents for updating | |
| refresh | No | Should the index be refreshed after the update (defaults to true) | |
| script | Yes | Script to execute on matching documents |
Implementation Reference
- src/index.ts:587-660 (handler)The primary handler function for the \"update_by_query\" tool. Constructs the params object from inputs and calls esService.updateByQuery(params), then formats the response for the MCP server.
async ({ index, query, script, conflicts, maxDocs, refresh }) => { try { // Create the params object with the correct type structure const params: Record<string, any> = { index, body: { query, script: { source: script.source, params: script.params, }, }, refresh: refresh !== false, // true by default unless explicitly set to false }; // Add optional parameters if (conflicts) params.conflicts = conflicts; if (maxDocs) params.max_docs = maxDocs; const response = await esService.updateByQuery(params); // Format the response for better readability let resultText = `Update by query completed successfully in index '${index}':\n`; resultText += `- Total documents processed: ${response.total}\n`; resultText += `- Documents updated: ${response.updated}\n`; resultText += `- Documents that failed: ${ response.failures?.length || 0 }\n`; resultText += `- Time taken: ${response.took}ms`; // Add more detailed information if there were failures if (response.failures && response.failures.length > 0) { resultText += "\n\nFailures:"; response.failures .slice(0, 5) .forEach((failure: any, index: number) => { resultText += `\n${index + 1}. ID: ${failure.id}, Reason: ${ failure.cause?.reason || "Unknown" }`; }); if (response.failures.length > 5) { resultText += `\n...and ${ response.failures.length - 5 } more failures.`; } } return { content: [ { type: "text", text: resultText, }, ], }; } catch (error) { console.error( `Update by query failed: ${ error instanceof Error ? error.message : String(error) }` ); return { content: [ { type: "text", text: `Error: ${ error instanceof Error ? error.message : String(error) }`, }, ], }; } } - src/index.ts:548-586 (schema)Zod input schema defining parameters for the update_by_query tool: index, query, script, conflicts, maxDocs, refresh.
{ index: z .string() .trim() .min(1, "Index name is required") .describe("Name of the Elasticsearch index to update documents in"), query: z .record(z.any()) .describe("Elasticsearch query to select documents for updating"), script: z .object({ source: z .string() .min(1, "Script source is required") .describe("Painless script source for the update operation"), params: z .record(z.any()) .optional() .describe("Optional parameters for the script"), }) .describe("Script to execute on matching documents"), conflicts: z .enum(["abort", "proceed"]) .optional() .describe("What to do when version conflicts occur during the update"), maxDocs: z .number() .int() .positive() .optional() .describe("Limit the number of documents to update"), refresh: z .boolean() .optional() .default(true) .describe( "Should the index be refreshed after the update (defaults to true)" ), }, - src/index.ts:545-661 (registration)Registration of the \"update_by_query\" tool on the MCP server using server.tool().
server.tool( "update_by_query", "Update documents in an Elasticsearch index based on a query", { index: z .string() .trim() .min(1, "Index name is required") .describe("Name of the Elasticsearch index to update documents in"), query: z .record(z.any()) .describe("Elasticsearch query to select documents for updating"), script: z .object({ source: z .string() .min(1, "Script source is required") .describe("Painless script source for the update operation"), params: z .record(z.any()) .optional() .describe("Optional parameters for the script"), }) .describe("Script to execute on matching documents"), conflicts: z .enum(["abort", "proceed"]) .optional() .describe("What to do when version conflicts occur during the update"), maxDocs: z .number() .int() .positive() .optional() .describe("Limit the number of documents to update"), refresh: z .boolean() .optional() .default(true) .describe( "Should the index be refreshed after the update (defaults to true)" ), }, async ({ index, query, script, conflicts, maxDocs, refresh }) => { try { // Create the params object with the correct type structure const params: Record<string, any> = { index, body: { query, script: { source: script.source, params: script.params, }, }, refresh: refresh !== false, // true by default unless explicitly set to false }; // Add optional parameters if (conflicts) params.conflicts = conflicts; if (maxDocs) params.max_docs = maxDocs; const response = await esService.updateByQuery(params); // Format the response for better readability let resultText = `Update by query completed successfully in index '${index}':\n`; resultText += `- Total documents processed: ${response.total}\n`; resultText += `- Documents updated: ${response.updated}\n`; resultText += `- Documents that failed: ${ response.failures?.length || 0 }\n`; resultText += `- Time taken: ${response.took}ms`; // Add more detailed information if there were failures if (response.failures && response.failures.length > 0) { resultText += "\n\nFailures:"; response.failures .slice(0, 5) .forEach((failure: any, index: number) => { resultText += `\n${index + 1}. ID: ${failure.id}, Reason: ${ failure.cause?.reason || "Unknown" }`; }); if (response.failures.length > 5) { resultText += `\n...and ${ response.failures.length - 5 } more failures.`; } } return { content: [ { type: "text", text: resultText, }, ], }; } catch (error) { console.error( `Update by query failed: ${ error instanceof Error ? error.message : String(error) }` ); return { content: [ { type: "text", text: `Error: ${ error instanceof Error ? error.message : String(error) }`, }, ], }; } } ); - Helper method in ElasticsearchService class that directly calls the Elasticsearch client\'s updateByQuery method.
async updateByQuery(params: any): Promise<any> { return await this.client.updateByQuery(params); } - src/types.ts:28-42 (schema)TypeScript interface defining the structure of the result from an updateByQuery operation.
export interface UpdateByQueryResult { took: number; total: number; updated: number; deleted?: number; failures?: Array<{ id?: string; cause?: { type?: string; reason?: string; }; }>; version_conflicts?: number; task?: string; }