exploreFieldValues
Analyze and retrieve possible values for a specific field within an OpenSearch index, with options to filter results and limit the number of returned values.
Instructions
Explore possible values for a field in an index
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| field | Yes | Field name to explore | |
| index | Yes | Index pattern to search | |
| maxValues | No | Maximum number of values to return | |
| query | No | Optional query to filter documents | * |
Implementation Reference
- index.js:316-370 (handler)The execute handler function for the exploreFieldValues tool. Performs an OpenSearch aggregation (terms) on the specified field to retrieve top values, counts, and percentages.execute: async (args, { log }) => { log.info("Exploring field values", { index: args.index, field: args.field, query: args.query }); return safeOpenSearchQuery(async () => { const response = await client.search({ index: args.index, body: { size: 0, query: { query_string: { query: args.query } }, aggs: { field_values: { terms: { field: args.field, size: args.maxValues } } }, timeout: "25s" } }); const buckets = response.body.aggregations?.field_values?.buckets || []; const total = response.body.hits.total?.value || 0; if (buckets.length === 0) { return `No values found for field "${args.field}" in index ${args.index}.\n\nPossible reasons:\n- The field does not exist\n- The field is not indexed for aggregations\n- No documents match your query\n- The field has no values`; } let resultText = `## Values for field "${args.field}" in ${args.index}\n\n`; resultText += `Found ${total} matching documents. Top ${buckets.length} values:\n\n`; // Calculate percentage of total for each value let totalCount = buckets.reduce((sum, bucket) => sum + bucket.doc_count, 0); // Format results as a table resultText += "| Value | Count | Percentage |\n"; resultText += "|-------|-------|------------|\n"; buckets.forEach(bucket => { const percentage = ((bucket.doc_count / totalCount) * 100).toFixed(2); resultText += `| ${bucket.key} | ${bucket.doc_count} | ${percentage}% |\n`; }); return resultText; }, `Failed to explore values for field "${args.field}" in index ${args.index}.`); }, });
- index.js:310-315 (schema)Zod schema defining input parameters for the exploreFieldValues tool: index, field, query, maxValues.parameters: z.object({ index: z.string().describe("Index pattern to search"), field: z.string().describe("Field name to explore"), query: z.string().default("*").describe("Optional query to filter documents"), maxValues: z.number().default(20).describe("Maximum number of values to return"), }),
- index.js:307-307 (registration)Initial registration of the exploreFieldValues tool with name and description.server.addTool({
- index.js:62-86 (helper)Helper function used by exploreFieldValues (and other tools) to safely execute OpenSearch queries with error handling and user-friendly messages.async function safeOpenSearchQuery(operation, fallbackMessage) { try { debugLog('Executing OpenSearch query'); const result = await operation(); debugLog('OpenSearch query completed successfully'); return result; } catch (error) { console.error(`OpenSearch error: ${error.message}`, error); debugLog('OpenSearch query failed:', error); // Check for common OpenSearch errors if (error.message.includes('timeout')) { throw new UserError(`OpenSearch request timed out. The query may be too complex or the cluster is under heavy load.`); } else if (error.message.includes('connect')) { throw new UserError(`Cannot connect to OpenSearch. Please check your connection settings in .env file.`); } else if (error.message.includes('no such index')) { throw new UserError(`The specified index doesn't exist in OpenSearch.`); } else if (error.message.includes('unauthorized')) { throw new UserError(`Authentication failed with OpenSearch. Please check your credentials in .env file.`); } // For any other errors throw new UserError(fallbackMessage || `OpenSearch operation failed: ${error.message}`); } }