elasticsearch-esql

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.

513stars39forksUpdated 6/24/2026

Data Science & ML #logs #elasticsearch #data-analysis #query-language #esql

Security Assessment

Low Risk(80/100)

Detected risks:

Agent-reviewed override(Flagged curl|sh is the official elastic.co start-local quickstart in an env-setup guide; API_KEY=/PASSWORD=/.env are connection-config docs. ES|QL query-language learning skill.)

Security Score80/100

About elasticsearch-esql

A skill for executing ES|QL (Elasticsearch Query Language) queries against Elasticsearch, intended for querying data, analyzing logs, aggregating metrics, exploring data, and building charts or dashboards from the results. ES|QL is a piped query language distinct from Query DSL, SQL, and EQL, chaining commands with `|`, for example `FROM index | WHERE condition | STATS aggregation BY field | SORT field | LIMIT n`. It requires `_source` to be enabled on queried indices; indices with `_source` disabled will cause queries to fail.

Version awareness is central. ES|QL was introduced in 8.11 (tech preview) and became GA in 8.14, with later features such as LOOKUP JOIN (8.18+), MATCH (8.17+), and INLINE STATS (9.2+) added over time; on pre-8.18 clusters ENRICH is the fallback for LOOKUP JOIN, while INLINE STATS and counter-field RATE() have no fallback before 9.2. Cluster type is detected from the `GET /` response: a `build_flavor` of `serverless` means all GA and preview features are available regardless of the reported version number, `default` means using `version.number` for feature gating, and snapshot builds (e.g. `9.4.0-SNAPSHOT`) are handled by stripping the suffix and comparing major.minor.

Queries are run through a bundled Node script: `node scripts/esql.js test` verifies the connection (and must succeed before further exploration), `indices` and `schema` discover index and field names, and `raw` executes ES|QL with optional TSV output via `--tsv`/`-t` and `--no-header`. The guidance stresses always running the connection test first, never guessing index or field names but discovering the schema, preferring a single index and a single advanced query over many basic ones, and matching user intent to the right feature—CATEGORIZE for grouping similar messages, CHANGE_POINT for spikes and anomalies, BUCKET or TS for time series, PROMQL for Prometheus-style queries (9.4+ preview), and MATCH/QSTR/KQL for search. Time-series indices use `TS`, `TBUCKET`, and `RATE`, with discovery commands METRICS_INFO and TS_INFO on 9.4+. The skill points to extensive reference files for generation tips, time-series queries, the PROMQL command, the complete ES|QL reference, and search strategy.

FAQ

What is ES|QL and how does it differ from Query DSL or SQL?

ES|QL is a piped query language for Elasticsearch that chains commands with `|`. It is not Query DSL (JSON-based), not SQL, and not EQL (Event Query Language).

Do I need to do anything before running queries?

Yes. Always run `node scripts/esql.js test` first to verify the connection and detect the deployment type, and always discover the schema with the `indices` and `schema` commands rather than guessing index or field names.

How does it handle feature availability across versions?

It detects cluster type from `GET /`. If `build_flavor` is `serverless`, all GA and preview features are assumed available; for `default` it gates features by `version.number`; snapshot builds strip the `-SNAPSHOT` suffix and compare major.minor.

Is there a fallback for LOOKUP JOIN on older clusters?

Yes. On pre-8.18 clusters, ENRICH is the documented fallback for LOOKUP JOIN. However, INLINE STATS and counter-field RATE() have no fallback before 9.2.