[DOCS] ES|QL limitations (#101673)

* Supported types

* More limitations

* Document the behavior of text fields

* Review feedback

* Review feedback

docs/reference/esql/esql-enrich-data.asciidoc

@@ -137,3 +137,9 @@ include::{es-repo-dir}/ingest/apis/enrich/execute-enrich-policy.asciidoc[tag=upd
 ==== Update an enrich policy
 
 include::../ingest/enrich.asciidoc[tag=update-enrich-policy]
+
+==== Limitations
+// tag::limitations[]
+The {esql} `ENRICH` command only supports enrich policies of type `match`.
+Furthermore, `ENRICH` only supports enriching on a column of type `keyword`.
+// end::limitations[]

docs/reference/esql/esql-kibana.asciidoc

@@ -250,18 +250,20 @@ image::images/esql/esql-kibana-create-rule.png[align="center",width=50%]
 [[esql-kibana-limitations]]
 === Limitations
 
+// tag::limitations[]
 * The user interface to filter data is not enabled when Discover is in {esql}
 mode. To filter data, write a query that uses the <<esql-where>> command
 instead.
 * In {esql} mode, clicking a field in the field list in Discover does not show
 quick statistics for that field.
 * Discover shows no more than 10,000 rows. This limit only applies to the number
-of rows that are retrieved by the query and displayed in Discover. Any query or
-aggregation runs on the full data set.
+of rows that are retrieved by the query and displayed in Discover. Queries and
+aggregations run on the full data set.
 * Discover shows no more than 50 columns. If a query returns
 more than 50 columns, Discover only shows the first 50.
 * Querying many many indices at once without any filters can cause an error in
 kibana which looks like `[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 <<esql-drop>> or <<esql-keep>> to limit the number
-of fields returned.
+content length (536885793) is bigger than the maximum allowed string
+(536870888)`. The response from {esql} is too long. Use <<esql-drop>> or
+<<esql-keep>> to limit the number of fields returned.
+// end::limitations[]

docs/reference/esql/esql-limitations.asciidoc

@@ -5,36 +5,145 @@
 <titleabbrev>Limitations</titleabbrev>
 ++++
 
-This is work in progress.
+[discrete]
+[[esql-max-rows]]
+=== Result set size limit
+
+By default, an {esql} query returns up to 500 rows. You can increase the number
+of rows up to 10,000 using the <<esql-limit>> command. Queries do not return
+more than 10,000 rows, regardless of the `LIMIT` command's value.
+
+This limit only applies to the number of rows that are retrieved by the query
+and displayed in Discover. Queries and aggregations run on the full data set.
+
+To overcome this limitation:
+
+* Reduce the result set size by modifying the query to only return relevant
+data. Use <<esql-where>> to select a smaller subset of the data.
+* Shift any post-query processing to the query itself. You can use the {esql}
+<<esql-stats-by>> command to aggregate data in the query.
+* Increase the limit with the `esql.query.result_truncation_max_size` static
+cluster setting.
 
 [discrete]
 [[esql-supported-types]]
-=== Supported types
+=== Field types
+
+[discrete]
+==== Supported types
 
 {esql} currently supports the following <<mapping-types,field types>>:
 
-** `alias`
-** `boolean`
-** `date`
-** `double` (`float`, `half_float`, `scaled_float` are represented as `double`)
-** `ip`
-** `keyword` family including `keyword`, `constant_keyword`, and `wildcard`
-** `int` (`short` and `byte` are represented as `int`)
-** `long`
-** `null`
-** `text`
-** `unsigned_long`
-** `version`
+* `alias`
+* `boolean`
+* `date`
+* `double` (`float`, `half_float`, `scaled_float` are represented as `double`)
+* `ip`
+* `keyword` family including `keyword`, `constant_keyword`, and `wildcard`
+* `int` (`short` and `byte` are represented as `int`)
+* `long`
+* `null`
+* `text`
+* `unsigned_long`
+* `version`
+
+[discrete]
+==== Unsupported types
+
+{esql} does not yet support the following field types:
+
+* TSDB metrics
+** `counter`
+** `position`
+** `aggregate_metric_double`
+* Geo/spatial
+** `geo_point`
+** `geo_shape`
+** `point`
+** `shape`
+* Date/time
+** `date_nanos`
+** `date_range`
+* Other types
+** `binary`
+** `completion`
+** `dense_vector`
+** `double_range`
+** `float_range`
+** `histogram`
+** `integer_range`
+** `ip_range`
+** `long_range`
+** `nested`
+** `rank_feature`
+** `rank_features`
+** `search_as_you_type`
+
+Querying 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.
+
+[discrete]
+[[esql-limitations-text-fields]]
+=== `text` fields behave like `keyword` fields
+
+While {esql} supports <<text,`text`>> fields, {esql} does not treat these fields
+like the Search API does. {esql} queries do not query or aggregate the
+<<analysis,analyzed string>>. Instead, an {esql} query will try to get a `text`
+field's subfield of the <<keyword,keyword family type>> and query/aggregate
+that. If it's not possible to retrieve a `keyword` subfield, {esql} will get the
+string from a document's `_source`. If the `_source` cannot be retrieved, for
+example when using synthetic source, `null` is returned.
+
+Note that {esql}'s retrieval of `keyword` subfields may have unexpected
+consequences. An {esql} query on a `text` field is case-sensitive. Furthermore,
+a subfield may have been mapped with a <<normalizer,normalizer>>, which can
+transform the original string. Or it may have been mapped with <<ignore-above>>,
+which can truncate the string. None of these mapping operations are applied to
+an {esql} query, which may lead to false positives or negatives. 
+
+To avoid these issues, a best practice is to be explicit about the field that
+you query, and query `keyword` sub-fields instead of `text` fields.
 
 [discrete]
 [[esql-tsdb]]
-=== {esql} and time series data
+=== Time series data streams are not supported
 
-{esql} does not support time series data (TSDS).
+{esql} does not support querying time series data streams (TSDS).
 
 [discrete]
-[[esql-max-rows]]
-=== 10,000 row maximum
+[[esql-limitations-date-math]]
+=== Date math limitations
+
+Date math expressions work well when the leftmost expression is a datetime, for
+example:
+[source,txt]
+----
+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:
+[source,txt]
+----
+1year + 2hour + now()
+now() + (1year + 2hour)
+----
+
+Date math does not allow subtracting two datetimes, for example:
+[source,txt]
+----
+now() - 2023-10-26
+----
+
+[discrete]
+[[esql-limitations-enrich]]
+=== Enrich limitations
+
+include::esql-enrich-data.asciidoc[tag=limitations]
+
+[discrete]
+[[esql-limitations-kibana]]
+=== Kibana limitations
 
-A single query will not return more than 10,000 rows, regardless of the
-`LIMIT` command's value.
+include::esql-kibana.asciidoc[tag=limitations]