# Elasticsearch Query Optimization

Diagnose slow Elasticsearch Query DSL searches and propose measured fixes.

- Repository: https://github.com/elastic/agent-skills (603 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-10-29
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add elastic/agent-skills --skill elasticsearch-query-optimization -g -a claude-code -y`
Codex: `npx skills add elastic/agent-skills --skill elasticsearch-query-optimization -g -a codex -y`
Cursor: `npx skills add elastic/agent-skills --skill elasticsearch-query-optimization -g -a cursor -y`
Gemini CLI: `npx skills add elastic/agent-skills --skill elasticsearch-query-optimization -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add elastic/agent-skills`

## Description

Diagnose slow Elasticsearch Query DSL searches and propose measured fixes. Use when a search is slow, profile output shows an expensive clause, exact-match filters sit in scoring context, or leading wildcards dominate latency. Ground every recommendation in search profiling, move non-scoring clauses to filter context, eliminate leading wildcards, and re-profile to confirm improvement.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Elasticsearch Query DSL Optimization

Diagnose why a Query DSL search is slow, identify the dominant cost from the profile (not guesswork), rewrite the query
to remove that cost while preserving match semantics, and re-measure with profiling enabled.

<!-- begin-partial: preamble -->

## Environment Configuration

This skill executes Elasticsearch operations through the `elastic` CLI. If the
[`elastic` CLI](https://github.com/elastic/cli#configuration) is not installed, tell the user what it is needed for. Do
not guess credentials, call the HTTP API directly, or attempt other workarounds.

This skill references operations in HTTP-shorthand form (e.g., `GET /`, `GET /_cat/indices`, `GET /{index}/_mapping`,
`GET /{index}/_settings/index.mode`, `POST /_query`). The [Operations](#operations) table at the end of this document
maps each shorthand to the equivalent `elastic` CLI command, always use the CLI rather than calling the HTTP API
directly.

<!-- end-partial: preamble -->

> **Scope:** Query DSL searches via `POST /{index}/_search`. This skill does not migrate queries to ES|QL, it optimizes
> the existing bool/match/term/wildcard structure the user already runs.
>
> **Ground rule:** Never recommend "add shards" or "scale hardware" as the primary fix when the profile names a specific
> clause (for example `WildcardQuery` at ~3.8s). Fix the query first; infrastructure changes require evidence the query
> is already optimal.

## Process

1. **Confirm connectivity and locate the target index.** Call `GET /`. If the call fails, stop, do not guess endpoints
   or credentials. When the user names an index pattern (for example `logs-*`), narrow candidates with
   `GET /_cat/indices` and pick the index or pattern the query actually targets.

   **Decision:** proceed only when the index is known. **Data needed:** index name or pattern, and the slow Query DSL
   body (from the user or from a saved search).

The rest: https://github.com/elastic/agent-skills/blob/HEAD/plugins/elasticsearch/skills/elasticsearch-query-optimization/SKILL.md