docs/reference/query-languages/esql/limitations.md
By default, an {{esql}} query returns up to 1,000 rows. You can increase the number of rows up to 10,000 using the LIMIT command.
:::{include} _snippets/common/result-set-size-limitation.md :::
{{esql}} currently supports the following field types:
alias
boolean
date
date_nanos (Tech Preview)
bucket, date_format, date_parse, date_diff, date_extractto_datetime to cast to millisecond dates to use unsupported functionsdouble (float, half_float, scaled_float are represented as double)
dense_vector {applies_to}stack: preview 9.2+ {applies_to}serverless: preview
flattened {applies_to}stack: preview 9.5.0
ip
keyword family including keyword, constant_keyword, and wildcard
int (short and byte are represented as int)
long
null
text family including text, semantic_text and match_only_text
unsigned_long {applies_to}stack: preview {applies_to}serverless: preview
version
Spatial types
geo_pointgeo_shapepointshapeTSDB metrics {applies_to}stack: preview 9.2+ {applies_to}serverless: preview
countergaugeaggregate_metric_double: Aggregation functions that do not natively support aggregate_metric_double will use the average value and treat it as a double. {applies_to}stack: preview 9.4 {applies_to}serverless: previewexponential_histogram {applies_to}stack: preview 9.3+, ga 9.4.0tdigest {applies_to}stack: preview 9.3+, ga 9.4.0{{esql}} does not support certain field types. If the limitation only applies to specific product versions, it is indicated in the following list:
{applies_to}stack: ga 9.0-9.1 dense_vector
{applies_to}stack: ga 9.0-9.1 TSDB metrics
countergaugeaggregate_metric_doubleOther types
binarycompletiondouble_rangefloat_rangehistograminteger_rangeip_rangelong_rangenestedrank_featurerank_featuressearch_as_you_typeQuerying a column with an unsupported type returns an error. If a column with an unsupported type is not explicitly used in a query, it is returned with null values, with the exception of nested fields. Nested fields are not returned at all.
Some field types are not supported in all contexts:
Spatial types are not supported in the SORT processing command. Specifying an expression that evaluates to one of these types as a sort key will result in an error:
geo_pointgeo_shapecartesian_pointcartesian_shapeThe spatial types geo_point, geo_shape, cartesian_point and cartesian_shape are maintained at source precision in the original documents,
but indexed at reduced precision by Lucene, for performance reasons.
To ensure this optimization is available in the widest context, all spatial functions will produce results
at this reduced precision, aligned with the underlying Lucene index grid.
For geo_point and geo_shape, this grid is smaller than 1 cm at the equator, which is still very high precision for most use cases.
If the exact, original precision is desired, return the original field in the ES|QL query, which will maintain the original values.
To prioritize performance over precision, simply drop that field.
For example:
FROM airports
| EVAL geohex = ST_GEOHEX(location, 1)
| KEEP location, geohex
This query will perform slowly, due to the need to retrieve the original location field from the source document.
However, the following example will perform much faster:
FROM airports
| EVAL geohex = ST_GEOHEX(location, 1)
| EVAL x = ST_X(location), y = ST_Y(location)
| KEEP x, y, geohex
This query will perform much faster, since the original field location is not retrieved, and the three spatial functions used will all return values aligned with the Lucene index grid.
Note that if you return both the original location and the extracted x and y you will see very slight differences in the extracted values due to the precision loss.
stack: preview 9.2.0 The following types are only partially supported on 9.2.0. This is fixed in 9.2.1:
dense_vector: The KNN function and the TO_DENSE_VECTOR function will work and any field data will be retrieved as part of the results. However, the type will appear as unsupported when these functions are not used.
aggregate_metric_double: Using the TO_AGGREGATE_METRIC_DOUBLE function will work and any field data will be retrieved as part of the results. However, the type will appear as unsupported if this function is not used.
:::{note}
This means that a simple query like FROM test will not retrieve dense_vector or aggregate_metric_double data. However, using the appropriate functions will work:
FROM test WHERE KNN("dense_vector_field", [0, 1, 2, ...])FROM test | EVAL agm_data = TO_AGGREGATE_METRIC_DOUBLE(aggregate_metric_double_field)
:::{{esql}} respects runtime fields defined in the index mapping and treats them like regular mapped fields. Use the EVAL command to compute fields at query time, the built-in equivalent of runtime fields.
Runtime fields are different from unmapped fields. An unmapped field is a field that does not exist in the mapping at all. By default, {{esql}} returns an error when you reference an unmapped field, but you can change this behavior using the SET unmapped_fields directive. Loading unmapped fields from _source with SET unmapped_fields="load" is slower than querying mapped fields, and filters or sorts on loaded fields can force a full scan. To learn more, refer to Unmapped fields.
{{esql}} does not support configurations where the _source field is disabled.
One limitation of full-text search is that it is necessary to use the search function,
like MATCH,
in a WHERE command directly after the
FROM source command, or close enough to it.
Otherwise, the query will fail with a validation error.
{applies_to}stack: preview 9.5 {applies_to}serverless: preview
This restriction does not apply when MATCH targets an expression rather
than an indexed field (for example, a column produced by EVAL or STATS).
In that case, MATCH evaluates by scanning values row by row instead of
using the index, and can appear anywhere in the query.
When searching expressions:
MATCH on an expression does not contribute to the relevance score when
using METADATA _score.For example, this query is valid:
FROM books
| WHERE MATCH(author, "Faulkner") AND MATCH(author, "Tolkien")
But this query will fail due to the STATS command:
FROM books
| STATS AVG(price) BY author
| WHERE MATCH(author, "Faulkner")
Note that any queries on text fields that do not explicitly use the full-text functions,
MATCH,
QSTR or
KQL,
will behave as if the fields are actually keyword fields: they are case-sensitive and need to match the full string.
As discussed in more detail in Using {{esql}} to query multiple indices, {{esql}} can execute a single query across multiple indices, data streams, or aliases. However, there are some limitations to be aware of:
WHERE to filter out the results from the paused index. If you see an error of type search_phase_execution_exception, with the message Search rejected due to missing shards, you likely have an index or shard in UNASSIGNED state.::::{applies-switch} :::{applies-item} stack: preview 9.2+ Time series data streams (TSDS) are supported in technical preview. ::: :::{applies-item} stack: ga 9.0-9.1 {{esql}} does not support querying time series data streams (TSDS). ::: ::::
Date math expressions work well when the leftmost expression is a datetime, for example:
now() + 1 year - 2hour + ...
But using parentheses or putting the datetime to the right is not always supported yet. For example, the following expressions fail:
1year + 2hour + now()
now() + (1year + 2hour)
Date math does not allow subtracting two datetimes, for example:
now() - 2023-10-26
While all three enrich policy types are supported, there are some limitations to be aware of:
geo_match enrich policy type only supports the intersects spatial relation.match_field in the ENRICH command is of the correct type. For example, if the enrich policy is of type geo_match, the match_field in the ENRICH command must be of type geo_point or geo_shape. Likewise, a range enrich policy requires a match_field of type integer, long, date, or ip, depending on the type of the range field in the original enrich index.range policies when the match_field is of type KEYWORD. In this case the field values will be parsed during query execution, row by row. If any value fails to parse, the output values for that row will be set to null, an appropriate warning will be produced and the query will continue to execute.The DISSECT command does not support reference keys.
The GROK command does not support configuring custom patterns, or multiple patterns. The GROK command is not subject to Grok watchdog settings.
{{esql}} supports multivalued fields,
but functions return null when applied to a multivalued field, unless documented otherwise.
Work around this limitation by converting the field to single value with one of the
multivalue functions.
{{esql}} only supports the UTC timezone.
CATEGORIZE grouping function is not currently supported.
Also, INLINE STATS cannot yet have an unbounded SORT before it. You must either move the SORT after it, or add a LIMIT before the SORT.
Subqueries and
views are closely related,
since both extend the
FROM command with
branched query plans. They share the overall branching constraints but each
has its own additional limitations, described in turn below.
:::{include} _snippets/common/subquery_limitations.md :::
Views reuse the same branching model as subqueries, nested branching is generally not supported, but views can work around this limitation via query compaction. Beyond that, views have a few additional restrictions of their own, listed next.
:::{include} _snippets/common/view_limitations.md :::
WHERE command instead.[esql] > Unexpected error from Elasticsearch: The content length (536885793) is bigger than the maximum allowed string (536870888). The response from {{esql}} is too long. Use DROP or KEEP to limit the number of fields returned.Refer to Known issues for a list of known issues for {{esql}}.