/elasticsearch-esql

name: elasticsearch-esql
description: >
  Execute ES|QL (Elasticsearch Query Language) queries, use when the user wants to
  query Elasticsearch data, analyze logs, aggregate metrics, explore data, or create
  charts and dashboards from ES|QL results.
metadata:
  author: elastic
  version: 0.7.0
  universal: true
compatibility: Elasticsearch 8.14 or later (ES|QL GA; introduced 8.11 as tech preview),
  self-managed, Elastic Cloud Hosted, or Elastic Cloud Serverless; individual ES|QL
  features are version-gated (see references/esql-version-history.md). Requires the
  `elastic` CLI ≥ 0.2 with `stack es` support.

Elasticsearch ES|QL

Execute ES|QL queries against Elasticsearch: discover the schema, choose the right ES|QL feature for the task, generate the simplest correct query, and run it.

<!-- 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 -->

What is ES|QL?

ES|QL (Elasticsearch Query Language) is a piped query language for Elasticsearch. It is **NOT** the same as:

• Elasticsearch Query DSL (JSON-based)
• SQL
• EQL (Event Query Language)

ES|QL uses pipes (`|`) to chain commands: `FROM index | WHERE condition | STATS aggregation BY field | SORT field | LIMIT n`

> **Prerequisite:** ES|QL requires `_source` to be enabled on queried indices. Indices with `_source` disabled (e.g., > `"_source": { "enabled": false }`) will cause ES|QL queries to fail. > > **Version Compatibility:** ES|QL was introduced in 8.11 (tech preview) and became GA in 8.14. Features like > `LOOKUP JOIN` (8.18+), `MATCH` (8.17+), and `INLINE STATS` (9.2+) were added in later versions. On pre-8.18 clusters, > use `ENRICH` as a fallback for `LOOKUP JOIN` (see generation tips). `INLINE STATS` and counter-field `RATE()` have > **no fallback** before 9.2. Check [references/esql-version-history.md](references/esql-version-history.md) for feature > availability by version. > > **Cluster Detection:** Call `GET /` to determine the cluster type and version: > > - `build_flavor: "serverless"` — Elastic Cloud Serverless. `version.number` tracks the stack line under active > development (next minor from main), so clients that only semver-compare may treat Serverless as “latest.” **Do not** > use `version.number` to gate features: if `build_flavor` is `"serverless"`, assume all GA and preview ES|QL features > are available. > - `build_flavor: "default"` — Stack (self-managed or Cloud-hosted). Use `version.number` for feature availability. > - **Snapshot builds** have `version.number` like `9.4.0-SNAPSHOT`. Strip the `-SNAPSHOT` suffix and use the > major.minor for version checks. Snapshot builds include all features from that version plus potentially unreleased > features from development — if a query fails with an unknown function/command, it may simply not have landed yet. > Elastic employees commonly use snapshot builds for testing.

Process

1. **Verify the connection and detect the deployment type.** Call `GET /` first. This confirms connectivity and detects whether the deployment is a Serverless project (all features available) or a versioned cluster (features depend on version). The `build_flavor` field is the authoritative signal — if it equals `"serverless"`, ignore the reported version number and use all ES|QL features freely. If the call fails, stop and point the user at the CLI configuration instructions rather than guessing endpoints or credentials.

2. **Discover the schema (required — never guess index or field names).** List candidate indices with `GET /_cat/indices` (pass a pattern to narrow), then fetch field types for the chosen index with `GET /{index}/_mapping`.

Always run schema discovery before generating queries. Index names and field names vary across deployments and cannot be reliably guessed. Even common-sounding data (e.g., "logs") may live in indices named `logs-test`, `logs-app-*`, or `application_logs`. Field names may use ECS dotted notation (`source.ip`, `service.name`) or flat custom names — the only way to know is to check.

**Prefer simplicity:** Query a single index unless the user explicitly asks for data across multiple sources. Do not combine indices with different schemas using `COALESCE` unless specifically requested — pick the single most relevant index for the question. When multiple indices contain similar data, prefer the one with the most complete schema for the task at hand.

**Detect time series indices.** Check the index mode with `GET /{index}/_settings/index.mode`. If it is `time_series`, use `TS <data-stream>` (not `FROM`), `TBUCKET(interval)` (not `DATE_TRUNC`), and wrap counter fields with `SUM(RATE(...))`. Read the full TS section in [Generation Tips](references/generation-tips.md) before writing any time series query. For TSDS indices on 9.4+, prefer the in-language discovery commands `METRICS_INFO` and `TS_INFO` (both GA) over inspecting mappings — they enumerate the metric catalogue and the dimension labels of each time series directly, and are run as ES|QL queries via `POST /_query`. Treat `METRICS_INFO` as authoritative for `metric_type` (`counter`/`gauge`/`histogram`) and `field_type` (`histogram`, `tdigest`, `exponential_histogram` for distribution metrics). Both must follow `TS` and must precede `STATS`/`