ES|QL is Elasticsearch's piped query language, available since version 8.11 in technical preview and reaching general availability in 8.17. It uses a dedicated compute engine separate from the traditional Query DSL execution path. Queries flow through a pipeline of commands where each command transforms the output of the previous one. This design introduces a distinct set of errors that differ from what you encounter with standard Query DSL.
The basic command structure follows a pipe-separated pattern: FROM index | WHERE condition | STATS agg BY field | SORT field | LIMIT n. The EVAL command creates computed columns. All queries run through the _query API endpoint: POST /_query with the query in the request body.
Syntax and Parsing Errors
ES|QL parsing errors surface as parsing_exception with a line and column number pointing to the problem. Common triggers include missing pipe separators between commands, using SQL-style syntax, and referencing commands in the wrong order. The FROM command must always come first. A frequent mistake is writing FROM index WHERE x > 5 without the pipe - the correct form is FROM index | WHERE x > 5.
Function name typos produce errors like "Unknown function [COUN]" rather than silently failing. Field names that conflict with reserved words need backtick escaping. If a field is named from or limit, reference it as `from` or `limit`.
String literals must use double quotes, not single quotes. Writing WHERE status = 'active' will fail - use WHERE status == "active" instead. Note the double equals for comparison, which differs from Query DSL filter syntax.
Unsupported Types, Nested Fields, and Type Mismatches
ES|QL does not support all Elasticsearch field types. Referencing an unsupported type produces a verification_exception. Fields of type nested, join, flattened (prior to 8.18), and some specialized types cannot be used directly. Columns with unsupported types that are not explicitly referenced return null values - a FROM index | LIMIT 10 query shows nulls for those columns rather than failing. The error only triggers when you filter, sort, or aggregate on such a field. Nested fields are a special case: they are excluded from results entirely rather than returned as nulls. ES|QL has no mechanism to query or unnest nested documents.
ES|QL has strict type requirements within expressions. Comparing a keyword field to an integer produces a verification_exception like "first argument of [>] is [keyword] so second argument must also be [keyword]". Use explicit conversion functions: TO_INTEGER, TO_LONG, TO_DOUBLE, TO_STRING, TO_DATETIME. When a conversion fails at runtime - for example, TO_INTEGER("not_a_number") - ES|QL returns null for that row and adds a warning to the response headers rather than throwing an error.
Date parsing is strict. TO_DATETIME only accepts yyyy-MM-dd'T'HH:mm:ss.SSS'Z' format. For other formats, use the DATE_PARSE function with an explicit format string.
Memory Limits and STATS Aggregations
The ES|QL compute engine runs with its own memory budget, separate from the request circuit breaker used by Query DSL. Large STATS aggregations on high-cardinality fields can exceed this budget. The engine holds grouping keys and partial aggregation state in memory across all nodes participating in the query.
Queries without filters are the usual culprit. A query like FROM logs-* | STATS count = COUNT(*) BY user_id across billions of documents with millions of distinct users will hit memory limits. Add WHERE clauses to narrow the data before aggregation, or use time-based filtering to process smaller windows.
The default row limit is 10,000. Setting LIMIT higher has no effect unless you increase the esql.query.result_truncation_max_size cluster setting. For bulk data export, use PIT with search_after instead. A known bug in versions 8.16.0 through 8.17.8 caused incorrect results in STATS with exactly two keyword grouping fields where the first had more than 65,000 distinct values. This was fixed in 8.17.9 and 8.18.7.
ENRICH Command and Its Requirements
The ENRICH command joins data from enrich indices into your query results. It supports three policy types: match (exact keyword match), range (numeric, date, or IP ranges), and geo_match (spatial intersection). Before using ENRICH, you must create and execute an enrich policy through the standard Elasticsearch enrich APIs - ES|QL cannot create policies inline. The match field must be type-compatible: geo_match requires geo_point or geo_shape, range needs integer, long, date, or ip fields. keyword fields are accepted for range policies but incur a performance penalty as values are parsed row by row.
Enrich indices are pre-built lookup tables stored on every node. If your enrich source data changes, re-execute the policy to rebuild the enrich index. Stale enrich data produces correct queries with wrong results. The geo_match type only supports the intersects spatial relation - contains, within, and disjoint are not available.
Performance and Query DSL Differences
ES|QL uses a columnar, vectorized execution engine that processes data in blocks across multiple threads. For aggregation-heavy workloads, this engine can outperform equivalent Query DSL aggregations by avoiding per-document Java object overhead. For simple filtered queries returning a few documents, Query DSL is typically faster because it short-circuits using inverted index structures that ES|QL does not always exploit the same way.
Full-text search is available through the MATCH and QSTR functions, but ES|QL queries do not produce _score values. Geo support is limited: spatial types work in WHERE clauses with ST_INTERSECTS but not in SORT. Nested queries have no ES|QL equivalent.
Profile your queries by measuring end-to-end latency. The _query endpoint does not support the profile parameter that Query DSL offers, so comparison requires external timing. If ES|QL is slower for a specific pattern, the Query DSL equivalent may be a better fit.
