From 5bf8e7b26da43c810c23915021c29c12fae51b27 Mon Sep 17 00:00:00 2001 From: Garrett Spong Date: Tue, 6 Feb 2024 15:26:01 -0700 Subject: [PATCH] Updates esql kb docs to latest for 8.13 --- .../esql/documentation/esql_apis.asciidoc | 20 + .../esql_async_query_api.asciidoc | 165 +++++++++ .../esql_async_query_delete_api.asciidoc | 42 +++ .../esql_async_query_get_api.asciidoc | 58 +++ .../esql/documentation/esql_commands.asciidoc | 2 + .../documentation/esql_enrich_data.asciidoc | 27 +- .../esql/documentation/esql_examples.asciidoc | 99 +++++ .../documentation/esql_functions.asciidoc | 140 ------- .../documentation/esql_get_started.asciidoc | 343 +++++++++++++++++- .../esql/documentation/esql_kibana.asciidoc | 269 +++++++++++++- .../esql/documentation/esql_language.asciidoc | 13 +- .../documentation/esql_limitations.asciidoc | 204 ++++++++++- ...ql_process_data_with_dissect_grok.asciidoc | 321 ++++++++++++++++ .../documentation/esql_query_api.asciidoc | 44 +-- .../esql/documentation/esql_rest.asciidoc | 125 ++++++- .../esql_security_solution.asciidoc | 41 +++ .../esql/documentation/esql_syntax.asciidoc | 88 ++++- .../esql/documentation/esql_using.asciidoc | 21 ++ .../esql/documentation/functions/abs.asciidoc | 37 +- .../functions/aggregation_functions.asciidoc | 2 + .../documentation/functions/asin.asciidoc | 23 +- .../documentation/functions/atan.asciidoc | 25 +- .../documentation/functions/atan2.asciidoc | 27 +- .../functions/auto_bucket.asciidoc | 110 ++++-- .../esql/documentation/functions/avg.asciidoc | 36 +- .../documentation/functions/binary.asciidoc | 96 ++++- .../documentation/functions/case.asciidoc | 32 +- .../documentation/functions/ceil.asciidoc | 29 +- .../functions/cidr_match.asciidoc | 30 +- .../documentation/functions/coalesce.asciidoc | 19 +- .../documentation/functions/concat.asciidoc | 27 +- .../esql/documentation/functions/cos.asciidoc | 23 +- .../documentation/functions/cosh.asciidoc | 22 +- .../documentation/functions/count.asciidoc | 43 ++- .../functions/count_distinct.asciidoc | 73 +++- .../functions/date_diff.asciidoc | 63 ++++ .../functions/date_extract.asciidoc | 49 ++- .../functions/date_format.asciidoc | 33 +- .../functions/date_parse.asciidoc | 2 +- .../functions/date_time_functions.asciidoc | 2 + .../functions/date_trunc.asciidoc | 56 ++- .../esql/documentation/functions/e.asciidoc | 9 +- .../functions/ends_with.asciidoc | 25 +- .../documentation/functions/floor.asciidoc | 30 +- .../documentation/functions/greatest.asciidoc | 35 +- .../esql/documentation/functions/in.asciidoc | 10 +- .../functions/is_finite.asciidoc | 10 - .../functions/is_infinite.asciidoc | 10 - .../documentation/functions/is_nan.asciidoc | 10 - .../documentation/functions/least.asciidoc | 35 +- .../documentation/functions/left.asciidoc | 26 +- .../documentation/functions/length.asciidoc | 27 +- .../documentation/functions/like.asciidoc | 12 +- .../esql/documentation/functions/log.asciidoc | 48 +++ .../documentation/functions/log10.asciidoc | 24 +- .../documentation/functions/ltrim.asciidoc | 21 +- .../functions/math_functions.asciidoc | 2 + .../esql/documentation/functions/max.asciidoc | 32 +- .../documentation/functions/median.asciidoc | 44 ++- .../median_absolute_deviation.asciidoc | 57 ++- .../esql/documentation/functions/min.asciidoc | 32 +- .../documentation/functions/mv_avg.asciidoc | 28 +- .../functions/mv_concat.asciidoc | 29 +- .../documentation/functions/mv_count.asciidoc | 25 +- .../functions/mv_dedupe.asciidoc | 25 +- .../documentation/functions/mv_first.asciidoc | 40 ++ .../functions/mv_functions.asciidoc | 4 + .../documentation/functions/mv_last.asciidoc | 40 ++ .../documentation/functions/mv_max.asciidoc | 26 +- .../functions/mv_median.asciidoc | 28 +- .../documentation/functions/mv_min.asciidoc | 26 +- .../documentation/functions/mv_sum.asciidoc | 25 +- .../esql/documentation/functions/now.asciidoc | 21 +- .../functions/operators.asciidoc | 8 +- .../functions/percentile.asciidoc | 44 ++- .../esql/documentation/functions/pi.asciidoc | 9 +- .../esql/documentation/functions/pow.asciidoc | 81 +---- .../functions/predicates.asciidoc | 2 + .../documentation/functions/replace.asciidoc | 33 +- .../documentation/functions/right.asciidoc | 26 +- .../documentation/functions/rlike.asciidoc | 14 +- .../documentation/functions/round.asciidoc | 21 ++ .../documentation/functions/rtrim.asciidoc | 19 + .../esql/documentation/functions/sin.asciidoc | 23 +- .../documentation/functions/sinh.asciidoc | 22 +- .../documentation/functions/split.asciidoc | 31 +- .../documentation/functions/sqrt.asciidoc | 27 +- .../functions/st_centroid.asciidoc | 18 + .../functions/starts_with.asciidoc | 27 +- .../functions/string_functions.asciidoc | 4 + .../functions/substring.asciidoc | 30 +- .../esql/documentation/functions/sum.asciidoc | 30 +- .../esql/documentation/functions/tan.asciidoc | 23 +- .../documentation/functions/tanh.asciidoc | 22 +- .../esql/documentation/functions/tau.asciidoc | 10 +- .../functions/to_boolean.asciidoc | 38 +- .../functions/to_cartesianpoint.asciidoc | 37 ++ .../functions/to_cartesianshape.asciidoc | 38 ++ .../functions/to_datetime.asciidoc | 37 +- .../functions/to_degrees.asciidoc | 26 +- .../functions/to_double.asciidoc | 48 ++- .../functions/to_geopoint.asciidoc | 38 ++ .../functions/to_geoshape.asciidoc | 38 ++ .../functions/to_integer.asciidoc | 42 ++- .../documentation/functions/to_ip.asciidoc | 27 +- .../documentation/functions/to_long.asciidoc | 34 +- .../documentation/functions/to_lower.asciidoc | 32 ++ .../functions/to_radians.asciidoc | 26 +- .../functions/to_string.asciidoc | 26 +- .../functions/to_unsigned_long.asciidoc | 41 ++- .../documentation/functions/to_upper.asciidoc | 32 ++ .../functions/to_version.asciidoc | 30 +- .../documentation/functions/trim.asciidoc | 20 +- .../type_conversion_functions.asciidoc | 8 + .../functions/types/add.asciidoc | 20 + .../functions/types/auto_bucket.asciidoc | 2 +- .../functions/types/case.asciidoc | 2 +- .../functions/types/coalesce.asciidoc | 2 +- .../functions/types/concat.asciidoc | 2 +- .../functions/types/date_diff.asciidoc | 6 + .../functions/types/date_extract.asciidoc | 2 +- .../functions/types/div.asciidoc | 7 + .../functions/types/ends_with.asciidoc | 3 +- .../functions/types/equals.asciidoc | 5 + .../functions/types/greater_than.asciidoc | 5 + .../types/greater_than_or_equal.asciidoc | 5 + .../functions/types/left.asciidoc | 3 +- .../functions/types/length.asciidoc | 3 +- .../functions/types/less_than.asciidoc | 5 + .../types/less_than_or_equal.asciidoc | 5 + .../functions/types/log.asciidoc | 20 + .../functions/types/ltrim.asciidoc | 2 +- .../functions/types/mod.asciidoc | 7 + .../functions/types/mul.asciidoc | 8 + .../functions/types/mv_avg.asciidoc | 2 +- .../functions/types/mv_concat.asciidoc | 2 +- .../functions/types/mv_count.asciidoc | 10 +- .../functions/types/mv_dedupe.asciidoc | 6 +- .../functions/types/mv_first.asciidoc | 18 + .../functions/types/mv_last.asciidoc | 18 + .../functions/types/mv_max.asciidoc | 6 +- .../functions/types/mv_median.asciidoc | 2 +- .../functions/types/mv_min.asciidoc | 6 +- .../functions/types/mv_sum.asciidoc | 5 +- .../functions/types/neg.asciidoc | 9 + .../functions/types/not_equals.asciidoc | 5 + .../functions/types/pow.asciidoc | 14 +- .../functions/types/replace.asciidoc | 2 +- .../functions/types/right.asciidoc | 3 +- .../functions/types/round.asciidoc | 2 +- .../functions/types/rtrim.asciidoc | 2 +- .../functions/types/split.asciidoc | 3 +- .../functions/types/st_centroid.asciidoc | 6 + .../functions/types/starts_with.asciidoc | 3 +- .../functions/types/sub.asciidoc | 12 + .../functions/types/substring.asciidoc | 3 +- .../functions/types/to_boolean.asciidoc | 11 + .../types/to_cartesianpoint.asciidoc | 7 + .../types/to_cartesianshape.asciidoc | 8 + .../functions/types/to_datetime.asciidoc | 11 + .../functions/types/to_degrees.asciidoc | 8 + .../functions/types/to_double.asciidoc | 12 + .../functions/types/to_geopoint.asciidoc | 7 + .../functions/types/to_geoshape.asciidoc | 8 + .../functions/types/to_integer.asciidoc | 12 + .../functions/types/to_ip.asciidoc | 3 +- .../functions/types/to_long.asciidoc | 12 + .../{is_finite.asciidoc => to_lower.asciidoc} | 5 +- .../functions/types/to_radians.asciidoc | 8 + .../functions/types/to_string.asciidoc | 4 + .../functions/types/to_unsigned_long.asciidoc | 12 + ...is_infinite.asciidoc => to_upper.asciidoc} | 5 +- .../functions/types/trim.asciidoc | 2 +- .../documentation/functions/unary.asciidoc | 12 + .../esql/documentation/index.asciidoc | 87 +++-- .../documentation/metadata_fields.asciidoc | 8 +- .../documentation/multivalued_fields.asciidoc | 16 +- .../processing_commands/dissect.asciidoc | 54 ++- .../processing_commands/drop.asciidoc | 22 +- .../processing_commands/enrich.asciidoc | 30 +- .../processing_commands/eval.asciidoc | 61 +++- .../processing_commands/grok.asciidoc | 62 +++- .../processing_commands/keep.asciidoc | 84 ++++- .../processing_commands/limit.asciidoc | 42 ++- .../processing_commands/mv_expand.asciidoc | 19 +- .../processing_commands/rename.asciidoc | 21 +- .../processing_commands/sort.asciidoc | 46 ++- .../processing_commands/stats.asciidoc | 122 ++++++- .../processing_commands/where.asciidoc | 47 ++- .../source_commands/from.asciidoc | 45 ++- .../source_commands/row.asciidoc | 20 + .../source_commands/show.asciidoc | 29 +- .../documentation/task_management.asciidoc | 2 +- 193 files changed, 5155 insertions(+), 901 deletions(-) create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_apis.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_async_query_api.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_async_query_delete_api.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_async_query_get_api.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_examples.asciidoc delete mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_functions.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_process_data_with_dissect_grok.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_security_solution.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_using.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_diff.asciidoc delete mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/is_finite.asciidoc delete mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/is_infinite.asciidoc delete mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/is_nan.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/log.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_first.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_last.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/st_centroid.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_cartesianpoint.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_cartesianshape.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_geopoint.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_geoshape.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_lower.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_upper.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/add.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/date_diff.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/div.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/equals.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/greater_than.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/greater_than_or_equal.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/less_than.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/less_than_or_equal.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/log.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mod.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mul.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_first.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_last.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/neg.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/not_equals.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/st_centroid.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/sub.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_boolean.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_cartesianpoint.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_cartesianshape.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_datetime.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_degrees.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_double.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_geopoint.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_geoshape.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_integer.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_long.asciidoc rename x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/{is_finite.asciidoc => to_lower.asciidoc} (58%) create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_radians.asciidoc create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_unsigned_long.asciidoc rename x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/{is_infinite.asciidoc => to_upper.asciidoc} (58%) create mode 100644 x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/unary.asciidoc diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_apis.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_apis.asciidoc new file mode 100644 index 00000000000000..686a71506bc148 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_apis.asciidoc @@ -0,0 +1,20 @@ +[[esql-apis]] +== {esql} APIs + +The {es} Query Language ({esql}) provides a powerful way to filter, transform, +and analyze data stored in {es}, and in the future in other runtimes. For an +overview of {esql} and related tutorials, see <>. + +* <> +* <> +* <> +* <> + + +include::esql-query-api.asciidoc[] + +include::esql-async-query-api.asciidoc[] + +include::esql-async-query-get-api.asciidoc[] + +include::esql-async-query-delete-api.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_async_query_api.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_async_query_api.asciidoc new file mode 100644 index 00000000000000..0d15eb313a61f1 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_async_query_api.asciidoc @@ -0,0 +1,165 @@ +[[esql-async-query-api]] +=== {esql} async query API +++++ +{esql} async query API +++++ + +Runs an async <>. + +The async query API lets you asynchronously execute a query request, +monitor its progress, and retrieve results when they become available. + +The API accepts the same parameters and request body as the synchronous +<>, along with additional async related +properties as outlined below. + +[source,console] +---- +POST /_query/async +{ + "query": """ + FROM library + | EVAL year = DATE_TRUNC(1 YEARS, release_date) + | STATS MAX(page_count) BY year + | SORT year + | LIMIT 5 + """, + "wait_for_completion_timeout": "2s" +} +---- +// TEST[setup:library] + +If the results are not available within the given timeout period, 2 seconds +in this case, no results are returned but rather a response that +includes: + + * A query ID + * An `is_running` value of _true_, indicating the query is ongoing + +The query continues to run in the background without blocking other +requests. + +[source,console-result] +---- +{ + "id": "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=", + "is_running": true +} +---- +// TEST[skip: no access to query ID - may return response values] + +Otherwise, if the response's `is_running` value is `false`, the async +query has finished and the results are returned. + +[source,console-result] +---- +{ + "is_running": false, + "columns": ... +} +---- +// TEST[skip: no access to query ID - may return response values] + +[[esql-async-query-api-request]] +==== {api-request-title} + +`POST /_query/async` + +[[esql-async-query-api-prereqs]] +==== {api-prereq-title} + +* If the {es} {security-features} are enabled, you must have the `read` +<> for the data stream, index, +or alias you query. + +[[esql-async-query-api-path-params]] +==== {api-path-parms-title} + +The API accepts the same parameters as the synchronous +<>. + +[[esql-async-query-api-request-body]] +==== {api-request-body-title} + +The API accepts the same request body as the synchronous +<>, along with the following +parameters: + +[[esql-async-query-api-wait-for-completion-timeout]] +`wait_for_completion_timeout`:: ++ +-- +(Optional, <>) +Timeout duration to wait for the request to finish. Defaults to a 1 second, +meaning the request waits for 1 second for the query results. + +If the query completes during this period then results will be +returned. Otherwise, a query `id` is returned that can later be used to +retrieve the results. + +If the request does not complete during this period, a query +<> is returned. +-- + +[[esql-async-query-api-keep-on-completion]] +`keep_on_completion`:: ++ +-- +(Optional, Boolean) +If `true`, the query and its results are stored in the cluster. + +If `false`, the query and its results are stored in the cluster only if the +request does not complete during the period set by the +<> +parameter. Defaults to `false`. +-- + +`keep_alive`:: ++ +-- +(Optional, <>) +Period for which the query and its results are stored in the cluster. Defaults +to `5d` (five days). + +When this period expires, the query and its results are deleted, even if the +query is still ongoing. + +If the <> parameter +is `false`, {es} only stores async queries that do not complete within the period +set by the <> +parameter, regardless of this value. +-- + +[[esql-async-query-api-response-body]] +==== {api-response-body-title} + +The API returns the same response body as the synchronous +<>, along with the following +properties: + +[[esql-async-query-api-response-body-query-id]] +`id`:: ++ +-- +(string) +Identifier for the query. + +This query ID is only provided if one of the following conditions is met: + +* A query request does not return complete results during the +<> +parameter's timeout period. + +* The query request's <> +parameter is `true`. + +You can use this ID with the <> to get the current status and available results for the query. +-- + +`is_running`:: ++ +-- +(Boolean) +If `true`, the query request is still executing. +-- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_async_query_delete_api.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_async_query_delete_api.asciidoc new file mode 100644 index 00000000000000..90f8c06b9124a9 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_async_query_delete_api.asciidoc @@ -0,0 +1,42 @@ +[[esql-async-query-delete-api]] +=== {esql} async query delete API +++++ +{esql} async query delete API +++++ + +The {esql} async query delete API is used to manually delete an async query +by ID. If the query is still running, the query will be cancelled. Otherwise, +the stored results are deleted. + +[source,console] +---- +DELETE /query/async/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM= +---- +// TEST[skip: no access to query ID] + +[[esql-async-query-delete-api-request]] +==== {api-request-title} + +`DELETE /_query/async/` + +[[esql-async-query-delete-api-prereqs]] +==== {api-prereq-title} + +* If the {es} {security-features} are enabled, only the following users can +use this API to delete a query: + +** The authenticated user that submitted the original query request +** Users with the `cancel_task` <> + + +[[esql-async-query-delete-api-path-params]] +==== {api-path-parms-title} + +``:: +(Required, string) +Identifier for the query to delete. ++ +A query ID is provided in the <>'s +response for a query that does not complete in the awaited time. A query ID is +also provided if the request's <> +parameter is `true`. diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_async_query_get_api.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_async_query_get_api.asciidoc new file mode 100644 index 00000000000000..ec68313b2c4900 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_async_query_get_api.asciidoc @@ -0,0 +1,58 @@ +[[esql-async-query-get-api]] +=== {esql} async query get API +++++ +{esql} async query get API +++++ + +Returns the current status and available results for an <> or a stored results. + +[source,console] +---- +GET /_query/async/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM= +---- +// TEST[skip: no access to query ID] + +[[esql-async-query-get-api-request]] +==== {api-request-title} + +`GET /_query/async/` + +[[esql-async-query-get-api-prereqs]] +==== {api-prereq-title} + +* If the {es} {security-features} are enabled, only the user who first submitted +the {esql} query can retrieve the results using this API. + +[[esql-async-query-get-api-path-params]] +==== {api-path-parms-title} + +``:: +(Required, string) +Identifier for the query. ++ +A query ID is provided in the <>'s +response for a query that does not complete in the awaited time. A query ID is +also provided if the request's <> +parameter is `true`. + +[[esql-async-query-get-api-query-params]] +==== {api-query-parms-title} + +`wait_for_completion_timeout`:: +(Optional, <>) +Timeout duration to wait for the request to finish. Defaults to no timeout, +meaning the request waits for complete query results. ++ +If this parameter is specified and the request completes during this period, +complete query results are returned. ++ +If the request does not complete during this period, the response returns an +`is_running` value of `true` and no results. + +[[esql-async-query-get-api-response-body]] +==== {api-response-body-title} + +The {esql} async query get API returns the same response body as the {esql} +query API. See the {esql} query API's <>. diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_commands.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_commands.asciidoc index 8b0e99344add1c..708127718fe38d 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_commands.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_commands.asciidoc @@ -5,6 +5,7 @@ Commands ++++ +[[esql-source-commands]] // tag::source_commands[] ==== Source commands @@ -20,6 +21,7 @@ image::images/esql/source-command.svg[A source command producing a table from {e // end::source_command[] +[[esql-processing-commands]] // tag::proc_commands[] ==== Processing commands diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_enrich_data.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_enrich_data.asciidoc index 9708728e6b305a..e465d7daae126c 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_enrich_data.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_enrich_data.asciidoc @@ -1,12 +1,13 @@ [[esql-enrich-data]] -=== Enrich data +=== Data enrichment ++++ -Enrich data +Data enrichment ++++ -You can use {esql}'s <> processing command to enrich a table with -data from indices in {es}. +The {esql} <> processing command combines, at query-time, data from +one or more source indexes with field-value combinations found in {es} enrich +indexes. For example, you can use `ENRICH` to: @@ -14,6 +15,7 @@ For example, you can use `ENRICH` to: * Add product information to retail orders based on product IDs * Supplement contact information based on an email address +[discrete] [[esql-how-enrich-works]] ==== How the `ENRICH` command works @@ -22,6 +24,7 @@ It requires a few special components: image::images/esql/esql-enrich.png[align="center"] + [[esql-enrich-policy]] Enrich policy:: + @@ -60,6 +63,7 @@ enrich index. include::../ingest/enrich.asciidoc[tag=enrich-index] -- +[discrete] [[esql-set-up-enrich-policy]] ==== Set up an enrich policy @@ -75,27 +79,33 @@ Once you have enrich policies set up, you can <> and <>. +[discrete] [IMPORTANT] ==== The `ENRICH` command performs several operations and may impact the speed of your query. +[discrete] ==== +[discrete] [[esql-enrich-prereqs]] ==== Prerequisites include::{es-repo-dir}/ingest/apis/enrich/put-enrich-policy.asciidoc[tag=enrich-policy-api-prereqs] +[discrete] [[esql-create-enrich-source-index]] ==== Add enrich data include::../ingest/enrich.asciidoc[tag=create-enrich-source-index] +[discrete] [[esql-create-enrich-policy]] ==== Create an enrich policy include::../ingest/enrich.asciidoc[tag=create-enrich-policy] +[discrete] [[esql-execute-enrich-policy]] ==== Execute the enrich policy @@ -105,6 +115,7 @@ image::images/esql/esql-enrich-policy.png[align="center"] include::../ingest/enrich.asciidoc[tag=execute-enrich-policy2] +[discrete] [[esql-use-enrich]] ==== Use the enrich policy @@ -115,12 +126,20 @@ image::images/esql/esql-enrich-command.png[align="center",width=50%] include::processing-commands/enrich.asciidoc[tag=examples] +[discrete] [[esql-update-enrich-data]] ==== Update an enrich index include::{es-repo-dir}/ingest/apis/enrich/execute-enrich-policy.asciidoc[tag=update-enrich-index] +[discrete] [[esql-update-enrich-policies]] ==== 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[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_examples.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_examples.asciidoc new file mode 100644 index 00000000000000..817ec4f7b6f24d --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_examples.asciidoc @@ -0,0 +1,99 @@ +[[esql-examples]] +== {esql} examples + +++++ +Examples +++++ + + +[discrete] +=== Aggregating and enriching windows event logs + +[source,esql] +---- +FROM logs-* +| WHERE event.code IS NOT NULL +| STATS event_code_count = COUNT(event.code) BY event.code,host.name +| ENRICH win_events ON event.code WITH event_description +| WHERE event_description IS NOT NULL and host.name IS NOT NULL +| RENAME event_description AS event.description +| SORT event_code_count DESC +| KEEP event_code_count,event.code,host.name,event.description +---- + +* It starts by querying logs from indices that match the pattern "logs-*". +* Filters events where the "event.code" field is not null. +* Aggregates the count of events by "event.code" and "host.name." +* Enriches the events with additional information using the "EVENT_DESCRIPTION" field. +* Filters out events where "EVENT_DESCRIPTION" or "host.name" is null. +* Renames "EVENT_DESCRIPTION" as "event.description." +* Sorts the result by "event_code_count" in descending order. +* Keeps only selected fields: "event_code_count," "event.code," "host.name," and "event.description." + + +[discrete] +=== Summing outbound traffic from a process `curl.exe` + +[source,esql] +---- +FROM logs-endpoint +| WHERE process.name == "curl.exe" +| STATS bytes = SUM(destination.bytes) BY destination.address +| EVAL kb = bytes/1024 +| SORT kb DESC +| LIMIT 10 +| KEEP kb,destination.address +---- + +* Queries logs from the "logs-endpoint" source. +* Filters events where the "process.name" field is "curl.exe." +* Calculates the sum of bytes sent to destination addresses and converts it to kilobytes (KB). +* Sorts the results by "kb" (kilobytes) in descending order. +* Limits the output to the top 10 results. +* Keeps only the "kb" and "destination.address" fields. + + +[discrete] +=== Manipulating DNS logs to find a high number of unique dns queries per registered domain + +[source,esql] +---- +FROM logs-* +| GROK dns.question.name "%{DATA}\\.%{GREEDYDATA:dns.question.registered_domain:string}" +| STATS unique_queries = COUNT_DISTINCT(dns.question.name) BY dns.question.registered_domain, process.name +| WHERE unique_queries > 10 +| SORT unique_queries DESC +| RENAME unique_queries AS `Unique Queries`, dns.question.registered_domain AS `Registered Domain`, process.name AS `Process` +---- + +* Queries logs from indices matching "logs-*." +* Uses the "grok" pattern to extract the registered domain from the "dns.question.name" field. +* Calculates the count of unique DNS queries per registered domain and process name. +* Filters results where "unique_queries" are greater than 10. +* Sorts the results by "unique_queries" in descending order. +* Renames fields for clarity: "unique_queries" to "Unique Queries," "dns.question.registered_domain" to "Registered Domain," and "process.name" to "Process." + + +[discrete] +=== Identifying high-numbers of outbound user connections + +[source,esql] +---- +FROM logs-* +| WHERE NOT CIDR_MATCH(destination.ip, "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16") +| STATS destcount = COUNT(destination.ip) BY user.name, host.name +| ENRICH ldap_lookup_new ON user.name +| WHERE group.name IS NOT NULL +| EVAL follow_up = CASE(destcount >= 100, "true","false") +| SORT destcount DESC +| KEEP destcount, host.name, user.name, group.name, follow_up +---- + +* Queries logs from indices matching "logs-*." +* Filters out events where the destination IP address falls within private IP address ranges (e.g., 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16). +* Calculates the count of unique destination IPs by "user.name" and "host.name." +* Enriches the "user.name" field with LDAP group information. +* Filters out results where "group.name" is not null. +* Uses a "CASE" statement to create a "follow_up" field, setting it to "true" when "destcount" is greater than or equal to 100 and "false" otherwise. +* Sorts the results by "destcount" in descending order. +* Keeps selected fields: "destcount," "host.name," "user.name," "group.name," and "follow_up." diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_functions.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_functions.asciidoc deleted file mode 100644 index b921719fc097bb..00000000000000 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_functions.asciidoc +++ /dev/null @@ -1,140 +0,0 @@ -[[esql-functions]] -== {esql} functions - -++++ -Functions -++++ - -<>, <> and <> support -these functions: - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> - -include::functions/abs.asciidoc[] -include::functions/acos.asciidoc[] -include::functions/asin.asciidoc[] -include::functions/atan.asciidoc[] -include::functions/atan2.asciidoc[] -include::functions/auto_bucket.asciidoc[] -include::functions/case.asciidoc[] -include::functions/ceil.asciidoc[] -include::functions/cidr_match.asciidoc[] -include::functions/coalesce.asciidoc[] -include::functions/concat.asciidoc[] -include::functions/cos.asciidoc[] -include::functions/cosh.asciidoc[] -include::functions/date_extract.asciidoc[] -include::functions/date_format.asciidoc[] -include::functions/date_parse.asciidoc[] -include::functions/date_trunc.asciidoc[] -include::functions/e.asciidoc[] -include::functions/ends_with.asciidoc[] -include::functions/floor.asciidoc[] -include::functions/greatest.asciidoc[] -include::functions/is_finite.asciidoc[] -include::functions/is_infinite.asciidoc[] -include::functions/is_nan.asciidoc[] -include::functions/least.asciidoc[] -include::functions/left.asciidoc[] -include::functions/length.asciidoc[] -include::functions/log10.asciidoc[] -include::functions/ltrim.asciidoc[] -include::functions/mv_avg.asciidoc[] -include::functions/mv_concat.asciidoc[] -include::functions/mv_count.asciidoc[] -include::functions/mv_dedupe.asciidoc[] -include::functions/mv_max.asciidoc[] -include::functions/mv_median.asciidoc[] -include::functions/mv_min.asciidoc[] -include::functions/mv_sum.asciidoc[] -include::functions/now.asciidoc[] -include::functions/pi.asciidoc[] -include::functions/pow.asciidoc[] -include::functions/replace.asciidoc[] -include::functions/right.asciidoc[] -include::functions/round.asciidoc[] -include::functions/rtrim.asciidoc[] -include::functions/sin.asciidoc[] -include::functions/sinh.asciidoc[] -include::functions/split.asciidoc[] -include::functions/sqrt.asciidoc[] -include::functions/starts_with.asciidoc[] -include::functions/substring.asciidoc[] -include::functions/tan.asciidoc[] -include::functions/tanh.asciidoc[] -include::functions/tau.asciidoc[] -include::functions/to_boolean.asciidoc[] -include::functions/to_datetime.asciidoc[] -include::functions/to_degrees.asciidoc[] -include::functions/to_double.asciidoc[] -include::functions/to_integer.asciidoc[] -include::functions/to_ip.asciidoc[] -include::functions/to_long.asciidoc[] -include::functions/to_radians.asciidoc[] -include::functions/to_string.asciidoc[] -include::functions/to_unsigned_long.asciidoc[] -include::functions/to_version.asciidoc[] -include::functions/trim.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_get_started.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_get_started.asciidoc index 1f3cdf85c173eb..631a961b023ab0 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_get_started.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_get_started.asciidoc @@ -1,8 +1,347 @@ [[esql-getting-started]] -== Getting started with {esql} +== Getting started with {esql} queries ++++ Getting started ++++ -coming::[8.11] \ No newline at end of file +preview::["Do not use {esql} on production environments. This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features."] + +This guide shows how you can use {esql} to query and aggregate your data. + +[discrete] +[[esql-getting-started-prerequisites]] +=== Prerequisites + +To follow along with the queries in this guide, you can either set up your own +deployment, or use Elastic's public {esql} demo environment. + +include::{es-repo-dir}/tab-widgets/esql/esql-getting-started-widget-sample-data.asciidoc[] + +[discrete] +[[esql-getting-started-running-queries]] +=== Run an {esql} query + +In {kib}, you can use Console or Discover to run {esql} queries: + +include::{es-repo-dir}/tab-widgets/esql/esql-getting-started-widget-discover-console.asciidoc[] + +[discrete] +[[esql-getting-started-first-query]] +=== Your first {esql} query + +Each {esql} query starts with a <>. A +source command produces a table, typically with data from {es}. + +image::images/esql/source-command.svg[A source command producing a table from {es},align="center"] + +The <> source command returns a table with documents from a data +stream, index, or alias. Each row in the resulting table represents a document. +This query returns up to 500 documents from the `sample_data` index: + +[source,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=gs-from] +---- + +Each column corresponds to a field, and can be accessed by the name of that +field. + +[TIP] +==== +{esql} keywords are case-insensitive. The following query is identical to the +previous one: + +[source,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=gs-from-lowercase] +---- +==== + +[discrete] +[[esql-getting-started-limit]] +=== Processing commands + +A source command can be followed by one or more +<>, separated by a pipe character: +`|`. Processing commands change an input table by adding, removing, or changing +rows and columns. Processing commands can perform filtering, projection, +aggregation, and more. + +image::images/esql/esql-limit.png[A processing command changing an input table,align="center",width="60%"] + +For example, you can use the <> command to limit the number of rows +that are returned, up to a maximum of 10,000 rows: + +[source,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=gs-limit] +---- + +[TIP] +==== +For readability, you can put each command on a separate line. However, you don't +have to. The following query is identical to the previous one: + +[source,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=gs-limit-one-line] +---- +==== + +[discrete] +[[esql-getting-started-sort]] +==== Sort a table + +image::images/esql/esql-sort.png[A processing command sorting an input table,align="center",width="60%"] + +Another processing command is the <> command. By default, the rows +returned by `FROM` don't have a defined sort order. Use the `SORT` command to +sort rows on one or more columns: + +[source,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=gs-sort] +---- + +[discrete] +[[esql-getting-started-where]] +==== Query the data + +Use the <> command to query the data. For example, to find all +events with a duration longer than 5ms: + +[source,esql] +---- +include::{esql-specs}/where.csv-spec[tag=gs-where] +---- + +`WHERE` supports several <>. For example, you can use <> to run a wildcard query against the `message` column: + +[source,esql] +---- +include::{esql-specs}/where-like.csv-spec[tag=gs-like] +---- + +[discrete] +[[esql-getting-started-more-commands]] +==== More processing commands + +There are many other processing commands, like <> and <> +to keep or drop columns, <> to enrich a table with data from +indices in {es}, and <> and <> to process data. Refer +to <> for an overview of all processing commands. + +[discrete] +[[esql-getting-started-chaining]] +=== Chain processing commands + +You can chain processing commands, separated by a pipe character: `|`. Each +processing command works on the output table of the previous command. The result +of a query is the table produced by the final processing command. + +image::images/esql/esql-sort-limit.png[Processing commands can be chained,align="center"] + +The following example first sorts the table on `@timestamp`, and next limits the +result set to 3 rows: + +[source,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=gs-chaining] +---- + +NOTE: The order of processing commands is important. First limiting the result +set to 3 rows before sorting those 3 rows would most likely return a result that +is different than this example, where the sorting comes before the limit. + +[discrete] +[[esql-getting-started-eval]] +=== Compute values + +Use the <> command to append columns to a table, with calculated +values. For example, the following query appends a `duration_ms` column. The +values in the column are computed by dividing `event_duration` by 1,000,000. In +other words: `event_duration` converted from nanoseconds to milliseconds. + +[source,esql] +---- +include::{esql-specs}/eval.csv-spec[tag=gs-eval] +---- + +`EVAL` supports several <>. For example, to round a +number to the closest number with the specified number of digits, use the +<> function: + +[source,esql] +---- +include::{esql-specs}/eval.csv-spec[tag=gs-round] +---- + +[discrete] +[[esql-getting-started-stats]] +=== Calculate statistics + +{esql} can not only be used to query your data, you can also use it to aggregate +your data. Use the <> command to calculate statistics. For +example, the median duration: + +[source,esql] +---- +include::{esql-specs}/stats.csv-spec[tag=gs-stats] +---- + +You can calculate multiple stats with one command: + +[source,esql] +---- +include::{esql-specs}/stats.csv-spec[tag=gs-two-stats] +---- + +Use `BY` to group calculated stats by one or more columns. For example, to +calculate the median duration per client IP: + +[source,esql] +---- +include::{esql-specs}/stats.csv-spec[tag=gs-stats-by] +---- + +[discrete] +[[esql-getting-started-access-columns]] +=== Access columns + +You can access columns by their name. If a name contains special characters, +<> with backticks (+{backtick}+). + +Assigning an explicit name to a column created by `EVAL` or `STATS` is optional. +If you don't provide a name, the new column name is equal to the function +expression. For example: + +[source,esql] +---- +include::{esql-specs}/eval.csv-spec[tag=gs-eval-no-column-name] +---- + +In this query, `EVAL` adds a new column named `event_duration/1000000.0`. +Because its name contains special characters, to access this column, quote it +with backticks: + +[source,esql] +---- +include::{esql-specs}/eval.csv-spec[tag=gs-eval-stats-backticks] +---- + +[discrete] +[[esql-getting-started-histogram]] +=== Create a histogram + +To track statistics over time, {esql} enables you to create histograms using the +<> function. `AUTO_BUCKET` creates human-friendly bucket sizes +and returns a value for each row that corresponds to the resulting bucket the +row falls into. + +For example, to create hourly buckets for the data on October 23rd: + +[source,esql] +---- +include::{esql-specs}/date.csv-spec[tag=gs-auto_bucket] +---- + +Combine `AUTO_BUCKET` with <> to create a histogram. For example, +to count the number of events per hour: + +[source,esql] +---- +include::{esql-specs}/date.csv-spec[tag=gs-auto_bucket-stats-by] +---- + +Or the median duration per hour: + +[source,esql] +---- +include::{esql-specs}/date.csv-spec[tag=gs-auto_bucket-stats-by-median] +---- + +[discrete] +[[esql-getting-started-enrich]] +=== Enrich data + +{esql} enables you to <> a table with data from indices +in {es}, using the <> command. + +image::images/esql/esql-enrich.png[align="center"] + +Before you can use `ENRICH`, you first need to +<> and <> +an <>. + +include::{es-repo-dir}/tab-widgets/esql/esql-getting-started-widget-enrich-policy.asciidoc[] + +After creating and executing a policy, you can use it with the `ENRICH` +command: + +[source,esql] +---- +include::{esql-specs}/enrich.csv-spec[tag=gs-enrich] +---- + +You can use the new `env` column that's added by the `ENRICH` command in +subsequent commands. For example, to calculate the median duration per +environment: + +[source,esql] +---- +include::{esql-specs}/enrich.csv-spec[tag=gs-enrich-stats-by] +---- + +For more about data enrichment with {esql}, refer to <>. + +[discrete] +[[esql-getting-started-process-data]] +=== Process data + +Your data may contain unstructured strings that you want to +<> to make it easier to +analyze the data. For example, the sample data contains log messages like: + +[source,txt] +---- +"Connected to 10.1.0.3" +---- + +By extracting the IP address from these messages, you can determine which IP has +accepted the most client connections. + +To structure unstructured strings at query time, you can use the {esql} +<> and <> commands. `DISSECT` works by breaking up a +string using a delimiter-based pattern. `GROK` works similarly, but uses regular +expressions. This makes `GROK` more powerful, but generally also slower. + +In this case, no regular expressions are needed, as the `message` is +straightforward: "Connected to ", followed by the server IP. To match this +string, you can use the following `DISSECT` command: + +[source,esql] +---- +include::{esql-specs}/dissect.csv-spec[tag=gs-dissect] +---- + +This adds a `server_ip` column to those rows that have a `message` that matches +this pattern. For other rows, the value of `server_ip` is `null`. + +You can use the new `server_ip` column that's added by the `DISSECT` command in +subsequent commands. For example, to determine how many connections each server +has accepted: + +[source,esql] +---- +include::{esql-specs}/dissect.csv-spec[tag=gs-dissect-stats-by] +---- + +For more about data processing with {esql}, refer to +<>. + +[discrete] +[[esql-getting-learn-more]] +=== Learn more + +To learn more about {esql}, refer to <> and <>. \ No newline at end of file diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_kibana.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_kibana.asciidoc index 534cba22ed1a12..07502add5a6204 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_kibana.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_kibana.asciidoc @@ -1,15 +1,272 @@ [[esql-kibana]] -== Using {esql} in {kib} +=== Using {esql} in {kib} ++++ -Kibana +Using {esql} in {kib} ++++ +You can use {esql} in {kib} to query and aggregate your data, create +visualizations, and set up alerts. -Use {esql} in Discover to explore a data set. From the data view dropdown, -select *Try {esql}* to get started. +This guide shows you how to use {esql} in Kibana. To follow along with the +queries, load the "Sample web logs" sample data set by clicking *Try sample +data* from the {kib} Home, selecting *Other sample data sets*, and clicking *Add +data* on the *Sample web logs* card. -NOTE: {esql} queries in Discover and Lens are subject to the time range selected -with the time filter. +[discrete] +[[esql-kibana-get-started]] +=== Get started with {esql} +// tag::esql-mode[] +To get started with {esql} in Discover, open the main menu and select +*Discover*. Next, from the Data views menu, select *Try ES|QL*. +image::images/esql/esql-data-view-menu.png[align="center",width=33%] +// end::esql-mode[] + +The ability to select {esql} from the Data views menu can be enabled and +disabled using the `discover:enableESQL` setting from +{kibana-ref}/advanced-options.html[Advanced Settings]. + +[discrete] +[[esql-kibana-query-bar]] +=== The query bar + +After switching to {esql} mode, the query bar shows a sample query. For example: + +[source,esql] +---- +from kibana_sample_data_logs | limit 10 +---- + +Every query starts with a <>. In this query, the +source command is <>. `FROM` retrieves data from data streams, indices, or +aliases. In this example, the data is retrieved from `kibana_sample_data_logs`. + +A source command can be followed by one or more <>. In this query, the processing command is <>. `LIMIT` +limits the number of rows that are retrieved. + +TIP: Click the help icon (image:images/esql/esql-icon-help.svg[]) to open the +in-product reference documentation for all commands and functions. + +// tag::autocomplete[] +To make it easier to write queries, auto-complete offers suggestions with +possible commands and functions: + +image::images/esql/esql-kibana-auto-complete.png[align="center"] +// end::autocomplete[] + +[NOTE] +==== +{esql} keywords are case-insensitive. The following query is identical to the +previous one: + +[source,esql] +---- +FROM kibana_sample_data_logs | LIMIT 10 +---- +==== + +[discrete] +==== Expand the query bar + +For readability, you can put each processing command on a new line. The +following query is identical to the previous one: + +[source,esql] +---- +FROM kibana_sample_data_logs +| LIMIT 10 +---- + +// tag::compact[] +To make it easier to write multi-line queries, click the double-headed arrow +button (image:images/esql/esql-icon-expand-query-bar.svg[]) to expand the query +bar: + +image::images/esql/esql-expanded-query-bar.png[align="center"] + +To return to a compact query bar, click the minimize editor button +(image:images/esql/esql-icon-minimize-query-bar.svg[]). +// end::compact[] + +[discrete] +==== Warnings + +A query may result in warnings, for example when querying an unsupported field +type. When that happens, a warning symbol is shown in the query bar. To see the +detailed warning, expand the query bar, and click *warnings*. + +[discrete] +[[esql-kibana-results-table]] +=== The results table + +For the example query, the results table shows 10 rows. Omitting the `LIMIT` +command, the results table defaults to up to 500 rows. Using `LIMIT`, you can +increase the limit to up to 10,000 rows. + +NOTE: the 10,000 row 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. + +Each row shows two columns for the example query: a column with the `@timestamp` +field and a column with the full document. To display specific fields from the +documents, use the <> command: + +[source,esql] +---- +FROM kibana_sample_data_logs +| KEEP @timestamp, bytes, geo.dest +---- + +To display all fields as separate columns, use `KEEP *`: + +[source,esql] +---- +FROM kibana_sample_data_logs +| KEEP * +---- + +NOTE: The maximum number of columns in Discover is 50. If a query returns more +than 50 columns, Discover only shows the first 50. + +[discrete] +==== Sorting + +To sort on one of the columns, click the column name you want to sort on and +select the sort order. Note that this performs client-side sorting. It only +sorts the rows that were retrieved by the query, which may not be the full +dataset because of the (implicit) limit. To sort the full data set, use the +<> command: + +[source,esql] +---- +FROM kibana_sample_data_logs +| KEEP @timestamp, bytes, geo.dest +| SORT bytes DESC +---- + +[discrete] +[[esql-kibana-time-filter]] +=== Time filtering + +To display data within a specified time range, use the +{kibana-ref}/set-time-filter.html[time filter]. The time filter is only enabled +when the indices you're querying have a field called `@timestamp`. + +If your indices do not have a timestamp field called `@timestamp`, you can limit +the time range using the <> command and the <> function. +For example, if the timestamp field is called `timestamp`, to query the last 15 +minutes of data: +[source,esql] +---- +FROM kibana_sample_data_logs +| WHERE timestamp > NOW() - 15minutes +---- + +[discrete] +[[esql-kibana-visualizations]] +=== Analyze and visualize data + +Between the query bar and the results table, Discover shows a date histogram +visualization. If the indices you're querying do not contain an `@timestamp` +field, the histogram is not shown. + +The visualization adapts to the query. A query's nature determines the type of +visualization. For example, this query aggregates the total number of bytes per +destination country: + +[source,esql] +---- +FROM kibana_sample_data_logs +| STATS total_bytes = SUM(bytes) BY geo.dest +| SORT total_bytes DESC +| LIMIT 3 +---- + +The resulting visualization is a bar chart showing the top 3 countries: + +image::images/esql/esql-kibana-bar-chart.png[align="center"] + +To change the visualization into another type, click the visualization type +dropdown: + +image::images/esql/esql-kibana-visualization-type.png[align="center",width=33%] + +To make other changes to the visualization, like the axes and colors, click the +pencil button (image:images/esql/esql-icon-edit-visualization.svg[]). This opens +an in-line editor: + +image::images/esql/esql-kibana-in-line-editor.png[align="center"] + +You can save the visualization to a new or existing dashboard by clicking the +save button (image:images/esql/esql-icon-save-visualization.svg[]). Once saved +to a dashboard, you can continue to make changes to visualization. Click the +options button in the top-right (image:images/esql/esql-icon-options.svg[]) and +select *Edit ESQL visualization* to open the in-line editor: + +image::images/esql/esql-kibana-edit-on-dashboard.png[align="center"] + +[discrete] +[[esql-kibana-enrich]] +=== Create an enrich policy + +The {esql} <> command enables you to <> +your query dataset with fields from another dataset. Before you can use +`ENRICH`, you need to <>. If a policy exists, it will be suggested by auto-complete. If not, +click *Click to create* to create one. + +image::images/esql/esql-kibana-enrich-autocomplete.png[align="center"] + +Next, you can enter a policy name, the policy type, source indices, and +optionally a query: + +image::images/esql/esql-kibana-enrich-step-1.png[align="center",width="50%"] + +Click *Next* to select the match field and enrich fields: + +image::images/esql/esql-kibana-enrich-step-2.png[align="center",width="50%"] + +Finally, click *Create and execute*. + +Now, you can use the enrich policy in an {esql} query: + +image::images/esql/esql-kibana-enriched-data.png[align="center"] + +[discrete] +[[esql-kibana-alerting-rule]] +=== Create an alerting rule + +You can use {esql} queries to create alerts. From Discover, click *Alerts* and +select *Create search threshold rule*. This opens a panel that enables you to +create a rule using an {esql} query. Next, you can test the query, add a +connector, and save the rule. + +image::images/esql/esql-kibana-create-rule.png[align="center",width=50%] + +[discrete] +[[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 <> 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. 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. +* CSV export from 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. Queries and +aggregations run on the full data set. +* Querying 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 <> or +<> to limit the number of fields returned. +// end::limitations[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_language.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_language.asciidoc index 2becd04cec948a..8ffc0af7cbeb2c 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_language.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_language.asciidoc @@ -1,8 +1,8 @@ [[esql-language]] -== Working with the {esql} language +== Learning {esql} ++++ -Working with the {esql} language +Learning {esql} ++++ Detailed information about the {esql} language: @@ -10,14 +10,15 @@ Detailed information about the {esql} language: * <> * <> * <> -* <> * <> +* <> * <> +* <> include::esql-syntax.asciidoc[] include::esql-commands.asciidoc[] include::esql-functions-operators.asciidoc[] -include::multivalued-fields.asciidoc[] include::metadata-fields.asciidoc[] -include::esql-enrich-data.asciidoc[] - +include::multivalued-fields.asciidoc[] +include::esql-process-data-with-dissect-grok.asciidoc[] +include::esql-enrich-data.asciidoc[] \ No newline at end of file diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_limitations.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_limitations.asciidoc index f39ff737442764..f3b3dd824fb22d 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_limitations.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_limitations.asciidoc @@ -5,28 +5,196 @@ Limitations ++++ +[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 <> command. +include::processing-commands/limit.asciidoc[tag=limitation] + [discrete] [[esql-supported-types]] -=== Supported types +=== Field types -* {esql} currently supports the following <>: +[discrete] +==== Supported types + +{esql} currently supports the following <>: -** `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` +* Spatial types +** `geo_point` +** `geo_shape` +** `point` +** `shape` [discrete] -[[esql-max-rows]] -=== 10,000 row maximum +==== Unsupported types + +{esql} does not yet support the following field types: + +* TSDB metrics +** `counter` +** `position` +** `aggregate_metric_double` +* Date/time +** `date_nanos` +** `date_range` +* Other types +** `binary` +** `completion` +** `dense_vector` +** `double_range` +** `flattened` +** `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-full-text-search]] +=== Full-text search is not supported + +Because of <>, +full-text search is not yet supported. Queries on `text` fields are like queries +on `keyword` fields: they are case-sensitive and need to match the full string. + +For example, after indexing a field of type `text` with the value `Elasticsearch +query language`, the following `WHERE` clause does not match because the `LIKE` +operator is case-sensitive: +[source,esql] +---- +| WHERE field LIKE "elasticsearch query language" +---- + +The following `WHERE` clause does not match either, because the `LIKE` operator +tries to match the whole string: +[source,esql] +---- +| WHERE field LIKE "Elasticsearch" +---- + +As a workaround, use wildcards and regular expressions. For example: +[source,esql] +---- +| WHERE field RLIKE "[Ee]lasticsearch.*" +---- + +[discrete] +[[esql-limitations-text-fields]] +=== `text` fields behave like `keyword` fields + +While {esql} supports <> fields, {esql} does not treat these fields +like the Search API does. {esql} queries do not query or aggregate the +<>. Instead, an {esql} query will try to get a `text` +field's subfield of the <> 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 <>, which can +transform the original string. Or it may have been mapped with <>, +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]] +=== Time series data streams are not supported + +{esql} does not support querying time series data streams (TSDS). + +[discrete] +[[esql-limitations-ccs]] +=== {ccs-cap} is not supported + +{esql} does not support {ccs}. + +[discrete] +[[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-dissect]] +=== Dissect limitations + +include::esql-process-data-with-dissect-grok.asciidoc[tag=dissect-limitations] + +[discrete] +[[esql-limitations-grok]] +=== Grok limitations + +include::esql-process-data-with-dissect-grok.asciidoc[tag=grok-limitations] + +[discrete] +[[esql-limitations-mv]] +=== Multivalue limitations + +{esql} <>, 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 <>. + +[discrete] +[[esql-limitations-timezone]] +=== Timezone support + +{esql} only supports the UTC timezone. + +[discrete] +[[esql-limitations-kibana]] +=== Kibana limitations -A single query will not return more than 10,000 rows, regardless of the -`LIMIT` command's value. \ No newline at end of file +include::esql-kibana.asciidoc[tag=limitations] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_process_data_with_dissect_grok.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_process_data_with_dissect_grok.asciidoc new file mode 100644 index 00000000000000..87748fee4f2025 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_process_data_with_dissect_grok.asciidoc @@ -0,0 +1,321 @@ +[[esql-process-data-with-dissect-and-grok]] +=== Data processing with DISSECT and GROK + +++++ +Data processing with DISSECT and GROK +++++ + +Your data may contain unstructured strings that you want to structure. This +makes it easier to analyze the data. For example, log messages may contain IP +addresses that you want to extract so you can find the most active IP addresses. + +image::images/esql/unstructured-data.png[align="center",width=75%] + +{es} can structure your data at index time or query time. At index time, you can +use the <> and <> ingest +processors, or the {ls} {logstash-ref}/plugins-filters-dissect.html[Dissect] and +{logstash-ref}/plugins-filters-grok.html[Grok] filters. At query time, you can +use the {esql} <> and <> commands. + +[[esql-grok-or-dissect]] +==== `DISSECT` or `GROK`? Or both? + +`DISSECT` works by breaking up a string using a delimiter-based pattern. `GROK` +works similarly, but uses regular expressions. This makes `GROK` more powerful, +but generally also slower. `DISSECT` works well when data is reliably repeated. +`GROK` is a better choice when you really need the power of regular expressions, +for example when the structure of your text varies from row to row. + +You can use both `DISSECT` and `GROK` for hybrid use cases. For example when a +section of the line is reliably repeated, but the entire line is not. `DISSECT` +can deconstruct the section of the line that is repeated. `GROK` can process the +remaining field values using regular expressions. + +[[esql-process-data-with-dissect]] +==== Process data with `DISSECT` + +The <> processing command matches a string against a +delimiter-based pattern, and extracts the specified keys as columns. + +For example, the following pattern: +[source,txt] +---- +%{clientip} [%{@timestamp}] %{status} +---- + +matches a log line of this format: +[source,txt] +---- +1.2.3.4 [2023-01-23T12:15:00.000Z] Connected +---- + +and results in adding the following columns to the input table: + +[%header.monospaced.styled,format=dsv,separator=|] +|=== +clientip:keyword | @timestamp:keyword | status:keyword +1.2.3.4 | 2023-01-23T12:15:00.000Z | Connected +|=== + +[[esql-dissect-patterns]] +===== Dissect patterns + +include::../ingest/processors/dissect.asciidoc[tag=intro-example-explanation] + +An empty key (`%{}`) or <> can be used to +match values, but exclude the value from the output. + +All matched values are output as keyword string data types. Use the +<> to convert to another data type. + +Dissect also supports <> that can +change dissect's default behavior. For example, you can instruct dissect to +ignore certain fields, append fields, skip over padding, etc. + +[[esql-dissect-terminology]] +===== Terminology + +dissect pattern:: +the set of fields and delimiters describing the textual +format. Also known as a dissection. +The dissection is described using a set of `%{}` sections: +`%{a} - %{b} - %{c}` + +field:: +the text from `%{` to `}` inclusive. + +delimiter:: +the text between `}` and the next `%{` characters. +Any set of characters other than `%{`, `'not }'`, or `}` is a delimiter. + +key:: ++ +-- +the text between the `%{` and `}`, exclusive of the `?`, `+`, `&` prefixes +and the ordinal suffix. + +Examples: + +* `%{?aaa}` - the key is `aaa` +* `%{+bbb/3}` - the key is `bbb` +* `%{&ccc}` - the key is `ccc` +-- + +[[esql-dissect-examples]] +===== Examples + +include::processing-commands/dissect.asciidoc[tag=examples] + +[[esql-dissect-key-modifiers]] +===== Dissect key modifiers + +include::../ingest/processors/dissect.asciidoc[tag=dissect-key-modifiers] + +[[esql-dissect-key-modifiers-table]] +.Dissect key modifiers +[options="header",role="styled"] +|====== +| Modifier | Name | Position | Example | Description | Details +| `->` | Skip right padding | (far) right | `%{keyname1->}` | Skips any repeated characters to the right | <> +| `+` | Append | left | `%{+keyname} %{+keyname}` | Appends two or more fields together | <> +| `+` with `/n` | Append with order | left and right | `%{+keyname/2} %{+keyname/1}` | Appends two or more fields together in the order specified | <> +| `?` | Named skip key | left | `%{?ignoreme}` | Skips the matched value in the output. Same behavior as `%{}`| <> +|====== + +[[esql-dissect-modifier-skip-right-padding]] +====== Right padding modifier (`->`) +include::../ingest/processors/dissect.asciidoc[tag=dissect-modifier-skip-right-padding] + +For example: +[source.merge.styled,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=dissectRightPaddingModifier] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/docs.csv-spec[tag=dissectRightPaddingModifier-result] +|=== + +include::../ingest/processors/dissect.asciidoc[tag=dissect-modifier-empty-right-padding] + +For example: +[source.merge.styled,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=dissectEmptyRightPaddingModifier] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/docs.csv-spec[tag=dissectEmptyRightPaddingModifier-result] +|=== + +[[esql-append-modifier]] +====== Append modifier (`+`) +include::../ingest/processors/dissect.asciidoc[tag=append-modifier] + +[source.merge.styled,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=dissectAppendModifier] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/docs.csv-spec[tag=dissectAppendModifier-result] +|=== + +[[esql-append-order-modifier]] +====== Append with order modifier (`+` and `/n`) +include::../ingest/processors/dissect.asciidoc[tag=append-order-modifier] + +[source.merge.styled,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=dissectAppendWithOrderModifier] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/docs.csv-spec[tag=dissectAppendWithOrderModifier-result] +|=== + +[[esql-named-skip-key]] +====== Named skip key (`?`) +include::../ingest/processors/dissect.asciidoc[tag=named-skip-key] +This can be done with a named skip key using the `{?name}` syntax. In the +following query, `ident` and `auth` are not added to the output table: + +[source.merge.styled,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=dissectNamedSkipKey] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/docs.csv-spec[tag=dissectNamedSkipKey-result] +|=== + +[[esql-dissect-limitations]] +===== Limitations + +// tag::dissect-limitations[] +The `DISSECT` command does not support reference keys. +// end::dissect-limitations[] + +[[esql-process-data-with-grok]] +==== Process data with `GROK` + +The <> processing command matches a string against a pattern based on +regular expressions, and extracts the specified keys as columns. + +For example, the following pattern: +[source,txt] +---- +%{IP:ip} \[%{TIMESTAMP_ISO8601:@timestamp}\] %{GREEDYDATA:status} +---- + +matches a log line of this format: +[source,txt] +---- +1.2.3.4 [2023-01-23T12:15:00.000Z] Connected +---- + +Putting it together as an {esql} query: + +[source.merge.styled,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=grokWithEscape] +---- + +`GROK` adds the following columns to the input table: + +[%header.monospaced.styled,format=dsv,separator=|] +|=== +@timestamp:keyword | ip:keyword | status:keyword +2023-01-23T12:15:00.000Z | 1.2.3.4 | Connected +|=== + +[NOTE] +==== + +Special regex characters in grok patterns, like `[` and `]` need to be escaped +with a `\`. For example, in the earlier pattern: +[source,txt] +---- +%{IP:ip} \[%{TIMESTAMP_ISO8601:@timestamp}\] %{GREEDYDATA:status} +---- + +In {esql} queries, the backslash character itself is a special character that +needs to be escaped with another `\`. For this example, the corresponding {esql} +query becomes: +[source.merge.styled,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=grokWithEscape] +---- +==== + +[[esql-grok-patterns]] +===== Grok patterns + +The syntax for a grok pattern is `%{SYNTAX:SEMANTIC}` + +The `SYNTAX` is the name of the pattern that matches your text. For example, +`3.44` is matched by the `NUMBER` pattern and `55.3.244.1` is matched by the +`IP` pattern. The syntax is how you match. + +The `SEMANTIC` is the identifier you give to the piece of text being matched. +For example, `3.44` could be the duration of an event, so you could call it +simply `duration`. Further, a string `55.3.244.1` might identify the `client` +making a request. + +By default, matched values are output as keyword string data types. To convert a +semantic's data type, suffix it with the target data type. For example +`%{NUMBER:num:int}`, which converts the `num` semantic from a string to an +integer. Currently the only supported conversions are `int` and `float`. For +other types, use the <>. + +For an overview of the available patterns, refer to +{es-repo}/blob/{branch}/libs/grok/src/main/resources/patterns[GitHub]. You can +also retrieve a list of all patterns using a <>. + +[[esql-grok-regex]] +===== Regular expressions + +Grok is based on regular expressions. Any regular expressions are valid in grok +as well. Grok uses the Oniguruma regular expression library. Refer to +https://github.com/kkos/oniguruma/blob/master/doc/RE[the Oniguruma GitHub +repository] for the full supported regexp syntax. + +[[esql-custom-patterns]] +===== Custom patterns + +If grok doesn't have a pattern you need, you can use the Oniguruma syntax for +named capture which lets you match a piece of text and save it as a column: +[source,txt] +---- +(?the pattern here) +---- + +For example, postfix logs have a `queue id` that is a 10 or 11-character +hexadecimal value. This can be captured to a column named `queue_id` with: +[source,txt] +---- +(?[0-9A-F]{10,11}) +---- + +[[esql-grok-examples]] +===== Examples + +include::processing-commands/grok.asciidoc[tag=examples] + +[[esql-grok-debugger]] +===== Grok debugger + +To write and debug grok patterns, you can use the +{kibana-ref}/xpack-grokdebugger.html[Grok Debugger]. It provides a UI for +testing patterns against sample data. Under the covers, it uses the same engine +as the `GROK` command. + +[[esql-grok-limitations]] +===== Limitations + +// tag::grok-limitations[] +The `GROK` command does not support configuring <>, or <>. The `GROK` command is not +subject to <>. +// end::grok-limitations[] \ No newline at end of file diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_query_api.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_query_api.asciidoc index 437871d31a88fb..d7fa25a5a8d4f2 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_query_api.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_query_api.asciidoc @@ -1,5 +1,5 @@ [[esql-query-api]] -== {esql} query API +=== {esql} query API ++++ {esql} query API ++++ @@ -23,13 +23,13 @@ POST /_query [discrete] [[esql-query-api-request]] -=== {api-request-title} +==== {api-request-title} `POST _query` [discrete] [[esql-query-api-prereqs]] -=== {api-prereq-title} +==== {api-prereq-title} * If the {es} {security-features} are enabled, you must have the `read` <> for the data stream, index, @@ -37,12 +37,18 @@ or alias you search. [discrete] [[esql-query-api-query-params]] -=== {api-query-parms-title} +==== {api-query-parms-title} `delimiter`:: (Optional, string) Separator for CSV results. Defaults to `,`. The API only supports this parameter for CSV responses. +`drop_null_columns`:: +(Optional, boolean) Should columns that are entirely `null` be removed from +the `columns` and `values` portion of the results? Defaults to `false`. If +`true` the the response will include an extra section under the name +`all_columns` which has the name of all columns. + `format`:: (Optional, string) Format for the response. For valid values, refer to <>. @@ -54,13 +60,17 @@ precedence. [discrete] [role="child_attributes"] [[esql-query-api-request-body]] -=== {api-request-body-title} +==== {api-request-body-title} `columnar`:: (Optional, Boolean) If `true`, returns results in a columnar format. Defaults to `false`. The API only supports this parameter for CBOR, JSON, SMILE, and YAML responses. See <>. +`locale`:: +(Optional, string) Returns results (especially dates) formatted per the conventions of the locale. +For syntax, refer to <>. + `params`:: (Optional, array) Values for parameters in the `query`. For syntax, refer to <>. @@ -68,29 +78,19 @@ responses. See <>. `query`:: (Required, object) {esql} query to run. For syntax, refer to <>. -[[esql-search-api-time-zone]] -`time_zone`:: -(Optional, string) ISO-8601 time zone ID for the search. Several {esql} -date/time functions use this time zone. Defaults to `Z` (UTC). - [discrete] [role="child_attributes"] [[esql-query-api-response-body]] -=== {api-response-body-title} +==== {api-response-body-title} `columns`:: (array of objects) -Column headings for the search results. Each object is a column. -+ -.Properties of `columns` objects -[%collapsible%open] -==== -`name`:: -(string) Name of the column. - -`type`:: -(string) Data type for the column. -==== +Column `name` and `type` for each column returned in `values`. Each object is a single column. + +`all_columns`:: +(array of objects) +Column `name` and `type` for each queried column. Each object is a single column. This is only +returned if `drop_null_columns` is sent with the request. `rows`:: (array of arrays) diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_rest.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_rest.asciidoc index 55c9946ad08b43..fc06cfea904af6 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_rest.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_rest.asciidoc @@ -1,5 +1,5 @@ [[esql-rest]] -== {esql} REST API +=== {esql} REST API ++++ REST API @@ -38,7 +38,7 @@ James S.A. Corey |Leviathan Wakes |561 |2011-06-02T00:00:00.000Z [discrete] [[esql-kibana-console]] -=== Kibana Console +==== Kibana Console If you are using {kibana-ref}/console-kibana.html[Kibana Console] (which is highly recommended), take advantage of the triple quotes `"""` when creating the @@ -62,7 +62,7 @@ POST /_query?format=txt [discrete] [[esql-rest-format]] -=== Response formats +==== Response formats {esql} can return the data in the following human readable and binary formats. You can set the format by specifying the `format` parameter in the URL or by @@ -121,7 +121,7 @@ Use the `tsv` format instead. [discrete] [[esql-rest-filtering]] -=== Filtering using {es} Query DSL +==== Filtering using {es} Query DSL Specify a Query DSL query in the `filter` parameter to filter the set of documents that an {esql} query runs on. @@ -161,7 +161,7 @@ Douglas Adams |The Hitchhiker's Guide to the Galaxy|180 |1979-10-12T [discrete] [[esql-rest-columnar]] -=== Columnar results +==== Columnar results By default, {esql} returns results as rows. For example, `FROM` returns each individual document as one row. For the `json`, `yaml`, `cbor` and `smile` @@ -204,9 +204,36 @@ Which returns: } ---- +[discrete] +[[esql-locale-param]] +==== Returning localized results + +Use the `locale` parameter in the request body to return results (especially dates) formatted per the conventions of the locale. +If `locale` is not specified, defaults to `en-US` (English). +Refer to https://www.oracle.com/java/technologies/javase/jdk17-suported-locales.html[JDK Supported Locales]. + +Syntax: the `locale` parameter accepts language tags in the (case-insensitive) format `xy` and `xy-XY`. + +For example, to return a month name in French: + +[source,console] +---- +POST /_query +{ + "locale": "fr-FR", + "query": """ + ROW birth_date_string = "2023-01-15T00:00:00.000Z" + | EVAL birth_date = date_parse(birth_date_string) + | EVAL month_of_birth = DATE_FORMAT("MMMM",birth_date) + | LIMIT 5 + """ +} +---- +// TEST[setup:library] + [discrete] [[esql-rest-params]] -=== Passing parameters to a query +==== Passing parameters to a query Values, for example for a condition, can be passed to a query "inline", by integrating the value in the query string itself: @@ -247,3 +274,89 @@ POST /_query } ---- // TEST[setup:library] + +[discrete] +[[esql-rest-async-query]] +==== Running an async {esql} query + +The <> lets you asynchronously +execute a query request, monitor its progress, and retrieve results when +they become available. + +Executing an {esql} query is commonly quite fast, however queries across +large data sets or frozen data can take some time. To avoid long waits, +run an async {esql} query. + +Queries initiated by the async query API may return results or not. The +`wait_for_completion_timeout` property determines how long to wait for +the results. If the results are not available by this time, a +<> is returned which +can be later used to retrieve the results. For example: + +[source,console] +---- +POST /_query/async +{ + "query": """ + FROM library + | EVAL year = DATE_TRUNC(1 YEARS, release_date) + | STATS MAX(page_count) BY year + | SORT year + | LIMIT 5 + """, + "wait_for_completion_timeout": "2s" +} +---- +// TEST[setup:library] + +If the results are not available within the given timeout period, 2 +seconds in this case, no results are returned but rather a response that +includes: + +* A query ID +* An `is_running` value of _true_, indicating the query is ongoing + +The query continues to run in the background without blocking other +requests. + +[source,console-result] +---- +{ + "id": "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=", + "is_running": true +} +---- +// TEST[skip: no access to query ID - may return response values] + +To check the progress of an async query, use the <> with the query ID. Specify how long you'd like +to wait for complete results in the `wait_for_completion_timeout` parameter. + +[source,console] +---- +GET /_query/async/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=?wait_for_completion_timeout=30s +---- +// TEST[skip: no access to query ID - may return response values] + +If the response's `is_running` value is `false`, the query has finished +and the results are returned. + +[source,console-result] +---- +{ + "is_running": false, + "columns": ... +} +---- +// TEST[skip: no access to query ID - may return response values] + +Use the <> to +delete an async query before the `keep_alive` period ends. If the query +is still running, {es} cancels it. + +[source,console] +---- +DELETE /_query/async/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI= +---- +// TEST[skip: no access to query ID] + diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_security_solution.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_security_solution.asciidoc new file mode 100644 index 00000000000000..24766a5ef93f19 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_security_solution.asciidoc @@ -0,0 +1,41 @@ +[[esql-elastic-security]] +=== Using {esql} in {elastic-sec} + +++++ +Using {esql} in {elastic-sec} +++++ + +You can use {esql} in {elastic-sec} to investigate events in Timeline and create +detection rules. Use the Elastic AI Assistant to build {esql} queries, or answer +questions about the {esql} query language. + +[discrete] +[[esql-elastic-security-timeline]] +=== Use {esql} to investigate events in Timeline + +You can use {esql} in Timeline to filter, transform, and analyze event data +stored in {es}. To start using {esql}, open the **{esql}** tab. To learn +more, refer to {security-guide}/timelines-ui.html#esql-in-timeline[Investigate +events in Timeline]. + +[discrete] +[[esql-elastic-security-detection-rules]] +=== Use {esql} to create detection rules + +Use the {esql} rule type to create detection rules using {esql} queries. The +{esql} rule type supports aggregating and non-aggregating queries. To learn +more, refer to {security-guide}/rules-ui-create.html#create-esql-rule[Create an +{esql} rule]. + +[discrete] +[[esql-elastic-security-ai-assistant]] +=== Elastic AI Assistant + +Use the Elastic AI Assistant to build {esql} queries, or answer questions about +the {esql} query language. To learn more, refer to +{security-guide}/security-assistant.html[AI Assistant]. + +NOTE: For AI Assistant to answer questions about {esql} and write {esql} +queries, you need to +{security-guide}/security-assistant.html#set-up-ai-assistant[enable knowledge +base]. diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_syntax.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_syntax.asciidoc index 725b1d3ff1e035..c5d56ef15fdfde 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_syntax.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_syntax.asciidoc @@ -9,7 +9,7 @@ [[esql-basic-syntax]] === Basic syntax -An {esql} query is composed of a <> followed +An {esql} query is composed of a <> followed by an optional series of <>, separated by a pipe character: `|`. For example: @@ -36,6 +36,92 @@ source-command | processing-command1 | processing-command2 ---- ==== +[discrete] +[[esql-identifiers]] +==== Identifiers + +Identifiers need to be quoted with backticks (+{backtick}+) if: + +* they don't start with a letter, `_` or `@` +* any of the other characters is not a letter, number, or `_` + +For example: + +[source,esql] +---- +FROM index +| KEEP `1.field` +---- + +When referencing a function alias that itself uses a quoted identifier, the +backticks of the quoted identifier need to be escaped with another backtick. For +example: + +[source,esql] +---- +FROM index +| STATS COUNT(`1.field`) +| EVAL my_count = `COUNT(``1.field``)` +---- + +[discrete] +[[esql-literals]] +==== Literals + +{esql} currently supports numeric and string literals. + +[discrete] +[[esql-string-literals]] +===== String literals + +A string literal is a sequence of unicode characters delimited by double +quotes (`"`). + +[source,esql] +---- +// Filter by a string value +FROM index +| WHERE first_name == "Georgi" +---- + +If the literal string itself contains quotes, these need to be escaped (`\\"`). +{esql} also supports the triple-quotes (`"""`) delimiter, for convenience: + +[source,esql] +---- +ROW name = """Indiana "Indy" Jones""" +---- + +The special characters CR, LF and TAB can be provided with the usual escaping: +`\r`, `\n`, `\t`, respectively. + +[discrete] +[[esql-numeric-literals]] +===== Numerical literals + +The numeric literals are accepted in decimal and in the scientific notation +with the exponent marker (`e` or `E`), starting either with a digit, decimal +point `.` or the negative sign `-`: + +[source, sql] +---- +1969 -- integer notation +3.14 -- decimal notation +.1234 -- decimal notation starting with decimal point +4E5 -- scientific notation (with exponent marker) +1.2e-3 -- scientific notation with decimal point +-.1e2 -- scientific notation starting with the negative sign +---- + +The integer numeric literals are implicitly converted to the `integer`, `long` +or the `double` type, whichever can first accommodate the literal's value. + +The floating point literals are implicitly converted the `double` type. + +To obtain constant values of different types, use one of the numeric +<>. + + [discrete] [[esql-comments]] ==== Comments diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_using.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_using.asciidoc new file mode 100644 index 00000000000000..f11fdd2d058a59 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/esql_using.asciidoc @@ -0,0 +1,21 @@ +[[esql-using]] +== Using {esql} + +<>:: +Information about using the <>. + +<>:: +Using {esql} in {kib} to query and aggregate your data, create visualizations, +and set up alerts. + +<>:: +Using {esql} in {elastic-sec} to investigate events in Timeline, create +detection rules, and build {esql} queries using Elastic AI Assistant. + +<>:: +Using the <> to list and cancel {esql} queries. + +include::esql-rest.asciidoc[] +include::esql-kibana.asciidoc[] +include::esql-security-solution.asciidoc[] +include::task-management.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/abs.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/abs.asciidoc index 3adb7dff07043a..32b49bc287a833 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/abs.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/abs.asciidoc @@ -1,18 +1,41 @@ [discrete] [[esql-abs]] === `ABS` + +*Syntax* + [.text-center] image::esql/functions/signature/abs.svg[Embedded,opts=inline] +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + Returns the absolute value. -[source,esql] +*Supported types* + +include::types/abs.asciidoc[] + +*Examples* + +[source.merge.styled,esql] ---- -FROM employees -| KEEP first_name, last_name, height -| EVAL abs_height = ABS(0.0 - height) +include::{esql-specs}/math.csv-spec[tag=docsAbs] ---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/math.csv-spec[tag=docsAbs-result] +|=== -Supported types: - -include::types/abs.asciidoc[] +[source.merge.styled,esql] +---- +include::{esql-specs}/math.csv-spec[tag=docsAbsEmployees] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/math.csv-spec[tag=docsAbsEmployees-result] +|=== \ No newline at end of file diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/aggregation_functions.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/aggregation_functions.asciidoc index bd501ea49f1582..91293728fd45c3 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/aggregation_functions.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/aggregation_functions.asciidoc @@ -16,6 +16,7 @@ The <> function supports these aggregate functions: * <> * <> * <> +* <> * <> // end::agg_list[] @@ -27,4 +28,5 @@ include::median.asciidoc[] include::median-absolute-deviation.asciidoc[] include::min.asciidoc[] include::percentile.asciidoc[] +include::st_centroid.asciidoc[] include::sum.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/asin.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/asin.asciidoc index f03b5276b7dd6e..a326852e9b0160 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/asin.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/asin.asciidoc @@ -1,10 +1,27 @@ [discrete] [[esql-asin]] === `ASIN` + +*Syntax* + [.text-center] image::esql/functions/signature/asin.svg[Embedded,opts=inline] -Inverse https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[sine] trigonometric function. +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +Returns the {wikipedia}/Inverse_trigonometric_functions[arcsine] of the input +numeric expression as an angle, expressed in radians. + +*Supported types* + +include::types/asin.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,7 +31,3 @@ include::{esql-specs}/floats.csv-spec[tag=asin] |=== include::{esql-specs}/floats.csv-spec[tag=asin-result] |=== - -Supported types: - -include::types/asin.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/atan.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/atan.asciidoc index 3813e096aeba1a..604fc4d0bbecc5 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/atan.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/atan.asciidoc @@ -1,10 +1,27 @@ [discrete] [[esql-atan]] === `ATAN` + +*Syntax* + [.text-center] image::esql/functions/signature/atan.svg[Embedded,opts=inline] -Inverse https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[tangent] trigonometric function. +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +Returns the {wikipedia}/Inverse_trigonometric_functions[arctangent] of the input +numeric expression as an angle, expressed in radians. + +*Supported types* + +include::types/atan.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -13,8 +30,4 @@ include::{esql-specs}/floats.csv-spec[tag=atan] [%header.monospaced.styled,format=dsv,separator=|] |=== include::{esql-specs}/floats.csv-spec[tag=atan-result] -|=== - -Supported types: - -include::types/atan.asciidoc[] +|=== \ No newline at end of file diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/atan2.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/atan2.asciidoc index e78a219333344b..1920b4b7ac1a0c 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/atan2.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/atan2.asciidoc @@ -1,11 +1,30 @@ [discrete] [[esql-atan2]] === `ATAN2` + +*Syntax* + [.text-center] image::esql/functions/signature/atan2.svg[Embedded,opts=inline] -The https://en.wikipedia.org/wiki/Atan2[angle] between the positive x-axis and the -ray from the origin to the point (x , y) in the Cartesian plane. +*Parameters* + +`y`:: +Numeric expression. If `null`, the function returns `null`. + +`x`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +The {wikipedia}/Atan2[angle] between the positive x-axis and the ray from the +origin to the point (x , y) in the Cartesian plane, expressed in radians. + +*Supported types* + +include::types/atan2.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -15,7 +34,3 @@ include::{esql-specs}/floats.csv-spec[tag=atan2] |=== include::{esql-specs}/floats.csv-spec[tag=atan2-result] |=== - -Supported types: - -include::types/atan2.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/auto_bucket.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/auto_bucket.asciidoc index 47e453f3822298..aedfdaa7c0e125 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/auto_bucket.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/auto_bucket.asciidoc @@ -1,72 +1,118 @@ [discrete] [[esql-auto_bucket]] === `AUTO_BUCKET` -Creates human-friendly buckets and returns a `datetime` value for each row that -corresponds to the resulting bucket the row falls into. Combine `AUTO_BUCKET` -with <> to create a date histogram. -You provide a target number of buckets, a start date, and an end date, and it -picks an appropriate bucket size to generate the target number of buckets or -fewer. For example, this asks for at most 20 buckets over a whole year, which -picks monthly buckets: +*Syntax* + +[source,esql] +---- +AUTO_BUCKET(expression, buckets, from, to) +---- + +*Parameters* + +`field`:: +Numeric or date expression from which to derive buckets. + +`buckets`:: +Target number of buckets. + +`from`:: +Start of the range. Can be a number or a date expressed as a string. + +`to`:: +End of the range. Can be a number or a date expressed as a string. + +*Description* + +Creates human-friendly buckets and returns a value for each row that corresponds +to the resulting bucket the row falls into. + +Using a target number of buckets, a start of a range, and an end of a range, +`AUTO_BUCKET` picks an appropriate bucket size to generate the target number of +buckets or fewer. For example, asking for at most 20 buckets over a year results +in monthly buckets: [source.merge.styled,esql] ---- -include::{esql-specs}/date.csv-spec[tag=auto_bucket_month] +include::{esql-specs}/date.csv-spec[tag=docsAutoBucketMonth] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/date.csv-spec[tag=auto_bucket_month-result] +include::{esql-specs}/date.csv-spec[tag=docsAutoBucketMonth-result] |=== The goal isn't to provide *exactly* the target number of buckets, it's to pick a -range that people are comfortable with that provides at most the target number of -buckets. +range that people are comfortable with that provides at most the target number +of buckets. -If you ask for more buckets then `AUTO_BUCKET` can pick a smaller range. For example, -asking for at most 100 buckets in a year will get you week long buckets: +Combine `AUTO_BUCKET` with +<> to create a histogram: [source.merge.styled,esql] ---- -include::{esql-specs}/date.csv-spec[tag=auto_bucket_week] +include::{esql-specs}/date.csv-spec[tag=docsAutoBucketMonthlyHistogram] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/date.csv-spec[tag=auto_bucket_week-result] +include::{esql-specs}/date.csv-spec[tag=docsAutoBucketMonthlyHistogram-result] |=== -`AUTO_BUCKET` does not filter any rows. It only uses the provided time range to -pick a good bucket size. For rows with a date outside of the range, it returns a -`datetime` that corresponds to a bucket outside the range. Combine `AUTO_BUCKET` -with <> to filter rows. +NOTE: `AUTO_BUCKET` does not create buckets that don't match any documents. +That's why this example is missing `1985-03-01` and other dates. -A more complete example might look like: +Asking for more buckets can result in a smaller range. For example, asking for +at most 100 buckets in a year results in weekly buckets: [source.merge.styled,esql] ---- -include::{esql-specs}/date.csv-spec[tag=auto_bucket_in_agg] +include::{esql-specs}/date.csv-spec[tag=docsAutoBucketWeeklyHistogram] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/date.csv-spec[tag=auto_bucket_in_agg-result] +include::{esql-specs}/date.csv-spec[tag=docsAutoBucketWeeklyHistogram-result] |=== -NOTE: `AUTO_BUCKET` does not create buckets that don't match any documents. That's -why the example above is missing `1985-03-01` and other dates. +NOTE: `AUTO_BUCKET` does not filter any rows. It only uses the provided range to +pick a good bucket size. For rows with a value outside of the range, it returns +a bucket value that corresponds to a bucket outside the range. Combine +`AUTO_BUCKET` with <> to filter rows. -==== Numeric fields +`AUTO_BUCKET` can also operate on numeric fields. For example, to create a +salary histogram: -`auto_bucket` can also operate on numeric fields like this: [source.merge.styled,esql] ---- -include::{esql-specs}/ints.csv-spec[tag=auto_bucket] +include::{esql-specs}/ints.csv-spec[tag=docsAutoBucketNumeric] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/ints.csv-spec[tag=auto_bucket-result] +include::{esql-specs}/ints.csv-spec[tag=docsAutoBucketNumeric-result] |=== -Unlike the example above where you are intentionally filtering on a date range, -you rarely want to filter on a numeric range. So you have find the `min` and `max` -separately. We don't yet have an easy way to do that automatically. Improvements -coming! +Unlike the earlier example that intentionally filters on a date range, you +rarely want to filter on a numeric range. You have to find the `min` and `max` +separately. {esql} doesn't yet have an easy way to do that automatically. + +*Examples* + +Create hourly buckets for the last 24 hours, and calculate the number of events +per hour: + + +[source.styled,esql] +---- +include::{esql-specs}/date.csv-spec[tag=docsAutoBucketLast24hr] +---- + +Create monthly buckets for the year 1985, and calculate the average salary by +hiring month: + +[source.merge.styled,esql] +---- +include::{esql-specs}/date.csv-spec[tag=auto_bucket_in_agg] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/date.csv-spec[tag=auto_bucket_in_agg-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/avg.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/avg.asciidoc index 972d30545ceb44..7eadff29f1bfc3 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/avg.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/avg.asciidoc @@ -1,7 +1,28 @@ [discrete] [[esql-agg-avg]] === `AVG` -The average of a numeric field. + +*Syntax* + +[source,esql] +---- +AVG(expression) +---- + +`expression`:: +Numeric expression. +//If `null`, the function returns `null`. +// TODO: Remove comment when https://github.com/elastic/elasticsearch/issues/104900 is fixed. + +*Description* + +The average of a numeric expression. + +*Supported types* + +The result is always a `double` no matter the input type. + +*Examples* [source.merge.styled,esql] ---- @@ -12,4 +33,15 @@ include::{esql-specs}/stats.csv-spec[tag=avg] include::{esql-specs}/stats.csv-spec[tag=avg-result] |=== -The result is always a `double` not matter the input type. +The expression can use inline functions. For example, to calculate the average +over a multivalued column, first use `MV_AVG` to average the multiple values per +row, and use the result with the `AVG` function: + +[source.merge.styled,esql] +---- +include::{esql-specs}/stats.csv-spec[tag=docsStatsAvgNestedExpression] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats.csv-spec[tag=docsStatsAvgNestedExpression-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/binary.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/binary.asciidoc index ba93f57af7ad6a..2d4daa6ad2ecab 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/binary.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/binary.asciidoc @@ -2,11 +2,91 @@ [[esql-binary-operators]] === Binary operators -These binary comparison operators are supported: - -* equality: `==` -* inequality: `!=` -* less than: `<` -* less than or equal: `<=` -* larger than: `>` -* larger than or equal: `>=` \ No newline at end of file +[[esql-binary-operators-equality]] +==== Equality +[.text-center] +image::esql/functions/signature/equals.svg[Embedded,opts=inline] + +Supported types: + +include::types/equals.asciidoc[] + +==== Inequality `!=` +[.text-center] +image::esql/functions/signature/not_equals.svg[Embedded,opts=inline] + +Supported types: + +include::types/not_equals.asciidoc[] + +==== Less than `<` +[.text-center] +image::esql/functions/signature/less_than.svg[Embedded,opts=inline] + +Supported types: + +include::types/less_than.asciidoc[] + +==== Less than or equal to `<=` +[.text-center] +image::esql/functions/signature/less_than_or_equal.svg[Embedded,opts=inline] + +Supported types: + +include::types/less_than_or_equal.asciidoc[] + +==== Greater than `>` +[.text-center] +image::esql/functions/signature/greater_than.svg[Embedded,opts=inline] + +Supported types: + +include::types/greater_than.asciidoc[] + +==== Greater than or equal to `>=` +[.text-center] +image::esql/functions/signature/greater_than_or_equal.svg[Embedded,opts=inline] + +Supported types: + +include::types/greater_than_or_equal.asciidoc[] + +==== Add `+` +[.text-center] +image::esql/functions/signature/add.svg[Embedded,opts=inline] + +Supported types: + +include::types/add.asciidoc[] + +==== Subtract `-` +[.text-center] +image::esql/functions/signature/sub.svg[Embedded,opts=inline] + +Supported types: + +include::types/sub.asciidoc[] + +==== Multiply `*` +[.text-center] +image::esql/functions/signature/mul.svg[Embedded,opts=inline] + +Supported types: + +include::types/mul.asciidoc[] + +==== Divide `/` +[.text-center] +image::esql/functions/signature/div.svg[Embedded,opts=inline] + +Supported types: + +include::types/div.asciidoc[] + +==== Modulus `%` +[.text-center] +image::esql/functions/signature/mod.svg[Embedded,opts=inline] + +Supported types: + +include::types/mod.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/case.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/case.asciidoc index b243adf875cb48..b5fda636135b24 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/case.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/case.asciidoc @@ -4,7 +4,7 @@ *Syntax* -[source,txt] +[source,esql] ---- CASE(condition1, value1[, ..., conditionN, valueN][, default_value]) ---- @@ -27,10 +27,13 @@ Accepts pairs of conditions and values. The function returns the value that belongs to the first condition that evaluates to `true`. If the number of arguments is odd, the last argument is the default value which -is returned when no condition matches. +is returned when no condition matches. If the number of arguments is even, and +no condition matches, the function returns `null`. *Example* +Determine whether employees are monolingual, bilingual, or polyglot: + [source,esql] [source.merge.styled,esql] ---- @@ -40,3 +43,28 @@ include::{esql-specs}/docs.csv-spec[tag=case] |=== include::{esql-specs}/docs.csv-spec[tag=case-result] |=== + +Calculate the total connection success rate based on log messages: + +[source,esql] +[source.merge.styled,esql] +---- +include::{esql-specs}/conditional.csv-spec[tag=docsCaseSuccessRate] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/conditional.csv-spec[tag=docsCaseSuccessRate-result] +|=== + +Calculate an hourly error rate as a percentage of the total number of log +messages: + +[source,esql] +[source.merge.styled,esql] +---- +include::{esql-specs}/conditional.csv-spec[tag=docsCaseHourlyErrorRate] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/conditional.csv-spec[tag=docsCaseHourlyErrorRate-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/ceil.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/ceil.asciidoc index f977e544e6c3f1..bc132e6bf47e69 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/ceil.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/ceil.asciidoc @@ -1,11 +1,32 @@ [discrete] [[esql-ceil]] === `CEIL` + +*Syntax* + [.text-center] image::esql/functions/signature/ceil.svg[Embedded,opts=inline] +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + Round a number up to the nearest integer. +NOTE: This is a noop for `long` (including unsigned) and `integer`. + For `double` this picks the closest `double` value to the integer + similar to {javadoc}/java.base/java/lang/Math.html#ceil(double)[Math.ceil]. + +*Supported types* + +include::types/ceil.asciidoc[] + + +*Example* + [source.merge.styled,esql] ---- include::{esql-specs}/math.csv-spec[tag=ceil] @@ -14,11 +35,3 @@ include::{esql-specs}/math.csv-spec[tag=ceil] |=== include::{esql-specs}/math.csv-spec[tag=ceil-result] |=== - -NOTE: This is a noop for `long` (including unsigned) and `integer`. - For `double` this picks the the closest `double` value to the integer ala - {javadoc}/java.base/java/lang/Math.html#ceil(double)[Math.ceil]. - -Supported types: - -include::types/ceil.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/cidr_match.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/cidr_match.asciidoc index 5072a6eef7fd58..1c7fbb57a00445 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/cidr_match.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/cidr_match.asciidoc @@ -2,15 +2,33 @@ [[esql-cidr_match]] === `CIDR_MATCH` +*Syntax* + +[source,esql] +---- +CIDR_MATCH(ip, block1[, ..., blockN]) +---- + +*Parameters* + +`ip`:: +IP address of type `ip` (both IPv4 and IPv6 are supported). + +`blockX`:: +CIDR block to test the IP against. + +*Description* + Returns `true` if the provided IP is contained in one of the provided CIDR blocks. -`CIDR_MATCH` accepts two or more arguments. The first argument is the IP -address of type `ip` (both IPv4 and IPv6 are supported). Subsequent arguments -are the CIDR blocks to test the IP against. +*Example* -[source,esql] +[source.merge.styled,esql] ---- -FROM hosts -| WHERE CIDR_MATCH(ip, "127.0.0.2/32", "127.0.0.3/32") +include::{esql-specs}/ip.csv-spec[tag=cdirMatchMultipleArgs] ---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/ip.csv-spec[tag=cdirMatchMultipleArgs-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/coalesce.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/coalesce.asciidoc index 550780eaa070da..1121a75209151a 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/coalesce.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/coalesce.asciidoc @@ -2,7 +2,24 @@ [[esql-coalesce]] === `COALESCE` -Returns the first non-null value. +*Syntax* + +[source,esql] +---- +COALESCE(expression1 [, ..., expressionN]) +---- + +*Parameters* + +`expressionX`:: +Expression to evaluate. + +*Description* + +Returns the first of its arguments that is not null. If all arguments are null, +it returns `null`. + +*Example* [source.merge.styled,esql] ---- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/concat.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/concat.asciidoc index 4864f5623a1705..0b30211a72be2a 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/concat.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/concat.asciidoc @@ -1,11 +1,30 @@ [discrete] [[esql-concat]] === `CONCAT` -Concatenates two or more strings. + +*Syntax* [source,esql] ---- -FROM employees -| KEEP first_name, last_name, height -| EVAL fullname = CONCAT(first_name, " ", last_name) +CONCAT(string1, string2[, ..., stringN]) +---- + +*Parameters* + +`stringX`:: +Strings to concatenate. + +*Description* + +Concatenates two or more strings. + +*Example* + +[source.merge.styled,esql] +---- +include::{esql-specs}/eval.csv-spec[tag=docsConcat] ---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/eval.csv-spec[tag=docsConcat-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/cos.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/cos.asciidoc index 5dcbb7bea37f4d..a5a0251bbd70ae 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/cos.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/cos.asciidoc @@ -1,10 +1,27 @@ [discrete] [[esql-cos]] === `COS` + +*Syntax* + [.text-center] image::esql/functions/signature/cos.svg[Embedded,opts=inline] -https://en.wikipedia.org/wiki/Sine_and_cosine[Cosine] trigonometric function. +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +Returns the {wikipedia}/Sine_and_cosine[cosine] of `n`. Input expected in +radians. + +*Supported types* + +include::types/cos.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,7 +31,3 @@ include::{esql-specs}/floats.csv-spec[tag=cos] |=== include::{esql-specs}/floats.csv-spec[tag=cos-result] |=== - -Supported types: - -include::types/cos.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/cosh.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/cosh.asciidoc index 7bf08409586559..5883bc4b9d0c45 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/cosh.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/cosh.asciidoc @@ -1,10 +1,26 @@ [discrete] [[esql-cosh]] === `COSH` + +*Syntax* + [.text-center] image::esql/functions/signature/cosh.svg[Embedded,opts=inline] -https://en.wikipedia.org/wiki/Hyperbolic_functions[Cosine] hyperbolic function. +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +Returns the {wikipedia}/Hyperbolic_functions[hyperbolic cosine]. + +*Supported types* + +include::types/cosh.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,7 +30,3 @@ include::{esql-specs}/floats.csv-spec[tag=cosh] |=== include::{esql-specs}/floats.csv-spec[tag=cosh-result] |=== - -Supported types: - -include::types/cosh.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/count.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/count.asciidoc index a148df07edb4dc..38732336413adb 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/count.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/count.asciidoc @@ -1,7 +1,29 @@ [discrete] [[esql-agg-count]] === `COUNT` -Counts field values. + +*Syntax* + +[source,esql] +---- +COUNT([expression]) +---- + +*Parameters* + +`expression`:: +Expression that outputs values to be counted. +If omitted, equivalent to `COUNT(*)` (the number of rows). + +*Description* + +Returns the total number (count) of input values. + +*Supported types* + +Can take any field type as input. + +*Examples* [source.merge.styled,esql] ---- @@ -12,10 +34,7 @@ include::{esql-specs}/stats.csv-spec[tag=count] include::{esql-specs}/stats.csv-spec[tag=count-result] |=== -Can take any field type as input and the result is always a `long` not matter -the input type. - -To count the number of rows, use `COUNT(*)`: +To count the number of rows, use `COUNT()` or `COUNT(*)`: [source.merge.styled,esql] ---- @@ -24,4 +43,16 @@ include::{esql-specs}/docs.csv-spec[tag=countAll] [%header.monospaced.styled,format=dsv,separator=|] |=== include::{esql-specs}/docs.csv-spec[tag=countAll-result] -|=== \ No newline at end of file +|=== + +The expression can use inline functions. This example splits a string into +multiple values using the `SPLIT` function and counts the values: + +[source.merge.styled,esql] +---- +include::{esql-specs}/stats.csv-spec[tag=docsCountWithExpression] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats.csv-spec[tag=docsCountWithExpression-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/count_distinct.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/count_distinct.asciidoc index b5b1659140f636..a9f30d24e0e83f 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/count_distinct.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/count_distinct.asciidoc @@ -1,7 +1,33 @@ [discrete] [[esql-agg-count-distinct]] === `COUNT_DISTINCT` -The approximate number of distinct values. + +*Syntax* + +[source,esql] +---- +COUNT_DISTINCT(expression[, precision_threshold]) +---- + +*Parameters* + +`expression`:: +Expression that outputs the values on which to perform a distinct count. + +`precision_threshold`:: +Precision threshold. Refer to <>. The +maximum supported value is 40000. Thresholds above this number will have the +same effect as a threshold of 40000. The default value is 3000. + +*Description* + +Returns the approximate number of distinct values. + +*Supported types* + +Can take any field type as input. + +*Examples* [source.merge.styled,esql] ---- @@ -12,10 +38,31 @@ include::{esql-specs}/stats_count_distinct.csv-spec[tag=count-distinct] include::{esql-specs}/stats_count_distinct.csv-spec[tag=count-distinct-result] |=== -Can take any field type as input and the result is always a `long` not matter -the input type. +With the optional second parameter to configure the precision threshold: + +[source.merge.styled,esql] +---- +include::{esql-specs}/stats_count_distinct.csv-spec[tag=count-distinct-precision] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats_count_distinct.csv-spec[tag=count-distinct-precision-result] +|=== + +The expression can use inline functions. This example splits a string into +multiple values using the `SPLIT` function and counts the unique values: + +[source.merge.styled,esql] +---- +include::{esql-specs}/stats_count_distinct.csv-spec[tag=docsCountDistinctWithExpression] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats_count_distinct.csv-spec[tag=docsCountDistinctWithExpression-result] +|=== [discrete] +[[esql-agg-count-distinct-approximate]] ==== Counts are approximate Computing exact counts requires loading values into a set and returning its @@ -30,17 +77,9 @@ properties: include::../../aggregations/metrics/cardinality-aggregation.asciidoc[tag=explanation] -[discrete] -==== Precision is configurable - -The `COUNT_DISTINCT` function takes an optional second parameter to configure the -precision discussed previously. - -[source.merge.styled,esql] ----- -include::{esql-specs}/stats_count_distinct.csv-spec[tag=count-distinct-precision] ----- -[%header.monospaced.styled,format=dsv,separator=|] -|=== -include::{esql-specs}/stats_count_distinct.csv-spec[tag=count-distinct-precision-result] -|=== +The `COUNT_DISTINCT` function takes an optional second parameter to configure +the precision threshold. The precision_threshold options allows to trade memory +for accuracy, and defines a unique count below which counts are expected to be +close to accurate. Above this value, counts might become a bit more fuzzy. The +maximum supported value is 40000, thresholds above this number will have the +same effect as a threshold of 40000. The default value is `3000`. \ No newline at end of file diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_diff.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_diff.asciidoc new file mode 100644 index 00000000000000..fa51e6f906110c --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_diff.asciidoc @@ -0,0 +1,63 @@ +[discrete] +[[esql-date_diff]] +=== `DATE_DIFF` + +*Syntax* + +[.text-center] +image::esql/functions/signature/date_diff.svg[Embedded,opts=inline] + +*Parameters* + +`unit`:: +Time difference unit. + +`startTimestamp`:: +Start timestamp. + +`endTimestamp`:: +End timestamp. + +*Description* + +Subtracts the `startTimestamp` from the `endTimestamp` and returns the +difference in multiples of `unit`. If `startTimestamp` is later than the +`endTimestamp`, negative values are returned. + +[cols="^,^",role="styled"] +|=== +2+h|Datetime difference units + +s|unit +s|abbreviations + +| year | years, yy, yyyy +| quarter | quarters, qq, q +| month | months, mm, m +| dayofyear | dy, y +| day | days, dd, d +| week | weeks, wk, ww +| weekday | weekdays, dw +| hour | hours, hh +| minute | minutes, mi, n +| second | seconds, ss, s +| millisecond | milliseconds, ms +| microsecond | microseconds, mcs +| nanosecond | nanoseconds, ns +|=== + +*Supported types* + +include::types/date_diff.asciidoc[] + +*Example* + +[source.merge.styled,esql] +---- +include::{esql-specs}/date.csv-spec[tag=docsDateDiff] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/date.csv-spec[tag=docsDateDiff-result] +|=== + diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_extract.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_extract.asciidoc index 89ef1cf261094f..ce949483494a54 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_extract.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_extract.asciidoc @@ -1,15 +1,56 @@ [discrete] [[esql-date_extract]] === `DATE_EXTRACT` -Extracts parts of a date, like year, month, day, hour. -The supported field types are those provided by https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoField.html[java.time.temporal.ChronoField]. + +*Syntax* + +[source,esql] +---- +DATE_EXTRACT(date_part, date) +---- + +*Parameters* + +`date_part`:: +Part of the date to extract. Can be: `aligned_day_of_week_in_month`, +`aligned_day_of_week_in_year`, `aligned_week_of_month`, `aligned_week_of_year`, +`ampm_of_day`, `clock_hour_of_ampm`, `clock_hour_of_day`, `day_of_month`, +`day_of_week`, `day_of_year`, `epoch_day`, `era`, `hour_of_ampm`, `hour_of_day`, +`instant_seconds`, `micro_of_day`, `micro_of_second`, `milli_of_day`, +`milli_of_second`, `minute_of_day`, `minute_of_hour`, `month_of_year`, +`nano_of_day`, `nano_of_second`, `offset_seconds`, `proleptic_month`, +`second_of_day`, `second_of_minute`, `year`, or `year_of_era`. Refer to +https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoField.html[java.time.temporal.ChronoField] +for a description of these values. ++ +If `null`, the function returns `null`. + +`date`:: +Date expression. If `null`, the function returns `null`. + +*Description* + +Extracts parts of a date, like year, month, day, hour. + +*Examples* [source.merge.styled,esql] ---- -include::{esql-specs}/docs.csv-spec[tag=dateExtract] +include::{esql-specs}/date.csv-spec[tag=dateExtract] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/docs.csv-spec[tag=dateExtract-result] +include::{esql-specs}/date.csv-spec[tag=dateExtract-result] |=== +Find all events that occurred outside of business hours (before 9 AM or after 5 +PM), on any given date: + +[source.merge.styled,esql] +---- +include::{esql-specs}/date.csv-spec[tag=docsDateExtractBusinessHours] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/date.csv-spec[tag=docsDateExtractBusinessHours-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_format.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_format.asciidoc index 5a87f31412cc81..4a0d36d133a4ce 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_format.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_format.asciidoc @@ -1,12 +1,35 @@ [discrete] [[esql-date_format]] === `DATE_FORMAT` -Returns a string representation of a date in the provided format. If no format -is specified, the `yyyy-MM-dd'T'HH:mm:ss.SSSZ` format is used. + +*Syntax* [source,esql] ---- -FROM employees -| KEEP first_name, last_name, hire_date -| EVAL hired = DATE_FORMAT("YYYY-MM-dd", hire_date) +DATE_FORMAT([format,] date) +---- + +*Parameters* + +`format`:: +Date format (optional). If no format is specified, the +`yyyy-MM-dd'T'HH:mm:ss.SSSZ` format is used. If `null`, the function returns +`null`. + +`date`:: +Date expression. If `null`, the function returns `null`. + +*Description* + +Returns a string representation of a date, in the provided format. + +*Example* + +[source.merge.styled,esql] +---- +include::{esql-specs}/date.csv-spec[tag=docsDateFormat] ---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/date.csv-spec[tag=docsDateFormat-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_parse.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_parse.asciidoc index c74656ff1dbd77..9580ae238b6639 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_parse.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_parse.asciidoc @@ -4,7 +4,7 @@ *Syntax* -[source,txt] +[source,esql] ---- DATE_PARSE([format,] date_string) ---- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_time_functions.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_time_functions.asciidoc index 8ff7b1e974eeb4..f90bc007f744e5 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_time_functions.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_time_functions.asciidoc @@ -9,6 +9,7 @@ // tag::date_list[] * <> +* <> * <> * <> * <> @@ -17,6 +18,7 @@ // end::date_list[] include::auto_bucket.asciidoc[] +include::date_diff.asciidoc[] include::date_extract.asciidoc[] include::date_format.asciidoc[] include::date_parse.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_trunc.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_trunc.asciidoc index cacfefe73d0fd6..4aa228dc14e65f 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_trunc.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/date_trunc.asciidoc @@ -1,13 +1,57 @@ [discrete] [[esql-date_trunc]] === `DATE_TRUNC` -Rounds down a date to the closest interval. Intervals can be expressed using the -<>. + +*Syntax* [source,esql] ---- -FROM employees -| EVAL year_hired = DATE_TRUNC(1 year, hire_date) -| STATS count(emp_no) BY year_hired -| SORT year_hired +DATE_TRUNC(interval, date) +---- + +*Parameters* + +`interval`:: +Interval, expressed using the <>. If `null`, the function returns `null`. + +`date`:: +Date expression. If `null`, the function returns `null`. + +*Description* + +Rounds down a date to the closest interval. + +*Examples* + +[source.merge.styled,esql] +---- +include::{esql-specs}/date.csv-spec[tag=docsDateTrunc] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/date.csv-spec[tag=docsDateTrunc-result] +|=== + +Combine `DATE_TRUNC` with <> to create date histograms. For +example, the number of hires per year: + +[source.merge.styled,esql] +---- +include::{esql-specs}/date.csv-spec[tag=docsDateTruncHistogram] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/date.csv-spec[tag=docsDateTruncHistogram-result] +|=== + +Or an hourly error rate: + +[source.merge.styled,esql] +---- +include::{esql-specs}/conditional.csv-spec[tag=docsCaseHourlyErrorRate] ---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/conditional.csv-spec[tag=docsCaseHourlyErrorRate-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/e.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/e.asciidoc index 56bf97fd01740b..ac082c1a68a07c 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/e.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/e.asciidoc @@ -1,10 +1,17 @@ [discrete] [[esql-e]] === `E` + +*Syntax* + [.text-center] image::esql/functions/signature/e.svg[Embedded,opts=inline] -{wikipedia}/E_(mathematical_constant)[Euler's number]. +*Description* + +Returns {wikipedia}/E_(mathematical_constant)[Euler's number]. + +*Example* [source.merge.styled,esql] ---- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/ends_with.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/ends_with.asciidoc index fd2d99931163a5..49477996ada19c 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/ends_with.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/ends_with.asciidoc @@ -1,11 +1,30 @@ [discrete] [[esql-ends_with]] === `ENDS_WITH` + +*Syntax* + [.text-center] image::esql/functions/signature/ends_with.svg[Embedded,opts=inline] +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +`suffix`:: +String expression. If `null`, the function returns `null`. + +*Description* + Returns a boolean that indicates whether a keyword string ends with another -string: +string. + +*Supported types* + +include::types/ends_with.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -15,7 +34,3 @@ include::{esql-specs}/string.csv-spec[tag=endsWith] |=== include::{esql-specs}/string.csv-spec[tag=endsWith-result] |=== - -Supported types: - -include::types/ends_with.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/floor.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/floor.asciidoc index 109033bb18827f..0730a87e595fdf 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/floor.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/floor.asciidoc @@ -1,10 +1,30 @@ [discrete] [[esql-floor]] === `FLOOR` + +*Syntax* + [.text-center] image::esql/functions/signature/floor.svg[Embedded,opts=inline] -Round a number down to the nearest integer. +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +Rounds a number down to the nearest integer. + +NOTE: This is a noop for `long` (including unsigned) and `integer`. + For `double` this picks the closest `double` value to the integer + similar to {javadoc}/java.base/java/lang/Math.html#floor(double)[Math.floor]. + +*Supported types* + +include::types/floor.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,11 +34,3 @@ include::{esql-specs}/math.csv-spec[tag=floor] |=== include::{esql-specs}/math.csv-spec[tag=floor-result] |=== - -NOTE: This is a noop for `long` (including unsigned) and `integer`. - For `double` this picks the the closest `double` value to the integer ala - {javadoc}/java.base/java/lang/Math.html#floor(double)[Math.floor]. - -Supported types: - -include::types/floor.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/greatest.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/greatest.asciidoc index 24dd08de2819c9..b9fc114d39ec64 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/greatest.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/greatest.asciidoc @@ -1,11 +1,34 @@ [discrete] [[esql-greatest]] === `GREATEST` + +*Syntax* + [.text-center] image::esql/functions/signature/greatest.svg[Embedded,opts=inline] -Returns the maximum value from many columns. This is similar to <> -except it's intended to run on multiple columns at once. +*Parameters* + +`first`:: +First of the columns to evaluate. + +`rest`:: +The rest of the columns to evaluate. + +*Description* + +Returns the maximum value from multiple columns. This is similar to <> +except it is intended to run on multiple columns at once. + +NOTE: When run on `keyword` or `text` fields, this returns the last string + in alphabetical order. When run on `boolean` columns this will return + `true` if any values are `true`. + +*Supported types* + +include::types/greatest.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -15,11 +38,3 @@ include::{esql-specs}/math.csv-spec[tag=greatest] |=== include::{esql-specs}/math.csv-spec[tag=greatest-result] |=== - -NOTE: When run on `keyword` or `text` fields, this'll return the last string - in alphabetical order. When run on `boolean` columns this will return - `true` if any values are `true`. - -Supported types: - -include::types/greatest.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/in.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/in.asciidoc index be5688250ecc7c..c64c64873f7cb6 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/in.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/in.asciidoc @@ -2,10 +2,16 @@ [[esql-in-operator]] === `IN` +//tag::body[] The `IN` operator allows testing whether a field or expression equals an element in a list of literals, fields or expressions: -[source,esql] +[source.merge.styled,esql] ---- include::{esql-specs}/row.csv-spec[tag=in-with-expressions] ----- \ No newline at end of file +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/row.csv-spec[tag=in-with-expressions-result] +|=== +//end::body[] \ No newline at end of file diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/is_finite.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/is_finite.asciidoc deleted file mode 100644 index f7b7ad73a3952d..00000000000000 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/is_finite.asciidoc +++ /dev/null @@ -1,10 +0,0 @@ -[discrete] -[[esql-is_finite]] -=== `IS_FINITE` -Returns a boolean that indicates whether its input is a finite number. - -[source,esql] ----- -ROW d = 1.0 -| EVAL s = IS_FINITE(d/0) ----- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/is_infinite.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/is_infinite.asciidoc deleted file mode 100644 index 56158a786c0200..00000000000000 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/is_infinite.asciidoc +++ /dev/null @@ -1,10 +0,0 @@ -[discrete] -[[esql-is_infinite]] -=== `IS_INFINITE` -Returns a boolean that indicates whether its input is infinite. - -[source,esql] ----- -ROW d = 1.0 -| EVAL s = IS_INFINITE(d/0) ----- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/is_nan.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/is_nan.asciidoc deleted file mode 100644 index 25b50a9e96bbac..00000000000000 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/is_nan.asciidoc +++ /dev/null @@ -1,10 +0,0 @@ -[discrete] -[[esql-is_nan]] -=== `IS_NAN` -Returns a boolean that indicates whether its input is not a number. - -[source,esql] ----- -ROW d = 1.0 -| EVAL s = IS_NAN(d) ----- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/least.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/least.asciidoc index 62d7406199cd4f..41f58b0d415c23 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/least.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/least.asciidoc @@ -1,11 +1,34 @@ [discrete] [[esql-least]] === `LEAST` + +*Syntax* + [.text-center] image::esql/functions/signature/least.svg[Embedded,opts=inline] -Returns the minimum value from many columns. This is similar to <> -except it's intended to run on multiple columns at once. +*Parameters* + +`first`:: +First of the columns to evaluate. + +`rest`:: +The rest of the columns to evaluate. + +*Description* + +Returns the minimum value from multiple columns. This is similar to +<> except it is intended to run on multiple columns at once. + +NOTE: When run on `keyword` or `text` fields, this returns the first string + in alphabetical order. When run on `boolean` columns this will return + `false` if any values are `false`. + +*Supported types* + +include::types/least.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -15,11 +38,3 @@ include::{esql-specs}/math.csv-spec[tag=least] |=== include::{esql-specs}/math.csv-spec[tag=least-result] |=== - -NOTE: When run on `keyword` or `text` fields, this'll return the first string - in alphabetical order. When run on `boolean` columns this will return - `false` if any values are `false`. - -Supported types: - -include::types/least.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/left.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/left.asciidoc index 67e739377aa46c..5d666656b1ee40 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/left.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/left.asciidoc @@ -1,10 +1,30 @@ [discrete] [[esql-left]] === `LEFT` + +*Syntax* + [.text-center] image::esql/functions/signature/left.svg[Embedded,opts=inline] -Return the substring that extracts 'length' chars from the 'string' starting from the left. +*Parameters* + +`str`:: +The string from which to return a substring. + +`length`:: +The number of characters to return. + +*Description* + +Returns the substring that extracts 'length' chars from 'str' starting +from the left. + +*Supported types* + +include::types/left.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,7 +34,3 @@ include::{esql-specs}/string.csv-spec[tag=left] |=== include::{esql-specs}/string.csv-spec[tag=left-result] |=== - -Supported types: - -include::types/left.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/length.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/length.asciidoc index 12e1bed3d0a66f..b89b75a702460d 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/length.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/length.asciidoc @@ -1,11 +1,30 @@ [discrete] [[esql-length]] === `LENGTH` -Returns the character length of a string. + +*Syntax* [source,esql] ---- -FROM employees -| KEEP first_name, last_name, height -| EVAL fn_length = LENGTH(first_name) +LENGTH(str) +---- + +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +*Description* + +Returns the character length of a string. + +*Example* + +[source.merge.styled,esql] +---- +include::{esql-specs}/eval.csv-spec[tag=length] ---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/eval.csv-spec[tag=length-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/like.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/like.asciidoc index 9d06a3d051b931..d89b6715f86eb3 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/like.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/like.asciidoc @@ -2,6 +2,7 @@ [[esql-like-operator]] === `LIKE` +// tag::body[] Use `LIKE` to filter data based on string patterns using wildcards. `LIKE` usually acts on a field placed on the left-hand side of the operator, but it can also act on a constant (literal) expression. The right-hand side of the operator @@ -12,9 +13,12 @@ The following wildcard characters are supported: * `*` matches zero or more characters. * `?` matches one character. -[source,esql] +[source.merge.styled,esql] ---- -FROM employees -| WHERE first_name LIKE "?b*" -| KEEP first_name, last_name +include::{esql-specs}/docs.csv-spec[tag=like] ---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/docs.csv-spec[tag=like-result] +|=== +// end::body[] \ No newline at end of file diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/log.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/log.asciidoc new file mode 100644 index 00000000000000..79ea72898bc2f8 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/log.asciidoc @@ -0,0 +1,48 @@ +[discrete] +[[esql-log]] +=== `LOG` + +*Syntax* + +[source,esql] +---- +LOG([base,] value) +---- + +*Parameters* + +`base`:: +Numeric expression. If `null`, the function returns `null`. The base is an optional input parameter. If a base is not provided, this function returns the natural logarithm (base e) of a value. + +`value`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +Returns the logarithm of a value to a base. The input can be any numeric value, the return value is always a double. + +Logs of zero, negative numbers, infinites and base of one return `null` as well as a warning. + +*Supported types* + +include::types/log.asciidoc[] + +*Example* + +[source.merge.styled,esql] +---- +include::{esql-specs}/math.csv-spec[tag=log] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/math.csv-spec[tag=log-result] +|=== + +[source.merge.styled,esql] +---- +include::{esql-specs}/math.csv-spec[tag=logUnary] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/math.csv-spec[tag=logUnary-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/log10.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/log10.asciidoc index 219519ca2a0d71..d806da3173818b 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/log10.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/log10.asciidoc @@ -1,13 +1,27 @@ [discrete] [[esql-log10]] === `LOG10` + +*Syntax* + [.text-center] image::esql/functions/signature/log10.svg[Embedded,opts=inline] -Returns the log base 10. The input can be any numeric value, the return value -is always a double. +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* -Logs of negative numbers are NaN. Logs of infinites are infinite, as is the log of 0. +Returns the logarithm to base 10. The input can be any numeric value, the return +value is always a double. + +Logs of 0, negative numbers, and infinites return `null` as well as a warning. + +*Supported types* + +include::types/log10.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -17,7 +31,3 @@ include::{esql-specs}/math.csv-spec[tag=log10] |=== include::{esql-specs}/math.csv-spec[tag=log10-result] |=== - -Supported types: - -include::types/log10.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/ltrim.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/ltrim.asciidoc index 6e6d30a73b865b..4b7b619d06afc2 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/ltrim.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/ltrim.asciidoc @@ -1,8 +1,27 @@ [discrete] [[esql-ltrim]] === `LTRIM` + +*Syntax* + +[.text-center] +image::esql/functions/signature/ltrim.svg[Embedded,opts=inline] + +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +*Description* + Removes leading whitespaces from strings. +*Supported types* + +include::types/rtrim.asciidoc[] + +*Example* + [source.merge.styled,esql] ---- include::{esql-specs}/string.csv-spec[tag=ltrim] @@ -10,4 +29,4 @@ include::{esql-specs}/string.csv-spec[tag=ltrim] [%header.monospaced.styled,format=dsv,separator=|] |=== include::{esql-specs}/string.csv-spec[tag=ltrim-result] -|=== +|=== \ No newline at end of file diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/math_functions.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/math_functions.asciidoc index 21131ae9074d7e..0ddf7412db2a12 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/math_functions.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/math_functions.asciidoc @@ -18,6 +18,7 @@ * <> * <> * <> +* <> * <> * <> * <> @@ -40,6 +41,7 @@ include::cos.asciidoc[] include::cosh.asciidoc[] include::e.asciidoc[] include::floor.asciidoc[] +include::log.asciidoc[] include::log10.asciidoc[] include::pi.asciidoc[] include::pow.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/max.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/max.asciidoc index 53997e501b37f3..f2e0d0a0205b36 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/max.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/max.asciidoc @@ -1,7 +1,24 @@ [discrete] [[esql-agg-max]] === `MAX` -The maximum value of a numeric field. + +*Syntax* + +[source,esql] +---- +MAX(expression) +---- + +*Parameters* + +`expression`:: +Expression from which to return the maximum value. + +*Description* + +Returns the maximum value of a numeric expression. + +*Example* [source.merge.styled,esql] ---- @@ -11,3 +28,16 @@ include::{esql-specs}/stats.csv-spec[tag=max] |=== include::{esql-specs}/stats.csv-spec[tag=max-result] |=== + +The expression can use inline functions. For example, to calculate the maximum +over an average of a multivalued column, use `MV_AVG` to first average the +multiple values per row, and use the result with the `MAX` function: + +[source.merge.styled,esql] +---- +include::{esql-specs}/stats.csv-spec[tag=docsStatsMaxNestedExpression] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats.csv-spec[tag=docsStatsMaxNestedExpression-result] +|=== \ No newline at end of file diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/median.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/median.asciidoc index 5a0d0c049602e0..ef845aafd39158 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/median.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/median.asciidoc @@ -1,9 +1,34 @@ [discrete] [[esql-agg-median]] === `MEDIAN` -The value that is greater than half of all values and less than half of + +*Syntax* + +[source,esql] +---- +MEDIAN(expression) +---- + +*Parameters* + +`expression`:: +Expression from which to return the median value. + +*Description* + +Returns the value that is greater than half of all values and less than half of all values, also known as the 50% <>. +NOTE: Like <>, `MEDIAN` is <>. + +[WARNING] +==== +`MEDIAN` is also {wikipedia}/Nondeterministic_algorithm[non-deterministic]. +This means you can get slightly different results using the same data. +==== + +*Example* + [source.merge.styled,esql] ---- include::{esql-specs}/stats_percentile.csv-spec[tag=median] @@ -13,10 +38,15 @@ include::{esql-specs}/stats_percentile.csv-spec[tag=median] include::{esql-specs}/stats_percentile.csv-spec[tag=median-result] |=== -NOTE: Like <>, `MEDIAN` is <>. +The expression can use inline functions. For example, to calculate the median of +the maximum values of a multivalued column, first use `MV_MAX` to get the +maximum value per row, and use the result with the `MEDIAN` function: -[WARNING] -==== -`MEDIAN` is also {wikipedia}/Nondeterministic_algorithm[non-deterministic]. -This means you can get slightly different results using the same data. -==== +[source.merge.styled,esql] +---- +include::{esql-specs}/stats_percentile.csv-spec[tag=docsStatsMedianNestedExpression] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats_percentile.csv-spec[tag=docsStatsMedianNestedExpression-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/median_absolute_deviation.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/median_absolute_deviation.asciidoc index fe0923da1fb88f..796e0797157deb 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/median_absolute_deviation.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/median_absolute_deviation.asciidoc @@ -1,23 +1,29 @@ [discrete] [[esql-agg-median-absolute-deviation]] === `MEDIAN_ABSOLUTE_DEVIATION` -The median absolute deviation, a measure of variability. It is a robust -statistic, meaning that it is useful for describing data that may have outliers, -or may not be normally distributed. For such data it can be more descriptive than -standard deviation. -It is calculated as the median of each data point’s deviation from the median of -the entire sample. That is, for a random variable `X`, the median absolute deviation -is `median(|median(X) - Xi|)`. +*Syntax* -[source.merge.styled,esql] +[source,esql] ---- -include::{esql-specs}/stats_percentile.csv-spec[tag=median-absolute-deviation] +MEDIAN_ABSOLUTE_DEVIATION(expression) ---- -[%header.monospaced.styled,format=dsv,separator=|] -|=== -include::{esql-specs}/stats_percentile.csv-spec[tag=median-absolute-deviation-result] -|=== + +*Parameters* + +`expression`:: +Expression from which to return the median absolute deviation. + +*Description* + +Returns the median absolute deviation, a measure of variability. It is a robust +statistic, meaning that it is useful for describing data that may have outliers, +or may not be normally distributed. For such data it can be more descriptive +than standard deviation. + +It is calculated as the median of each data point's deviation from the median of +the entire sample. That is, for a random variable `X`, the median absolute +deviation is `median(|median(X) - X|)`. NOTE: Like <>, `MEDIAN_ABSOLUTE_DEVIATION` is <>. @@ -27,3 +33,28 @@ NOTE: Like <>, `MEDIAN_ABSOLUTE_DEVIATION` is `MEDIAN_ABSOLUTE_DEVIATION` is also {wikipedia}/Nondeterministic_algorithm[non-deterministic]. This means you can get slightly different results using the same data. ==== + +*Example* + +[source.merge.styled,esql] +---- +include::{esql-specs}/stats_percentile.csv-spec[tag=median-absolute-deviation] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats_percentile.csv-spec[tag=median-absolute-deviation-result] +|=== + +The expression can use inline functions. For example, to calculate the the +median absolute deviation of the maximum values of a multivalued column, first +use `MV_MAX` to get the maximum value per row, and use the result with the +`MEDIAN_ABSOLUTE_DEVIATION` function: + +[source.merge.styled,esql] +---- +include::{esql-specs}/stats_percentile.csv-spec[tag=docsStatsMADNestedExpression] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats_percentile.csv-spec[tag=docsStatsMADNestedExpression-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/min.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/min.asciidoc index a143cca69c01a8..313822818128c9 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/min.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/min.asciidoc @@ -1,7 +1,24 @@ [discrete] [[esql-agg-min]] === `MIN` -The minimum value of a numeric field. + +*Syntax* + +[source,esql] +---- +MIN(expression) +---- + +*Parameters* + +`expression`:: +Expression from which to return the minimum value. + +*Description* + +Returns the minimum value of a numeric expression. + +*Example* [source.merge.styled,esql] ---- @@ -11,3 +28,16 @@ include::{esql-specs}/stats.csv-spec[tag=min] |=== include::{esql-specs}/stats.csv-spec[tag=min-result] |=== + +The expression can use inline functions. For example, to calculate the minimum +over an average of a multivalued column, use `MV_AVG` to first average the +multiple values per row, and use the result with the `MIN` function: + +[source.merge.styled,esql] +---- +include::{esql-specs}/stats.csv-spec[tag=docsStatsMinNestedExpression] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats.csv-spec[tag=docsStatsMinNestedExpression-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_avg.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_avg.asciidoc index ad5f6722055166..27fa2542a8b8f7 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_avg.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_avg.asciidoc @@ -1,8 +1,29 @@ [discrete] [[esql-mv_avg]] === `MV_AVG` -Converts a multivalued field into a single valued field containing the average -of all of the values. For example: + +*Syntax* + +[source,esql] +---- +MV_AVG(expression) +---- + +*Parameters* + +`expression`:: +Multivalue expression. + +*Description* + +Converts a multivalued expression into a single valued column containing the +average of all of the values. + +*Supported types* + +include::types/mv_avg.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -12,6 +33,3 @@ include::{esql-specs}/math.csv-spec[tag=mv_avg] |=== include::{esql-specs}/math.csv-spec[tag=mv_avg-result] |=== - - -NOTE: The output type is always a `double` and the input type can be any number. diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_concat.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_concat.asciidoc index d4be4584551313..e42cc84d62b155 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_concat.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_concat.asciidoc @@ -1,8 +1,30 @@ [discrete] [[esql-mv_concat]] === `MV_CONCAT` -Converts a multivalued string field into a single valued field containing the -concatenation of all values separated by a delimiter: + +*Syntax* + +[.text-center] +image::esql/functions/signature/mv_concat.svg[Embedded,opts=inline] + +*Parameters* + +`v`:: +Multivalue expression. + +`delim`:: +Delimiter. + +*Description* + +Converts a multivalued string expression into a single valued column containing +the concatenation of all values separated by a delimiter. + +*Supported types* + +include::types/mv_concat.asciidoc[] + +*Examples* [source.merge.styled,esql] ---- @@ -13,7 +35,7 @@ include::{esql-specs}/string.csv-spec[tag=mv_concat] include::{esql-specs}/string.csv-spec[tag=mv_concat-result] |=== -If you want to concat non-string fields call <> on them first: +To concat non-string columns, call <> first: [source.merge.styled,esql] ---- @@ -23,4 +45,3 @@ include::{esql-specs}/string.csv-spec[tag=mv_concat-to_string] |=== include::{esql-specs}/string.csv-spec[tag=mv_concat-to_string-result] |=== - diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_count.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_count.asciidoc index 5bcda53ca5a9bb..05453355560304 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_count.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_count.asciidoc @@ -1,8 +1,27 @@ [discrete] [[esql-mv_count]] === `MV_COUNT` -Converts a multivalued field into a single valued field containing a count of the number -of values: + +*Syntax* + +[.text-center] +image::esql/functions/signature/mv_count.svg[Embedded,opts=inline] + +*Parameters* + +`v`:: +Multivalue expression. + +*Description* + +Converts a multivalued expression into a single valued column containing a count +of the number of values. + +*Supported types* + +include::types/mv_count.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -12,5 +31,3 @@ include::{esql-specs}/string.csv-spec[tag=mv_count] |=== include::{esql-specs}/string.csv-spec[tag=mv_count-result] |=== - -NOTE: This function accepts all types and always returns an `integer`. diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_dedupe.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_dedupe.asciidoc index c6af3f2d1aa3f1..09b3827c45e456 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_dedupe.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_dedupe.asciidoc @@ -1,7 +1,28 @@ [discrete] [[esql-mv_dedupe]] === `MV_DEDUPE` -Removes duplicates from a multivalued field. For example: + +*Syntax* + +[.text-center] +image::esql/functions/signature/mv_dedupe.svg[Embedded,opts=inline] + +*Parameters* + +`v`:: +Multivalue expression. + +*Description* + +Removes duplicates from a multivalue expression. + +NOTE: `MV_DEDUPE` may, but won't always, sort the values in the column. + +*Supported types* + +include::types/mv_dedupe.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -11,5 +32,3 @@ include::{esql-specs}/string.csv-spec[tag=mv_dedupe] |=== include::{esql-specs}/string.csv-spec[tag=mv_dedupe-result] |=== - -NOTE: `MV_DEDUPE` may, but won't always, sort the values in the field. diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_first.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_first.asciidoc new file mode 100644 index 00000000000000..13d21b15f958e5 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_first.asciidoc @@ -0,0 +1,40 @@ +[discrete] +[[esql-mv_first]] +=== `MV_FIRST` + +*Syntax* + +[.text-center] +image::esql/functions/signature/mv_first.svg[Embedded,opts=inline] + +*Parameters* + +`v`:: +Multivalue expression. + +*Description* + +Converts a multivalued expression into a single valued column containing the +first value. This is most useful when reading from a function that emits +multivalued columns in a known order like <>. + +The order that <> are read from +underlying storage is not guaranteed. It is *frequently* ascending, but don't +rely on that. If you need the minimum value use <> instead of +`MV_FIRST`. `MV_MIN` has optimizations for sorted values so there isn't a +performance benefit to `MV_FIRST`. + +*Supported types* + +include::types/mv_first.asciidoc[] + +*Example* + +[source.merge.styled,esql] +---- +include::{esql-specs}/string.csv-spec[tag=mv_first] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/string.csv-spec[tag=mv_first-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_functions.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_functions.asciidoc index 83dbaaadc5c065..a95a3d36a99633 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_functions.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_functions.asciidoc @@ -12,6 +12,8 @@ * <> * <> * <> +* <> +* <> * <> * <> * <> @@ -22,6 +24,8 @@ include::mv_avg.asciidoc[] include::mv_concat.asciidoc[] include::mv_count.asciidoc[] include::mv_dedupe.asciidoc[] +include::mv_first.asciidoc[] +include::mv_last.asciidoc[] include::mv_max.asciidoc[] include::mv_median.asciidoc[] include::mv_min.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_last.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_last.asciidoc new file mode 100644 index 00000000000000..ee6a4a8fed8bac --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_last.asciidoc @@ -0,0 +1,40 @@ +[discrete] +[[esql-mv_last]] +=== `MV_LAST` + +*Syntax* + +[.text-center] +image::esql/functions/signature/mv_last.svg[Embedded,opts=inline] + +*Parameters* + +`v`:: +Multivalue expression. + +*Description* + +Converts a multivalue expression into a single valued column containing the last +value. This is most useful when reading from a function that emits multivalued +columns in a known order like <>. + +The order that <> are read from +underlying storage is not guaranteed. It is *frequently* ascending, but don't +rely on that. If you need the maximum value use <> instead of +`MV_LAST`. `MV_MAX` has optimizations for sorted values so there isn't a +performance benefit to `MV_LAST`. + +*Supported types* + +include::types/mv_last.asciidoc[] + +*Example* + +[source.merge.styled,esql] +---- +include::{esql-specs}/string.csv-spec[tag=mv_last] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/string.csv-spec[tag=mv_last-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_max.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_max.asciidoc index e8ef951f168f51..e13e61e0d123d7 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_max.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_max.asciidoc @@ -1,7 +1,27 @@ [discrete] [[esql-mv_max]] === `MV_MAX` -Converts a multivalued field into a single valued field containing the maximum value. For example: + +*Syntax* + +[.text-center] +image::esql/functions/signature/mv_max.svg[Embedded,opts=inline] + +*Parameters* + +`v`:: +Multivalue expression. + +*Description* + +Converts a multivalued expression into a single valued column containing the +maximum value. + +*Supported types* + +include::types/mv_max.asciidoc[] + +*Examples* [source.merge.styled,esql] ---- @@ -12,8 +32,8 @@ include::{esql-specs}/math.csv-spec[tag=mv_max] include::{esql-specs}/math.csv-spec[tag=mv_max-result] |=== -It can be used by any field type, including `keyword` fields. In that case picks the -last string, comparing their utf-8 representation byte by byte: +It can be used by any column type, including `keyword` columns. In that case +it picks the last string, comparing their utf-8 representation byte by byte: [source.merge.styled,esql] ---- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_median.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_median.asciidoc index c84cf7a895da54..05c54342c0f74e 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_median.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_median.asciidoc @@ -1,7 +1,27 @@ [discrete] [[esql-mv_median]] === `MV_MEDIAN` -Converts a multivalued field into a single valued field containing the median value. For example: + +[source,esql] +---- +MV_MEDIAN(v) +---- + +*Parameters* + +`v`:: +Multivalue expression. + +*Description* + +Converts a multivalued column into a single valued column containing the median +value. + +*Supported types* + +include::types/mv_median.asciidoc[] + +*Examples* [source.merge.styled,esql] ---- @@ -12,9 +32,9 @@ include::{esql-specs}/math.csv-spec[tag=mv_median] include::{esql-specs}/math.csv-spec[tag=mv_median-result] |=== -It can be used by any numeric field type and returns a value of the same type. If the -row has an even number of values for a column the result will be the average of the -middle two entries. If the field is not floating point then the average rounds *down*: +If the row has an even number of values for a column, the result will be the +average of the middle two entries. If the column is not floating point, the +average rounds *down*: [source.merge.styled,esql] ---- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_min.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_min.asciidoc index 235e5c3c2bb5eb..b851f480fd6199 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_min.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_min.asciidoc @@ -1,7 +1,27 @@ [discrete] [[esql-mv_min]] === `MV_MIN` -Converts a multivalued field into a single valued field containing the minimum value. For example: + +*Syntax* + +[.text-center] +image::esql/functions/signature/mv_min.svg[Embedded,opts=inline] + +*Parameters* + +`v`:: +Multivalue expression. + +*Description* + +Converts a multivalued expression into a single valued column containing the +minimum value. + +*Supported types* + +include::types/mv_min.asciidoc[] + +*Examples* [source.merge.styled,esql] ---- @@ -12,8 +32,8 @@ include::{esql-specs}/math.csv-spec[tag=mv_min] include::{esql-specs}/math.csv-spec[tag=mv_min-result] |=== -It can be used by any field type, including `keyword` fields. In that case picks the -first string, comparing their utf-8 representation byte by byte: +It can be used by any column type, including `keyword` columns. In that case, +it picks the first string, comparing their utf-8 representation byte by byte: [source.merge.styled,esql] ---- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_sum.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_sum.asciidoc index 646af03305954e..bc252bc9d3fa0b 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_sum.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/mv_sum.asciidoc @@ -1,8 +1,27 @@ [discrete] [[esql-mv_sum]] === `MV_SUM` -Converts a multivalued field into a single valued field containing the sum -of all of the values. For example: + +[source,esql] +---- +MV_SUM(v) +---- + +*Parameters* + +`v`:: +Multivalue expression. + +*Description* + +Converts a multivalued column into a single valued column containing the sum +of all of the values. + +*Supported types* + +include::types/mv_sum.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -12,5 +31,3 @@ include::{esql-specs}/math.csv-spec[tag=mv_sum] |=== include::{esql-specs}/math.csv-spec[tag=mv_sum-result] |=== - -NOTE: The input type can be any number and the output type is the same as the input type. diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/now.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/now.asciidoc index 5d33449a1e906f..3c46f557acd1f2 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/now.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/now.asciidoc @@ -1,9 +1,28 @@ [discrete] [[esql-now]] === `NOW` + +*Syntax* + +[source,esql] +---- +NOW() +---- + +*Description* + Returns current date and time. +*Example* + [source,esql] ---- -ROW current_date = NOW() +include::{esql-specs}/date.csv-spec[tag=docsNow] +---- + +To retrieve logs from the last hour: + +[source,esql] ---- +include::{esql-specs}/date.csv-spec[tag=docsNowWhere] +---- \ No newline at end of file diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/operators.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/operators.asciidoc index c236413b5dd7e6..96cdd5a3778bef 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/operators.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/operators.asciidoc @@ -9,28 +9,24 @@ Boolean operators for comparing against one or multiple expressions. // tag::op_list[] * <> +* <> * <> * <> * <> * <> * <> -* <> -* <> -* <> * <> * <> * <> // end::op_list[] include::binary.asciidoc[] +include::unary.asciidoc[] include::logical.asciidoc[] include::predicates.asciidoc[] include::cidr_match.asciidoc[] include::ends_with.asciidoc[] include::in.asciidoc[] -include::is_finite.asciidoc[] -include::is_infinite.asciidoc[] -include::is_nan.asciidoc[] include::like.asciidoc[] include::rlike.asciidoc[] include::starts_with.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/percentile.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/percentile.asciidoc index 917a4a81e7b4f2..e00ee436c31cf3 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/percentile.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/percentile.asciidoc @@ -1,9 +1,29 @@ [discrete] [[esql-agg-percentile]] === `PERCENTILE` -The value at which a certain percentage of observed values occur. For example, -the 95th percentile is the value which is greater than 95% of the observed values and -the 50th percentile is the <>. + +*Syntax* + +[source,esql] +---- +PERCENTILE(expression, percentile) +---- + +*Parameters* + +`expression`:: +Expression from which to return a percentile. + +`percentile`:: +A constant numeric expression. + +*Description* + +Returns the value at which a certain percentage of observed values occur. For +example, the 95th percentile is the value which is greater than 95% of the +observed values and the 50th percentile is the <>. + +*Example* [source.merge.styled,esql] ---- @@ -14,6 +34,19 @@ include::{esql-specs}/stats_percentile.csv-spec[tag=percentile] include::{esql-specs}/stats_percentile.csv-spec[tag=percentile-result] |=== +The expression can use inline functions. For example, to calculate a percentile +of the maximum values of a multivalued column, first use `MV_MAX` to get the +maximum value per row, and use the result with the `PERCENTILE` function: + +[source.merge.styled,esql] +---- +include::{esql-specs}/stats_percentile.csv-spec[tag=docsStatsPercentileNestedExpression] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats_percentile.csv-spec[tag=docsStatsPercentileNestedExpression-result] +|=== + [discrete] [[esql-agg-percentile-approximate]] ==== `PERCENTILE` is (usually) approximate @@ -24,7 +57,4 @@ include::../../aggregations/metrics/percentile-aggregation.asciidoc[tag=approxim ==== `PERCENTILE` is also {wikipedia}/Nondeterministic_algorithm[non-deterministic]. This means you can get slightly different results using the same data. -==== - - - +==== \ No newline at end of file diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/pi.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/pi.asciidoc index cd630aaabadcd7..fb88cbffc99d0d 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/pi.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/pi.asciidoc @@ -1,10 +1,17 @@ [discrete] [[esql-pi]] === `PI` + +*Syntax* + [.text-center] image::esql/functions/signature/pi.svg[Embedded,opts=inline] -The {wikipedia}/Pi[ratio] of a circle's circumference to its diameter. +*Description* + +Returns the {wikipedia}/Pi[ratio] of a circle's circumference to its diameter. + +*Example* [source.merge.styled,esql] ---- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/pow.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/pow.asciidoc index 9f7805bfd3eae9..8c31bd21e8a463 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/pow.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/pow.asciidoc @@ -1,81 +1,41 @@ [discrete] [[esql-pow]] === `POW` -[.text-center] -image::esql/functions/signature/pow.svg[Embedded,opts=inline] - -Returns the value of a base (first argument) raised to the power of an exponent (second argument). -Both arguments must be numeric. -[source.merge.styled,esql] ----- -include::{esql-specs}/math.csv-spec[tag=powDI] ----- -[%header.monospaced.styled,format=dsv,separator=|] -|=== -include::{esql-specs}/math.csv-spec[tag=powDI-result] -|=== +*Syntax* -[discrete] -==== Type rules +[.text-center] +image::esql/functions/signature/pow.svg[Embedded,opts=inline] -The type of the returned value is determined by the types of the base and exponent. -The following rules are applied to determine the result type: +*Parameters* -* If either of the base or exponent are of a floating point type, the result will be a double -* Otherwise, if either the base or the exponent are 64-bit (long or unsigned long), the result will be a long -* Otherwise, the result will be a 32-bit integer (this covers all other numeric types, including int, short and byte) +`base`:: +Numeric expression. If `null`, the function returns `null`. -For example, using simple integers as arguments will lead to an integer result: +`exponent`:: +Numeric expression. If `null`, the function returns `null`. -[source.merge.styled,esql] ----- -include::{esql-specs}/math.csv-spec[tag=powII] ----- -[%header.monospaced.styled,format=dsv,separator=|] -|=== -include::{esql-specs}/math.csv-spec[tag=powII-result] -|=== +*Description* -NOTE: The actual power function is performed using double precision values for all cases. -This means that for very large non-floating point values there is a small chance that the -operation can lead to slightly different answers than expected. -However, a more likely outcome of very large non-floating point values is numerical overflow. +Returns the value of `base` raised to the power of `exponent`. Both arguments +must be numeric. The output is always a double. Note that it is still possible +to overflow a double result here; in that case, null will be returned. -[discrete] -==== Arithmetic errors +*Supported types* -Arithmetic errors and numeric overflow do not result in an error. Instead, the result will be `null` -and a warning for the `ArithmeticException` added. -For example: - -[source.merge.styled,esql] ----- -include::{esql-specs}/math.csv-spec[tag=powULOverrun] ----- -[%header.monospaced.styled,format=dsv,separator=|] -|=== -include::{esql-specs}/math.csv-spec[tag=powULOverrun-warning] -|=== -[%header.monospaced.styled,format=dsv,separator=|] -|=== -include::{esql-specs}/math.csv-spec[tag=powULOverrun-result] -|=== +include::types/pow.asciidoc[] -If it is desired to protect against numerical overruns, use `TO_DOUBLE` on either of the arguments: +*Examples* [source.merge.styled,esql] ---- -include::{esql-specs}/math.csv-spec[tag=pow2d] +include::{esql-specs}/math.csv-spec[tag=powDI] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/math.csv-spec[tag=pow2d-result] +include::{esql-specs}/math.csv-spec[tag=powDI-result] |=== -[discrete] -==== Fractional exponents - The exponent can be a fraction, which is similar to performing a root. For example, the exponent of `0.5` will give the square root of the base: @@ -87,10 +47,3 @@ include::{esql-specs}/math.csv-spec[tag=powID-sqrt] |=== include::{esql-specs}/math.csv-spec[tag=powID-sqrt-result] |=== - -[discrete] -==== Table of supported input and output types - -For clarity, the following table describes the output result type for all combinations of numeric input types: - -include::types/pow.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/predicates.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/predicates.asciidoc index 9a3ea89e9aa731..16b461b40ebf7f 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/predicates.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/predicates.asciidoc @@ -2,6 +2,7 @@ [[esql-predicates]] === `IS NULL` and `IS NOT NULL` predicates +//tag::body[] For NULL comparison, use the `IS NULL` and `IS NOT NULL` predicates: [source.merge.styled,esql] @@ -21,3 +22,4 @@ include::{esql-specs}/null.csv-spec[tag=is-not-null] |=== include::{esql-specs}/null.csv-spec[tag=is-not-null-result] |=== +//end::body[] \ No newline at end of file diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/replace.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/replace.asciidoc index 9bc0f85fdddce0..05856829eb193e 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/replace.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/replace.asciidoc @@ -1,11 +1,38 @@ [discrete] [[esql-replace]] === `REPLACE` -The function substitutes in the string (1st argument) any match of the regular expression (2nd argument) with the replacement string (3rd argument). -If any of the arguments are `NULL`, the result is `NULL`. +*Syntax* -. This example replaces an occurrence of the word "World" with the word "Universe": +[.text-center] +image::esql/functions/signature/replace.svg[Embedded,opts=inline] + +*Parameters* + +`str`:: +String expression. + +`regex`:: +Regular expression. + +`newStr`:: +Replacement string. + +*Description* + +The function substitutes in the string `str` any match of the regular expression +`regex` with the replacement string `newStr`. + +If any of the arguments is `null`, the result is `null`. + +*Supported types* + +include::types/replace.asciidoc[] + +*Example* + +This example replaces any occurrence of the word "World" with the word +"Universe": [source.merge.styled,esql] ---- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/right.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/right.asciidoc index a0f18192d410d8..1b291e53729ee6 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/right.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/right.asciidoc @@ -1,10 +1,30 @@ [discrete] [[esql-right]] === `RIGHT` + +*Syntax* + [.text-center] image::esql/functions/signature/right.svg[Embedded,opts=inline] -Return the substring that extracts 'length' chars from the 'string' starting from the right. +*Parameters* + +`str`:: +The string from which to returns a substring. + +`length`:: +The number of characters to return. + +*Description* + +Return the substring that extracts 'length' chars from 'str' starting +from the right. + +*Supported types* + +include::types/right.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,7 +34,3 @@ include::{esql-specs}/string.csv-spec[tag=right] |=== include::{esql-specs}/string.csv-spec[tag=right-result] |=== - -Supported types: - -include::types/right.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/rlike.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/rlike.asciidoc index 0fd8d8ab319da8..1cdbbe69641239 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/rlike.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/rlike.asciidoc @@ -2,14 +2,18 @@ [[esql-rlike-operator]] ==== `RLIKE` +// tag::body[] Use `RLIKE` to filter data based on string patterns using using <>. `RLIKE` usually acts on a field placed on the left-hand side of the operator, but it can also act on a constant (literal) expression. The right-hand side of the operator represents the pattern. -[source,esql] +[source.merge.styled,esql] ---- -FROM employees -| WHERE first_name RLIKE ".leja.*" -| KEEP first_name, last_name ----- \ No newline at end of file +include::{esql-specs}/docs.csv-spec[tag=rlike] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/docs.csv-spec[tag=rlike-result] +|=== +// end::body[] \ No newline at end of file diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/round.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/round.asciidoc index 4ec71cf682d0f3..7f1285e85f6646 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/round.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/round.asciidoc @@ -1,10 +1,31 @@ [discrete] [[esql-round]] === `ROUND` +*Syntax* + +[.text-center] +image::esql/functions/signature/round.svg[Embedded,opts=inline] + +*Parameters* + +`value`:: +Numeric expression. If `null`, the function returns `null`. + +`decimals`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + Rounds a number to the closest number with the specified number of digits. Defaults to 0 digits if no number of digits is provided. If the specified number of digits is negative, rounds to the number of digits left of the decimal point. +*Supported types* + +include::types/round.asciidoc[] + +*Example* + [source.merge.styled,esql] ---- include::{esql-specs}/docs.csv-spec[tag=round] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/rtrim.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/rtrim.asciidoc index 3224331e9ed6ab..588b7b9fc5433e 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/rtrim.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/rtrim.asciidoc @@ -1,8 +1,27 @@ [discrete] [[esql-rtrim]] === `RTRIM` + +*Syntax* + +[.text-center] +image::esql/functions/signature/rtrim.svg[Embedded,opts=inline] + +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +*Description* + Removes trailing whitespaces from strings. +*Supported types* + +include::types/rtrim.asciidoc[] + +*Example* + [source.merge.styled,esql] ---- include::{esql-specs}/string.csv-spec[tag=rtrim] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/sin.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/sin.asciidoc index 5fa33a315392d1..e6a8e0cf9331fc 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/sin.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/sin.asciidoc @@ -1,10 +1,27 @@ [discrete] [[esql-sin]] === `SIN` + +*Syntax* + [.text-center] image::esql/functions/signature/sin.svg[Embedded,opts=inline] -https://en.wikipedia.org/wiki/Sine_and_cosine[Sine] trigonometric function. +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +{wikipedia}/Sine_and_cosine[Sine] trigonometric function. Input expected in +radians. + +*Supported types* + +include::types/sin.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,7 +31,3 @@ include::{esql-specs}/floats.csv-spec[tag=sin] |=== include::{esql-specs}/floats.csv-spec[tag=sin-result] |=== - -Supported types: - -include::types/sin.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/sinh.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/sinh.asciidoc index 11d1ea29bffef4..683ae6962c2fd1 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/sinh.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/sinh.asciidoc @@ -1,10 +1,26 @@ [discrete] [[esql-sinh]] === `SINH` + +*Syntax* + [.text-center] image::esql/functions/signature/sinh.svg[Embedded,opts=inline] -https://en.wikipedia.org/wiki/Hyperbolic_functions[Sine] hyperbolic function. +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +{wikipedia}/Hyperbolic_functions[Sine] hyperbolic function. + +*Supported types* + +include::types/sinh.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,7 +30,3 @@ include::{esql-specs}/floats.csv-spec[tag=sinh] |=== include::{esql-specs}/floats.csv-spec[tag=sinh-result] |=== - -Supported types: - -include::types/sinh.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/split.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/split.asciidoc index a6f8869bf89caa..0a4ce584d01da9 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/split.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/split.asciidoc @@ -1,18 +1,33 @@ [discrete] [[esql-split]] === `SPLIT` -Split a single valued string into multiple strings. For example: -[source,esql] +[.text-center] +image::esql/functions/signature/split.svg[Embedded,opts=inline] + +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +`delim`:: +Delimiter. Only single byte delimiters are currently supported. + +*Description* + +Splits a single valued string into multiple strings. + +*Supported types* + +include::types/split.asciidoc[] + +*Example* + +[source.merge.styled,esql] ---- include::{esql-specs}/string.csv-spec[tag=split] ---- - -Which splits `"foo;bar;baz;qux;quux;corge"` on `;` and returns an array: - -[%header,format=dsv,separator=|] +[%header.monospaced.styled,format=dsv,separator=|] |=== include::{esql-specs}/string.csv-spec[tag=split-result] |=== - -WARNING: Only single byte delimiters are currently supported. diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/sqrt.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/sqrt.asciidoc index 02f7060089971d..faf504a6b0af4c 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/sqrt.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/sqrt.asciidoc @@ -1,13 +1,30 @@ [discrete] [[esql-sqrt]] === `SQRT` + +*Syntax* + [.text-center] image::esql/functions/signature/sqrt.svg[Embedded,opts=inline] -Returns the square root of a number. The input can be any numeric value, the return value -is always a double. +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +Returns the square root of a number. The input can be any numeric value, the +return value is always a double. + +Square roots of negative numbers are NaN. Square roots of infinites are +infinite. -Square roots of negative numbers are NaN. Square roots of infinites are infinite. +*Supported types* + +include::types/sqrt.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -17,7 +34,3 @@ include::{esql-specs}/math.csv-spec[tag=sqrt] |=== include::{esql-specs}/math.csv-spec[tag=sqrt-result] |=== - -Supported types: - -include::types/sqrt.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/st_centroid.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/st_centroid.asciidoc new file mode 100644 index 00000000000000..abed1e71eab8f5 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/st_centroid.asciidoc @@ -0,0 +1,18 @@ +[discrete] +[[esql-agg-st-centroid]] +=== `ST_CENTROID` + +Calculate the spatial centroid over a field with spatial point geometry type. + +[source.merge.styled,esql] +---- +include::{esql-specs}/spatial.csv-spec[tag=st_centroid-airports] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/spatial.csv-spec[tag=st_centroid-airports-result] +|=== + +Supported types: + +include::types/st_centroid.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/starts_with.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/starts_with.asciidoc index 38cee79ea63f87..4d45e89882400d 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/starts_with.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/starts_with.asciidoc @@ -1,11 +1,30 @@ [discrete] [[esql-starts_with]] === `STARTS_WITH` + +*Syntax* + [.text-center] -image::esql/functions/signature/ends_with.svg[Embedded,opts=inline] +image::esql/functions/signature/starts_with.svg[Embedded,opts=inline] + +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +`prefix`:: +String expression. If `null`, the function returns `null`. + +*Description* Returns a boolean that indicates whether a keyword string starts with another -string: +string. + +*Supported types* + +include::types/starts_with.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -15,7 +34,3 @@ include::{esql-specs}/docs.csv-spec[tag=startsWith] |=== include::{esql-specs}/docs.csv-spec[tag=startsWith-result] |=== - -Supported types: - -include::types/starts_with.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/string_functions.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/string_functions.asciidoc index b209244b932971..e9fe04ce15761e 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/string_functions.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/string_functions.asciidoc @@ -17,6 +17,8 @@ * <> * <> * <> +* <> +* <> * <> // end::string_list[] @@ -29,4 +31,6 @@ include::right.asciidoc[] include::rtrim.asciidoc[] include::split.asciidoc[] include::substring.asciidoc[] +include::to_lower.asciidoc[] +include::to_upper.asciidoc[] include::trim.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/substring.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/substring.asciidoc index 8b8234de05bbaf..73df7a19aa6b74 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/substring.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/substring.asciidoc @@ -1,8 +1,36 @@ [discrete] [[esql-substring]] === `SUBSTRING` + +*Syntax* + +[.text-center] +image::esql/functions/signature/substring.svg[Embedded,opts=inline] + +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +`start`:: +Start position. + +`length`:: +Length of the substring from the start position. Optional; if omitted, all +positions after `start` are returned. + +*Description* + Returns a substring of a string, specified by a start position and an optional -length. This example returns the first three characters of every last name: +length. + +*Supported types* + +include::types/substring.asciidoc[] + +*Examples* + +This example returns the first three characters of every last name: [source.merge.styled,esql] ---- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/sum.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/sum.asciidoc index abf790040114d1..efe65d5503ec63 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/sum.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/sum.asciidoc @@ -1,7 +1,22 @@ [discrete] [[esql-agg-sum]] === `SUM` -The sum of a numeric field. + +*Syntax* + +[source,esql] +---- +SUM(expression) +---- + +`expression`:: +Numeric expression. + +*Description* + +Returns the sum of a numeric expression. + +*Example* [source.merge.styled,esql] ---- @@ -11,3 +26,16 @@ include::{esql-specs}/stats.csv-spec[tag=sum] |=== include::{esql-specs}/stats.csv-spec[tag=sum-result] |=== + +The expression can use inline functions. For example, to calculate +the sum of each employee's maximum salary changes, apply the +`MV_MAX` function to each row and then sum the results: + +[source.merge.styled,esql] +---- +include::{esql-specs}/stats.csv-spec[tag=docsStatsSumNestedExpression] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats.csv-spec[tag=docsStatsSumNestedExpression-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/tan.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/tan.asciidoc index 1c66562eada7a7..cc06421616fc17 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/tan.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/tan.asciidoc @@ -1,10 +1,27 @@ [discrete] [[esql-tan]] === `TAN` + +*Syntax* + [.text-center] image::esql/functions/signature/tan.svg[Embedded,opts=inline] -https://en.wikipedia.org/wiki/Sine_and_cosine[Tangent] trigonometric function. +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +{wikipedia}/Sine_and_cosine[Tangent] trigonometric function. Input expected in +radians. + +*Supported types* + +include::types/tan.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,7 +31,3 @@ include::{esql-specs}/floats.csv-spec[tag=tan] |=== include::{esql-specs}/floats.csv-spec[tag=tan-result] |=== - -Supported types: - -include::types/tan.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/tanh.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/tanh.asciidoc index 218a0155d861c9..a21354d23ba503 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/tanh.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/tanh.asciidoc @@ -1,10 +1,26 @@ [discrete] [[esql-tanh]] === `TANH` + +*Syntax* + [.text-center] image::esql/functions/signature/tanh.svg[Embedded,opts=inline] -https://en.wikipedia.org/wiki/Hyperbolic_functions[Tangent] hyperbolic function. +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +{wikipedia}/Hyperbolic_functions[Tangent] hyperbolic function. + +*Supported types* + +include::types/tanh.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,7 +30,3 @@ include::{esql-specs}/floats.csv-spec[tag=tanh] |=== include::{esql-specs}/floats.csv-spec[tag=tanh-result] |=== - -Supported types: - -include::types/tanh.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/tau.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/tau.asciidoc index 61f352b0db8dea..d9720eb34d7959 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/tau.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/tau.asciidoc @@ -1,10 +1,18 @@ [discrete] [[esql-tau]] === `TAU` + +*Syntax* + [.text-center] image::esql/functions/signature/tau.svg[Embedded,opts=inline] -The https://tauday.com/tau-manifesto[ratio] of a circle's circumference to its radius. +*Description* + +Returns the https://tauday.com/tau-manifesto[ratio] of a circle's circumference +to its radius. + +*Example* [source.merge.styled,esql] ---- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_boolean.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_boolean.asciidoc index 03f21a503218cc..54c41625f3eba7 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_boolean.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_boolean.asciidoc @@ -1,14 +1,39 @@ [discrete] [[esql-to_boolean]] === `TO_BOOLEAN` -Converts an input value to a boolean value. -The input can be a single- or multi-valued field or an expression. The input -type must be of a string or numeric type. +*Alias* + +`TO_BOOL` + +*Syntax* + +[source,esql] +---- +TO_BOOLEAN(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + +Converts an input value to a boolean value. A string value of *"true"* will be case-insensitive converted to the Boolean *true*. For anything else, including the empty string, the function will -return *false*. For example: +return *false*. + +The numerical value of *0* will be converted to *false*, anything else will be +converted to *true*. + +*Supported types* + +The input type must be of a string or numeric type. + +*Example* [source.merge.styled,esql] ---- @@ -18,8 +43,3 @@ include::{esql-specs}/boolean.csv-spec[tag=to_boolean] |=== include::{esql-specs}/boolean.csv-spec[tag=to_boolean-result] |=== - -The numerical value of *0* will be converted to *false*, anything else will be -converted to *true*. - -Alias: TO_BOOL diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_cartesianpoint.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_cartesianpoint.asciidoc new file mode 100644 index 00000000000000..223556d2c0e96d --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_cartesianpoint.asciidoc @@ -0,0 +1,37 @@ +[discrete] +[[esql-to_cartesianpoint]] +=== `TO_CARTESIANPOINT` + +*Syntax* + +[source,esql] +---- +TO_CARTESIANPOINT(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + +Converts an input value to a `point` value. + +A string will only be successfully converted if it respects the +{wikipedia}/Well-known_text_representation_of_geometry[WKT Point] format. + +*Supported types* + +include::types/to_cartesianpoint.asciidoc[] + +*Example* + +[source.merge.styled,esql] +---- +include::{esql-specs}/spatial.csv-spec[tag=to_cartesianpoint-str] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/spatial.csv-spec[tag=to_cartesianpoint-str-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_cartesianshape.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_cartesianshape.asciidoc new file mode 100644 index 00000000000000..287d437b3906c5 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_cartesianshape.asciidoc @@ -0,0 +1,38 @@ +[discrete] +[[esql-to_cartesianshape]] +=== `TO_CARTESIANSHAPE` + +*Syntax* + +[source,esql] +---- +TO_CARTESIANSHAPE(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. +The input type must be a string, a `cartesian_shape` or a `cartesian_point`. + +*Description* + +Converts an input value to a `cartesian_shape` value. + +A string will only be successfully converted if it respects the +{wikipedia}/Well-known_text_representation_of_geometry[WKT] format. + +*Supported types* + +include::types/to_cartesianshape.asciidoc[] + +*Example* + +[source.merge.styled,esql] +---- +include::{esql-specs}/spatial_shapes.csv-spec[tag=to_cartesianshape-str] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/spatial_shapes.csv-spec[tag=to_cartesianshape-str-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_datetime.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_datetime.asciidoc index 750c8025cb6c29..9baf7d818d93c4 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_datetime.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_datetime.asciidoc @@ -1,13 +1,36 @@ [discrete] [[esql-to_datetime]] === `TO_DATETIME` -Converts an input value to a date value. -The input can be a single- or multi-valued field or an expression. The input -type must be of a string or numeric type. +*Alias* + +`TO_DT` + +*Syntax* + +[source,esql] +---- +TO_DATETIME(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + +Converts an input value to a date value. A string will only be successfully converted if it's respecting the format -`yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` (to convert dates in other formats, use <>). For example: +`yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`. To convert dates in other formats, use +<>. + +*Supported types* + +The input type must be of a string or numeric type. + +*Examples* [source.merge.styled,esql] ---- @@ -30,10 +53,8 @@ A following header will contain the failure reason and the offending value: `"java.lang.IllegalArgumentException: failed to parse date field [1964-06-02 00:00:00] with format [yyyy-MM-dd'T'HH:mm:ss.SSS'Z']"` - If the input parameter is of a numeric type, its value will be interpreted as -milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch]. -For example: +milliseconds since the {wikipedia}/Unix_time[Unix epoch]. For example: [source.merge.styled,esql] ---- @@ -43,5 +64,3 @@ include::{esql-specs}/date.csv-spec[tag=to_datetime-int] |=== include::{esql-specs}/date.csv-spec[tag=to_datetime-int-result] |=== - -Alias: TO_DT diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_degrees.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_degrees.asciidoc index 71b480253fe358..7b0846c9a4c3f9 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_degrees.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_degrees.asciidoc @@ -1,13 +1,29 @@ [discrete] [[esql-to_degrees]] === `TO_DEGREES` -Converts a number in https://en.wikipedia.org/wiki/Radian[radians] -to https://en.wikipedia.org/wiki/Degree_(angle)[degrees]. -The input can be a single- or multi-valued field or an expression. The input -type must be of a numeric type and result is always `double`. +*Syntax* -Example: +[source,esql] +---- +TO_DEGREES(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + +Converts a number in {wikipedia}/Radian[radians] to +{wikipedia}/Degree_(angle)[degrees]. + +*Supported types* + +The input type must be of a numeric type and result is always `double`. + +*Example* [source.merge.styled,esql] ---- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_double.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_double.asciidoc index 27ad84e4c77622..5d372d6c77c39c 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_double.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_double.asciidoc @@ -1,12 +1,37 @@ [discrete] [[esql-to_double]] === `TO_DOUBLE` + +*Alias* + +`TO_DBL` + +*Syntax* + +[source,esql] +---- +TO_DOUBLE(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + Converts an input value to a double value. -The input can be a single- or multi-valued field or an expression. The input -type must be of a boolean, date, string or numeric type. +If the input parameter is of a date type, its value will be interpreted as +milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to double. -Example: +Boolean *true* will be converted to double *1.0*, *false* to *0.0*. + +*Supported types* + +The input type must be of a boolean, date, string or numeric type. + +*Example* [source.merge.styled,esql] ---- @@ -17,22 +42,13 @@ include::{esql-specs}/floats.csv-spec[tag=to_double-str] include::{esql-specs}/floats.csv-spec[tag=to_double-str-result] |=== -Note that in this example, the last conversion of the string isn't -possible. When this happens, the result is a *null* value. In this case a -_Warning_ header is added to the response. The header will provide information -on the source of the failure: +Note that in this example, the last conversion of the string isn't possible. +When this happens, the result is a *null* value. In this case a _Warning_ header +is added to the response. The header will provide information on the source of +the failure: `"Line 1:115: evaluation of [TO_DOUBLE(str2)] failed, treating result as null. Only first 20 failures recorded."` A following header will contain the failure reason and the offending value: `"java.lang.NumberFormatException: For input string: \"foo\""` - - -If the input parameter is of a date type, its value will be interpreted as -milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch], -converted to double. - -Boolean *true* will be converted to double *1.0*, *false* to *0.0*. - -Alias: TO_DBL diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_geopoint.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_geopoint.asciidoc new file mode 100644 index 00000000000000..d4d7d397d8f7ba --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_geopoint.asciidoc @@ -0,0 +1,38 @@ +[discrete] +[[esql-to_geopoint]] +=== `TO_GEOPOINT` + +*Syntax* + +[source,esql] +---- +TO_GEOPOINT(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. +The input type must be a string or a `geo_point`. + +*Description* + +Converts an input value to a `geo_point` value. + +*Supported types* + +include::types/to_geopoint.asciidoc[] + +A string will only be successfully converted if it respects the +{wikipedia}/Well-known_text_representation_of_geometry[WKT Point] format. + +*Example* + +[source.merge.styled,esql] +---- +include::{esql-specs}/spatial.csv-spec[tag=to_geopoint-str] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/spatial.csv-spec[tag=to_geopoint-str-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_geoshape.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_geoshape.asciidoc new file mode 100644 index 00000000000000..8a6ec978dc7bf5 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_geoshape.asciidoc @@ -0,0 +1,38 @@ +[discrete] +[[esql-to_geoshape]] +=== `TO_GEOSHAPE` + +*Syntax* + +[source,esql] +---- +TO_GEOPOINT(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. +The input type must be a string, a `geo_shape` or a `geo_point`. + +*Description* + +Converts an input value to a `geo_shape` value. + +A string will only be successfully converted if it respects the +{wikipedia}/Well-known_text_representation_of_geometry[WKT] format. + +*Supported types* + +include::types/to_geoshape.asciidoc[] + +*Example* + +[source.merge.styled,esql] +---- +include::{esql-specs}/spatial_shapes.csv-spec[tag=to_geoshape-str] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/spatial_shapes.csv-spec[tag=to_geoshape-str-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_integer.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_integer.asciidoc index e185b87d6d95dc..f07bdcd231e406 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_integer.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_integer.asciidoc @@ -1,12 +1,37 @@ [discrete] [[esql-to_integer]] === `TO_INTEGER` + +*Alias* + +`TO_INT` + +*Syntax* + +[source,esql] +---- +TO_INTEGER(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + Converts an input value to an integer value. -The input can be a single- or multi-valued field or an expression. The input -type must be of a boolean, date, string or numeric type. +If the input parameter is of a date type, its value will be interpreted as +milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to integer. -Example: +Boolean *true* will be converted to integer *1*, *false* to *0*. + +*Supported types* + +The input type must be of a boolean, date, string or numeric type. + +*Example* [source.merge.styled,esql] ---- @@ -26,13 +51,4 @@ provide information on the source of the failure: A following header will contain the failure reason and the offending value: -`"org.elasticsearch.xpack.ql.QlIllegalArgumentException: [501379200000] out of [integer] range"` - - -If the input parameter is of a date type, its value will be interpreted as -milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch], -converted to integer. - -Boolean *true* will be converted to integer *1*, *false* to *0*. - -Alias: TO_INT +`"org.elasticsearch.xpack.ql.InvalidArgumentException: [501379200000] out of [integer] range"` diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_ip.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_ip.asciidoc index dea147eba1a41f..28e98ea69c3059 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_ip.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_ip.asciidoc @@ -1,11 +1,24 @@ [discrete] [[esql-to_ip]] === `TO_IP` -Converts an input string to an IP value. -The input can be a single- or multi-valued field or an expression. +*Syntax* + +[source,esql] +---- +TO_IP(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + +Converts an input string to an IP value. -Example: +*Example* [source.merge.styled,esql] ---- @@ -16,10 +29,10 @@ include::{esql-specs}/ip.csv-spec[tag=to_ip] include::{esql-specs}/ip.csv-spec[tag=to_ip-result] |=== -Note that in the example above the last conversion of the string isn't -possible. When this happens, the result is a *null* value. In this case a -_Warning_ header is added to the response. The header will provide information -on the source of the failure: +Note that in this example, the last conversion of the string isn't possible. +When this happens, the result is a *null* value. In this case a _Warning_ header +is added to the response. The header will provide information on the source of +the failure: `"Line 1:68: evaluation of [TO_IP(str2)] failed, treating result as null. Only first 20 failures recorded."` diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_long.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_long.asciidoc index 9501c28a316577..04b2e3980a07d0 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_long.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_long.asciidoc @@ -1,12 +1,33 @@ [discrete] [[esql-to_long]] === `TO_LONG` + +*Syntax* + +[source,esql] +---- +TO_LONG(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + Converts an input value to a long value. -The input can be a single- or multi-valued field or an expression. The input -type must be of a boolean, date, string or numeric type. +If the input parameter is of a date type, its value will be interpreted as +milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to long. + +Boolean *true* will be converted to long *1*, *false* to *0*. + +*Supported types* -Example: +The input type must be of a boolean, date, string or numeric type. + +*Example* [source.merge.styled,esql] ---- @@ -27,10 +48,3 @@ on the source of the failure: A following header will contain the failure reason and the offending value: `"java.lang.NumberFormatException: For input string: \"foo\""` - - -If the input parameter is of a date type, its value will be interpreted as -milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch], -converted to long. - -Boolean *true* will be converted to long *1*, *false* to *0*. diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_lower.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_lower.asciidoc new file mode 100644 index 00000000000000..5b98d82c9a94fc --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_lower.asciidoc @@ -0,0 +1,32 @@ +[discrete] +[[esql-to_lower]] +=== `TO_LOWER` + +*Syntax* + +[.text-center] +image::esql/functions/signature/to_lower.svg[Embedded,opts=inline] + +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +*Description* + +Returns a new string representing the input string converted to lower case. + +*Supported types* + +include::types/to_lower.asciidoc[] + +*Example* + +[source.merge.styled,esql] +---- +include::{esql-specs}/string.csv-spec[tag=to_lower] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/string.csv-spec[tag=to_lower-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_radians.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_radians.asciidoc index 1f86f1fb983cc0..f3b1fbd1f37946 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_radians.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_radians.asciidoc @@ -1,13 +1,29 @@ [discrete] [[esql-to_radians]] === `TO_RADIANS` -Converts a number in https://en.wikipedia.org/wiki/Degree_(angle)[degrees] to -https://en.wikipedia.org/wiki/Radian[radians]. -The input can be a single- or multi-valued field or an expression. The input -type must be of a numeric type and result is always `double`. +*Syntax* -Example: +[source,esql] +---- +TO_RADIANS(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + +Converts a number in {wikipedia}/Degree_(angle)[degrees] to +{wikipedia}/Radian[radians]. + +*Supported types* + +The input type must be of a numeric type and result is always `double`. + +*Example* [source.merge.styled,esql] ---- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_string.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_string.asciidoc index d03b6511b8de5e..e771915977d97d 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_string.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_string.asciidoc @@ -1,10 +1,28 @@ [discrete] [[esql-to_string]] === `TO_STRING` + +*Alias* + +`TO_STR` + [.text-center] image::esql/functions/signature/to_string.svg[Embedded,opts=inline] -Converts a field into a string. For example: +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + +Converts an input value into a string. + +*Supported types* + +include::types/to_string.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -25,9 +43,3 @@ include::{esql-specs}/string.csv-spec[tag=to_string_multivalue] |=== include::{esql-specs}/string.csv-spec[tag=to_string_multivalue-result] |=== - -Alias: TO_STR - -Supported types: - -include::types/to_string.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_unsigned_long.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_unsigned_long.asciidoc index af3ff05bf055c8..a4a6cfd54ed6f5 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_unsigned_long.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_unsigned_long.asciidoc @@ -1,12 +1,38 @@ [discrete] [[esql-to_unsigned_long]] === `TO_UNSIGNED_LONG` + +*Aliases* + +`TO_ULONG`, `TO_UL` + +*Syntax* + +[source,esql] +---- +TO_UNSIGNED_LONG(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + Converts an input value to an unsigned long value. -The input can be a single- or multi-valued field or an expression. The input -type must be of a boolean, date, string or numeric type. +*Supported types* -Example: +The input type must be of a boolean, date, string or numeric type. + +If the input parameter is of a date type, its value will be interpreted as +milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to unsigned +long. + +Boolean *true* will be converted to unsigned long *1*, *false* to *0*. + +*Example* [source.merge.styled,esql] ---- @@ -27,12 +53,3 @@ on the source of the failure: A following header will contain the failure reason and the offending value: `"java.lang.NumberFormatException: Character f is neither a decimal digit number, decimal point, nor \"e\" notation exponential mark."` - - -If the input parameter is of a date type, its value will be interpreted as -milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch], -converted to unsigned long. - -Boolean *true* will be converted to unsigned long *1*, *false* to *0*. - -Alias: TO_ULONG, TO_UL diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_upper.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_upper.asciidoc new file mode 100644 index 00000000000000..cea63bcbb4bb07 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_upper.asciidoc @@ -0,0 +1,32 @@ +[discrete] +[[esql-to_upper]] +=== `TO_UPPER` + +*Syntax* + +[.text-center] +image::esql/functions/signature/to_upper.svg[Embedded,opts=inline] + +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +*Description* + +Returns a new string representing the input string converted to upper case. + +*Supported types* + +include::types/to_upper.asciidoc[] + +*Example* + +[source.merge.styled,esql] +---- +include::{esql-specs}/string.csv-spec[tag=to_upper] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/string.csv-spec[tag=to_upper-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_version.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_version.asciidoc index 33419233c47882..6a1583889c87f2 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_version.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/to_version.asciidoc @@ -1,10 +1,30 @@ [discrete] [[esql-to_version]] === `TO_VERSION` + +*Alias* + +`TO_VER` + +*Syntax* + [.text-center] image::esql/functions/signature/to_version.svg[Embedded,opts=inline] -Converts an input string to a version value. For example: +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + +Converts an input string to a version value. + +*Supported types* + +include::types/to_version.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,11 +34,3 @@ include::{esql-specs}/version.csv-spec[tag=to_version] |=== include::{esql-specs}/version.csv-spec[tag=to_version-result] |=== - -The input can be a single- or multi-valued field or an expression. - -Alias: TO_VER - -Supported types: - -include::types/to_version.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/trim.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/trim.asciidoc index 6ace6118dd7578..0b246b7526cd2d 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/trim.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/trim.asciidoc @@ -1,11 +1,27 @@ [discrete] [[esql-trim]] === `TRIM` + +*Syntax* + [.text-center] image::esql/functions/signature/trim.svg[Embedded,opts=inline] +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +*Description* + Removes leading and trailing whitespaces from strings. +*Supported types* + +include::types/trim.asciidoc[] + +*Example* + [source.merge.styled,esql] ---- include::{esql-specs}/string.csv-spec[tag=trim] @@ -14,7 +30,3 @@ include::{esql-specs}/string.csv-spec[tag=trim] |=== include::{esql-specs}/string.csv-spec[tag=trim-result] |=== - -Supported types: - -include::types/trim.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/type_conversion_functions.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/type_conversion_functions.asciidoc index 640006c936526c..611e1f7fddfb42 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/type_conversion_functions.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/type_conversion_functions.asciidoc @@ -9,9 +9,13 @@ // tag::type_list[] * <> +* <> +* <> * <> * <> * <> +* <> +* <> * <> * <> * <> @@ -22,9 +26,13 @@ // end::type_list[] include::to_boolean.asciidoc[] +include::to_cartesianpoint.asciidoc[] +include::to_cartesianshape.asciidoc[] include::to_datetime.asciidoc[] include::to_degrees.asciidoc[] include::to_double.asciidoc[] +include::to_geopoint.asciidoc[] +include::to_geoshape.asciidoc[] include::to_integer.asciidoc[] include::to_ip.asciidoc[] include::to_long.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/add.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/add.asciidoc new file mode 100644 index 00000000000000..3665c112d802de --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/add.asciidoc @@ -0,0 +1,20 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +date_period | date_period | date_period +date_period | datetime | datetime +datetime | date_period | datetime +datetime | time_duration | datetime +double | double | double +double | integer | double +double | long | double +integer | double | double +integer | integer | integer +integer | long | long +long | double | double +long | integer | long +long | long | long +time_duration | datetime | datetime +time_duration | time_duration | time_duration +unsigned_long | unsigned_long | unsigned_long +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/auto_bucket.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/auto_bucket.asciidoc index d2f134b99fbb08..e0ede29e40df19 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/auto_bucket.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/auto_bucket.asciidoc @@ -1,5 +1,5 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | arg2 | arg3 | arg4 | result +field | buckets | from | to | result |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/case.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/case.asciidoc index 7062d7000115a4..3bf3d8ad3d7132 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/case.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/case.asciidoc @@ -1,5 +1,5 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | arg2 | result +condition | rest | result |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/coalesce.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/coalesce.asciidoc index e36316ab87bb5d..2daf6126d6fb0c 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/coalesce.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/coalesce.asciidoc @@ -1,6 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | arg2 | result +expression | expressionX | result boolean | boolean | boolean integer | integer | integer keyword | keyword | keyword diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/concat.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/concat.asciidoc index f422b45f0b34c3..1f14abf9c498f1 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/concat.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/concat.asciidoc @@ -1,6 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | arg2 | result +first | rest | result keyword | keyword | keyword text | text | keyword |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/date_diff.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/date_diff.asciidoc new file mode 100644 index 00000000000000..b4e5c6ad5e0b5f --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/date_diff.asciidoc @@ -0,0 +1,6 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +unit | startTimestamp | endTimestamp | result +keyword | datetime | datetime | integer +text | datetime | datetime | integer +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/date_extract.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/date_extract.asciidoc index 9963c85b2af857..edd244548fb180 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/date_extract.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/date_extract.asciidoc @@ -1,5 +1,5 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | arg2 | result +date_part | field | result keyword | datetime | long |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/div.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/div.asciidoc new file mode 100644 index 00000000000000..eee2d68e4653ff --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/div.asciidoc @@ -0,0 +1,7 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +double | double | double +integer | integer | integer +long | long | long +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/ends_with.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/ends_with.asciidoc index 6c406b80c0cad6..88489185b41f79 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/ends_with.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/ends_with.asciidoc @@ -1,5 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | arg2 | result +str | suffix | result keyword | keyword | boolean +text | text | boolean |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/equals.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/equals.asciidoc new file mode 100644 index 00000000000000..27fb19b6d38a2d --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/equals.asciidoc @@ -0,0 +1,5 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +integer | integer | boolean +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/greater_than.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/greater_than.asciidoc new file mode 100644 index 00000000000000..27fb19b6d38a2d --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/greater_than.asciidoc @@ -0,0 +1,5 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +integer | integer | boolean +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/greater_than_or_equal.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/greater_than_or_equal.asciidoc new file mode 100644 index 00000000000000..27fb19b6d38a2d --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/greater_than_or_equal.asciidoc @@ -0,0 +1,5 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +integer | integer | boolean +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/left.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/left.asciidoc index c30a055f3be493..6899a408969f78 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/left.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/left.asciidoc @@ -1,5 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -string | length | result +str | length | result keyword | integer | keyword +text | integer | keyword |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/length.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/length.asciidoc index 9af62defcb2a95..de84fe63c794a3 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/length.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/length.asciidoc @@ -1,5 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | result +str | result keyword | integer +text | integer |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/less_than.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/less_than.asciidoc new file mode 100644 index 00000000000000..27fb19b6d38a2d --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/less_than.asciidoc @@ -0,0 +1,5 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +integer | integer | boolean +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/less_than_or_equal.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/less_than_or_equal.asciidoc new file mode 100644 index 00000000000000..27fb19b6d38a2d --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/less_than_or_equal.asciidoc @@ -0,0 +1,5 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +integer | integer | boolean +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/log.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/log.asciidoc new file mode 100644 index 00000000000000..d72ea848c349f9 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/log.asciidoc @@ -0,0 +1,20 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +base | value | result +double | double | double +double | integer | double +double | long | double +double | unsigned_long | double +integer | double | double +integer | integer | double +integer | long | double +integer | unsigned_long | double +long | double | double +long | integer | double +long | long | double +long | unsigned_long | double +unsigned_long | double | double +unsigned_long | integer | double +unsigned_long | long | double +unsigned_long | unsigned_long | double +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/ltrim.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/ltrim.asciidoc index 11c02c8f0c3bb4..26f4e7633d8aef 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/ltrim.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/ltrim.asciidoc @@ -1,6 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | result +str | result keyword | keyword text | text |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mod.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mod.asciidoc new file mode 100644 index 00000000000000..eee2d68e4653ff --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mod.asciidoc @@ -0,0 +1,7 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +double | double | double +integer | integer | integer +long | long | long +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mul.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mul.asciidoc new file mode 100644 index 00000000000000..2f5100b1d1494c --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mul.asciidoc @@ -0,0 +1,8 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +double | double | double +integer | integer | integer +long | long | long +unsigned_long | unsigned_long | unsigned_long +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_avg.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_avg.asciidoc index dd4f6b0725cc85..0bba9b341c3019 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_avg.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_avg.asciidoc @@ -1,6 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | result +field | result double | double integer | double long | double diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_concat.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_concat.asciidoc index 2836799f335e83..e3ea8b0830f475 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_concat.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_concat.asciidoc @@ -1,6 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | arg2 | result +v | delim | result keyword | keyword | keyword keyword | text | keyword text | keyword | keyword diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_count.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_count.asciidoc index 2fcdfc65fa63b3..a2e7119bab05d7 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_count.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_count.asciidoc @@ -1,10 +1,18 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | result +v | result boolean | integer +cartesian_point | integer +cartesian_shape | integer +datetime | integer double | integer +geo_point | integer +geo_shape | integer integer | integer +ip | integer keyword | integer long | integer +text | integer unsigned_long | integer +version | integer |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_dedupe.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_dedupe.asciidoc index 4e12c684226623..dc1175ccdd9518 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_dedupe.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_dedupe.asciidoc @@ -1,9 +1,13 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | result +v | result boolean | boolean +datetime | datetime double | double integer | integer +ip | ip keyword | keyword long | long +text | text +version | version |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_first.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_first.asciidoc new file mode 100644 index 00000000000000..620c7cf13b7715 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_first.asciidoc @@ -0,0 +1,18 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +v | result +boolean | boolean +cartesian_point | cartesian_point +cartesian_shape | cartesian_shape +datetime | datetime +double | double +geo_point | geo_point +geo_shape | geo_shape +integer | integer +ip | ip +keyword | keyword +long | long +text | text +unsigned_long | unsigned_long +version | version +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_last.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_last.asciidoc new file mode 100644 index 00000000000000..620c7cf13b7715 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_last.asciidoc @@ -0,0 +1,18 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +v | result +boolean | boolean +cartesian_point | cartesian_point +cartesian_shape | cartesian_shape +datetime | datetime +double | double +geo_point | geo_point +geo_shape | geo_shape +integer | integer +ip | ip +keyword | keyword +long | long +text | text +unsigned_long | unsigned_long +version | version +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_max.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_max.asciidoc index 50740a71e4b492..1a9a1bee083882 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_max.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_max.asciidoc @@ -1,10 +1,14 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | result +v | result boolean | boolean +datetime | datetime double | double integer | integer +ip | ip keyword | keyword long | long +text | text unsigned_long | unsigned_long +version | version |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_median.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_median.asciidoc index f1831429aa95c5..4bb9cf6c7a1cb1 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_median.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_median.asciidoc @@ -1,6 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | result +v | result double | double integer | integer long | long diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_min.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_min.asciidoc index 50740a71e4b492..1a9a1bee083882 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_min.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_min.asciidoc @@ -1,10 +1,14 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | result +v | result boolean | boolean +datetime | datetime double | double integer | integer +ip | ip keyword | keyword long | long +text | text unsigned_long | unsigned_long +version | version |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_sum.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_sum.asciidoc index 09cb78511d2758..4bb9cf6c7a1cb1 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_sum.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/mv_sum.asciidoc @@ -1,5 +1,8 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | result +v | result double | double +integer | integer +long | long +unsigned_long | unsigned_long |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/neg.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/neg.asciidoc new file mode 100644 index 00000000000000..1b841483fb22e5 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/neg.asciidoc @@ -0,0 +1,9 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +v | result +date_period | date_period +double | double +integer | integer +long | long +time_duration | time_duration +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/not_equals.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/not_equals.asciidoc new file mode 100644 index 00000000000000..27fb19b6d38a2d --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/not_equals.asciidoc @@ -0,0 +1,5 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +integer | integer | boolean +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/pow.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/pow.asciidoc index 37bddc60c118f0..0e22c123ebf536 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/pow.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/pow.asciidoc @@ -3,8 +3,18 @@ base | exponent | result double | double | double double | integer | double +double | long | double +double | unsigned_long | double integer | double | double -integer | integer | integer +integer | integer | double +integer | long | double +integer | unsigned_long | double long | double | double -long | integer | long +long | integer | double +long | long | double +long | unsigned_long | double +unsigned_long | double | double +unsigned_long | integer | double +unsigned_long | long | double +unsigned_long | unsigned_long | double |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/replace.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/replace.asciidoc index 6824d1fd97128e..8c2be37bd63a0c 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/replace.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/replace.asciidoc @@ -1,6 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | arg2 | arg3 | result +str | regex | newStr | result keyword | keyword | keyword | keyword keyword | keyword | text | keyword keyword | text | keyword | keyword diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/right.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/right.asciidoc index c30a055f3be493..6899a408969f78 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/right.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/right.asciidoc @@ -1,5 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -string | length | result +str | length | result keyword | integer | keyword +text | integer | keyword |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/round.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/round.asciidoc index 5ba9e2f776d75e..33e89c91f0bfe0 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/round.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/round.asciidoc @@ -1,5 +1,5 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | arg2 | result +value | decimals | result double | integer | double |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/rtrim.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/rtrim.asciidoc index 11c02c8f0c3bb4..26f4e7633d8aef 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/rtrim.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/rtrim.asciidoc @@ -1,6 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | result +str | result keyword | keyword text | text |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/split.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/split.asciidoc index f1f744dbe4126d..4b5e6856c8fe2a 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/split.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/split.asciidoc @@ -1,5 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | arg2 | result +str | delim | result keyword | keyword | keyword +text | text | keyword |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/st_centroid.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/st_centroid.asciidoc new file mode 100644 index 00000000000000..cbafb9d0fa6dcc --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/st_centroid.asciidoc @@ -0,0 +1,6 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +v | result +geo_point | geo_point +cartesian_point | cartesian_point +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/starts_with.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/starts_with.asciidoc index 6c406b80c0cad6..863ddef3c0361c 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/starts_with.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/starts_with.asciidoc @@ -1,5 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | arg2 | result +str | prefix | result keyword | keyword | boolean +text | text | boolean |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/sub.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/sub.asciidoc new file mode 100644 index 00000000000000..826c4f6274652b --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/sub.asciidoc @@ -0,0 +1,12 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +date_period | date_period | date_period +datetime | date_period | datetime +datetime | time_duration | datetime +double | double | double +integer | integer | integer +long | long | long +time_duration | time_duration | time_duration +unsigned_long | unsigned_long | unsigned_long +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/substring.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/substring.asciidoc index 2aa96ceeb7e43c..f12a40c9253fb3 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/substring.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/substring.asciidoc @@ -1,5 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | arg2 | arg3 | result +str | start | length | result keyword | integer | integer | keyword +text | integer | integer | keyword |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_boolean.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_boolean.asciidoc new file mode 100644 index 00000000000000..7f543963eb0907 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_boolean.asciidoc @@ -0,0 +1,11 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +v | result +boolean | boolean +double | boolean +integer | boolean +keyword | boolean +long | boolean +text | boolean +unsigned_long | boolean +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_cartesianpoint.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_cartesianpoint.asciidoc new file mode 100644 index 00000000000000..081d879c4b7131 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_cartesianpoint.asciidoc @@ -0,0 +1,7 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +v | result +cartesian_point | cartesian_point +keyword | cartesian_point +text | cartesian_point +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_cartesianshape.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_cartesianshape.asciidoc new file mode 100644 index 00000000000000..258a31169782d4 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_cartesianshape.asciidoc @@ -0,0 +1,8 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +v | result +cartesian_point | cartesian_shape +cartesian_shape | cartesian_shape +keyword | cartesian_shape +text | cartesian_shape +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_datetime.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_datetime.asciidoc new file mode 100644 index 00000000000000..bbd755f81f4da8 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_datetime.asciidoc @@ -0,0 +1,11 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +v | result +datetime | datetime +double | datetime +integer | datetime +keyword | datetime +long | datetime +text | datetime +unsigned_long | datetime +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_degrees.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_degrees.asciidoc new file mode 100644 index 00000000000000..7cb7ca46022c2b --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_degrees.asciidoc @@ -0,0 +1,8 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +v | result +double | double +integer | double +long | double +unsigned_long | double +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_double.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_double.asciidoc new file mode 100644 index 00000000000000..38e8482b775440 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_double.asciidoc @@ -0,0 +1,12 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +v | result +boolean | double +datetime | double +double | double +integer | double +keyword | double +long | double +text | double +unsigned_long | double +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_geopoint.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_geopoint.asciidoc new file mode 100644 index 00000000000000..c464aec9e983cd --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_geopoint.asciidoc @@ -0,0 +1,7 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +v | result +geo_point | geo_point +keyword | geo_point +text | geo_point +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_geoshape.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_geoshape.asciidoc new file mode 100644 index 00000000000000..5fc8611ee2f928 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_geoshape.asciidoc @@ -0,0 +1,8 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +v | result +geo_point | geo_shape +geo_shape | geo_shape +keyword | geo_shape +text | geo_shape +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_integer.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_integer.asciidoc new file mode 100644 index 00000000000000..bcea15b9ec80b2 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_integer.asciidoc @@ -0,0 +1,12 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +v | result +boolean | integer +datetime | integer +double | integer +integer | integer +keyword | integer +long | integer +text | integer +unsigned_long | integer +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_ip.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_ip.asciidoc index a21bbf14d87caf..6d7f9338a9aeba 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_ip.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_ip.asciidoc @@ -1,6 +1,7 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | result +v | result ip | ip keyword | ip +text | ip |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_long.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_long.asciidoc new file mode 100644 index 00000000000000..307f573f1db2df --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_long.asciidoc @@ -0,0 +1,12 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +v | result +boolean | long +datetime | long +double | long +integer | long +keyword | long +long | long +text | long +unsigned_long | long +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/is_finite.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_lower.asciidoc similarity index 58% rename from x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/is_finite.asciidoc rename to x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_lower.asciidoc index 0c555059004c11..26f4e7633d8aef 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/is_finite.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_lower.asciidoc @@ -1,5 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | result -double | boolean +str | result +keyword | keyword +text | text |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_radians.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_radians.asciidoc new file mode 100644 index 00000000000000..7cb7ca46022c2b --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_radians.asciidoc @@ -0,0 +1,8 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +v | result +double | double +integer | double +long | double +unsigned_long | double +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_string.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_string.asciidoc index b8fcd4477aa70f..773e396f413737 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_string.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_string.asciidoc @@ -2,8 +2,12 @@ |=== v | result boolean | keyword +cartesian_point | keyword +cartesian_shape | keyword datetime | keyword double | keyword +geo_point | keyword +geo_shape | keyword integer | keyword ip | keyword keyword | keyword diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_unsigned_long.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_unsigned_long.asciidoc new file mode 100644 index 00000000000000..76d9cf44f4dd27 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_unsigned_long.asciidoc @@ -0,0 +1,12 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +v | result +boolean | unsigned_long +datetime | unsigned_long +double | unsigned_long +integer | unsigned_long +keyword | unsigned_long +long | unsigned_long +text | unsigned_long +unsigned_long | unsigned_long +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/is_infinite.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_upper.asciidoc similarity index 58% rename from x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/is_infinite.asciidoc rename to x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_upper.asciidoc index 0c555059004c11..26f4e7633d8aef 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/is_infinite.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/to_upper.asciidoc @@ -1,5 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | result -double | boolean +str | result +keyword | keyword +text | text |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/trim.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/trim.asciidoc index 11c02c8f0c3bb4..26f4e7633d8aef 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/trim.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/types/trim.asciidoc @@ -1,6 +1,6 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== -arg1 | result +str | result keyword | keyword text | text |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/unary.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/unary.asciidoc new file mode 100644 index 00000000000000..69ce754c1b4a08 --- /dev/null +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/functions/unary.asciidoc @@ -0,0 +1,12 @@ +[discrete] +[[esql-unary-operators]] +=== Unary operators + +The only unary operators is negation (`-`): + +[.text-center] +image::esql/functions/signature/neg.svg[Embedded,opts=inline] + +Supported types: + +include::types/neg.asciidoc[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/index.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/index.asciidoc index 09b74740a5b672..8fb20b981b93e4 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/index.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/index.asciidoc @@ -6,66 +6,73 @@ [partintro] -preview::[] +preview::["Do not use {esql} on production environments. This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features."] -The {es} Query Language ({esql}) provides a powerful way to filter, transform, and analyze data stored in {es}. -Users can author {esql} queries to find specific events, perform statistical analysis, and generate visualizations. -It supports a wide range of commands and functions that enable users to perform various data operations, -such as filtering, aggregation, time-series analysis, and more. +The {es} Query Language ({esql}) provides a powerful way to filter, transform, +and analyze data stored in {es}, and in the future in other runtimes. It is +designed to be easy to learn and use, by end users, SRE teams, application +developers, and administrators. -The {es} Query Language ({esql}) makes use of "pipes" to manipulate and transform data in a step-by-step fashion. -This approach allows users to compose a series of operations, where the output of one operation becomes the input for the next, -enabling complex data transformations and analysis. +Users can author {esql} queries to find specific events, perform statistical +analysis, and generate visualizations. It supports a wide range of commands and +functions that enable users to perform various data operations, such as +filtering, aggregation, time-series analysis, and more. -A simple example of an {esql} query is shown below: -[source,esql] ----- -FROM employees -| EVAL age = DATE_DIFF(NOW(), birth_date, 'Y') -| STATS AVG(age) BY department -| SORT age DESC ----- +The {es} Query Language ({esql}) makes use of "pipes" (|) to manipulate and +transform data in a step-by-step fashion. This approach allows users to compose +a series of operations, where the output of one operation becomes the input for +the next, enabling complex data transformations and analysis. -Each {esql} query starts with a <>. A source command produces -a table, typically with data from {es}. +[discrete] +=== The {esql} Compute Engine -image::images/esql/source-command.svg[A source command producing a table from {es},align="center"] +{esql} is more than a language: it represents a significant investment in new +compute capabilities within {es}. To achieve both the functional and performance +requirements for {esql}, it was necessary to build an entirely new compute +architecture. {esql} search, aggregation, and transformation functions are +directly executed within Elasticsearch itself. Query expressions are not +transpiled to Query DSL for execution. This approach allows {esql} to be +extremely performant and versatile. -A source command can be followed by one or more -<>. Processing commands change an -input table by adding, removing, or changing rows and columns. -Processing commands can perform filtering, projection, aggregation, and more. +The new {esql} execution engine was designed with performance in mind — it +operates on blocks at a time instead of per row, targets vectorization and cache +locality, and embraces specialization and multi-threading. It is a separate +component from the existing Elasticsearch aggregation framework with different +performance characteristics. -image::images/esql/processing-command.svg[A processing command changing an input table,align="center"] +The {esql} documentation is organized in these sections: -You can chain processing commands, separated by a pipe character: `|`. Each -processing command works on the output table of the previous command. +<>:: +A tutorial to help you get started with {esql}. -image::images/esql/chaining-processing-commands.svg[Processing commands can be chained,align="center"] +<>:: -The result of a query is the table produced by the final processing command. +Reference documentation for the <>, +<>, and <>. Information about working with <> and <>. And guidance for +<> and <>. -[discrete] -=== The {esql} Compute Engine +<>:: +An overview of using the <>, <>, +<>, and <>. -{esql} is more than a language. It represents a significant investment in new compute capabilities within {es}. -To achieve both the functional and performance requirements for {esql}, it was necessary to build an entirely new -compute architecture. {esql} search, aggregation, and transformation functions are directly executed within Elasticsearch -itself. Query expressions are not transpiled to Query DSL for execution. This approach allows {esql} to be extremely performant and versatile. +<>:: +The current limitations of {esql}. -The new {esql} execution engine was designed with performance in mind — it operates on blocks at a time instead of per row, targets vectorization and cache locality, and embraces specialization and multi-threading. It is a separate component from the existing Elasticsearch aggregation framework with different performance characteristics. +<>:: +A few examples of what you can do with {esql}. include::esql-get-started.asciidoc[] include::esql-language.asciidoc[] -include::esql-rest.asciidoc[] - -include::esql-kibana.asciidoc[] - -include::task-management.asciidoc[] +include::esql-using.asciidoc[] include::esql-limitations.asciidoc[] +include::esql-examples.asciidoc[] + :esql-tests!: :esql-specs!: diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/metadata_fields.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/metadata_fields.asciidoc index c034d4d0dd2b34..eb08ee085de38f 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/metadata_fields.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/metadata_fields.asciidoc @@ -34,11 +34,11 @@ like the other index fields: [source.merge.styled,esql] ---- -include::{esql-specs}/metadata-ignoreCsvTests.csv-spec[tag=multipleIndices] +include::{esql-specs}/metadata-IT_tests_only.csv-spec[tag=multipleIndices] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/metadata-ignoreCsvTests.csv-spec[tag=multipleIndices-result] +include::{esql-specs}/metadata-IT_tests_only.csv-spec[tag=multipleIndices-result] |=== Also, similar to the index fields, once an aggregation is performed, a @@ -47,9 +47,9 @@ used as grouping field: [source.merge.styled,esql] ---- -include::{esql-specs}/metadata-ignoreCsvTests.csv-spec[tag=metaIndexInAggs] +include::{esql-specs}/metadata-IT_tests_only.csv-spec[tag=metaIndexInAggs] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/metadata-ignoreCsvTests.csv-spec[tag=metaIndexInAggs-result] +include::{esql-specs}/metadata-IT_tests_only.csv-spec[tag=metaIndexInAggs-result] |=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/multivalued_fields.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/multivalued_fields.asciidoc index 5e48eb4ef8af8b..871a741d5ee243 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/multivalued_fields.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/multivalued_fields.asciidoc @@ -180,12 +180,20 @@ POST /mv/_bulk?refresh { "a": 1, "b": [2, 1] } { "index" : {} } { "a": 2, "b": 3 } +---- +[source,console] +---- POST /_query { "query": "FROM mv | EVAL b + 2, a + b | LIMIT 4" } ---- +// TEST[continued] +// TEST[warning:Line 1:16: evaluation of [b + 2] failed, treating result as null. Only first 20 failures recorded.] +// TEST[warning:Line 1:16: java.lang.IllegalArgumentException: single-value function encountered multi-value] +// TEST[warning:Line 1:23: evaluation of [a + b] failed, treating result as null. Only first 20 failures recorded.] +// TEST[warning:Line 1:23: java.lang.IllegalArgumentException: single-value function encountered multi-value] [source,console-result] ---- @@ -193,8 +201,8 @@ POST /_query "columns": [ { "name": "a", "type": "long"}, { "name": "b", "type": "long"}, - { "name": "b+2", "type": "long"}, - { "name": "a+b", "type": "long"} + { "name": "b + 2", "type": "long"}, + { "name": "a + b", "type": "long"} ], "values": [ [1, [1, 2], null, null], @@ -228,8 +236,8 @@ POST /_query "columns": [ { "name": "a", "type": "long"}, { "name": "b", "type": "long"}, - { "name": "b+2", "type": "long"}, - { "name": "a+b", "type": "long"} + { "name": "b + 2", "type": "long"}, + { "name": "a + b", "type": "long"} ], "values": [ [1, 1, 3, 2], diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/dissect.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/dissect.asciidoc index e6206615342f7c..c48b72af0de7e2 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/dissect.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/dissect.asciidoc @@ -2,18 +2,58 @@ [[esql-dissect]] === `DISSECT` -`DISSECT` enables you to extract structured data out of a string. `DISSECT` -matches the string against a delimiter-based pattern, and extracts the specified -keys as columns. +**Syntax** -Refer to the <> for the -syntax of dissect patterns. +[source,esql] +---- +DISSECT input "pattern" [APPEND_SEPARATOR=""] +---- + +*Parameters* + +`input`:: +The column that contains the string you want to structure. If the column has +multiple values, `DISSECT` will process each value. + +`pattern`:: +A <>. + +``:: +A string used as the separator between appended values, when using the <>. + +*Description* + +`DISSECT` enables you to <>. `DISSECT` matches the string against a +delimiter-based pattern, and extracts the specified keys as columns. + +Refer to <> for the syntax of dissect patterns. + +*Examples* + +// tag::examples[] +The following example parses a string that contains a timestamp, some text, and +an IP address: + +[source.merge.styled,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=basicDissect] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/docs.csv-spec[tag=basicDissect-result] +|=== + +By default, `DISSECT` outputs keyword string columns. To convert to another +type, use <>: [source.merge.styled,esql] ---- -include::{esql-specs}/dissect.csv-spec[tag=dissect] +include::{esql-specs}/docs.csv-spec[tag=dissectWithToDatetime] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/dissect.csv-spec[tag=dissect-result] +include::{esql-specs}/docs.csv-spec[tag=dissectWithToDatetime-result] |=== + +// end::examples[] \ No newline at end of file diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/drop.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/drop.asciidoc index 50e3b27fb1b285..8f03141d5e05aa 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/drop.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/drop.asciidoc @@ -2,11 +2,27 @@ [[esql-drop]] === `DROP` -Use `DROP` to remove columns: +**Syntax** [source,esql] ---- -include::{esql-specs}/docs.csv-spec[tag=dropheight] +DROP columns +---- + +*Parameters* + +`columns`:: +A comma-separated list of columns to remove. Supports wildcards. + +*Description* + +The `DROP` processing command removes one or more columns. + +*Examples* + +[source,esql] +---- +include::{esql-specs}/drop.csv-spec[tag=height] ---- Rather than specify each column by name, you can use wildcards to drop all @@ -14,5 +30,5 @@ columns with a name that matches a pattern: [source,esql] ---- -include::{esql-specs}/docs.csv-spec[tag=dropheightwithwildcard] +include::{esql-specs}/drop.csv-spec[tag=heightWithWildcard] ---- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/enrich.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/enrich.asciidoc index 1e489119d4ca31..603683858b8c0d 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/enrich.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/enrich.asciidoc @@ -4,7 +4,7 @@ **Syntax** -[source,txt] +[source,esql] ---- ENRICH policy [ON match_field] [WITH [new_name1 = ]field1, [new_name2 = ]field2, ...] ---- @@ -15,18 +15,18 @@ ENRICH policy [ON match_field] [WITH [new_name1 = ]field1, [new_name2 = ]field2, The name of the enrich policy. You need to <> and <> the enrich policy first. -`ON match_field`:: +`match_field`:: The match field. `ENRICH` uses its value to look for records in the enrich index. If not specified, the match will be performed on the column with the same name as the `match_field` defined in the <>. -`WITH fieldX`:: +`fieldX`:: The enrich fields from the enrich index that are added to the result as new columns. If a column with the same name as the enrich field already exists, the existing column will be replaced by the new column. If not specified, each of the enrich fields defined in the policy is added -`new_nameX =`:: +`new_nameX`:: Enables you to change the name of the column that's added for each of the enrich fields. Defaults to the enrich field name. @@ -49,15 +49,15 @@ column for each enrich field defined in the policy. The match is performed using the `match_field` defined in the <> and requires that the input table has a column with the same name (`language_code` in this example). `ENRICH` will look for records in the -<> based on the match field value. +<> based on the match field value. [source.merge.styled,esql] ---- -include::{esql-specs}/docs-ignoreCsvTests.csv-spec[tag=enrich] +include::{esql-specs}/docs-IT_tests_only.csv-spec[tag=enrich] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/docs-ignoreCsvTests.csv-spec[tag=enrich-result] +include::{esql-specs}/docs-IT_tests_only.csv-spec[tag=enrich-result] |=== To use a column with a different name than the `match_field` defined in the @@ -65,35 +65,35 @@ policy as the match field, use `ON `: [source.merge.styled,esql] ---- -include::{esql-specs}/docs-ignoreCsvTests.csv-spec[tag=enrich_on] +include::{esql-specs}/docs-IT_tests_only.csv-spec[tag=enrich_on] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/docs-ignoreCsvTests.csv-spec[tag=enrich_on-result] +include::{esql-specs}/docs-IT_tests_only.csv-spec[tag=enrich_on-result] |=== By default, each of the enrich fields defined in the policy is added as a -column. To explicitly select the enrich fields that are added, use -`WITH , ...`: +column. To explicitly select the enrich fields that are added, use +`WITH , , ...`: [source.merge.styled,esql] ---- -include::{esql-specs}/docs-ignoreCsvTests.csv-spec[tag=enrich_with] +include::{esql-specs}/docs-IT_tests_only.csv-spec[tag=enrich_with] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/docs-ignoreCsvTests.csv-spec[tag=enrich_with-result] +include::{esql-specs}/docs-IT_tests_only.csv-spec[tag=enrich_with-result] |=== You can rename the columns that are added using `WITH new_name=`: [source.merge.styled,esql] ---- -include::{esql-specs}/docs-ignoreCsvTests.csv-spec[tag=enrich_rename] +include::{esql-specs}/docs-IT_tests_only.csv-spec[tag=enrich_rename] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/docs-ignoreCsvTests.csv-spec[tag=enrich_rename-result] +include::{esql-specs}/docs-IT_tests_only.csv-spec[tag=enrich_rename-result] |=== In case of name collisions, the newly created columns will override existing diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/eval.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/eval.asciidoc index a0a78f2a3bf977..9b34fca7ceeffb 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/eval.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/eval.asciidoc @@ -1,15 +1,38 @@ [discrete] [[esql-eval]] === `EVAL` -`EVAL` enables you to append new columns: + +**Syntax** + +[source,esql] +---- +EVAL [column1 =] value1[, ..., [columnN =] valueN] +---- + +*Parameters* + +`columnX`:: +The column name. + +`valueX`:: +The value for the column. Can be a literal, an expression, or a +<>. + +*Description* + +The `EVAL` processing command enables you to append new columns with calculated +values. `EVAL` supports various functions for calculating values. Refer to +<> for more information. + +*Examples* [source.merge.styled,esql] ---- -include::{esql-specs}/docs.csv-spec[tag=eval] +include::{esql-specs}/eval.csv-spec[tag=eval] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/docs.csv-spec[tag=eval-result] +include::{esql-specs}/eval.csv-spec[tag=eval-result] |=== If the specified column already exists, the existing column will be dropped, and @@ -17,14 +40,34 @@ the new column will be appended to the table: [source.merge.styled,esql] ---- -include::{esql-specs}/docs.csv-spec[tag=evalReplace] +include::{esql-specs}/eval.csv-spec[tag=evalReplace] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/docs.csv-spec[tag=evalReplace-result] +include::{esql-specs}/eval.csv-spec[tag=evalReplace-result] |=== -[discrete] -==== Functions -`EVAL` supports various functions for calculating values. Refer to -<> for more information. +Specifying the output column name is optional. If not specified, the new column +name is equal to the expression. The following query adds a column named +`height*3.281`: + +[source.merge.styled,esql] +---- +include::{esql-specs}/eval.csv-spec[tag=evalUnnamedColumn] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/eval.csv-spec[tag=evalUnnamedColumn-result] +|=== + +Because this name contains special characters, <> with backticks (+{backtick}+) when using it in subsequent commands: + +[source.merge.styled,esql] +---- +include::{esql-specs}/eval.csv-spec[tag=evalUnnamedColumnStats] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/eval.csv-spec[tag=evalUnnamedColumnStats-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/grok.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/grok.asciidoc index 914c13b2320ebe..d5d58a9eaee12b 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/grok.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/grok.asciidoc @@ -2,20 +2,66 @@ [[esql-grok]] === `GROK` -`GROK` enables you to extract structured data out of a string. `GROK` matches -the string against patterns, based on regular expressions, and extracts the -specified patterns as columns. +**Syntax** -Refer to the <> for the syntax for -of grok patterns. +[source,esql] +---- +GROK input "pattern" +---- + +*Parameters* + +`input`:: +The column that contains the string you want to structure. If the column has +multiple values, `GROK` will process each value. + +`pattern`:: +A grok pattern. + +*Description* + +`GROK` enables you to <>. `GROK` matches the string against patterns, +based on regular expressions, and extracts the specified patterns as columns. + +Refer to <> for the syntax of grok patterns. + +*Examples* + +// tag::examples[] +The following example parses a string that contains a timestamp, an IP address, +an email address, and a number: + +[source.merge.styled,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=basicGrok] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/docs.csv-spec[tag=basicGrok-result] +|=== + +By default, `GROK` outputs keyword string columns. `int` and `float` types can +be converted by appending `:type` to the semantics in the pattern. For example +`{NUMBER:num:int}`: + +[source.merge.styled,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=grokWithConversionSuffix] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/docs.csv-spec[tag=grokWithConversionSuffix-result] +|=== -For example: +For other type conversions, use <>: [source.merge.styled,esql] ---- -include::{esql-specs}/grok.csv-spec[tag=grok] +include::{esql-specs}/docs.csv-spec[tag=grokWithToDatetime] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/grok.csv-spec[tag=grok-result] +include::{esql-specs}/docs.csv-spec[tag=grokWithToDatetime-result] |=== +// end::examples[] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/keep.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/keep.asciidoc index 3e54e5a7d1c5cc..57f32a68aec4c5 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/keep.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/keep.asciidoc @@ -2,11 +2,37 @@ [[esql-keep]] === `KEEP` -The `KEEP` command enables you to specify what columns are returned and the -order in which they are returned. +**Syntax** -To limit the columns that are returned, use a comma-separated list of column -names. The columns are returned in the specified order: +[source,esql] +---- +KEEP columns +---- + +*Parameters* + +`columns`:: +A comma-separated list of columns to keep. Supports wildcards. + +*Description* + +The `KEEP` processing command enables you to specify what columns are returned +and the order in which they are returned. + +Precedence rules are applied when a field name matches multiple expressions. +Fields are added in the order they appear. If one field matches multiple expressions, the following precedence rules apply (from highest to lowest priority): + +1. Complete field name (no wildcards) +2. Partial wildcard expressions (for example: `fieldNam*`) +3. Wildcard only (`*`) + +If a field matches two expressions with the same precedence, the right-most expression wins. + +Refer to the examples for illustrations of these precedence rules. + +*Examples* + +The columns are returned in the specified order: [source.merge.styled,esql] ---- @@ -24,12 +50,58 @@ columns with a name that matches a pattern: ---- include::{esql-specs}/docs.csv-spec[tag=keepWildcard] ---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/docs.csv-spec[tag=keep-wildcard-result] +|=== The asterisk wildcard (`*`) by itself translates to all columns that do not -match the other arguments. This query will first return all columns with a name -that starts with an h, followed by all other columns: +match the other arguments. + +This query will first return all columns with a name +that starts with `h`, followed by all other columns: [source,esql] ---- include::{esql-specs}/docs.csv-spec[tag=keepDoubleWildcard] ---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/docs.csv-spec[tag=keep-double-wildcard-result] +|=== + +The following examples show how precedence rules work when a field name matches multiple expressions. + +Complete field name has precedence over wildcard expressions: + +[source,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=keepCompleteName] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/docs.csv-spec[tag=keep-complete-name-result] +|=== + +Wildcard expressions have the same priority, but last one wins (despite being less specific): + +[source,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=keepWildcardPrecedence] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/docs.csv-spec[tag=keep-wildcard-precedence-result] +|=== + +A simple wildcard expression `*` has the lowest precedence. +Output order is determined by the other arguments: + +[source,esql] +---- +include::{esql-specs}/docs.csv-spec[tag=keepWildcardLowest] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/docs.csv-spec[tag=keep-wildcard-lowest-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/limit.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/limit.asciidoc index c02b534af59e16..4ccf3024a4c1e6 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/limit.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/limit.asciidoc @@ -2,12 +2,46 @@ [[esql-limit]] === `LIMIT` -The `LIMIT` processing command enables you to limit the number of rows: +**Syntax** [source,esql] ---- -include::{esql-specs}/docs.csv-spec[tag=limit] +LIMIT max_number_of_rows ---- -If not specified, `LIMIT` defaults to `500`. A single query will not return -more than 10,000 rows, regardless of the `LIMIT` value. +*Parameters* + +`max_number_of_rows`:: +The maximum number of rows to return. + +*Description* + +The `LIMIT` processing command enables you to limit the number of rows that are +returned. +// tag::limitation[] +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. +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 <> to select a smaller subset of the data. +* Shift any post-query processing to the query itself. You can use the {esql} +<> command to aggregate data in the query. + +The default and maximum limits can be changed using these dynamic cluster +settings: + +* `esql.query.result_truncation_default_size` +* `esql.query.result_truncation_max_size` +// end::limitation[] + +*Example* + +[source,esql] +---- +include::{esql-specs}/limit.csv-spec[tag=basic] +---- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/mv_expand.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/mv_expand.asciidoc index d62b28aabe4407..46dc4fd0a33cff 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/mv_expand.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/mv_expand.asciidoc @@ -2,7 +2,24 @@ [[esql-mv_expand]] === `MV_EXPAND` -The `MV_EXPAND` processing command expands multivalued fields into one row per value, duplicating other fields: +**Syntax** + +[source,esql] +---- +MV_EXPAND column +---- + +*Parameters* + +`column`:: +The multivalued column to expand. + +*Description* + +The `MV_EXPAND` processing command expands multivalued columns into one row per +value, duplicating other columns. + +*Example* [source.merge.styled,esql] ---- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/rename.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/rename.asciidoc index 1dda4243179764..773fe8b640f752 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/rename.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/rename.asciidoc @@ -2,22 +2,33 @@ [[esql-rename]] === `RENAME` -Use `RENAME` to rename a column using the following syntax: +**Syntax** [source,esql] ---- -RENAME AS +RENAME old_name1 AS new_name1[, ..., old_nameN AS new_nameN] ---- -For example: +*Parameters* + +`old_nameX`:: +The name of a column you want to rename. + +`new_nameX`:: +The new name of the column. + +*Description* + +The `RENAME` processing command renames one or more columns. If a column with +the new name already exists, it will be replaced by the new column. + +*Examples* [source,esql] ---- include::{esql-specs}/docs.csv-spec[tag=rename] ---- -If a column with the new name already exists, it will be replaced by the new -column. Multiple columns can be renamed with a single `RENAME` command: diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/sort.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/sort.asciidoc index 76a91933759320..fea7bfaf0c65f8 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/sort.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/sort.asciidoc @@ -1,35 +1,59 @@ [discrete] [[esql-sort]] === `SORT` -Use the `SORT` command to sort rows on one or more fields: + +**Syntax** + +[source,esql] +---- +SORT column1 [ASC/DESC][NULLS FIRST/NULLS LAST][, ..., columnN [ASC/DESC][NULLS FIRST/NULLS LAST]] +---- + +*Parameters* + +`columnX`:: +The column to sort on. + +*Description* + +The `SORT` processing command sorts a table on one or more columns. + +The default sort order is ascending. Use `ASC` or `DESC` to specify an explicit +sort order. + +Two rows with the same sort key are considered equal. You can provide additional +sort expressions to act as tie breakers. + +Sorting on multivalued columns uses the lowest value when sorting ascending and +the highest value when sorting descending. + +By default, `null` values are treated as being larger than any other value. With +an ascending sort order, `null` values are sorted last, and with a descending +sort order, `null` values are sorted first. You can change that by providing +`NULLS FIRST` or `NULLS LAST`. + +*Examples* [source,esql] ---- include::{esql-specs}/docs.csv-spec[tag=sort] ---- -The default sort order is ascending. Set an explicit sort order using `ASC` or -`DESC`: +Explicitly sorting in ascending order with `ASC`: [source,esql] ---- include::{esql-specs}/docs.csv-spec[tag=sortDesc] ---- -Two rows with the same sort key are considered equal. You can provide additional -sort expressions to act as tie breakers: +Providing additional sort expressions to act as tie breakers: [source,esql] ---- include::{esql-specs}/docs.csv-spec[tag=sortTie] ---- -[discrete] -==== `null` values -By default, `null` values are treated as being larger than any other value. With -an ascending sort order, `null` values are sorted last, and with a descending -sort order, `null` values are sorted first. You can change that by providing -`NULLS FIRST` or `NULLS LAST`: +Sorting `null` values first using `NULLS FIRST`: [source,esql] ---- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/stats.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/stats.asciidoc index 71f4470e3dfb04..fe84c56bbfc190 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/stats.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/stats.asciidoc @@ -1,45 +1,141 @@ [discrete] [[esql-stats-by]] === `STATS ... BY` -Use `STATS ... BY` to group rows according to a common value and calculate one -or more aggregated values over the grouped rows. + +**Syntax** + +[source,esql] +---- +STATS [column1 =] expression1[, ..., [columnN =] expressionN] +[BY grouping_expression1[, ..., grouping_expressionN]] +---- + +*Parameters* + +`columnX`:: +The name by which the aggregated value is returned. If omitted, the name is +equal to the corresponding expression (`expressionX`). + +`expressionX`:: +An expression that computes an aggregated value. + +`grouping_expressionX`:: +An expression that outputs the values to group by. + +NOTE: Individual `null` values are skipped when computing aggregations. + +*Description* + +The `STATS ... BY` processing command groups rows according to a common value +and calculate one or more aggregated values over the grouped rows. If `BY` is +omitted, the output table contains exactly one row with the aggregations applied +over the entire dataset. + +The following <> are supported: + +include::../functions/aggregation-functions.asciidoc[tag=agg_list] + +NOTE: `STATS` without any groups is much much faster than adding a group. + +NOTE: Grouping on a single expression is currently much more optimized than grouping + on many expressions. In some tests we have seen grouping on a single `keyword` + column to be five times faster than grouping on two `keyword` columns. Do + not try to work around this by combining the two columns together with + something like <> and then grouping - that is not going to be + faster. + +*Examples* + +Calculating a statistic and grouping by the values of another column: [source.merge.styled,esql] ---- -include::{esql-specs}/docs.csv-spec[tag=stats] +include::{esql-specs}/stats.csv-spec[tag=stats] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/docs.csv-spec[tag=stats-result] +include::{esql-specs}/stats.csv-spec[tag=stats-result] |=== -If `BY` is omitted, the output table contains exactly one row with the -aggregations applied over the entire dataset: +Omitting `BY` returns one row with the aggregations applied over the entire +dataset: [source.merge.styled,esql] ---- -include::{esql-specs}/docs.csv-spec[tag=statsWithoutBy] +include::{esql-specs}/stats.csv-spec[tag=statsWithoutBy] ---- [%header.monospaced.styled,format=dsv,separator=|] |=== -include::{esql-specs}/docs.csv-spec[tag=statsWithoutBy-result] +include::{esql-specs}/stats.csv-spec[tag=statsWithoutBy-result] |=== It's possible to calculate multiple values: -[source,esql] +[source.merge.styled,esql] ---- -include::{esql-specs}/docs.csv-spec[tag=statsCalcMultipleValues] +include::{esql-specs}/stats.csv-spec[tag=statsCalcMultipleValues] ---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats.csv-spec[tag=statsCalcMultipleValues-result] +|=== It's also possible to group by multiple values (only supported for long and keyword family fields): [source,esql] ---- -include::{esql-specs}/docs.csv-spec[tag=statsGroupByMultipleValues] +include::{esql-specs}/stats.csv-spec[tag=statsGroupByMultipleValues] ---- -The following aggregation functions are supported: +Both the aggregating functions and the grouping expressions accept other +functions. This is useful for using `STATS...BY` on multivalue columns. +For example, to calculate the average salary change, you can use `MV_AVG` to +first average the multiple values per employee, and use the result with the +`AVG` function: -include::../functions/aggregation-functions.asciidoc[tag=agg_list] +[source.merge.styled,esql] +---- +include::{esql-specs}/stats.csv-spec[tag=docsStatsAvgNestedExpression] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats.csv-spec[tag=docsStatsAvgNestedExpression-result] +|=== + +An example of grouping by an expression is grouping employees on the first +letter of their last name: + +[source.merge.styled,esql] +---- +include::{esql-specs}/stats.csv-spec[tag=docsStatsByExpression] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats.csv-spec[tag=docsStatsByExpression-result] +|=== + +Specifying the output column name is optional. If not specified, the new column +name is equal to the expression. The following query returns a column named +`AVG(salary)`: + +[source.merge.styled,esql] +---- +include::{esql-specs}/stats.csv-spec[tag=statsUnnamedColumn] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats.csv-spec[tag=statsUnnamedColumn-result] +|=== + +Because this name contains special characters, <> with backticks (+{backtick}+) when using it in subsequent commands: + +[source.merge.styled,esql] +---- +include::{esql-specs}/stats.csv-spec[tag=statsUnnamedColumnEval] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats.csv-spec[tag=statsUnnamedColumnEval-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/where.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/where.asciidoc index 8dd55df12b9e75..3076f92c40fc05 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/where.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/processing_commands/where.asciidoc @@ -2,8 +2,24 @@ [[esql-where]] === `WHERE` -Use `WHERE` to produce a table that contains all the rows from the input table -for which the provided condition evaluates to `true`: +**Syntax** + +[source,esql] +---- +WHERE expression +---- + +*Parameters* + +`expression`:: +A boolean expression. + +*Description* + +The `WHERE` processing command produces a table that contains all the rows from +the input table for which the provided condition evaluates to `true`. + +*Examples* [source,esql] ---- @@ -17,17 +33,30 @@ Which, if `still_hired` is a boolean field, can be simplified to: include::{esql-specs}/docs.csv-spec[tag=whereBoolean] ---- -[discrete] -==== Operators +Use date math to retrieve data from a specific time range. For example, to +retrieve the last hour of logs: -Refer to <> for an overview of the supported operators. +[source,esql] +---- +include::{esql-specs}/date.csv-spec[tag=docsNowWhere] +---- -[discrete] -==== Functions -`WHERE` supports various functions for calculating values. Refer to -<> for more information. +`WHERE` supports various <>. For example the +<> function: [source,esql] ---- include::{esql-specs}/docs.csv-spec[tag=whereFunction] ---- + +For a complete list of all functions, refer to <>. + +include::../functions/predicates.asciidoc[tag=body] + +include::../functions/like.asciidoc[tag=body] + +include::../functions/rlike.asciidoc[tag=body] + +include::../functions/in.asciidoc[tag=body] + +For a complete list of all operators, refer to <>. \ No newline at end of file diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/source_commands/from.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/source_commands/from.asciidoc index 5718bfc27ac1c9..6f54a42ddad353 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/source_commands/from.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/source_commands/from.asciidoc @@ -2,10 +2,47 @@ [[esql-from]] === `FROM` -The `FROM` source command returns a table with up to 10,000 documents from a -data stream, index, or alias. Each row in the resulting table represents a -document. Each column corresponds to a field, and can be accessed by the name -of that field. +**Syntax** + +[source,esql] +---- +FROM index_pattern [METADATA fields] +---- + +*Parameters* + +`index_pattern`:: +A list of indices, data streams or aliases. Supports wildcards and date math. + +`fields`:: +A comma-separated list of <> to retrieve. + +*Description* + +The `FROM` source command returns a table with data from a data stream, index, +or alias. Each row in the resulting table represents a document. Each column +corresponds to a field, and can be accessed by the name of that field. + +[NOTE] +==== +By default, an {esql} query without an explicit <> uses an implicit +limit of 500. This applies to `FROM` too. A `FROM` command without `LIMIT`: + +[source,esql] +---- +FROM employees +---- + +is executed as: + +[source,esql] +---- +FROM employees +| LIMIT 500 +---- +==== + +*Examples* [source,esql] ---- diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/source_commands/row.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/source_commands/row.asciidoc index edfe5ecbf7cf3f..adce844f365b8f 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/source_commands/row.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/source_commands/row.asciidoc @@ -2,9 +2,29 @@ [[esql-row]] === `ROW` +**Syntax** + +[source,esql] +---- +ROW column1 = value1[, ..., columnN = valueN] +---- + +*Parameters* + +`columnX`:: +The column name. + +`valueX`:: +The value for the column. Can be a literal, an expression, or a +<>. + +*Description* + The `ROW` source command produces a row with one or more columns with values that you specify. This can be useful for testing. +*Examples* + [source.merge.styled,esql] ---- include::{esql-specs}/row.csv-spec[tag=example] diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/source_commands/show.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/source_commands/show.asciidoc index 956baf628e9f30..ea8c83ceb772a1 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/source_commands/show.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/source_commands/show.asciidoc @@ -1,10 +1,35 @@ [discrete] [[esql-show]] -=== `SHOW ` +=== `SHOW` -The `SHOW ` source command returns information about the deployment and +**Syntax** + +[source,esql] +---- +SHOW item +---- + +*Parameters* + +`item`:: +Can be `INFO` or `FUNCTIONS`. + +*Description* + +The `SHOW` source command returns information about the deployment and its capabilities: * Use `SHOW INFO` to return the deployment's version, build date and hash. * Use `SHOW FUNCTIONS` to return a list of all supported functions and a synopsis of each function. + +*Examples* + +[source.merge.styled,esql] +---- +include::{esql-specs}/show.csv-spec[tag=showFunctionsFiltered] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/show.csv-spec[tag=showFunctionsFiltered-result] +|=== diff --git a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/task_management.asciidoc b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/task_management.asciidoc index 96a624c89bf7d9..dfaff961230354 100644 --- a/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/task_management.asciidoc +++ b/x-pack/plugins/elastic_assistant/server/knowledge_base/esql/documentation/task_management.asciidoc @@ -1,5 +1,5 @@ [[esql-task-management]] -== {esql} task management +=== {esql} task management ++++ Task management