diff --git a/.gitattributes b/.gitattributes index a0f434f16b32b..f866a77b1ba64 100644 --- a/.gitattributes +++ b/.gitattributes @@ -13,6 +13,9 @@ x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/parser/EsqlBasePar x-pack/plugin/esql/src/main/generated/** linguist-generated=true x-pack/plugin/esql/src/main/generated-src/** linguist-generated=true -# ESQL functions docs are autogenerated. More information at `docs/reference/esql/functions/README.md` -docs/reference/esql/functions/*/** linguist-generated=true +# ESQL functions docs are autogenerated. More information at `docs/reference/query-languages/esql/README.md` +docs/reference/query-languages/esql/_snippets/functions/*/** linguist-generated=true +#docs/reference/query-languages/esql/_snippets/operators/*/** linguist-generated=true +docs/reference/query-languages/esql/images/** linguist-generated=true +docs/reference/query-languages/esql/kibana/** linguist-generated=true diff --git a/docs/docset.yml b/docs/docset.yml index b42e40cfb52c7..75a6746e295d6 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -2,8 +2,8 @@ project: 'Elasticsearch' exclude: - README.md - internal/* - - reference/esql/functions/kibana/docs/* - - reference/esql/functions/README.md + - reference/query-languages/esql/kibana/docs/** + - reference/query-languages/esql/README.md cross_links: - beats - cloud diff --git a/docs/reference/data-analysis/aggregations/_snippets/search-aggregations-metrics-cardinality-aggregation-explanation.md b/docs/reference/data-analysis/aggregations/_snippets/search-aggregations-metrics-cardinality-aggregation-explanation.md new file mode 100644 index 0000000000000..5bd61d1b1f23c --- /dev/null +++ b/docs/reference/data-analysis/aggregations/_snippets/search-aggregations-metrics-cardinality-aggregation-explanation.md @@ -0,0 +1,17 @@ +* configurable precision, which decides on how to trade memory for accuracy, +* excellent accuracy on low-cardinality sets, +* fixed memory usage: no matter if there are tens or billions of unique values, memory usage only depends on the configured precision. + +For a precision threshold of `c`, the implementation that we are using requires about `c * 8` bytes. + +The following chart shows how the error varies before and after the threshold: + +![cardinality error](/images/cardinality_error.png "") + +For all 3 thresholds, counts have been accurate up to the configured threshold. Although not guaranteed, +this is likely to be the case. Accuracy in practice depends on the dataset in question. In general, +most datasets show consistently good accuracy. Also note that even with a threshold as low as 100, +the error remains very low (1-6% as seen in the above graph) even when counting millions of items. + +The HyperLogLog++ algorithm depends on the leading zeros of hashed values, the exact distributions of +hashes in a dataset can affect the accuracy of the cardinality. diff --git a/docs/reference/query-languages/esql/_snippets/functions/percentile.md b/docs/reference/data-analysis/aggregations/_snippets/search-aggregations-metrics-percentile-aggregation-approximate.md similarity index 54% rename from docs/reference/query-languages/esql/_snippets/functions/percentile.md rename to docs/reference/data-analysis/aggregations/_snippets/search-aggregations-metrics-percentile-aggregation-approximate.md index 7d28bca744113..87ba905bc1518 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/percentile.md +++ b/docs/reference/data-analysis/aggregations/_snippets/search-aggregations-metrics-percentile-aggregation-approximate.md @@ -1,60 +1,3 @@ -## `PERCENTILE` [esql-percentile] - -**Syntax** - -:::{image} ../../../../../images/percentile.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**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 `MEDIAN`. - -**Supported types** - -| number | percentile | result | -| --- | --- | --- | -| double | double | double | -| double | integer | double | -| double | long | double | -| integer | double | double | -| integer | integer | double | -| integer | long | double | -| long | double | double | -| long | integer | double | -| long | long | double | - -**Examples** - -```esql -FROM employees -| STATS p0 = PERCENTILE(salary, 0) - , p50 = PERCENTILE(salary, 50) - , p99 = PERCENTILE(salary, 99) -``` - -| p0:double | p50:double | p99:double | -| --- | --- | --- | -| 25324 | 47003 | 74970.29 | - -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 - -```esql -FROM employees -| STATS p80_max_salary_change = PERCENTILE(MV_MAX(salary_change), 80) -``` - -| p80_max_salary_change:double | -| --- | -| 12.132 | - - -### `PERCENTILE` is (usually) approximate [esql-percentile-approximate] - There are many different algorithms to calculate percentiles. The naive implementation simply stores all the values in a sorted array. To find the 50th percentile, you simply find the value that is at `my_array[count(my_array) * 0.5]`. Clearly, the naive implementation does not scale — the sorted array grows linearly with the number of values in your dataset. To calculate percentiles across potentially billions of values in an Elasticsearch cluster, *approximate* percentiles are calculated. @@ -72,11 +15,3 @@ The following chart shows the relative error on a uniform distribution depending ![percentiles error](/images/percentiles_error.png "") It shows how precision is better for extreme percentiles. The reason why error diminishes for large number of values is that the law of large numbers makes the distribution of values more and more uniform and the t-digest tree can do a better job at summarizing it. It would not be the case on more skewed distributions. - -::::{warning} -`PERCENTILE` is also [non-deterministic](https://en.wikipedia.org/wiki/Nondeterministic_algorithm). This means you can get slightly different results using the same data. - -:::: - - - diff --git a/docs/reference/data-analysis/aggregations/search-aggregations-metrics-cardinality-aggregation.md b/docs/reference/data-analysis/aggregations/search-aggregations-metrics-cardinality-aggregation.md index 0c7711824a357..f67175f4892ab 100644 --- a/docs/reference/data-analysis/aggregations/search-aggregations-metrics-cardinality-aggregation.md +++ b/docs/reference/data-analysis/aggregations/search-aggregations-metrics-cardinality-aggregation.md @@ -65,19 +65,8 @@ Computing exact counts requires loading values into a hash set and returning its This `cardinality` aggregation is based on the [HyperLogLog++](https://static.googleusercontent.com/media/research.google.com/fr//pubs/archive/40671.pdf) algorithm, which counts based on the hashes of the values with some interesting properties: -* configurable precision, which decides on how to trade memory for accuracy, -* excellent accuracy on low-cardinality sets, -* fixed memory usage: no matter if there are tens or billions of unique values, memory usage only depends on the configured precision. - -For a precision threshold of `c`, the implementation that we are using requires about `c * 8` bytes. - -The following chart shows how the error varies before and after the threshold: - -![cardinality error](../../../images/cardinality_error.png "") - -For all 3 thresholds, counts have been accurate up to the configured threshold. Although not guaranteed, this is likely to be the case. Accuracy in practice depends on the dataset in question. In general, most datasets show consistently good accuracy. Also note that even with a threshold as low as 100, the error remains very low (1-6% as seen in the above graph) even when counting millions of items. - -The HyperLogLog++ algorithm depends on the leading zeros of hashed values, the exact distributions of hashes in a dataset can affect the accuracy of the cardinality. +:::{include} _snippets/search-aggregations-metrics-cardinality-aggregation-explanation.md +::: ## Pre-computed hashes [_pre_computed_hashes] diff --git a/docs/reference/data-analysis/aggregations/search-aggregations-metrics-percentile-aggregation.md b/docs/reference/data-analysis/aggregations/search-aggregations-metrics-percentile-aggregation.md index 1d9c78d0991a1..283e280a5bbe0 100644 --- a/docs/reference/data-analysis/aggregations/search-aggregations-metrics-percentile-aggregation.md +++ b/docs/reference/data-analysis/aggregations/search-aggregations-metrics-percentile-aggregation.md @@ -175,31 +175,14 @@ GET latency/_search ## Percentiles are (usually) approximate [search-aggregations-metrics-percentile-aggregation-approximation] -There are many different algorithms to calculate percentiles. The naive implementation simply stores all the values in a sorted array. To find the 50th percentile, you simply find the value that is at `my_array[count(my_array) * 0.5]`. - -Clearly, the naive implementation does not scale — the sorted array grows linearly with the number of values in your dataset. To calculate percentiles across potentially billions of values in an Elasticsearch cluster, *approximate* percentiles are calculated. - -The algorithm used by the `percentile` metric is called TDigest (introduced by Ted Dunning in [Computing Accurate Quantiles using T-Digests](https://github.com/tdunning/t-digest/blob/master/docs/t-digest-paper/histo.pdf)). - -When using this metric, there are a few guidelines to keep in mind: - -* Accuracy is proportional to `q(1-q)`. This means that extreme percentiles (e.g. 99%) are more accurate than less extreme percentiles, such as the median -* For small sets of values, percentiles are highly accurate (and potentially 100% accurate if the data is small enough). -* As the quantity of values in a bucket grows, the algorithm begins to approximate the percentiles. It is effectively trading accuracy for memory savings. The exact level of inaccuracy is difficult to generalize, since it depends on your data distribution and volume of data being aggregated - -The following chart shows the relative error on a uniform distribution depending on the number of collected values and the requested percentile: - -![percentiles error](../../../images/percentiles_error.png "") - -It shows how precision is better for extreme percentiles. The reason why error diminishes for large number of values is that the law of large numbers makes the distribution of values more and more uniform and the t-digest tree can do a better job at summarizing it. It would not be the case on more skewed distributions. +:::{include} /reference/data-analysis/aggregations/_snippets/search-aggregations-metrics-percentile-aggregation-approximate.md +::: ::::{warning} Percentile aggregations are also [non-deterministic](https://en.wikipedia.org/wiki/Nondeterministic_algorithm). This means you can get slightly different results using the same data. - :::: - ## Compression [search-aggregations-metrics-percentile-aggregation-compression] Approximate algorithms must balance memory utilization with estimation accuracy. This balance can be controlled using a `compression` parameter: diff --git a/docs/reference/esql/functions/README.md b/docs/reference/esql/functions/README.md deleted file mode 100644 index 35b852ba060f1..0000000000000 --- a/docs/reference/esql/functions/README.md +++ /dev/null @@ -1,23 +0,0 @@ -The files in these subdirectories are generated by ESQL's test suite: -* `description` - description of each function scraped from `@FunctionInfo#description` -* `examples` - examples of each function scraped from `@FunctionInfo#examples` -* `parameters` - description of each function's parameters scraped from `@Param` -* `signature` - railroad diagram of the syntax to invoke each function -* `types` - a table of each combination of support type for each parameter. These are generated from tests. -* `layout` - a fully generated description for each function -* `kibana/definition` - function definitions for kibana's ESQL editor -* `kibana/docs` - the inline docs for kibana - -Most functions can use the generated docs generated in the `layout` directory. -If we need something more custom for the function we can make a file in this -directory that can `include::` any parts of the files above. - -To regenerate the files for a function run its tests using gradle: -``` -./gradlew :x-pack:plugin:esql:test -Dtests.class='*SinTests' -``` - -To regenerate the files for all functions run all of ESQL's tests using gradle: -``` -./gradlew :x-pack:plugin:esql:test -``` diff --git a/docs/reference/esql/functions/kibana/definition/pi.json b/docs/reference/esql/functions/kibana/definition/pi.json deleted file mode 100644 index 0dd720dd69cb6..0000000000000 --- a/docs/reference/esql/functions/kibana/definition/pi.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", - "type" : "scalar", - "name" : "pi", - "description" : "Returns Pi, the ratio of a circle's circumference to its diameter.", - "signatures" : [ - { - "params" : [ ], - "returnType" : "double" - } - ], - "examples" : [ - "ROW PI()" - ], - "preview" : false, - "snapshot_only" : false -} diff --git a/docs/reference/esql/functions/kibana/definition/tau.json b/docs/reference/esql/functions/kibana/definition/tau.json deleted file mode 100644 index b5090e8a39a81..0000000000000 --- a/docs/reference/esql/functions/kibana/definition/tau.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", - "type" : "scalar", - "name" : "tau", - "description" : "Returns the ratio of a circle's circumference to its radius.", - "signatures" : [ - { - "params" : [ ], - "returnType" : "double" - } - ], - "examples" : [ - "ROW TAU()" - ], - "preview" : false, - "snapshot_only" : false -} diff --git a/docs/reference/esql/functions/kibana/docs/abs.md b/docs/reference/esql/functions/kibana/docs/abs.md deleted file mode 100644 index 9dc2c5c76f4f6..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/abs.md +++ /dev/null @@ -1,11 +0,0 @@ - - -### ABS -Returns the absolute value. - -``` -ROW number = -1.0 -| EVAL abs_number = ABS(number) -``` diff --git a/docs/reference/esql/functions/kibana/docs/avg.md b/docs/reference/esql/functions/kibana/docs/avg.md deleted file mode 100644 index 54006a0556175..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/avg.md +++ /dev/null @@ -1,11 +0,0 @@ - - -### AVG -The average of a numeric field. - -``` -FROM employees -| STATS AVG(height) -``` diff --git a/docs/reference/esql/functions/kibana/docs/cidr_match.md b/docs/reference/esql/functions/kibana/docs/cidr_match.md deleted file mode 100644 index f641fc5cba5b6..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/cidr_match.md +++ /dev/null @@ -1,12 +0,0 @@ - - -### CIDR_MATCH -Returns true if the provided IP is contained in one of the provided CIDR blocks. - -``` -FROM hosts -| WHERE CIDR_MATCH(ip1, "127.0.0.2/32", "127.0.0.3/32") -| KEEP card, host, ip0, ip1 -``` diff --git a/docs/reference/esql/functions/kibana/docs/cos.md b/docs/reference/esql/functions/kibana/docs/cos.md deleted file mode 100644 index c942ef8e1a49c..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/cos.md +++ /dev/null @@ -1,11 +0,0 @@ - - -### COS -Returns the cosine of an angle. - -``` -ROW a=1.8 -| EVAL cos=COS(a) -``` diff --git a/docs/reference/esql/functions/kibana/docs/cosh.md b/docs/reference/esql/functions/kibana/docs/cosh.md deleted file mode 100644 index 0338429521781..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/cosh.md +++ /dev/null @@ -1,11 +0,0 @@ - - -### COSH -Returns the hyperbolic cosine of a number. - -``` -ROW a=1.8 -| EVAL cosh=COSH(a) -``` diff --git a/docs/reference/esql/functions/kibana/docs/e.md b/docs/reference/esql/functions/kibana/docs/e.md deleted file mode 100644 index 7700101b9229e..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/e.md +++ /dev/null @@ -1,10 +0,0 @@ - - -### E -Returns Euler's number. - -``` -ROW E() -``` diff --git a/docs/reference/esql/functions/kibana/docs/from_base64.md b/docs/reference/esql/functions/kibana/docs/from_base64.md deleted file mode 100644 index 3b4a88f77c73a..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/from_base64.md +++ /dev/null @@ -1,11 +0,0 @@ - - -### FROM_BASE64 -Decode a base64 string. - -``` -row a = "ZWxhc3RpYw==" -| eval d = from_base64(a) -``` diff --git a/docs/reference/esql/functions/kibana/docs/kql.md b/docs/reference/esql/functions/kibana/docs/kql.md deleted file mode 100644 index 14c914d57af91..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/kql.md +++ /dev/null @@ -1,14 +0,0 @@ - - -### KQL -Performs a KQL query. Returns true if the provided KQL query string matches the row. - -``` -FROM books -| WHERE KQL("author: Faulkner") -| KEEP book_no, author -| SORT book_no -| LIMIT 5 -``` diff --git a/docs/reference/esql/functions/kibana/docs/left.md b/docs/reference/esql/functions/kibana/docs/left.md deleted file mode 100644 index 73b79f7976512..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/left.md +++ /dev/null @@ -1,14 +0,0 @@ - - -### LEFT -Returns the substring that extracts 'length' chars from 'string' starting from the left. - -``` -FROM employees -| KEEP last_name -| EVAL left = LEFT(last_name, 3) -| SORT last_name ASC -| LIMIT 5 -``` diff --git a/docs/reference/esql/functions/kibana/docs/max.md b/docs/reference/esql/functions/kibana/docs/max.md deleted file mode 100644 index 80e88885e7f34..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/max.md +++ /dev/null @@ -1,11 +0,0 @@ - - -### MAX -The maximum value of a field. - -``` -FROM employees -| STATS MAX(languages) -``` diff --git a/docs/reference/esql/functions/kibana/docs/md5.md b/docs/reference/esql/functions/kibana/docs/md5.md deleted file mode 100644 index aacb8a3960165..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/md5.md +++ /dev/null @@ -1,13 +0,0 @@ - - -### MD5 -Computes the MD5 hash of the input. - -``` -FROM sample_data -| WHERE message != "Connection error" -| EVAL md5 = md5(message) -| KEEP message, md5; -``` diff --git a/docs/reference/esql/functions/kibana/docs/min.md b/docs/reference/esql/functions/kibana/docs/min.md deleted file mode 100644 index 38d13b97fd344..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/min.md +++ /dev/null @@ -1,11 +0,0 @@ - - -### MIN -The minimum value of a field. - -``` -FROM employees -| STATS MIN(languages) -``` diff --git a/docs/reference/esql/functions/kibana/docs/mv_append.md b/docs/reference/esql/functions/kibana/docs/mv_append.md deleted file mode 100644 index 36b285be1877c..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/mv_append.md +++ /dev/null @@ -1,7 +0,0 @@ - - -### MV_APPEND -Concatenates values of two multi-value fields. - diff --git a/docs/reference/esql/functions/kibana/docs/mv_dedupe.md b/docs/reference/esql/functions/kibana/docs/mv_dedupe.md deleted file mode 100644 index 28884841d5524..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/mv_dedupe.md +++ /dev/null @@ -1,12 +0,0 @@ - - -### MV_DEDUPE -Remove duplicate values from a multivalued field. - -``` -ROW a=["foo", "foo", "bar", "foo"] -| EVAL dedupe_a = MV_DEDUPE(a) -``` -Note: `MV_DEDUPE` may, but won't always, sort the values in the column. diff --git a/docs/reference/esql/functions/kibana/docs/neg.md b/docs/reference/esql/functions/kibana/docs/neg.md deleted file mode 100644 index 2d1c65487343f..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/neg.md +++ /dev/null @@ -1,7 +0,0 @@ - - -### NEG -Returns the negation of the argument. - diff --git a/docs/reference/esql/functions/kibana/docs/not_rlike.md b/docs/reference/esql/functions/kibana/docs/not_rlike.md deleted file mode 100644 index dac23438c1612..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/not_rlike.md +++ /dev/null @@ -1,10 +0,0 @@ - - -### NOT_RLIKE -Use `NOT RLIKE` to filter data based on string patterns using using -<>. `NOT 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. - diff --git a/docs/reference/esql/functions/kibana/docs/now.md b/docs/reference/esql/functions/kibana/docs/now.md deleted file mode 100644 index 5143dc843ebd8..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/now.md +++ /dev/null @@ -1,10 +0,0 @@ - - -### NOW -Returns current date and time. - -``` -ROW current_date = NOW() -``` diff --git a/docs/reference/esql/functions/kibana/docs/pi.md b/docs/reference/esql/functions/kibana/docs/pi.md deleted file mode 100644 index 676d11cea3ea4..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/pi.md +++ /dev/null @@ -1,10 +0,0 @@ - - -### PI -Returns Pi, the ratio of a circle's circumference to its diameter. - -``` -ROW PI() -``` diff --git a/docs/reference/esql/functions/kibana/docs/right.md b/docs/reference/esql/functions/kibana/docs/right.md deleted file mode 100644 index 3b09ae311c9fa..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/right.md +++ /dev/null @@ -1,14 +0,0 @@ - - -### RIGHT -Return the substring that extracts 'length' chars from 'str' starting from the right. - -``` -FROM employees -| KEEP last_name -| EVAL right = RIGHT(last_name, 3) -| SORT last_name ASC -| LIMIT 5 -``` diff --git a/docs/reference/esql/functions/kibana/docs/sha1.md b/docs/reference/esql/functions/kibana/docs/sha1.md deleted file mode 100644 index a940aa133f06e..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/sha1.md +++ /dev/null @@ -1,13 +0,0 @@ - - -### SHA1 -Computes the SHA1 hash of the input. - -``` -FROM sample_data -| WHERE message != "Connection error" -| EVAL sha1 = sha1(message) -| KEEP message, sha1; -``` diff --git a/docs/reference/esql/functions/kibana/docs/sha256.md b/docs/reference/esql/functions/kibana/docs/sha256.md deleted file mode 100644 index fbe576c7c20d6..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/sha256.md +++ /dev/null @@ -1,13 +0,0 @@ - - -### SHA256 -Computes the SHA256 hash of the input. - -``` -FROM sample_data -| WHERE message != "Connection error" -| EVAL sha256 = sha256(message) -| KEEP message, sha256; -``` diff --git a/docs/reference/esql/functions/kibana/docs/sin.md b/docs/reference/esql/functions/kibana/docs/sin.md deleted file mode 100644 index d1128350d12fb..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/sin.md +++ /dev/null @@ -1,11 +0,0 @@ - - -### SIN -Returns the sine of an angle. - -``` -ROW a=1.8 -| EVAL sin=SIN(a) -``` diff --git a/docs/reference/esql/functions/kibana/docs/sinh.md b/docs/reference/esql/functions/kibana/docs/sinh.md deleted file mode 100644 index 249c9bb0906c3..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/sinh.md +++ /dev/null @@ -1,11 +0,0 @@ - - -### SINH -Returns the hyperbolic sine of a number. - -``` -ROW a=1.8 -| EVAL sinh=SINH(a) -``` diff --git a/docs/reference/esql/functions/kibana/docs/std_dev.md b/docs/reference/esql/functions/kibana/docs/std_dev.md deleted file mode 100644 index a6afca7b8f6b3..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/std_dev.md +++ /dev/null @@ -1,11 +0,0 @@ - - -### STD_DEV -The standard deviation of a numeric field. - -``` -FROM employees -| STATS STD_DEV(height) -``` diff --git a/docs/reference/esql/functions/kibana/docs/sum.md b/docs/reference/esql/functions/kibana/docs/sum.md deleted file mode 100644 index eb72ddb0dece1..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/sum.md +++ /dev/null @@ -1,11 +0,0 @@ - - -### SUM -The sum of a numeric expression. - -``` -FROM employees -| STATS SUM(languages) -``` diff --git a/docs/reference/esql/functions/kibana/docs/tan.md b/docs/reference/esql/functions/kibana/docs/tan.md deleted file mode 100644 index 41bd3c814b171..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/tan.md +++ /dev/null @@ -1,11 +0,0 @@ - - -### TAN -Returns the tangent of an angle. - -``` -ROW a=1.8 -| EVAL tan=TAN(a) -``` diff --git a/docs/reference/esql/functions/kibana/docs/tanh.md b/docs/reference/esql/functions/kibana/docs/tanh.md deleted file mode 100644 index 365add190de82..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/tanh.md +++ /dev/null @@ -1,11 +0,0 @@ - - -### TANH -Returns the hyperbolic tangent of a number. - -``` -ROW a=1.8 -| EVAL tanh=TANH(a) -``` diff --git a/docs/reference/esql/functions/kibana/docs/tau.md b/docs/reference/esql/functions/kibana/docs/tau.md deleted file mode 100644 index ca0f4474b597e..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/tau.md +++ /dev/null @@ -1,10 +0,0 @@ - - -### TAU -Returns the ratio of a circle's circumference to its radius. - -``` -ROW TAU() -``` diff --git a/docs/reference/esql/functions/kibana/docs/term.md b/docs/reference/esql/functions/kibana/docs/term.md deleted file mode 100644 index ffecd26d737f7..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/term.md +++ /dev/null @@ -1,13 +0,0 @@ - - -### TERM -Performs a Term query on the specified field. Returns true if the provided term matches the row. - -``` -FROM books -| WHERE TERM(author, "gabriel") -| KEEP book_no, title -| LIMIT 3; -``` diff --git a/docs/reference/esql/functions/kibana/docs/to_base64.md b/docs/reference/esql/functions/kibana/docs/to_base64.md deleted file mode 100644 index 2863a69da7b29..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/to_base64.md +++ /dev/null @@ -1,11 +0,0 @@ - - -### TO_BASE64 -Encode a string to a base64 string. - -``` -row a = "elastic" -| eval e = to_base64(a) -``` diff --git a/docs/reference/esql/functions/kibana/docs/to_boolean.md b/docs/reference/esql/functions/kibana/docs/to_boolean.md deleted file mode 100644 index 9cf97100c334e..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/to_boolean.md +++ /dev/null @@ -1,14 +0,0 @@ - - -### TO_BOOLEAN -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*. -The numerical value of *0* will be converted to *false*, anything else will be converted to *true*. - -``` -ROW str = ["true", "TRuE", "false", "", "yes", "1"] -| EVAL bool = TO_BOOLEAN(str) -``` diff --git a/docs/reference/esql/functions/kibana/docs/to_string.md b/docs/reference/esql/functions/kibana/docs/to_string.md deleted file mode 100644 index fb6586d1e7761..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/to_string.md +++ /dev/null @@ -1,11 +0,0 @@ - - -### TO_STRING -Converts an input value into a string. - -``` -ROW a=10 -| EVAL j = TO_STRING(a) -``` diff --git a/docs/reference/esql/functions/kibana/docs/to_version.md b/docs/reference/esql/functions/kibana/docs/to_version.md deleted file mode 100644 index c0109e3ee7320..0000000000000 --- a/docs/reference/esql/functions/kibana/docs/to_version.md +++ /dev/null @@ -1,10 +0,0 @@ - - -### TO_VERSION -Converts an input string to a version value. - -``` -ROW v = TO_VERSION("1.2.3") -``` diff --git a/docs/reference/esql/functions/kibana/inline_cast.json b/docs/reference/esql/functions/kibana/inline_cast.json deleted file mode 100644 index 9f663c8d0d6a3..0000000000000 --- a/docs/reference/esql/functions/kibana/inline_cast.json +++ /dev/null @@ -1,21 +0,0 @@ -{ - "bool" : "to_boolean", - "boolean" : "to_boolean", - "cartesian_point" : "to_cartesianpoint", - "cartesian_shape" : "to_cartesianshape", - "date_nanos" : "to_date_nanos", - "date_period" : "to_dateperiod", - "datetime" : "to_datetime", - "double" : "to_double", - "geo_point" : "to_geopoint", - "geo_shape" : "to_geoshape", - "int" : "to_integer", - "integer" : "to_integer", - "ip" : "to_ip", - "keyword" : "to_string", - "long" : "to_long", - "string" : "to_string", - "time_duration" : "to_timeduration", - "unsigned_long" : "to_unsigned_long", - "version" : "to_version" -} \ No newline at end of file diff --git a/docs/reference/query-languages/esql/README.md b/docs/reference/query-languages/esql/README.md new file mode 100644 index 0000000000000..13f1771caab39 --- /dev/null +++ b/docs/reference/query-languages/esql/README.md @@ -0,0 +1,50 @@ +The ES|QL documentation is composed of static content and generated content. +The static content exists in this directory and can be edited by hand. +However, the sub-directories `_snippets`, `images` and `kibana` contain mostly +generated content. + +### _snippets + +In `_snippets` there are files that can be included within other files +using the [File Inclusion](https://elastic.github.io/docs-builder/syntax/file_inclusion/) +feature of the Elastic Docs V3 system. +Most, but not all, files in this directory are generated. +In particular the directories `_snippets/functions/*` and `_snippets/operators/*` +contain subdirectories that are mostly generated: + +* `description` - description of each function scraped from `@FunctionInfo#description` +* `examples` - examples of each function scraped from `@FunctionInfo#examples` +* `parameters` - description of each function's parameters scraped from `@Param` +* `signature` - railroad diagram of the syntax to invoke each function +* `types` - a table of each combination of support type for each parameter. These are generated from tests. +* `layout` - a fully generated description for each function + +Most functions can use the generated docs generated in the `layout` directory. +If we need something more custom for the function we can make a file in this +directory that can `include::` any parts of the files above. + +To regenerate the files for a function run its tests using gradle. +For example to generate docs for the `CASE` function: +``` +./gradlew :x-pack:plugin:esql:test -Dtests.class='CaseTests' +``` + +To regenerate the files for all functions run all of ESQL's tests using gradle: +``` +./gradlew :x-pack:plugin:esql:test +``` + +### images + +The `images` directory contains `functions` and `operators` sub-directories with +the `*.svg` files used to describe the syntax of each function or operator. +These are all generated by the same tests that generate the functions and operators docs above. + +### kibana + +The `kibana` directory contains `definition` and `docs` sub-directories that are generated: + +* `kibana/definition` - function definitions for kibana's ESQL editor +* `kibana/docs` - the inline docs for kibana + +These are also generated as part of the unit tests described above. diff --git a/docs/reference/query-languages/esql/_snippets/aggregation-functions-new.md b/docs/reference/query-languages/esql/_snippets/aggregation-functions-new.md deleted file mode 100644 index 5506c8e49ea39..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/aggregation-functions-new.md +++ /dev/null @@ -1,53 +0,0 @@ -## {{esql}} aggregate functions [esql-agg-functions] - - -The [`STATS`](/reference/query-languages/esql/esql-commands.md#esql-stats-by) command supports these aggregate functions: - -:::{include} lists/aggregation-functions.md -::: - -:::{include} functions/avg.md -::: - -:::{include} functions/count.md -::: - -:::{include} functions/count_distinct.md -::: - -:::{include} functions/max.md -::: - -:::{include} functions/median.md -::: - -:::{include} functions/median_absolute_deviation.md -::: - -:::{include} functions/min.md -::: - -:::{include} functions/percentile.md -::: - -:::{include} functions/st_centroid_agg.md -::: - -:::{include} functions/st_extent_agg.md -::: - -:::{include} functions/std_dev.md -::: - -:::{include} functions/sum.md -::: - -:::{include} functions/top.md -::: - -:::{include} functions/values.md -::: - -:::{include} functions/weighted_avg.md -::: - diff --git a/docs/reference/query-languages/esql/_snippets/aggregation-functions-orig.md b/docs/reference/query-languages/esql/_snippets/aggregation-functions-orig.md deleted file mode 100644 index 1a5dc2f6f16c8..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/aggregation-functions-orig.md +++ /dev/null @@ -1,930 +0,0 @@ -## {{esql}} aggregate functions [esql-agg-functions] - - -The [`STATS`](/reference/query-languages/esql/esql-commands.md#esql-stats-by) command supports these aggregate functions: - -:::{include} lists/aggregation-functions.md -::: - -## `AVG` [esql-avg] - -**Syntax** - -:::{image} ../../../../images/avg.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -The average of a numeric field. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | - -**Examples** - -```esql -FROM employees -| STATS AVG(height) -``` - -| AVG(height):double | -| --- | -| 1.7682 | - -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 - -```esql -FROM employees -| STATS avg_salary_change = ROUND(AVG(MV_AVG(salary_change)), 10) -``` - -| avg_salary_change:double | -| --- | -| 1.3904535865 | - - -## `COUNT` [esql-count] - -**Syntax** - -:::{image} ../../../../images/count.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: 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** - -| field | result | -| --- | --- | -| boolean | long | -| cartesian_point | long | -| date | long | -| double | long | -| geo_point | long | -| integer | long | -| ip | long | -| keyword | long | -| long | long | -| text | long | -| unsigned_long | long | -| version | long | - -**Examples** - -```esql -FROM employees -| STATS COUNT(height) -``` - -| COUNT(height):long | -| --- | -| 100 | - -To count the number of rows, use `COUNT()` or `COUNT(*)` - -```esql -FROM employees -| STATS count = COUNT(*) BY languages -| SORT languages DESC -``` - -| count:long | languages:integer | -| --- | --- | -| 10 | null | -| 21 | 5 | -| 18 | 4 | -| 17 | 3 | -| 19 | 2 | -| 15 | 1 | - -The expression can use inline functions. This example splits a string into multiple values using the `SPLIT` function and counts the values - -```esql -ROW words="foo;bar;baz;qux;quux;foo" -| STATS word_count = COUNT(SPLIT(words, ";")) -``` - -| word_count:long | -| --- | -| 6 | - -To count the number of times an expression returns `TRUE` use a [`WHERE`](/reference/query-languages/esql/esql-commands.md#esql-where) command to remove rows that shouldn’t be included - -```esql -ROW n=1 -| WHERE n < 0 -| STATS COUNT(n) -``` - -| COUNT(n):long | -| --- | -| 0 | - -To count the same stream of data based on two different expressions use the pattern `COUNT( OR NULL)`. This builds on the three-valued logic ({{wikipedia}}/Three-valued_logic[3VL]) of the language: `TRUE OR NULL` is `TRUE`, but `FALSE OR NULL` is `NULL`, plus the way COUNT handles `NULL`s: `COUNT(TRUE)` and `COUNT(FALSE)` are both 1, but `COUNT(NULL)` is 0. - -```esql -ROW n=1 -| STATS COUNT(n > 0 OR NULL), COUNT(n < 0 OR NULL) -``` - -| COUNT(n > 0 OR NULL):long | COUNT(n < 0 OR NULL):long | -| --- | --- | -| 1 | 0 | - - -## `COUNT_DISTINCT` [esql-count_distinct] - -**Syntax** - -:::{image} ../../../../images/count_distinct.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Column or literal for which to count the number of distinct values. - -`precision` -: Precision threshold. Refer to [Counts are approximate](../esql-functions-operators.md#esql-agg-count-distinct-approximate). 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** - -| field | precision | result | -| --- | --- | --- | -| boolean | integer | long | -| boolean | long | long | -| boolean | unsigned_long | long | -| boolean | | long | -| date | integer | long | -| date | long | long | -| date | unsigned_long | long | -| date | | long | -| date_nanos | integer | long | -| date_nanos | long | long | -| date_nanos | unsigned_long | long | -| date_nanos | | long | -| double | integer | long | -| double | long | long | -| double | unsigned_long | long | -| double | | long | -| integer | integer | long | -| integer | long | long | -| integer | unsigned_long | long | -| integer | | long | -| ip | integer | long | -| ip | long | long | -| ip | unsigned_long | long | -| ip | | long | -| keyword | integer | long | -| keyword | long | long | -| keyword | unsigned_long | long | -| keyword | | long | -| long | integer | long | -| long | long | long | -| long | unsigned_long | long | -| long | | long | -| text | integer | long | -| text | long | long | -| text | unsigned_long | long | -| text | | long | -| version | integer | long | -| version | long | long | -| version | unsigned_long | long | -| version | | long | - -**Examples** - -```esql -FROM hosts -| STATS COUNT_DISTINCT(ip0), COUNT_DISTINCT(ip1) -``` - -| COUNT_DISTINCT(ip0):long | COUNT_DISTINCT(ip1):long | -| --- | --- | -| 7 | 8 | - -With the optional second parameter to configure the precision threshold - -```esql -FROM hosts -| STATS COUNT_DISTINCT(ip0, 80000), COUNT_DISTINCT(ip1, 5) -``` - -| COUNT_DISTINCT(ip0, 80000):long | COUNT_DISTINCT(ip1, 5):long | -| --- | --- | -| 7 | 9 | - -The expression can use inline functions. This example splits a string into multiple values using the `SPLIT` function and counts the unique values - -```esql -ROW words="foo;bar;baz;qux;quux;foo" -| STATS distinct_word_count = COUNT_DISTINCT(SPLIT(words, ";")) -``` - -| distinct_word_count:long | -| --- | -| 5 | - - -### Counts are approximate [esql-agg-count-distinct-approximate] - -Computing exact counts requires loading values into a set and returning its size. This doesn’t scale when working on high-cardinality sets and/or large values as the required memory usage and the need to communicate those per-shard sets between nodes would utilize too many resources of the cluster. - -This `COUNT_DISTINCT` function is based on the [HyperLogLog++](https://static.googleusercontent.com/media/research.google.com/fr//pubs/archive/40671.pdf) algorithm, which counts based on the hashes of the values with some interesting properties: - -* configurable precision, which decides on how to trade memory for accuracy, -* excellent accuracy on low-cardinality sets, -* fixed memory usage: no matter if there are tens or billions of unique values, memory usage only depends on the configured precision. - -For a precision threshold of `c`, the implementation that we are using requires about `c * 8` bytes. - -The following chart shows how the error varies before and after the threshold: - -![cardinality error](/images/cardinality_error.png "") - -For all 3 thresholds, counts have been accurate up to the configured threshold. Although not guaranteed, this is likely to be the case. Accuracy in practice depends on the dataset in question. In general, most datasets show consistently good accuracy. Also note that even with a threshold as low as 100, the error remains very low (1-6% as seen in the above graph) even when counting millions of items. - -The HyperLogLog++ algorithm depends on the leading zeros of hashed values, the exact distributions of hashes in a dataset can affect the accuracy of the cardinality. - -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`. - - -## `MAX` [esql-max] - -**Syntax** - -:::{image} ../../../../images/max.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -The maximum value of a field. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| date | date | -| date_nanos | date_nanos | -| double | double | -| integer | integer | -| ip | ip | -| keyword | keyword | -| long | long | -| text | keyword | -| version | version | - -**Examples** - -```esql -FROM employees -| STATS MAX(languages) -``` - -| MAX(languages):integer | -| --- | -| 5 | - -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 - -```esql -FROM employees -| STATS max_avg_salary_change = MAX(MV_AVG(salary_change)) -``` - -| max_avg_salary_change:double | -| --- | -| 13.75 | - - -## `MEDIAN` [esql-median] - -**Syntax** - -:::{image} ../../../../images/median.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -The value that is greater than half of all values and less than half of all values, also known as the 50% [`PERCENTILE`](../esql-functions-operators.md#esql-percentile). - -::::{note} -Like [`PERCENTILE`](../esql-functions-operators.md#esql-percentile), `MEDIAN` is [usually approximate](../esql-functions-operators.md#esql-percentile-approximate). -:::: - - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | - -**Examples** - -```esql -FROM employees -| STATS MEDIAN(salary), PERCENTILE(salary, 50) -``` - -| MEDIAN(salary):double | PERCENTILE(salary, 50):double | -| --- | --- | -| 47003 | 47003 | - -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 - -```esql -FROM employees -| STATS median_max_salary_change = MEDIAN(MV_MAX(salary_change)) -``` - -| median_max_salary_change:double | -| --- | -| 7.69 | - -::::{warning} -`MEDIAN` is also [non-deterministic](https://en.wikipedia.org/wiki/Nondeterministic_algorithm). This means you can get slightly different results using the same data. - -:::: - - - -## `MEDIAN_ABSOLUTE_DEVIATION` [esql-median_absolute_deviation] - -**Syntax** - -:::{image} ../../../../images/median_absolute_deviation.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**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 [`PERCENTILE`](../esql-functions-operators.md#esql-percentile), `MEDIAN_ABSOLUTE_DEVIATION` is [usually approximate](../esql-functions-operators.md#esql-percentile-approximate). -:::: - - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | - -**Examples** - -```esql -FROM employees -| STATS MEDIAN(salary), MEDIAN_ABSOLUTE_DEVIATION(salary) -``` - -| MEDIAN(salary):double | MEDIAN_ABSOLUTE_DEVIATION(salary):double | -| --- | --- | -| 47003 | 10096.5 | - -The expression can use inline functions. For example, to calculate 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 - -```esql -FROM employees -| STATS m_a_d_max_salary_change = MEDIAN_ABSOLUTE_DEVIATION(MV_MAX(salary_change)) -``` - -| m_a_d_max_salary_change:double | -| --- | -| 5.69 | - -::::{warning} -`MEDIAN_ABSOLUTE_DEVIATION` is also [non-deterministic](https://en.wikipedia.org/wiki/Nondeterministic_algorithm). This means you can get slightly different results using the same data. - -:::: - - - -## `MIN` [esql-min] - -**Syntax** - -:::{image} ../../../../images/min.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -The minimum value of a field. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| date | date | -| date_nanos | date_nanos | -| double | double | -| integer | integer | -| ip | ip | -| keyword | keyword | -| long | long | -| text | keyword | -| version | version | - -**Examples** - -```esql -FROM employees -| STATS MIN(languages) -``` - -| MIN(languages):integer | -| --- | -| 1 | - -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 - -```esql -FROM employees -| STATS min_avg_salary_change = MIN(MV_AVG(salary_change)) -``` - -| min_avg_salary_change:double | -| --- | -| -8.46 | - - -## `PERCENTILE` [esql-percentile] - -**Syntax** - -:::{image} ../../../../images/percentile.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**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 `MEDIAN`. - -**Supported types** - -| number | percentile | result | -| --- | --- | --- | -| double | double | double | -| double | integer | double | -| double | long | double | -| integer | double | double | -| integer | integer | double | -| integer | long | double | -| long | double | double | -| long | integer | double | -| long | long | double | - -**Examples** - -```esql -FROM employees -| STATS p0 = PERCENTILE(salary, 0) - , p50 = PERCENTILE(salary, 50) - , p99 = PERCENTILE(salary, 99) -``` - -| p0:double | p50:double | p99:double | -| --- | --- | --- | -| 25324 | 47003 | 74970.29 | - -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 - -```esql -FROM employees -| STATS p80_max_salary_change = PERCENTILE(MV_MAX(salary_change), 80) -``` - -| p80_max_salary_change:double | -| --- | -| 12.132 | - - -### `PERCENTILE` is (usually) approximate [esql-percentile-approximate] - -There are many different algorithms to calculate percentiles. The naive implementation simply stores all the values in a sorted array. To find the 50th percentile, you simply find the value that is at `my_array[count(my_array) * 0.5]`. - -Clearly, the naive implementation does not scale — the sorted array grows linearly with the number of values in your dataset. To calculate percentiles across potentially billions of values in an Elasticsearch cluster, *approximate* percentiles are calculated. - -The algorithm used by the `percentile` metric is called TDigest (introduced by Ted Dunning in [Computing Accurate Quantiles using T-Digests](https://github.com/tdunning/t-digest/blob/master/docs/t-digest-paper/histo.pdf)). - -When using this metric, there are a few guidelines to keep in mind: - -* Accuracy is proportional to `q(1-q)`. This means that extreme percentiles (e.g. 99%) are more accurate than less extreme percentiles, such as the median -* For small sets of values, percentiles are highly accurate (and potentially 100% accurate if the data is small enough). -* As the quantity of values in a bucket grows, the algorithm begins to approximate the percentiles. It is effectively trading accuracy for memory savings. The exact level of inaccuracy is difficult to generalize, since it depends on your data distribution and volume of data being aggregated - -The following chart shows the relative error on a uniform distribution depending on the number of collected values and the requested percentile: - -![percentiles error](/images/percentiles_error.png "") - -It shows how precision is better for extreme percentiles. The reason why error diminishes for large number of values is that the law of large numbers makes the distribution of values more and more uniform and the t-digest tree can do a better job at summarizing it. It would not be the case on more skewed distributions. - -::::{warning} -`PERCENTILE` is also [non-deterministic](https://en.wikipedia.org/wiki/Nondeterministic_algorithm). This means you can get slightly different results using the same data. - -:::: - - - -## `ST_CENTROID_AGG` [esql-st_centroid_agg] - -**Syntax** - -:::{image} ../../../../images/st_centroid_agg.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -Calculate the spatial centroid over a field with spatial point geometry type. - -**Supported types** - -| field | result | -| --- | --- | -| cartesian_point | cartesian_point | -| geo_point | geo_point | - -**Example** - -```esql -FROM airports -| STATS centroid=ST_CENTROID_AGG(location) -``` - -| centroid:geo_point | -| --- | -| POINT(-0.030548143003023033 24.37553649504829) | - - -## `ST_EXTENT_AGG` [esql-st_extent_agg] - -**Syntax** - -:::{image} ../../../../images/st_extent_agg.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -Calculate the spatial extent over a field with geometry type. Returns a bounding box for all values of the field. - -**Supported types** - -| field | result | -| --- | --- | -| cartesian_point | cartesian_shape | -| cartesian_shape | cartesian_shape | -| geo_point | geo_shape | -| geo_shape | geo_shape | - -**Example** - -```esql -FROM airports -| WHERE country == "India" -| STATS extent = ST_EXTENT_AGG(location) -``` - -| extent:geo_shape | -| --- | -| BBOX (70.77995480038226, 91.5882289968431, 33.9830909203738, 8.47650992218405) | - - -## `STD_DEV` [esql-std_dev] - -**Syntax** - -:::{image} ../../../../images/std_dev.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -The standard deviation of a numeric field. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | - -**Examples** - -```esql -FROM employees -| STATS STD_DEV(height) -``` - -| STD_DEV(height):double | -| --- | -| 0.20637044362020449 | - -The expression can use inline functions. For example, to calculate the standard deviation of each employee’s maximum salary changes, first use `MV_MAX` on each row, and then use `STD_DEV` on the result - -```esql -FROM employees -| STATS stddev_salary_change = STD_DEV(MV_MAX(salary_change)) -``` - -| stddev_salary_change:double | -| --- | -| 6.875829592924112 | - - -## `SUM` [esql-sum] - -**Syntax** - -:::{image} ../../../../images/sum.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -The sum of a numeric expression. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | long | -| long | long | - -**Examples** - -```esql -FROM employees -| STATS SUM(languages) -``` - -| SUM(languages):long | -| --- | -| 281 | - -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 - -```esql -FROM employees -| STATS total_salary_changes = SUM(MV_MAX(salary_change)) -``` - -| total_salary_changes:double | -| --- | -| 446.75 | - - -## `TOP` [esql-top] - -**Syntax** - -:::{image} ../../../../images/top.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: The field to collect the top values for. - -`limit` -: The maximum number of values to collect. - -`order` -: The order to calculate the top values. Either `asc` or `desc`. - -**Description** - -Collects the top values for a field. Includes repeated values. - -**Supported types** - -| field | limit | order | result | -| --- | --- | --- | --- | -| boolean | integer | keyword | boolean | -| date | integer | keyword | date | -| double | integer | keyword | double | -| integer | integer | keyword | integer | -| ip | integer | keyword | ip | -| keyword | integer | keyword | keyword | -| long | integer | keyword | long | -| text | integer | keyword | keyword | - -**Example** - -```esql -FROM employees -| STATS top_salaries = TOP(salary, 3, "desc"), top_salary = MAX(salary) -``` - -| top_salaries:integer | top_salary:integer | -| --- | --- | -| [74999, 74970, 74572] | 74999 | - - -## `VALUES` [esql-values] - -::::{warning} -Do not use 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. -:::: - - -**Syntax** - -:::{image} ../../../../images/values.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -Returns all values in a group as a multivalued field. The order of the returned values isn’t guaranteed. If you need the values returned in order use [`MV_SORT`](../esql-functions-operators.md#esql-mv_sort). - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| date | date | -| date_nanos | date_nanos | -| double | double | -| integer | integer | -| ip | ip | -| keyword | keyword | -| long | long | -| text | keyword | -| version | version | - -**Example** - -```esql - FROM employees -| EVAL first_letter = SUBSTRING(first_name, 0, 1) -| STATS first_name=MV_SORT(VALUES(first_name)) BY first_letter -| SORT first_letter -``` - -| first_name:keyword | first_letter:keyword | -| --- | --- | -| [Alejandro, Amabile, Anneke, Anoosh, Arumugam] | A | -| [Basil, Berhard, Berni, Bezalel, Bojan, Breannda, Brendon] | B | -| [Charlene, Chirstian, Claudi, Cristinel] | C | -| [Danel, Divier, Domenick, Duangkaew] | D | -| [Ebbe, Eberhardt, Erez] | E | -| Florian | F | -| [Gao, Georgi, Georgy, Gino, Guoxiang] | G | -| [Heping, Hidefumi, Hilari, Hironobu, Hironoby, Hisao] | H | -| [Jayson, Jungsoon] | J | -| [Kazuhide, Kazuhito, Kendra, Kenroku, Kshitij, Kwee, Kyoichi] | K | -| [Lillian, Lucien] | L | -| [Magy, Margareta, Mary, Mayuko, Mayumi, Mingsen, Mokhtar, Mona, Moss] | M | -| Otmar | O | -| [Parto, Parviz, Patricio, Prasadram, Premal] | P | -| [Ramzi, Remzi, Reuven] | R | -| [Sailaja, Saniya, Sanjiv, Satosi, Shahaf, Shir, Somnath, Sreekrishna, Sudharsan, Sumant, Suzette] | S | -| [Tse, Tuval, Tzvetan] | T | -| [Udi, Uri] | U | -| [Valdiodio, Valter, Vishv] | V | -| Weiyi | W | -| Xinglin | X | -| [Yinghua, Yishay, Yongqiao] | Y | -| [Zhongwei, Zvonko] | Z | -| null | null | - -::::{warning} -This can use a significant amount of memory and ES|QL doesn’t yet grow aggregations beyond memory. So this aggregation will work until it is used to collect more values than can fit into memory. Once it collects too many values it will fail the query with a [Circuit Breaker Error](docs-content://troubleshoot/elasticsearch/circuit-breaker-errors.md). - -:::: - - - -## `WEIGHTED_AVG` [esql-weighted_avg] - -**Syntax** - -:::{image} ../../../../images/weighted_avg.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: A numeric value. - -`weight` -: A numeric weight. - -**Description** - -The weighted average of a numeric expression. - -**Supported types** - -| number | weight | result | -| --- | --- | --- | -| double | double | double | -| double | integer | double | -| double | long | double | -| integer | double | double | -| integer | integer | double | -| integer | long | double | -| long | double | double | -| long | integer | double | -| long | long | double | - -**Example** - -```esql -FROM employees -| STATS w_avg = WEIGHTED_AVG(salary, height) by languages -| EVAL w_avg = ROUND(w_avg) -| KEEP w_avg, languages -| SORT languages -``` - -| w_avg:double | languages:integer | -| --- | --- | -| 51464.0 | 1 | -| 48477.0 | 2 | -| 52379.0 | 3 | -| 47990.0 | 4 | -| 42119.0 | 5 | -| 52142.0 | null | diff --git a/docs/reference/query-languages/esql/_snippets/conditional-functions-and-expressions-new.md b/docs/reference/query-languages/esql/_snippets/conditional-functions-and-expressions-new.md deleted file mode 100644 index a8572fc48286e..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/conditional-functions-and-expressions-new.md +++ /dev/null @@ -1,21 +0,0 @@ -## {{esql}} conditional functions and expressions [esql-conditional-functions-and-expressions] - - -Conditional functions return one of their arguments by evaluating in an if-else manner. {{esql}} supports these conditional functions: - -:::{include} lists/conditional-functions-and-expressions.md -::: - - -:::{include} functions/case.md -::: - -:::{include} functions/coalesce.md -::: - -:::{include} functions/greatest.md -::: - -:::{include} functions/least.md -::: - diff --git a/docs/reference/query-languages/esql/_snippets/conditional-functions-and-expressions-orig.md b/docs/reference/query-languages/esql/_snippets/conditional-functions-and-expressions-orig.md deleted file mode 100644 index aa3402ef92417..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/conditional-functions-and-expressions-orig.md +++ /dev/null @@ -1,287 +0,0 @@ -## {{esql}} conditional functions and expressions [esql-conditional-functions-and-expressions] - - -Conditional functions return one of their arguments by evaluating in an if-else manner. {{esql}} supports these conditional functions: - -:::{include} lists/conditional-functions-and-expressions.md -::: - - -## `CASE` [esql-case] - -**Syntax** - -:::{image} ../../../../images/case.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`condition` -: A condition. - -`trueValue` -: The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches. - -`elseValue` -: The value that’s returned when no condition evaluates to `true`. - -**Description** - -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. If the number of arguments is even, and no condition matches, the function returns `null`. - -**Supported types** - -| condition | trueValue | elseValue | result | -| --- | --- | --- | --- | -| boolean | boolean | boolean | boolean | -| boolean | boolean | | boolean | -| boolean | cartesian_point | cartesian_point | cartesian_point | -| boolean | cartesian_point | | cartesian_point | -| boolean | cartesian_shape | cartesian_shape | cartesian_shape | -| boolean | cartesian_shape | | cartesian_shape | -| boolean | date | date | date | -| boolean | date | | date | -| boolean | date_nanos | date_nanos | date_nanos | -| boolean | date_nanos | | date_nanos | -| boolean | double | double | double | -| boolean | double | | double | -| boolean | geo_point | geo_point | geo_point | -| boolean | geo_point | | geo_point | -| boolean | geo_shape | geo_shape | geo_shape | -| boolean | geo_shape | | geo_shape | -| boolean | integer | integer | integer | -| boolean | integer | | integer | -| boolean | ip | ip | ip | -| boolean | ip | | ip | -| boolean | keyword | keyword | keyword | -| boolean | keyword | text | keyword | -| boolean | keyword | | keyword | -| boolean | long | long | long | -| boolean | long | | long | -| boolean | text | keyword | keyword | -| boolean | text | text | keyword | -| boolean | text | | keyword | -| boolean | unsigned_long | unsigned_long | unsigned_long | -| boolean | unsigned_long | | unsigned_long | -| boolean | version | version | version | -| boolean | version | | version | - -**Examples** - -Determine whether employees are monolingual, bilingual, or polyglot: - -```esql -FROM employees -| EVAL type = CASE( - languages <= 1, "monolingual", - languages <= 2, "bilingual", - "polyglot") -| KEEP emp_no, languages, type -``` - -| emp_no:integer | languages:integer | type:keyword | -| --- | --- | --- | -| 10001 | 2 | bilingual | -| 10002 | 5 | polyglot | -| 10003 | 4 | polyglot | -| 10004 | 5 | polyglot | -| 10005 | 1 | monolingual | - -Calculate the total connection success rate based on log messages: - -```esql -FROM sample_data -| EVAL successful = CASE( - STARTS_WITH(message, "Connected to"), 1, - message == "Connection error", 0 - ) -| STATS success_rate = AVG(successful) -``` - -| success_rate:double | -| --- | -| 0.5 | - -Calculate an hourly error rate as a percentage of the total number of log messages: - -```esql -FROM sample_data -| EVAL error = CASE(message LIKE "*error*", 1, 0) -| EVAL hour = DATE_TRUNC(1 hour, @timestamp) -| STATS error_rate = AVG(error) by hour -| SORT hour -``` - -| error_rate:double | hour:date | -| --- | --- | -| 0.0 | 2023-10-23T12:00:00.000Z | -| 0.6 | 2023-10-23T13:00:00.000Z | - - -## `COALESCE` [esql-coalesce] - -**Syntax** - -:::{image} ../../../../images/coalesce.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`first` -: Expression to evaluate. - -`rest` -: Other expression to evaluate. - -**Description** - -Returns the first of its arguments that is not null. If all arguments are null, it returns `null`. - -**Supported types** - -| first | rest | result | -| --- | --- | --- | -| boolean | boolean | boolean | -| boolean | | boolean | -| cartesian_point | cartesian_point | cartesian_point | -| cartesian_shape | cartesian_shape | cartesian_shape | -| date | date | date | -| date_nanos | date_nanos | date_nanos | -| geo_point | geo_point | geo_point | -| geo_shape | geo_shape | geo_shape | -| integer | integer | integer | -| integer | | integer | -| ip | ip | ip | -| keyword | keyword | keyword | -| keyword | | keyword | -| long | long | long | -| long | | long | -| text | text | keyword | -| text | | keyword | -| version | version | version | - -**Example** - -```esql -ROW a=null, b="b" -| EVAL COALESCE(a, b) -``` - -| a:null | b:keyword | COALESCE(a, b):keyword | -| --- | --- | --- | -| null | b | b | - - -## `GREATEST` [esql-greatest] - -**Syntax** - -:::{image} ../../../../images/greatest.svg -:alt: Embedded -:class: text-center -::: - -**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 [`MV_MAX`](../esql-functions-operators.md#esql-mv_max) 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** - -| first | rest | result | -| --- | --- | --- | -| boolean | boolean | boolean | -| boolean | | boolean | -| date | date | date | -| date_nanos | date_nanos | date_nanos | -| double | double | double | -| integer | integer | integer | -| integer | | integer | -| ip | ip | ip | -| keyword | keyword | keyword | -| keyword | | keyword | -| long | long | long | -| long | | long | -| text | text | keyword | -| text | | keyword | -| version | version | version | - -**Example** - -```esql -ROW a = 10, b = 20 -| EVAL g = GREATEST(a, b) -``` - -| a:integer | b:integer | g:integer | -| --- | --- | --- | -| 10 | 20 | 20 | - - -## `LEAST` [esql-least] - -**Syntax** - -:::{image} ../../../../images/least.svg -:alt: Embedded -:class: text-center -::: - -**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 [`MV_MIN`](../esql-functions-operators.md#esql-mv_min) except it is intended to run on multiple columns at once. - -**Supported types** - -| first | rest | result | -| --- | --- | --- | -| boolean | boolean | boolean | -| boolean | | boolean | -| date | date | date | -| date_nanos | date_nanos | date_nanos | -| double | double | double | -| integer | integer | integer | -| integer | | integer | -| ip | ip | ip | -| keyword | keyword | keyword | -| keyword | | keyword | -| long | long | long | -| long | | long | -| text | text | keyword | -| text | | keyword | -| version | version | version | - -**Example** - -```esql -ROW a = 10, b = 20 -| EVAL l = LEAST(a, b) -``` - -| a:integer | b:integer | l:integer | -| --- | --- | --- | -| 10 | 20 | 10 | diff --git a/docs/reference/query-languages/esql/_snippets/date-time-functions-new.md b/docs/reference/query-languages/esql/_snippets/date-time-functions-new.md deleted file mode 100644 index cd6640d6ef9eb..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/date-time-functions-new.md +++ /dev/null @@ -1,27 +0,0 @@ -## {{esql}} date-time functions [esql-date-time-functions] - - -{{esql}} supports these date-time functions: - -:::{include} lists/date-time-functions.md -::: - - -:::{include} functions/date_diff.md -::: - -:::{include} functions/date_extract.md -::: - -:::{include} functions/date_format.md -::: - -:::{include} functions/date_parse.md -::: - -:::{include} functions/date_trunc.md -::: - -:::{include} functions/now.md -::: - diff --git a/docs/reference/query-languages/esql/_snippets/date-time-functions-orig.md b/docs/reference/query-languages/esql/_snippets/date-time-functions-orig.md deleted file mode 100644 index 03b08ca003032..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/date-time-functions-orig.md +++ /dev/null @@ -1,359 +0,0 @@ -## {{esql}} date-time functions [esql-date-time-functions] - - -{{esql}} supports these date-time functions: - -:::{include} lists/date-time-functions.md -::: - - -## `DATE_DIFF` [esql-date_diff] - -**Syntax** - -:::{image} ../../../../images/date_diff.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`unit` -: Time difference unit - -`startTimestamp` -: A string representing a start timestamp - -`endTimestamp` -: A string representing an 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. - -| Datetime difference units | -| --- | -| **unit** | **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 | - -Note that while there is an overlap between the function’s supported units and {{esql}}'s supported time span literals, these sets are distinct and not interchangeable. Similarly, the supported abbreviations are conveniently shared with implementations of this function in other established products and not necessarily common with the date-time nomenclature used by {{es}}. - -**Supported types** - -| unit | startTimestamp | endTimestamp | result | -| --- | --- | --- | --- | -| keyword | date | date | integer | -| keyword | date | date_nanos | integer | -| keyword | date_nanos | date | integer | -| keyword | date_nanos | date_nanos | integer | -| text | date | date | integer | -| text | date | date_nanos | integer | -| text | date_nanos | date | integer | -| text | date_nanos | date_nanos | integer | - -**Examples** - -```esql -ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), date2 = TO_DATETIME("2023-12-02T11:00:00.001Z") -| EVAL dd_ms = DATE_DIFF("microseconds", date1, date2) -``` - -| date1:date | date2:date | dd_ms:integer | -| --- | --- | --- | -| 2023-12-02T11:00:00.000Z | 2023-12-02T11:00:00.001Z | 1000 | - -When subtracting in calendar units - like year, month a.s.o. - only the fully elapsed units are counted. To avoid this and obtain also remainders, simply switch to the next smaller unit and do the date math accordingly. - -```esql -ROW end_23=TO_DATETIME("2023-12-31T23:59:59.999Z"), - start_24=TO_DATETIME("2024-01-01T00:00:00.000Z"), - end_24=TO_DATETIME("2024-12-31T23:59:59.999") -| EVAL end23_to_start24=DATE_DIFF("year", end_23, start_24) -| EVAL end23_to_end24=DATE_DIFF("year", end_23, end_24) -| EVAL start_to_end_24=DATE_DIFF("year", start_24, end_24) -``` - -| end_23:date | start_24:date | end_24:date | end23_to_start24:integer | end23_to_end24:integer | start_to_end_24:integer | -| --- | --- | --- | --- | --- | --- | -| 2023-12-31T23:59:59.999Z | 2024-01-01T00:00:00.000Z | 2024-12-31T23:59:59.999Z | 0 | 1 | 0 | - - -## `DATE_EXTRACT` [esql-date_extract] - -**Syntax** - -:::{image} ../../../../images/date_extract.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`datePart` -: 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 [java.time.temporal.ChronoField](https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoField.md) 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. - -**Supported types** - -| datePart | date | result | -| --- | --- | --- | -| keyword | date | long | -| keyword | date_nanos | long | -| text | date | long | -| text | date_nanos | long | - -**Examples** - -```esql -ROW date = DATE_PARSE("yyyy-MM-dd", "2022-05-06") -| EVAL year = DATE_EXTRACT("year", date) -``` - -| date:date | year:long | -| --- | --- | -| 2022-05-06T00:00:00.000Z | 2022 | - -Find all events that occurred outside of business hours (before 9 AM or after 5PM), on any given date: - -```esql -FROM sample_data -| WHERE DATE_EXTRACT("hour_of_day", @timestamp) < 9 AND DATE_EXTRACT("hour_of_day", @timestamp) >= 17 -``` - -| @timestamp:date | client_ip:ip | event_duration:long | message:keyword | -| --- | --- | --- | --- | - - -## `DATE_FORMAT` [esql-date_format] - -**Syntax** - -:::{image} ../../../../images/date_format.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`dateFormat` -: 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. - -**Supported types** - -| dateFormat | date | result | -| --- | --- | --- | -| date | | keyword | -| date_nanos | | keyword | -| keyword | date | keyword | -| keyword | date_nanos | keyword | -| text | date | keyword | -| text | date_nanos | keyword | - -**Example** - -```esql -FROM employees -| KEEP first_name, last_name, hire_date -| EVAL hired = DATE_FORMAT("yyyy-MM-dd", hire_date) -``` - -| first_name:keyword | last_name:keyword | hire_date:date | hired:keyword | -| --- | --- | --- | --- | -| Alejandro | McAlpine | 1991-06-26T00:00:00.000Z | 1991-06-26 | -| Amabile | Gomatam | 1992-11-18T00:00:00.000Z | 1992-11-18 | -| Anneke | Preusig | 1989-06-02T00:00:00.000Z | 1989-06-02 | - - -## `DATE_PARSE` [esql-date_parse] - -**Syntax** - -:::{image} ../../../../images/date_parse.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`datePattern` -: The date format. Refer to the [`DateTimeFormatter` documentation](https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.md) for the syntax. If `null`, the function returns `null`. - -`dateString` -: Date expression as a string. If `null` or an empty string, the function returns `null`. - -**Description** - -Returns a date by parsing the second argument using the format specified in the first argument. - -**Supported types** - -| datePattern | dateString | result | -| --- | --- | --- | -| keyword | keyword | date | -| keyword | text | date | -| text | keyword | date | -| text | text | date | - -**Example** - -```esql -ROW date_string = "2022-05-06" -| EVAL date = DATE_PARSE("yyyy-MM-dd", date_string) -``` - -| date_string:keyword | date:date | -| --- | --- | -| 2022-05-06 | 2022-05-06T00:00:00.000Z | - - -## `DATE_TRUNC` [esql-date_trunc] - -**Syntax** - -:::{image} ../../../../images/date_trunc.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`interval` -: Interval; expressed using the timespan literal syntax. - -`date` -: Date expression - -**Description** - -Rounds down a date to the closest interval. - -**Supported types** - -| interval | date | result | -| --- | --- | --- | -| date_period | date | date | -| date_period | date_nanos | date_nanos | -| time_duration | date | date | -| time_duration | date_nanos | date_nanos | - -**Examples** - -```esql -FROM employees -| KEEP first_name, last_name, hire_date -| EVAL year_hired = DATE_TRUNC(1 year, hire_date) -``` - -| first_name:keyword | last_name:keyword | hire_date:date | year_hired:date | -| --- | --- | --- | --- | -| Alejandro | McAlpine | 1991-06-26T00:00:00.000Z | 1991-01-01T00:00:00.000Z | -| Amabile | Gomatam | 1992-11-18T00:00:00.000Z | 1992-01-01T00:00:00.000Z | -| Anneke | Preusig | 1989-06-02T00:00:00.000Z | 1989-01-01T00:00:00.000Z | - -Combine `DATE_TRUNC` with [`STATS`](/reference/query-languages/esql/esql-commands.md#esql-stats-by) to create date histograms. For example, the number of hires per year: - -```esql -FROM employees -| EVAL year = DATE_TRUNC(1 year, hire_date) -| STATS hires = COUNT(emp_no) BY year -| SORT year -``` - -| hires:long | year:date | -| --- | --- | -| 11 | 1985-01-01T00:00:00.000Z | -| 11 | 1986-01-01T00:00:00.000Z | -| 15 | 1987-01-01T00:00:00.000Z | -| 9 | 1988-01-01T00:00:00.000Z | -| 13 | 1989-01-01T00:00:00.000Z | -| 12 | 1990-01-01T00:00:00.000Z | -| 6 | 1991-01-01T00:00:00.000Z | -| 8 | 1992-01-01T00:00:00.000Z | -| 3 | 1993-01-01T00:00:00.000Z | -| 4 | 1994-01-01T00:00:00.000Z | -| 5 | 1995-01-01T00:00:00.000Z | -| 1 | 1996-01-01T00:00:00.000Z | -| 1 | 1997-01-01T00:00:00.000Z | -| 1 | 1999-01-01T00:00:00.000Z | - -Or an hourly error rate: - -```esql -FROM sample_data -| EVAL error = CASE(message LIKE "*error*", 1, 0) -| EVAL hour = DATE_TRUNC(1 hour, @timestamp) -| STATS error_rate = AVG(error) by hour -| SORT hour -``` - -| error_rate:double | hour:date | -| --- | --- | -| 0.0 | 2023-10-23T12:00:00.000Z | -| 0.6 | 2023-10-23T13:00:00.000Z | - - -## `NOW` [esql-now] - -**Syntax** - -:::{image} ../../../../images/now.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -**Description** - -Returns current date and time. - -**Supported types** - -| result | -| --- | -| date | - -**Examples** - -```esql -ROW current_date = NOW() -``` - -| y:keyword | -| --- | -| 20 | - -To retrieve logs from the last hour: - -```esql -FROM sample_data -| WHERE @timestamp > NOW() - 1 hour -``` - -| @timestamp:date | client_ip:ip | event_duration:long | message:keyword | -| --- | --- | --- | --- | diff --git a/docs/reference/query-languages/esql/_snippets/functions/abs.md b/docs/reference/query-languages/esql/_snippets/functions/abs.md deleted file mode 100644 index 2a58e5e1a5c1e..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/abs.md +++ /dev/null @@ -1,51 +0,0 @@ -## `ABS` [esql-abs] - -**Syntax** - -:::{image} ../../../../../images/abs.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the absolute value. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | integer | -| long | long | -| unsigned_long | unsigned_long | - -**Examples** - -```esql -ROW number = -1.0 -| EVAL abs_number = ABS(number) -``` - -| number:double | abs_number:double | -| --- | --- | -| -1.0 | 1.0 | - -```esql -FROM employees -| KEEP first_name, last_name, height -| EVAL abs_height = ABS(0.0 - height) -``` - -| first_name:keyword | last_name:keyword | height:double | abs_height:double | -| --- | --- | --- | --- | -| Alejandro | McAlpine | 1.48 | 1.48 | -| Amabile | Gomatam | 2.09 | 2.09 | -| Anneke | Preusig | 1.56 | 1.56 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/acos.md b/docs/reference/query-languages/esql/_snippets/functions/acos.md deleted file mode 100644 index d28b0c9433769..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/acos.md +++ /dev/null @@ -1,39 +0,0 @@ -## `ACOS` [esql-acos] - -**Syntax** - -:::{image} ../../../../../images/acos.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Number between -1 and 1. If `null`, the function returns `null`. - -**Description** - -Returns the [arccosine](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions) of `n` as an angle, expressed in radians. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=.9 -| EVAL acos=ACOS(a) -``` - -| a:double | acos:double | -| --- | --- | -| .9 | 0.45102681179626236 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/appendix/count_distinct.md b/docs/reference/query-languages/esql/_snippets/functions/appendix/count_distinct.md new file mode 100644 index 0000000000000..3218dd61c0615 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/functions/appendix/count_distinct.md @@ -0,0 +1,24 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +### Counts are approximate [esql-agg-count-distinct-approximate] + +Computing exact counts requires loading values into a set and returning its +size. This doesn’t scale when working on high-cardinality sets and/or large +values as the required memory usage and the need to communicate those +per-shard sets between nodes would utilize too many resources of the cluster. + +This `COUNT_DISTINCT` function is based on the +[HyperLogLog++](https://static.googleusercontent.com/media/research.google.com/fr//pubs/archive/40671.pdf) +algorithm, which counts based on the hashes of the values with some interesting +properties: + +:::{include} /reference/data-analysis/aggregations/_snippets/search-aggregations-metrics-cardinality-aggregation-explanation.md +::: + +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`. + diff --git a/docs/reference/query-languages/esql/_snippets/functions/appendix/median.md b/docs/reference/query-languages/esql/_snippets/functions/appendix/median.md new file mode 100644 index 0000000000000..3e4e974202c2c --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/functions/appendix/median.md @@ -0,0 +1,6 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +::::{warning} +`MEDIAN` is also [non-deterministic](https://en.wikipedia.org/wiki/Nondeterministic_algorithm). +This means you can get slightly different results using the same data. +:::: diff --git a/docs/reference/query-languages/esql/_snippets/functions/appendix/median_absolute_deviation.md b/docs/reference/query-languages/esql/_snippets/functions/appendix/median_absolute_deviation.md new file mode 100644 index 0000000000000..967631e183039 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/functions/appendix/median_absolute_deviation.md @@ -0,0 +1,6 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +::::{warning} +`MEDIAN_ABSOLUTE_DEVIATION` is also [non-deterministic](https://en.wikipedia.org/wiki/Nondeterministic_algorithm). +This means you can get slightly different results using the same data. +:::: diff --git a/docs/reference/query-languages/esql/_snippets/functions/appendix/percentile.md b/docs/reference/query-languages/esql/_snippets/functions/appendix/percentile.md new file mode 100644 index 0000000000000..d163a1808403f --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/functions/appendix/percentile.md @@ -0,0 +1,11 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +### `PERCENTILE` is (usually) approximate [esql-percentile-approximate] + +:::{include} /reference/data-analysis/aggregations/_snippets/search-aggregations-metrics-percentile-aggregation-approximate.md +::: + +::::{warning} +`PERCENTILE` is also [non-deterministic](https://en.wikipedia.org/wiki/Nondeterministic_algorithm). +This means you can get slightly different results using the same data. +:::: diff --git a/docs/reference/query-languages/esql/_snippets/functions/appendix/values.md b/docs/reference/query-languages/esql/_snippets/functions/appendix/values.md new file mode 100644 index 0000000000000..5170ebd00674a --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/functions/appendix/values.md @@ -0,0 +1,9 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +::::{warning} +This can use a significant amount of memory and ES|QL doesn’t yet +grow aggregations beyond memory. So this aggregation will work until +it is used to collect more values than can fit into memory. Once it +collects too many values it will fail the query with +a [Circuit Breaker Error](docs-content://troubleshoot/elasticsearch/circuit-breaker-errors.md). +:::: diff --git a/docs/reference/query-languages/esql/_snippets/functions/asin.md b/docs/reference/query-languages/esql/_snippets/functions/asin.md deleted file mode 100644 index af39dce9bd94a..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/asin.md +++ /dev/null @@ -1,39 +0,0 @@ -## `ASIN` [esql-asin] - -**Syntax** - -:::{image} ../../../../../images/asin.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Number between -1 and 1. If `null`, the function returns `null`. - -**Description** - -Returns the [arcsine](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions) of the input numeric expression as an angle, expressed in radians. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=.9 -| EVAL asin=ASIN(a) -``` - -| a:double | asin:double | -| --- | --- | -| .9 | 1.1197695149986342 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/atan.md b/docs/reference/query-languages/esql/_snippets/functions/atan.md deleted file mode 100644 index 5ce84d247ed6e..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/atan.md +++ /dev/null @@ -1,39 +0,0 @@ -## `ATAN` [esql-atan] - -**Syntax** - -:::{image} ../../../../../images/atan.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the [arctangent](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions) of the input numeric expression as an angle, expressed in radians. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=12.9 -| EVAL atan=ATAN(a) -``` - -| a:double | atan:double | -| --- | --- | -| 12.9 | 1.4934316673669235 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/atan2.md b/docs/reference/query-languages/esql/_snippets/functions/atan2.md deleted file mode 100644 index d3d0d713efd08..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/atan2.md +++ /dev/null @@ -1,54 +0,0 @@ -## `ATAN2` [esql-atan2] - -**Syntax** - -:::{image} ../../../../../images/atan2.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`y_coordinate` -: y coordinate. If `null`, the function returns `null`. - -`x_coordinate` -: x coordinate. If `null`, the function returns `null`. - -**Description** - -The [angle](https://en.wikipedia.org/wiki/Atan2) 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** - -| y_coordinate | x_coordinate | 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 | - -**Example** - -```esql -ROW y=12.9, x=.6 -| EVAL atan2=ATAN2(y, x) -``` - -| y:double | x:double | atan2:double | -| --- | --- | --- | -| 12.9 | 0.6 | 1.5243181954438936 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/avg.md b/docs/reference/query-languages/esql/_snippets/functions/avg.md deleted file mode 100644 index ea52960c12281..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/avg.md +++ /dev/null @@ -1,47 +0,0 @@ -## `AVG` [esql-avg] - -**Syntax** - -:::{image} ../../../../../images/avg.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -The average of a numeric field. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | - -**Examples** - -```esql -FROM employees -| STATS AVG(height) -``` - -| AVG(height):double | -| --- | -| 1.7682 | - -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 - -```esql -FROM employees -| STATS avg_salary_change = ROUND(AVG(MV_AVG(salary_change)), 10) -``` - -| avg_salary_change:double | -| --- | -| 1.3904535865 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/bit_length.md b/docs/reference/query-languages/esql/_snippets/functions/bit_length.md deleted file mode 100644 index aee922724df03..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/bit_length.md +++ /dev/null @@ -1,46 +0,0 @@ -## `BIT_LENGTH` [esql-bit_length] - -**Syntax** - -:::{image} ../../../../../images/bit_length.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. If `null`, the function returns `null`. - -**Description** - -Returns the bit length of a string. - -::::{note} -All strings are in UTF-8, so a single character can use multiple bytes. -:::: - - -**Supported types** - -| string | result | -| --- | --- | -| keyword | integer | -| text | integer | - -**Example** - -```esql -FROM airports -| WHERE country == "India" -| KEEP city -| EVAL fn_length = LENGTH(city), fn_bit_length = BIT_LENGTH(city) -``` - -| city:keyword | fn_length:integer | fn_bit_length:integer | -| --- | --- | --- | -| Agwār | 5 | 48 | -| Ahmedabad | 9 | 72 | -| Bangalore | 9 | 72 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/bucket.md b/docs/reference/query-languages/esql/_snippets/functions/bucket.md deleted file mode 100644 index aed911c006492..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/bucket.md +++ /dev/null @@ -1,296 +0,0 @@ -## `BUCKET` [esql-bucket] - -**Syntax** - -:::{image} ../../../../../images/bucket.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Numeric or date expression from which to derive buckets. - -`buckets` -: Target number of buckets, or desired bucket size if `from` and `to` parameters are omitted. - -`from` -: Start of the range. Can be a number, a date or a date expressed as a string. - -`to` -: End of the range. Can be a number, a date or a date expressed as a string. - -**Description** - -Creates groups of values - buckets - out of a datetime or numeric input. The size of the buckets can either be provided directly, or chosen based on a recommended count and values range. - -**Supported types** - -| field | buckets | from | to | result | -| --- | --- | --- | --- | --- | -| date | date_period | | | date | -| date | integer | date | date | date | -| date | integer | date | keyword | date | -| date | integer | date | text | date | -| date | integer | keyword | date | date | -| date | integer | keyword | keyword | date | -| date | integer | keyword | text | date | -| date | integer | text | date | date | -| date | integer | text | keyword | date | -| date | integer | text | text | date | -| date | time_duration | | | date | -| date_nanos | date_period | | | date_nanos | -| date_nanos | integer | date | date | date_nanos | -| date_nanos | integer | date | keyword | date_nanos | -| date_nanos | integer | date | text | date_nanos | -| date_nanos | integer | keyword | date | date_nanos | -| date_nanos | integer | keyword | keyword | date_nanos | -| date_nanos | integer | keyword | text | date_nanos | -| date_nanos | integer | text | date | date_nanos | -| date_nanos | integer | text | keyword | date_nanos | -| date_nanos | integer | text | text | date_nanos | -| date_nanos | time_duration | | | date_nanos | -| double | double | | | double | -| double | integer | double | double | double | -| double | integer | double | integer | double | -| double | integer | double | long | double | -| double | integer | integer | double | double | -| double | integer | integer | integer | double | -| double | integer | integer | long | double | -| double | integer | long | double | double | -| double | integer | long | integer | double | -| double | integer | long | long | double | -| double | integer | | | double | -| double | long | | | double | -| integer | double | | | double | -| integer | integer | double | double | double | -| integer | integer | double | integer | double | -| integer | integer | double | long | double | -| integer | integer | integer | double | double | -| integer | integer | integer | integer | double | -| integer | integer | integer | long | double | -| integer | integer | long | double | double | -| integer | integer | long | integer | double | -| integer | integer | long | long | double | -| integer | integer | | | double | -| integer | long | | | double | -| long | double | | | double | -| long | integer | double | double | double | -| long | integer | double | integer | double | -| long | integer | double | long | double | -| long | integer | integer | double | double | -| long | integer | integer | integer | double | -| long | integer | integer | long | double | -| long | integer | long | double | double | -| long | integer | long | integer | double | -| long | integer | long | long | double | -| long | integer | | | double | -| long | long | | | double | - -**Examples** - -`BUCKET` can work in two modes: one in which the size of the bucket is computed based on a buckets count recommendation (four parameters) and a range, and another in which the bucket size is provided directly (two parameters). - -Using a target number of buckets, a start of a range, and an end of a range, `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: - -```esql -FROM employees -| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" -| STATS hire_date = MV_SORT(VALUES(hire_date)) BY month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z") -| SORT hire_date -``` - -| hire_date:date | month:date | -| --- | --- | -| [1985-02-18T00:00:00.000Z, 1985-02-24T00:00:00.000Z] | 1985-02-01T00:00:00.000Z | -| 1985-05-13T00:00:00.000Z | 1985-05-01T00:00:00.000Z | -| 1985-07-09T00:00:00.000Z | 1985-07-01T00:00:00.000Z | -| 1985-09-17T00:00:00.000Z | 1985-09-01T00:00:00.000Z | -| [1985-10-14T00:00:00.000Z, 1985-10-20T00:00:00.000Z] | 1985-10-01T00:00:00.000Z | -| [1985-11-19T00:00:00.000Z, 1985-11-20T00:00:00.000Z, 1985-11-21T00:00:00.000Z] | 1985-11-01T00:00:00.000Z | - -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. - -Combine `BUCKET` with an [aggregation](../../esql-functions-operators.md#esql-agg-functions) to create a histogram: - -```esql -FROM employees -| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" -| STATS hires_per_month = COUNT(*) BY month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z") -| SORT month -``` - -| hires_per_month:long | month:date | -| --- | --- | -| 2 | 1985-02-01T00:00:00.000Z | -| 1 | 1985-05-01T00:00:00.000Z | -| 1 | 1985-07-01T00:00:00.000Z | -| 1 | 1985-09-01T00:00:00.000Z | -| 2 | 1985-10-01T00:00:00.000Z | -| 4 | 1985-11-01T00:00:00.000Z | - -::::{note} -`BUCKET` does not create buckets that don’t match any documents. That’s why this example is missing `1985-03-01` and other dates. -:::: - - -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: - -```esql -FROM employees -| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" -| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 100, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z") -| SORT week -``` - -| hires_per_week:long | week:date | -| --- | --- | -| 2 | 1985-02-18T00:00:00.000Z | -| 1 | 1985-05-13T00:00:00.000Z | -| 1 | 1985-07-08T00:00:00.000Z | -| 1 | 1985-09-16T00:00:00.000Z | -| 2 | 1985-10-14T00:00:00.000Z | -| 4 | 1985-11-18T00:00:00.000Z | - -::::{note} -`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`BUCKET` with [`WHERE`](/reference/query-languages/esql/esql-commands.md#esql-where) to filter rows. -:::: - - -If the desired bucket size is known in advance, simply provide it as the second argument, leaving the range out: - -```esql -FROM employees -| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" -| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 1 week) -| SORT week -``` - -| hires_per_week:long | week:date | -| --- | --- | -| 2 | 1985-02-18T00:00:00.000Z | -| 1 | 1985-05-13T00:00:00.000Z | -| 1 | 1985-07-08T00:00:00.000Z | -| 1 | 1985-09-16T00:00:00.000Z | -| 2 | 1985-10-14T00:00:00.000Z | -| 4 | 1985-11-18T00:00:00.000Z | - -::::{note} -When providing the bucket size as the second parameter, it must be a time duration or date period. -:::: - - -`BUCKET` can also operate on numeric fields. For example, to create a salary histogram: - -```esql -FROM employees -| STATS COUNT(*) by bs = BUCKET(salary, 20, 25324, 74999) -| SORT bs -``` - -| COUNT(*):long | bs:double | -| --- | --- | -| 9 | 25000.0 | -| 9 | 30000.0 | -| 18 | 35000.0 | -| 11 | 40000.0 | -| 11 | 45000.0 | -| 10 | 50000.0 | -| 7 | 55000.0 | -| 9 | 60000.0 | -| 8 | 65000.0 | -| 8 | 70000.0 | - -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. - -The range can be omitted if the desired bucket size is known in advance. Simply provide it as the second argument: - -```esql -FROM employees -| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" -| STATS c = COUNT(1) BY b = BUCKET(salary, 5000.) -| SORT b -``` - -| c:long | b:double | -| --- | --- | -| 1 | 25000.0 | -| 1 | 30000.0 | -| 1 | 40000.0 | -| 2 | 45000.0 | -| 2 | 50000.0 | -| 1 | 55000.0 | -| 1 | 60000.0 | -| 1 | 65000.0 | -| 1 | 70000.0 | - -Create hourly buckets for the last 24 hours, and calculate the number of events per hour: - -```esql -FROM sample_data -| WHERE @timestamp >= NOW() - 1 day and @timestamp < NOW() -| STATS COUNT(*) BY bucket = BUCKET(@timestamp, 25, NOW() - 1 day, NOW()) -``` - -| COUNT(*):long | bucket:date | -| --- | --- | - -Create monthly buckets for the year 1985, and calculate the average salary by hiring month - -```esql -FROM employees -| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" -| STATS AVG(salary) BY bucket = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z") -| SORT bucket -``` - -| AVG(salary):double | bucket:date | -| --- | --- | -| 46305.0 | 1985-02-01T00:00:00.000Z | -| 44817.0 | 1985-05-01T00:00:00.000Z | -| 62405.0 | 1985-07-01T00:00:00.000Z | -| 49095.0 | 1985-09-01T00:00:00.000Z | -| 51532.0 | 1985-10-01T00:00:00.000Z | -| 54539.75 | 1985-11-01T00:00:00.000Z | - -`BUCKET` may be used in both the aggregating and grouping part of the [STATS …​ BY …​](/reference/query-languages/esql/esql-commands.md#esql-stats-by) command provided that in the aggregating part the function is referenced by an alias defined in the grouping part, or that it is invoked with the exact same expression: - -```esql -FROM employees -| STATS s1 = b1 + 1, s2 = BUCKET(salary / 1000 + 999, 50.) + 2 BY b1 = BUCKET(salary / 100 + 99, 50.), b2 = BUCKET(salary / 1000 + 999, 50.) -| SORT b1, b2 -| KEEP s1, b1, s2, b2 -``` - -| s1:double | b1:double | s2:double | b2:double | -| --- | --- | --- | --- | -| 351.0 | 350.0 | 1002.0 | 1000.0 | -| 401.0 | 400.0 | 1002.0 | 1000.0 | -| 451.0 | 450.0 | 1002.0 | 1000.0 | -| 501.0 | 500.0 | 1002.0 | 1000.0 | -| 551.0 | 550.0 | 1002.0 | 1000.0 | -| 601.0 | 600.0 | 1002.0 | 1000.0 | -| 601.0 | 600.0 | 1052.0 | 1050.0 | -| 651.0 | 650.0 | 1052.0 | 1050.0 | -| 701.0 | 700.0 | 1052.0 | 1050.0 | -| 751.0 | 750.0 | 1052.0 | 1050.0 | -| 801.0 | 800.0 | 1052.0 | 1050.0 | - -Sometimes you need to change the start value of each bucket by a given duration (similar to date histogram aggregation’s [`offset`](/reference/data-analysis/aggregations/search-aggregations-bucket-histogram-aggregation.md) parameter). To do so, you will need to take into account how the language handles expressions within the `STATS` command: if these contain functions or arithmetic operators, a virtual `EVAL` is inserted before and/or after the `STATS` command. Consequently, a double compensation is needed to adjust the bucketed date value before the aggregation and then again after. For instance, inserting a negative offset of `1 hour` to buckets of `1 year` looks like this: - -```esql -FROM employees -| STATS dates = MV_SORT(VALUES(birth_date)) BY b = BUCKET(birth_date + 1 HOUR, 1 YEAR) - 1 HOUR -| EVAL d_count = MV_COUNT(dates) -| SORT d_count, b -| LIMIT 3 -``` - -| dates:date | b:date | d_count:integer | -| --- | --- | --- | -| 1965-01-03T00:00:00.000Z | 1964-12-31T23:00:00.000Z | 1 | -| [1955-01-21T00:00:00.000Z, 1955-08-20T00:00:00.000Z, 1955-08-28T00:00:00.000Z, 1955-10-04T00:00:00.000Z] | 1954-12-31T23:00:00.000Z | 4 | -| [1957-04-04T00:00:00.000Z, 1957-05-23T00:00:00.000Z, 1957-05-25T00:00:00.000Z, 1957-12-03T00:00:00.000Z] | 1956-12-31T23:00:00.000Z | 4 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/byte_length.md b/docs/reference/query-languages/esql/_snippets/functions/byte_length.md deleted file mode 100644 index 74e24af309043..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/byte_length.md +++ /dev/null @@ -1,46 +0,0 @@ -## `BYTE_LENGTH` [esql-byte_length] - -**Syntax** - -:::{image} ../../../../../images/byte_length.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. If `null`, the function returns `null`. - -**Description** - -Returns the byte length of a string. - -::::{note} -All strings are in UTF-8, so a single character can use multiple bytes. -:::: - - -**Supported types** - -| string | result | -| --- | --- | -| keyword | integer | -| text | integer | - -**Example** - -```esql -FROM airports -| WHERE country == "India" -| KEEP city -| EVAL fn_length = LENGTH(city), fn_byte_length = BYTE_LENGTH(city) -``` - -| city:keyword | fn_length:integer | fn_byte_length:integer | -| --- | --- | --- | -| Agwār | 5 | 6 | -| Ahmedabad | 9 | 9 | -| Bangalore | 9 | 9 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/case.md b/docs/reference/query-languages/esql/_snippets/functions/case.md deleted file mode 100644 index 04b0da80aeab8..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/case.md +++ /dev/null @@ -1,113 +0,0 @@ -## `CASE` [esql-case] - -**Syntax** - -:::{image} ../../../../../images/case.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`condition` -: A condition. - -`trueValue` -: The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches. - -`elseValue` -: The value that’s returned when no condition evaluates to `true`. - -**Description** - -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. If the number of arguments is even, and no condition matches, the function returns `null`. - -**Supported types** - -| condition | trueValue | elseValue | result | -| --- | --- | --- | --- | -| boolean | boolean | boolean | boolean | -| boolean | boolean | | boolean | -| boolean | cartesian_point | cartesian_point | cartesian_point | -| boolean | cartesian_point | | cartesian_point | -| boolean | cartesian_shape | cartesian_shape | cartesian_shape | -| boolean | cartesian_shape | | cartesian_shape | -| boolean | date | date | date | -| boolean | date | | date | -| boolean | date_nanos | date_nanos | date_nanos | -| boolean | date_nanos | | date_nanos | -| boolean | double | double | double | -| boolean | double | | double | -| boolean | geo_point | geo_point | geo_point | -| boolean | geo_point | | geo_point | -| boolean | geo_shape | geo_shape | geo_shape | -| boolean | geo_shape | | geo_shape | -| boolean | integer | integer | integer | -| boolean | integer | | integer | -| boolean | ip | ip | ip | -| boolean | ip | | ip | -| boolean | keyword | keyword | keyword | -| boolean | keyword | text | keyword | -| boolean | keyword | | keyword | -| boolean | long | long | long | -| boolean | long | | long | -| boolean | text | keyword | keyword | -| boolean | text | text | keyword | -| boolean | text | | keyword | -| boolean | unsigned_long | unsigned_long | unsigned_long | -| boolean | unsigned_long | | unsigned_long | -| boolean | version | version | version | -| boolean | version | | version | - -**Examples** - -Determine whether employees are monolingual, bilingual, or polyglot: - -```esql -FROM employees -| EVAL type = CASE( - languages <= 1, "monolingual", - languages <= 2, "bilingual", - "polyglot") -| KEEP emp_no, languages, type -``` - -| emp_no:integer | languages:integer | type:keyword | -| --- | --- | --- | -| 10001 | 2 | bilingual | -| 10002 | 5 | polyglot | -| 10003 | 4 | polyglot | -| 10004 | 5 | polyglot | -| 10005 | 1 | monolingual | - -Calculate the total connection success rate based on log messages: - -```esql -FROM sample_data -| EVAL successful = CASE( - STARTS_WITH(message, "Connected to"), 1, - message == "Connection error", 0 - ) -| STATS success_rate = AVG(successful) -``` - -| success_rate:double | -| --- | -| 0.5 | - -Calculate an hourly error rate as a percentage of the total number of log messages: - -```esql -FROM sample_data -| EVAL error = CASE(message LIKE "*error*", 1, 0) -| EVAL hour = DATE_TRUNC(1 hour, @timestamp) -| STATS error_rate = AVG(error) by hour -| SORT hour -``` - -| error_rate:double | hour:date | -| --- | --- | -| 0.0 | 2023-10-23T12:00:00.000Z | -| 0.6 | 2023-10-23T13:00:00.000Z | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/categorize.md b/docs/reference/query-languages/esql/_snippets/functions/categorize.md deleted file mode 100644 index 4c4c09aa39192..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/categorize.md +++ /dev/null @@ -1,50 +0,0 @@ -## `CATEGORIZE` [esql-categorize] - -::::{warning} -Do not use 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. -:::: - - -**Syntax** - -:::{image} ../../../../../images/categorize.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Expression to categorize - -**Description** - -Groups text messages into categories of similarly formatted text values. - -`CATEGORIZE` has the following limitations: - -* can’t be used within other expressions -* can’t be used with multiple groupings -* can’t be used or referenced within aggregate functions - -**Supported types** - -| field | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -This example categorizes server logs messages into categories and aggregates their counts. - -```esql -FROM sample_data -| STATS count=COUNT() BY category=CATEGORIZE(message) -``` - -| count:long | category:keyword | -| --- | --- | -| 3 | .**?Connected.+?to.**? | -| 3 | .**?Connection.+?error.**? | -| 1 | .**?Disconnected.**? | diff --git a/docs/reference/query-languages/esql/_snippets/functions/cbrt.md b/docs/reference/query-languages/esql/_snippets/functions/cbrt.md deleted file mode 100644 index 09c6923b027cf..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/cbrt.md +++ /dev/null @@ -1,39 +0,0 @@ -## `CBRT` [esql-cbrt] - -**Syntax** - -:::{image} ../../../../../images/cbrt.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the cube root of a number. The input can be any numeric value, the return value is always a double. Cube roots of infinities are null. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW d = 1000.0 -| EVAL c = cbrt(d) -``` - -| d: double | c:double | -| --- | --- | -| 1000.0 | 10.0 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/ceil.md b/docs/reference/query-languages/esql/_snippets/functions/ceil.md deleted file mode 100644 index 9c56f8c5abd28..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/ceil.md +++ /dev/null @@ -1,44 +0,0 @@ -## `CEIL` [esql-ceil] - -**Syntax** - -:::{image} ../../../../../images/ceil.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: 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 [Math.ceil](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Math.md#ceil(double)). -:::: - - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | integer | -| long | long | -| unsigned_long | unsigned_long | - -**Example** - -```esql -ROW a=1.8 -| EVAL a=CEIL(a) -``` - -| a:double | -| --- | -| 2 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/cidr_match.md b/docs/reference/query-languages/esql/_snippets/functions/cidr_match.md deleted file mode 100644 index 3cb617306d4e7..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/cidr_match.md +++ /dev/null @@ -1,42 +0,0 @@ -## `CIDR_MATCH` [esql-cidr_match] - -**Syntax** - -:::{image} ../../../../../images/cidr_match.svg -:alt: Embedded -:class: text-center -::: - -**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. - -**Supported types** - -| ip | blockX | result | -| --- | --- | --- | -| ip | keyword | boolean | -| ip | text | boolean | - -**Example** - -```esql -FROM hosts -| WHERE CIDR_MATCH(ip1, "127.0.0.2/32", "127.0.0.3/32") -| KEEP card, host, ip0, ip1 -``` - -| card:keyword | host:keyword | ip0:ip | ip1:ip | -| --- | --- | --- | --- | -| eth1 | beta | 127.0.0.1 | 127.0.0.2 | -| eth0 | gamma | fe80::cae2:65ff:fece:feb9 | 127.0.0.3 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/coalesce.md b/docs/reference/query-languages/esql/_snippets/functions/coalesce.md deleted file mode 100644 index 1dfede94259cb..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/coalesce.md +++ /dev/null @@ -1,56 +0,0 @@ -## `COALESCE` [esql-coalesce] - -**Syntax** - -:::{image} ../../../../../images/coalesce.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`first` -: Expression to evaluate. - -`rest` -: Other expression to evaluate. - -**Description** - -Returns the first of its arguments that is not null. If all arguments are null, it returns `null`. - -**Supported types** - -| first | rest | result | -| --- | --- | --- | -| boolean | boolean | boolean | -| boolean | | boolean | -| cartesian_point | cartesian_point | cartesian_point | -| cartesian_shape | cartesian_shape | cartesian_shape | -| date | date | date | -| date_nanos | date_nanos | date_nanos | -| geo_point | geo_point | geo_point | -| geo_shape | geo_shape | geo_shape | -| integer | integer | integer | -| integer | | integer | -| ip | ip | ip | -| keyword | keyword | keyword | -| keyword | | keyword | -| long | long | long | -| long | | long | -| text | text | keyword | -| text | | keyword | -| version | version | version | - -**Example** - -```esql -ROW a=null, b="b" -| EVAL COALESCE(a, b) -``` - -| a:null | b:keyword | COALESCE(a, b):keyword | -| --- | --- | --- | -| null | b | b | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/concat.md b/docs/reference/query-languages/esql/_snippets/functions/concat.md deleted file mode 100644 index c48f803b291a4..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/concat.md +++ /dev/null @@ -1,45 +0,0 @@ -## `CONCAT` [esql-concat] - -**Syntax** - -:::{image} ../../../../../images/concat.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string1` -: Strings to concatenate. - -`string2` -: Strings to concatenate. - -**Description** - -Concatenates two or more strings. - -**Supported types** - -| string1 | string2 | result | -| --- | --- | --- | -| keyword | keyword | keyword | -| keyword | text | keyword | -| text | keyword | keyword | -| text | text | keyword | - -**Example** - -```esql -FROM employees -| KEEP first_name, last_name -| EVAL fullname = CONCAT(first_name, " ", last_name) -``` - -| first_name:keyword | last_name:keyword | fullname:keyword | -| --- | --- | --- | -| Alejandro | McAlpine | Alejandro McAlpine | -| Amabile | Gomatam | Amabile Gomatam | -| Anneke | Preusig | Anneke Preusig | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/cos.md b/docs/reference/query-languages/esql/_snippets/functions/cos.md deleted file mode 100644 index 518b4e45a2b21..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/cos.md +++ /dev/null @@ -1,39 +0,0 @@ -## `COS` [esql-cos] - -**Syntax** - -:::{image} ../../../../../images/cos.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`angle` -: An angle, in radians. If `null`, the function returns `null`. - -**Description** - -Returns the [cosine](https://en.wikipedia.org/wiki/Sine_and_cosine) of an angle. - -**Supported types** - -| angle | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=1.8 -| EVAL cos=COS(a) -``` - -| a:double | cos:double | -| --- | --- | -| 1.8 | -0.2272020946930871 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/cosh.md b/docs/reference/query-languages/esql/_snippets/functions/cosh.md deleted file mode 100644 index 2827fc4aeb78f..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/cosh.md +++ /dev/null @@ -1,39 +0,0 @@ -## `COSH` [esql-cosh] - -**Syntax** - -:::{image} ../../../../../images/cosh.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the [hyperbolic cosine](https://en.wikipedia.org/wiki/Hyperbolic_functions) of a number. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=1.8 -| EVAL cosh=COSH(a) -``` - -| a:double | cosh:double | -| --- | --- | -| 1.8 | 3.1074731763172667 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/count.md b/docs/reference/query-languages/esql/_snippets/functions/count.md deleted file mode 100644 index 1f88c3e496af2..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/count.md +++ /dev/null @@ -1,98 +0,0 @@ -## `COUNT` [esql-count] - -**Syntax** - -:::{image} ../../../../../images/count.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: 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** - -| field | result | -| --- | --- | -| boolean | long | -| cartesian_point | long | -| date | long | -| double | long | -| geo_point | long | -| integer | long | -| ip | long | -| keyword | long | -| long | long | -| text | long | -| unsigned_long | long | -| version | long | - -**Examples** - -```esql -FROM employees -| STATS COUNT(height) -``` - -| COUNT(height):long | -| --- | -| 100 | - -To count the number of rows, use `COUNT()` or `COUNT(*)` - -```esql -FROM employees -| STATS count = COUNT(*) BY languages -| SORT languages DESC -``` - -| count:long | languages:integer | -| --- | --- | -| 10 | null | -| 21 | 5 | -| 18 | 4 | -| 17 | 3 | -| 19 | 2 | -| 15 | 1 | - -The expression can use inline functions. This example splits a string into multiple values using the `SPLIT` function and counts the values - -```esql -ROW words="foo;bar;baz;qux;quux;foo" -| STATS word_count = COUNT(SPLIT(words, ";")) -``` - -| word_count:long | -| --- | -| 6 | - -To count the number of times an expression returns `TRUE` use a [`WHERE`](/reference/query-languages/esql/esql-commands.md#esql-where) command to remove rows that shouldn’t be included - -```esql -ROW n=1 -| WHERE n < 0 -| STATS COUNT(n) -``` - -| COUNT(n):long | -| --- | -| 0 | - -To count the same stream of data based on two different expressions use the pattern `COUNT( OR NULL)`. This builds on the three-valued logic ({{wikipedia}}/Three-valued_logic[3VL]) of the language: `TRUE OR NULL` is `TRUE`, but `FALSE OR NULL` is `NULL`, plus the way COUNT handles `NULL`s: `COUNT(TRUE)` and `COUNT(FALSE)` are both 1, but `COUNT(NULL)` is 0. - -```esql -ROW n=1 -| STATS COUNT(n > 0 OR NULL), COUNT(n < 0 OR NULL) -``` - -| COUNT(n > 0 OR NULL):long | COUNT(n < 0 OR NULL):long | -| --- | --- | -| 1 | 0 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/count_distinct.md b/docs/reference/query-languages/esql/_snippets/functions/count_distinct.md deleted file mode 100644 index bcfdb2c5129d9..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/count_distinct.md +++ /dev/null @@ -1,123 +0,0 @@ -## `COUNT_DISTINCT` [esql-count_distinct] - -**Syntax** - -:::{image} ../../../../../images/count_distinct.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Column or literal for which to count the number of distinct values. - -`precision` -: Precision threshold. Refer to [Counts are approximate](../../esql-functions-operators.md#esql-agg-count-distinct-approximate). 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** - -| field | precision | result | -| --- | --- | --- | -| boolean | integer | long | -| boolean | long | long | -| boolean | unsigned_long | long | -| boolean | | long | -| date | integer | long | -| date | long | long | -| date | unsigned_long | long | -| date | | long | -| date_nanos | integer | long | -| date_nanos | long | long | -| date_nanos | unsigned_long | long | -| date_nanos | | long | -| double | integer | long | -| double | long | long | -| double | unsigned_long | long | -| double | | long | -| integer | integer | long | -| integer | long | long | -| integer | unsigned_long | long | -| integer | | long | -| ip | integer | long | -| ip | long | long | -| ip | unsigned_long | long | -| ip | | long | -| keyword | integer | long | -| keyword | long | long | -| keyword | unsigned_long | long | -| keyword | | long | -| long | integer | long | -| long | long | long | -| long | unsigned_long | long | -| long | | long | -| text | integer | long | -| text | long | long | -| text | unsigned_long | long | -| text | | long | -| version | integer | long | -| version | long | long | -| version | unsigned_long | long | -| version | | long | - -**Examples** - -```esql -FROM hosts -| STATS COUNT_DISTINCT(ip0), COUNT_DISTINCT(ip1) -``` - -| COUNT_DISTINCT(ip0):long | COUNT_DISTINCT(ip1):long | -| --- | --- | -| 7 | 8 | - -With the optional second parameter to configure the precision threshold - -```esql -FROM hosts -| STATS COUNT_DISTINCT(ip0, 80000), COUNT_DISTINCT(ip1, 5) -``` - -| COUNT_DISTINCT(ip0, 80000):long | COUNT_DISTINCT(ip1, 5):long | -| --- | --- | -| 7 | 9 | - -The expression can use inline functions. This example splits a string into multiple values using the `SPLIT` function and counts the unique values - -```esql -ROW words="foo;bar;baz;qux;quux;foo" -| STATS distinct_word_count = COUNT_DISTINCT(SPLIT(words, ";")) -``` - -| distinct_word_count:long | -| --- | -| 5 | - - -### Counts are approximate [esql-agg-count-distinct-approximate] - -Computing exact counts requires loading values into a set and returning its size. This doesn’t scale when working on high-cardinality sets and/or large values as the required memory usage and the need to communicate those per-shard sets between nodes would utilize too many resources of the cluster. - -This `COUNT_DISTINCT` function is based on the [HyperLogLog++](https://static.googleusercontent.com/media/research.google.com/fr//pubs/archive/40671.pdf) algorithm, which counts based on the hashes of the values with some interesting properties: - -* configurable precision, which decides on how to trade memory for accuracy, -* excellent accuracy on low-cardinality sets, -* fixed memory usage: no matter if there are tens or billions of unique values, memory usage only depends on the configured precision. - -For a precision threshold of `c`, the implementation that we are using requires about `c * 8` bytes. - -The following chart shows how the error varies before and after the threshold: - -![cardinality error](/images/cardinality_error.png "") - -For all 3 thresholds, counts have been accurate up to the configured threshold. Although not guaranteed, this is likely to be the case. Accuracy in practice depends on the dataset in question. In general, most datasets show consistently good accuracy. Also note that even with a threshold as low as 100, the error remains very low (1-6% as seen in the above graph) even when counting millions of items. - -The HyperLogLog++ algorithm depends on the leading zeros of hashed values, the exact distributions of hashes in a dataset can affect the accuracy of the cardinality. - -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`. - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/date_diff.md b/docs/reference/query-languages/esql/_snippets/functions/date_diff.md deleted file mode 100644 index fa651f97eeb56..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/date_diff.md +++ /dev/null @@ -1,83 +0,0 @@ -## `DATE_DIFF` [esql-date_diff] - -**Syntax** - -:::{image} ../../../../../images/date_diff.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`unit` -: Time difference unit - -`startTimestamp` -: A string representing a start timestamp - -`endTimestamp` -: A string representing an 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. - -| Datetime difference units | -| --- | -| **unit** | **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 | - -Note that while there is an overlap between the function’s supported units and {{esql}}'s supported time span literals, these sets are distinct and not interchangeable. Similarly, the supported abbreviations are conveniently shared with implementations of this function in other established products and not necessarily common with the date-time nomenclature used by {{es}}. - -**Supported types** - -| unit | startTimestamp | endTimestamp | result | -| --- | --- | --- | --- | -| keyword | date | date | integer | -| keyword | date | date_nanos | integer | -| keyword | date_nanos | date | integer | -| keyword | date_nanos | date_nanos | integer | -| text | date | date | integer | -| text | date | date_nanos | integer | -| text | date_nanos | date | integer | -| text | date_nanos | date_nanos | integer | - -**Examples** - -```esql -ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), date2 = TO_DATETIME("2023-12-02T11:00:00.001Z") -| EVAL dd_ms = DATE_DIFF("microseconds", date1, date2) -``` - -| date1:date | date2:date | dd_ms:integer | -| --- | --- | --- | -| 2023-12-02T11:00:00.000Z | 2023-12-02T11:00:00.001Z | 1000 | - -When subtracting in calendar units - like year, month a.s.o. - only the fully elapsed units are counted. To avoid this and obtain also remainders, simply switch to the next smaller unit and do the date math accordingly. - -```esql -ROW end_23=TO_DATETIME("2023-12-31T23:59:59.999Z"), - start_24=TO_DATETIME("2024-01-01T00:00:00.000Z"), - end_24=TO_DATETIME("2024-12-31T23:59:59.999") -| EVAL end23_to_start24=DATE_DIFF("year", end_23, start_24) -| EVAL end23_to_end24=DATE_DIFF("year", end_23, end_24) -| EVAL start_to_end_24=DATE_DIFF("year", start_24, end_24) -``` - -| end_23:date | start_24:date | end_24:date | end23_to_start24:integer | end23_to_end24:integer | start_to_end_24:integer | -| --- | --- | --- | --- | --- | --- | -| 2023-12-31T23:59:59.999Z | 2024-01-01T00:00:00.000Z | 2024-12-31T23:59:59.999Z | 0 | 1 | 0 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/date_extract.md b/docs/reference/query-languages/esql/_snippets/functions/date_extract.md deleted file mode 100644 index dd25781311e61..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/date_extract.md +++ /dev/null @@ -1,52 +0,0 @@ -## `DATE_EXTRACT` [esql-date_extract] - -**Syntax** - -:::{image} ../../../../../images/date_extract.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`datePart` -: 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 [java.time.temporal.ChronoField](https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoField.md) 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. - -**Supported types** - -| datePart | date | result | -| --- | --- | --- | -| keyword | date | long | -| keyword | date_nanos | long | -| text | date | long | -| text | date_nanos | long | - -**Examples** - -```esql -ROW date = DATE_PARSE("yyyy-MM-dd", "2022-05-06") -| EVAL year = DATE_EXTRACT("year", date) -``` - -| date:date | year:long | -| --- | --- | -| 2022-05-06T00:00:00.000Z | 2022 | - -Find all events that occurred outside of business hours (before 9 AM or after 5PM), on any given date: - -```esql -FROM sample_data -| WHERE DATE_EXTRACT("hour_of_day", @timestamp) < 9 AND DATE_EXTRACT("hour_of_day", @timestamp) >= 17 -``` - -| @timestamp:date | client_ip:ip | event_duration:long | message:keyword | -| --- | --- | --- | --- | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/date_format.md b/docs/reference/query-languages/esql/_snippets/functions/date_format.md deleted file mode 100644 index 28385f98fa3df..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/date_format.md +++ /dev/null @@ -1,47 +0,0 @@ -## `DATE_FORMAT` [esql-date_format] - -**Syntax** - -:::{image} ../../../../../images/date_format.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`dateFormat` -: 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. - -**Supported types** - -| dateFormat | date | result | -| --- | --- | --- | -| date | | keyword | -| date_nanos | | keyword | -| keyword | date | keyword | -| keyword | date_nanos | keyword | -| text | date | keyword | -| text | date_nanos | keyword | - -**Example** - -```esql -FROM employees -| KEEP first_name, last_name, hire_date -| EVAL hired = DATE_FORMAT("yyyy-MM-dd", hire_date) -``` - -| first_name:keyword | last_name:keyword | hire_date:date | hired:keyword | -| --- | --- | --- | --- | -| Alejandro | McAlpine | 1991-06-26T00:00:00.000Z | 1991-06-26 | -| Amabile | Gomatam | 1992-11-18T00:00:00.000Z | 1992-11-18 | -| Anneke | Preusig | 1989-06-02T00:00:00.000Z | 1989-06-02 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/date_parse.md b/docs/reference/query-languages/esql/_snippets/functions/date_parse.md deleted file mode 100644 index d3af20f699500..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/date_parse.md +++ /dev/null @@ -1,42 +0,0 @@ -## `DATE_PARSE` [esql-date_parse] - -**Syntax** - -:::{image} ../../../../../images/date_parse.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`datePattern` -: The date format. Refer to the [`DateTimeFormatter` documentation](https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.md) for the syntax. If `null`, the function returns `null`. - -`dateString` -: Date expression as a string. If `null` or an empty string, the function returns `null`. - -**Description** - -Returns a date by parsing the second argument using the format specified in the first argument. - -**Supported types** - -| datePattern | dateString | result | -| --- | --- | --- | -| keyword | keyword | date | -| keyword | text | date | -| text | keyword | date | -| text | text | date | - -**Example** - -```esql -ROW date_string = "2022-05-06" -| EVAL date = DATE_PARSE("yyyy-MM-dd", date_string) -``` - -| date_string:keyword | date:date | -| --- | --- | -| 2022-05-06 | 2022-05-06T00:00:00.000Z | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/date_trunc.md b/docs/reference/query-languages/esql/_snippets/functions/date_trunc.md deleted file mode 100644 index 1245e452ee739..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/date_trunc.md +++ /dev/null @@ -1,86 +0,0 @@ -## `DATE_TRUNC` [esql-date_trunc] - -**Syntax** - -:::{image} ../../../../../images/date_trunc.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`interval` -: Interval; expressed using the timespan literal syntax. - -`date` -: Date expression - -**Description** - -Rounds down a date to the closest interval. - -**Supported types** - -| interval | date | result | -| --- | --- | --- | -| date_period | date | date | -| date_period | date_nanos | date_nanos | -| time_duration | date | date | -| time_duration | date_nanos | date_nanos | - -**Examples** - -```esql -FROM employees -| KEEP first_name, last_name, hire_date -| EVAL year_hired = DATE_TRUNC(1 year, hire_date) -``` - -| first_name:keyword | last_name:keyword | hire_date:date | year_hired:date | -| --- | --- | --- | --- | -| Alejandro | McAlpine | 1991-06-26T00:00:00.000Z | 1991-01-01T00:00:00.000Z | -| Amabile | Gomatam | 1992-11-18T00:00:00.000Z | 1992-01-01T00:00:00.000Z | -| Anneke | Preusig | 1989-06-02T00:00:00.000Z | 1989-01-01T00:00:00.000Z | - -Combine `DATE_TRUNC` with [`STATS`](/reference/query-languages/esql/esql-commands.md#esql-stats-by) to create date histograms. For example, the number of hires per year: - -```esql -FROM employees -| EVAL year = DATE_TRUNC(1 year, hire_date) -| STATS hires = COUNT(emp_no) BY year -| SORT year -``` - -| hires:long | year:date | -| --- | --- | -| 11 | 1985-01-01T00:00:00.000Z | -| 11 | 1986-01-01T00:00:00.000Z | -| 15 | 1987-01-01T00:00:00.000Z | -| 9 | 1988-01-01T00:00:00.000Z | -| 13 | 1989-01-01T00:00:00.000Z | -| 12 | 1990-01-01T00:00:00.000Z | -| 6 | 1991-01-01T00:00:00.000Z | -| 8 | 1992-01-01T00:00:00.000Z | -| 3 | 1993-01-01T00:00:00.000Z | -| 4 | 1994-01-01T00:00:00.000Z | -| 5 | 1995-01-01T00:00:00.000Z | -| 1 | 1996-01-01T00:00:00.000Z | -| 1 | 1997-01-01T00:00:00.000Z | -| 1 | 1999-01-01T00:00:00.000Z | - -Or an hourly error rate: - -```esql -FROM sample_data -| EVAL error = CASE(message LIKE "*error*", 1, 0) -| EVAL hour = DATE_TRUNC(1 hour, @timestamp) -| STATS error_rate = AVG(error) by hour -| SORT hour -``` - -| error_rate:double | hour:date | -| --- | --- | -| 0.0 | 2023-10-23T12:00:00.000Z | -| 0.6 | 2023-10-23T13:00:00.000Z | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/ceil.md b/docs/reference/query-languages/esql/_snippets/functions/description/ceil.md index 192b7a0ab0a18..294f5c0f20f4b 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/ceil.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/ceil.md @@ -5,7 +5,7 @@ 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 [Math.ceil](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Math.md#ceil(double)). +This is a noop for `long` (including unsigned) and `integer`. For `double` this picks the closest `double` value to the integer similar to [Math.ceil](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Math.html#ceil(double)). :::: diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/date_diff.md b/docs/reference/query-languages/esql/_snippets/functions/description/date_diff.md index 10ca516f9196e..4c674e2606f15 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/date_diff.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/date_diff.md @@ -4,9 +4,10 @@ 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. -| Datetime difference units | -| --- | -| **unit** | **abbreviations** | +**Datetime difference units** + +| unit | abbreviations | +| --- | --- | | year | years, yy, yyyy | | quarter | quarters, qq, q | | month | months, mm, m | @@ -21,5 +22,9 @@ Subtracts the `startTimestamp` from the `endTimestamp` and returns the differenc | microsecond | microseconds, mcs | | nanosecond | nanoseconds, ns | -Note that while there is an overlap between the function’s supported units and {{esql}}'s supported time span literals, these sets are distinct and not interchangeable. Similarly, the supported abbreviations are conveniently shared with implementations of this function in other established products and not necessarily common with the date-time nomenclature used by {{es}}. +Note that while there is an overlap between the function’s supported units and +{{esql}}’s supported time span literals, these sets are distinct and not +interchangeable. Similarly, the supported abbreviations are conveniently shared +with implementations of this function in other established products and not +necessarily common with the date-time nomenclature used by {{es}}. diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/floor.md b/docs/reference/query-languages/esql/_snippets/functions/description/floor.md index 101b5c9874202..a959d4d69392d 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/floor.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/floor.md @@ -5,7 +5,9 @@ Round 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 [Math.floor](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Math.md#floor(double)). +This is a noop for `long` (including unsigned) and `integer`. +For `double` this picks the closest `double` value to the integer +similar to [Math.floor](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Math.html#floor(double)). :::: diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/greatest.md b/docs/reference/query-languages/esql/_snippets/functions/description/greatest.md index 7a4141c94e62a..11ae376911432 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/greatest.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/greatest.md @@ -2,7 +2,7 @@ **Description** -Returns the maximum value from multiple columns. This is similar to [`MV_MAX`](../../../esql-functions-operators.md#esql-mv_max) except it is intended to run on multiple columns at once. +Returns the maximum value from multiple columns. This is similar to [`MV_MAX`](/reference/query-languages/esql/esql-functions-operators.md#esql-mv_max) 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`. diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/least.md b/docs/reference/query-languages/esql/_snippets/functions/description/least.md index e82bb5b5380e6..6ca296474d39e 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/least.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/least.md @@ -2,5 +2,5 @@ **Description** -Returns the minimum value from multiple columns. This is similar to [`MV_MIN`](../../../esql-functions-operators.md#esql-mv_min) except it is intended to run on multiple columns at once. +Returns the minimum value from multiple columns. This is similar to [`MV_MIN`](/reference/query-languages/esql/esql-functions-operators.md#esql-mv_min) except it is intended to run on multiple columns at once. diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/match.md b/docs/reference/query-languages/esql/_snippets/functions/description/match.md index 53b4e329a7205..3264a5696ba2a 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/match.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/match.md @@ -2,5 +2,5 @@ **Description** -Use `MATCH` to perform a [match query](/reference/query-languages/query-dsl-match-query.md) on the specified field. Using `MATCH` is equivalent to using the `match` query in the Elasticsearch Query DSL. Match can be used on fields from the text family like [text](/reference/elasticsearch/mapping-reference/text.md) and [semantic_text](/reference/elasticsearch/mapping-reference/semantic-text.md), as well as other field types like keyword, boolean, dates, and numeric types. Match can use [function named parameters](/reference/query-languages/esql/esql-syntax.md#esql-function-named-params) to specify additional options for the match query. All [match query parameters](/reference/query-languages/query-dsl-match-query.md#match-field-params) are supported. For a simplified syntax, you can use the [match operator](../../../esql-functions-operators.md#esql-search-operators) `:` operator instead of `MATCH`. `MATCH` returns true if the provided query matches the row. +Use `MATCH` to perform a [match query](/reference/query-languages/query-dsl-match-query.md) on the specified field. Using `MATCH` is equivalent to using the `match` query in the Elasticsearch Query DSL. Match can be used on fields from the text family like [text](/reference/elasticsearch/mapping-reference/text.md) and [semantic_text](/reference/elasticsearch/mapping-reference/semantic-text.md), as well as other field types like keyword, boolean, dates, and numeric types. Match can use [function named parameters](/reference/query-languages/esql/esql-syntax.md#esql-function-named-params) to specify additional options for the match query. All [match query parameters](/reference/query-languages/query-dsl-match-query.md#match-field-params) are supported. For a simplified syntax, you can use the [match operator](/reference/query-languages/esql/esql-functions-operators.md#esql-search-operators) `:` operator instead of `MATCH`. `MATCH` returns true if the provided query matches the row. diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/median.md b/docs/reference/query-languages/esql/_snippets/functions/description/median.md index b9df7111fab4f..29560cc83688f 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/median.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/median.md @@ -2,10 +2,10 @@ **Description** -The value that is greater than half of all values and less than half of all values, also known as the 50% [`PERCENTILE`](../../../esql-functions-operators.md#esql-percentile). +The value that is greater than half of all values and less than half of all values, also known as the 50% [`PERCENTILE`](/reference/query-languages/esql/esql-functions-operators.md#esql-percentile). ::::{note} -Like [`PERCENTILE`](../../../esql-functions-operators.md#esql-percentile), `MEDIAN` is [usually approximate](../../../esql-functions-operators.md#esql-percentile-approximate). +Like [`PERCENTILE`](/reference/query-languages/esql/esql-functions-operators.md#esql-percentile), `MEDIAN` is [usually approximate](/reference/query-languages/esql/esql-functions-operators.md#esql-percentile-approximate). :::: diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/median_absolute_deviation.md b/docs/reference/query-languages/esql/_snippets/functions/description/median_absolute_deviation.md index 433b79a232603..df5bed3c82e71 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/median_absolute_deviation.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/median_absolute_deviation.md @@ -5,7 +5,7 @@ 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 [`PERCENTILE`](../../../esql-functions-operators.md#esql-percentile), `MEDIAN_ABSOLUTE_DEVIATION` is [usually approximate](../../../esql-functions-operators.md#esql-percentile-approximate). +Like [`PERCENTILE`](/reference/query-languages/esql/esql-functions-operators.md#esql-percentile), `MEDIAN_ABSOLUTE_DEVIATION` is [usually approximate](/reference/query-languages/esql/esql-functions-operators.md#esql-percentile-approximate). :::: diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/mv_first.md b/docs/reference/query-languages/esql/_snippets/functions/description/mv_first.md index 9b8fc3346b56e..2a943472f6c4f 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/mv_first.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/mv_first.md @@ -2,7 +2,11 @@ **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 [`SPLIT`](../../../esql-functions-operators.md#esql-split). +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 [`SPLIT`](/reference/query-languages/esql/esql-functions-operators.md#esql-split). -The order that [multivalued fields](/reference/query-languages/esql/esql-multivalued-fields.md) 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 [`MV_MIN`](../../../esql-functions-operators.md#esql-mv_min) instead of `MV_FIRST`. `MV_MIN` has optimizations for sorted values so there isn’t a performance benefit to `MV_FIRST`. +The order that [multivalued fields](/reference/query-languages/esql/esql-multivalued-fields.md) 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 [`MV_MIN`](/reference/query-languages/esql/esql-functions-operators.md#esql-mv_min) instead of +`MV_FIRST`. `MV_MIN` has optimizations for sorted values so there isn’t a +performance benefit to `MV_FIRST`. diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/mv_last.md b/docs/reference/query-languages/esql/_snippets/functions/description/mv_last.md index 0a8adc7d96867..365a0d5f34cad 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/mv_last.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/mv_last.md @@ -2,7 +2,11 @@ **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 [`SPLIT`](../../../esql-functions-operators.md#esql-split). +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 [`SPLIT`](/reference/query-languages/esql/esql-functions-operators.md#esql-split). -The order that [multivalued fields](/reference/query-languages/esql/esql-multivalued-fields.md) 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 [`MV_MAX`](../../../esql-functions-operators.md#esql-mv_max) instead of `MV_LAST`. `MV_MAX` has optimizations for sorted values so there isn’t a performance benefit to `MV_LAST`. +The order that [multivalued fields](/reference/query-languages/esql/esql-multivalued-fields.md) 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 [`MV_MAX`](/reference/query-languages/esql/esql-functions-operators.md#esql-mv_max) instead of +`MV_LAST`. `MV_MAX` has optimizations for sorted values so there isn’t a +performance benefit to `MV_LAST`. diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/mv_slice.md b/docs/reference/query-languages/esql/_snippets/functions/description/mv_slice.md index eff8d3bf9233d..b70d4ed70c1be 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/mv_slice.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/mv_slice.md @@ -2,7 +2,9 @@ **Description** -Returns a subset of the multivalued field using the start and end index values. This is most useful when reading from a function that emits multivalued columns in a known order like [`SPLIT`](../../../esql-functions-operators.md#esql-split) or [`MV_SORT`](../../../esql-functions-operators.md#esql-mv_sort). +Returns a subset of the multivalued field using the start and end index values. This is most useful when reading from a function that emits multivalued columns in a known order like [`SPLIT`](/reference/query-languages/esql/esql-functions-operators.md#esql-split) or [`MV_SORT`](/reference/query-languages/esql/esql-functions-operators.md#esql-mv_sort). -The order that [multivalued fields](/reference/query-languages/esql/esql-multivalued-fields.md) are read from underlying storage is not guaranteed. It is **frequently** ascending, but don’t rely on that. +The order that [multivalued fields](/reference/query-languages/esql/esql-multivalued-fields.md) are read from +underlying storage is not guaranteed. It is **frequently** ascending, but don’t +rely on that. diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/st_contains.md b/docs/reference/query-languages/esql/_snippets/functions/description/st_contains.md index 37cf894d125c4..ffda3085adfe9 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/st_contains.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/st_contains.md @@ -2,5 +2,5 @@ **Description** -Returns whether the first geometry contains the second geometry. This is the inverse of the [ST_WITHIN](../../../esql-functions-operators.md#esql-st_within) function. +Returns whether the first geometry contains the second geometry. This is the inverse of the [ST_WITHIN](/reference/query-languages/esql/esql-functions-operators.md#esql-st_within) function. diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/st_disjoint.md b/docs/reference/query-languages/esql/_snippets/functions/description/st_disjoint.md index d86e6d113e61c..7741a25e2e44a 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/st_disjoint.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/st_disjoint.md @@ -2,5 +2,5 @@ **Description** -Returns whether the two geometries or geometry columns are disjoint. This is the inverse of the [ST_INTERSECTS](../../../esql-functions-operators.md#esql-st_intersects) function. In mathematical terms: ST_Disjoint(A, B) ⇔ A ⋂ B = ∅ +Returns whether the two geometries or geometry columns are disjoint. This is the inverse of the [ST_INTERSECTS](/reference/query-languages/esql/esql-functions-operators.md#esql-st_intersects) function. In mathematical terms: ST_Disjoint(A, B) ⇔ A ⋂ B = ∅ diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/st_intersects.md b/docs/reference/query-languages/esql/_snippets/functions/description/st_intersects.md index 7b651db5e02d3..9a7ed9ad6b418 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/st_intersects.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/st_intersects.md @@ -2,5 +2,5 @@ **Description** -Returns true if two geometries intersect. They intersect if they have any point in common, including their interior points (points along lines or within polygons). This is the inverse of the [ST_DISJOINT](../../../esql-functions-operators.md#esql-st_disjoint) function. In mathematical terms: ST_Intersects(A, B) ⇔ A ⋂ B ≠ ∅ +Returns true if two geometries intersect. They intersect if they have any point in common, including their interior points (points along lines or within polygons). This is the inverse of the [ST_DISJOINT](/reference/query-languages/esql/esql-functions-operators.md#esql-st_disjoint) function. In mathematical terms: ST_Intersects(A, B) ⇔ A ⋂ B ≠ ∅ diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/st_within.md b/docs/reference/query-languages/esql/_snippets/functions/description/st_within.md index 8037b47995f5a..3e6b0f2a615f1 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/st_within.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/st_within.md @@ -2,5 +2,5 @@ **Description** -Returns whether the first geometry is within the second geometry. This is the inverse of the [ST_CONTAINS](../../../esql-functions-operators.md#esql-st_contains) function. +Returns whether the first geometry is within the second geometry. This is the inverse of the [ST_CONTAINS](/reference/query-languages/esql/esql-functions-operators.md#esql-st_contains) function. diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/term.md b/docs/reference/query-languages/esql/_snippets/functions/description/term.md new file mode 100644 index 0000000000000..1e09b5fcedff0 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/functions/description/term.md @@ -0,0 +1,6 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +**Description** + +Performs a Term query on the specified field. Returns true if the provided term matches the row. + diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/to_boolean.md b/docs/reference/query-languages/esql/_snippets/functions/description/to_boolean.md index 2096073fca9a1..88b59106d8d9c 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/to_boolean.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/to_boolean.md @@ -2,5 +2,5 @@ **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**. The numerical value of **0** will be converted to **false**, anything else will be converted to **true**. +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`. The numerical value of `0` will be converted to `false`, anything else will be converted to `true`. diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/to_datetime.md b/docs/reference/query-languages/esql/_snippets/functions/description/to_datetime.md index 137594466b60d..3737d7899b427 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/to_datetime.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/to_datetime.md @@ -2,7 +2,7 @@ **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 [`DATE_PARSE`](../../../esql-functions-operators.md#esql-date_parse). +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 [`DATE_PARSE`](/reference/query-languages/esql/esql-functions-operators.md#esql-date_parse). ::::{note} Note that when converting from nanosecond resolution to millisecond resolution with this function, the nanosecond date is truncated, not rounded. diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/to_double.md b/docs/reference/query-languages/esql/_snippets/functions/description/to_double.md index 7582d3e1e20db..8203611cac25d 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/to_double.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/to_double.md @@ -2,5 +2,5 @@ **Description** -Converts an input value to a double value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to double. Boolean **true** will be converted to double **1.0**, **false** to **0.0**. +Converts an input value to a double value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to double. Boolean `true` will be converted to double `1.0`, `false` to `0.0`. diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/to_integer.md b/docs/reference/query-languages/esql/_snippets/functions/description/to_integer.md index aa074b5de6a3f..95627993ec00b 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/to_integer.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/to_integer.md @@ -2,5 +2,5 @@ **Description** -Converts an input value to an integer value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to integer. Boolean **true** will be converted to integer **1**, **false** to **0**. +Converts an input value to an integer value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to integer. Boolean `true` will be converted to integer `1`, `false` to `0`. diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/to_long.md b/docs/reference/query-languages/esql/_snippets/functions/description/to_long.md index 49bdbcce30ea8..f5650004c61eb 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/to_long.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/to_long.md @@ -2,5 +2,5 @@ **Description** -Converts an input value to a long value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to long. Boolean **true** will be converted to long **1**, **false** to **0**. +Converts an input value to a long value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to long. Boolean `true` will be converted to long `1`, `false` to `0`. diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/to_unsigned_long.md b/docs/reference/query-languages/esql/_snippets/functions/description/to_unsigned_long.md index 2fc55efd2a71c..544956c24bf04 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/to_unsigned_long.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/to_unsigned_long.md @@ -2,5 +2,5 @@ **Description** -Converts an input value to an unsigned long value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to unsigned long. Boolean **true** will be converted to unsigned long **1**, **false** to **0**. +Converts an input value to an unsigned long value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to unsigned long. Boolean `true` will be converted to unsigned long `1`, `false` to `0`. diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/values.md b/docs/reference/query-languages/esql/_snippets/functions/description/values.md index b2e311d75d3d9..246b3d79b0488 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/values.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/values.md @@ -2,5 +2,5 @@ **Description** -Returns all values in a group as a multivalued field. The order of the returned values isn’t guaranteed. If you need the values returned in order use [`MV_SORT`](../../../esql-functions-operators.md#esql-mv_sort). +Returns all values in a group as a multivalued field. The order of the returned values isn’t guaranteed. If you need the values returned in order use [`MV_SORT`](/reference/query-languages/esql/esql-functions-operators.md#esql-mv_sort). diff --git a/docs/reference/query-languages/esql/_snippets/functions/e.md b/docs/reference/query-languages/esql/_snippets/functions/e.md deleted file mode 100644 index 08d233cc0cbc8..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/e.md +++ /dev/null @@ -1,32 +0,0 @@ -## `E` [esql-e] - -**Syntax** - -:::{image} ../../../../../images/e.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -**Description** - -Returns [Euler’s number](https://en.wikipedia.org/wiki/E_(mathematical_constant)). - -**Supported types** - -| result | -| --- | -| double | - -**Example** - -```esql -ROW E() -``` - -| E():double | -| --- | -| 2.718281828459045 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/ends_with.md b/docs/reference/query-languages/esql/_snippets/functions/ends_with.md deleted file mode 100644 index 7ea1c1bd36a1c..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/ends_with.md +++ /dev/null @@ -1,47 +0,0 @@ -## `ENDS_WITH` [esql-ends_with] - -**Syntax** - -:::{image} ../../../../../images/ends_with.svg -:alt: Embedded -:class: text-center -::: - -**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. - -**Supported types** - -| str | suffix | result | -| --- | --- | --- | -| keyword | keyword | boolean | -| keyword | text | boolean | -| text | keyword | boolean | -| text | text | boolean | - -**Example** - -```esql -FROM employees -| KEEP last_name -| EVAL ln_E = ENDS_WITH(last_name, "d") -``` - -| last_name:keyword | ln_E:boolean | -| --- | --- | -| Awdeh | false | -| Azuma | false | -| Baek | false | -| Bamford | true | -| Bernatsky | false | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/bucket.md b/docs/reference/query-languages/esql/_snippets/functions/examples/bucket.md index 09563afc220eb..817dadf0467dc 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/bucket.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/bucket.md @@ -2,9 +2,13 @@ **Examples** -`BUCKET` can work in two modes: one in which the size of the bucket is computed based on a buckets count recommendation (four parameters) and a range, and another in which the bucket size is provided directly (two parameters). +`BUCKET` can work in two modes: one in which the size of the bucket is computed +based on a buckets count recommendation (four parameters) and a range, and +another in which the bucket size is provided directly (two parameters). -Using a target number of buckets, a start of a range, and an end of a range, `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: +Using a target number of buckets, a start of a range, and an end of a range, +`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: ```esql FROM employees @@ -22,9 +26,11 @@ FROM employees | [1985-10-14T00:00:00.000Z, 1985-10-20T00:00:00.000Z] | 1985-10-01T00:00:00.000Z | | [1985-11-19T00:00:00.000Z, 1985-11-20T00:00:00.000Z, 1985-11-21T00:00:00.000Z] | 1985-11-01T00:00:00.000Z | -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. -Combine `BUCKET` with an [aggregation](../../../esql-functions-operators.md#esql-agg-functions) to create a histogram: +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. + +Combine `BUCKET` with an [aggregation](/reference/query-languages/esql/esql-functions-operators.md#esql-agg-functions) to create a histogram: ```esql FROM employees @@ -42,12 +48,14 @@ FROM employees | 2 | 1985-10-01T00:00:00.000Z | | 4 | 1985-11-01T00:00:00.000Z | + ::::{note} -`BUCKET` does not create buckets that don’t match any documents. That’s why this example is missing `1985-03-01` and other dates. +`BUCKET` does not create buckets that don’t match any documents. +That’s why this example is missing `1985-03-01` and other dates. :::: - -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: +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: ```esql FROM employees @@ -65,12 +73,15 @@ FROM employees | 2 | 1985-10-14T00:00:00.000Z | | 4 | 1985-11-18T00:00:00.000Z | + ::::{note} -`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`BUCKET` with [`WHERE`](/reference/query-languages/esql/esql-commands.md#esql-where) to filter rows. +`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 `BUCKET` with [`WHERE`](/reference/query-languages/esql/esql-commands.md#esql-where) to filter rows. :::: - -If the desired bucket size is known in advance, simply provide it as the second argument, leaving the range out: +If the desired bucket size is known in advance, simply provide it as the second +argument, leaving the range out: ```esql FROM employees @@ -88,11 +99,12 @@ FROM employees | 2 | 1985-10-14T00:00:00.000Z | | 4 | 1985-11-18T00:00:00.000Z | + ::::{note} -When providing the bucket size as the second parameter, it must be a time duration or date period. +When providing the bucket size as the second parameter, it must be a time +duration or date period. :::: - `BUCKET` can also operate on numeric fields. For example, to create a salary histogram: ```esql @@ -114,9 +126,12 @@ FROM employees | 8 | 65000.0 | | 8 | 70000.0 | -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. -The range can be omitted if the desired bucket size is known in advance. Simply provide it as the second argument: +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. + +The range can be omitted if the desired bucket size is known in advance. Simply +provide it as the second argument: ```esql FROM employees @@ -166,7 +181,10 @@ FROM employees | 51532.0 | 1985-10-01T00:00:00.000Z | | 54539.75 | 1985-11-01T00:00:00.000Z | -`BUCKET` may be used in both the aggregating and grouping part of the [STATS …​ BY …​](/reference/query-languages/esql/esql-commands.md#esql-stats-by) command provided that in the aggregating part the function is referenced by an alias defined in the grouping part, or that it is invoked with the exact same expression: +`BUCKET` may be used in both the aggregating and grouping part of the +[STATS ... BY ...](/reference/query-languages/esql/esql-commands.md#esql-stats-by) command provided that in the aggregating +part the function is referenced by an alias defined in the +grouping part, or that it is invoked with the exact same expression: ```esql FROM employees @@ -189,7 +207,12 @@ FROM employees | 751.0 | 750.0 | 1052.0 | 1050.0 | | 801.0 | 800.0 | 1052.0 | 1050.0 | -Sometimes you need to change the start value of each bucket by a given duration (similar to date histogram aggregation’s [`offset`](/reference/data-analysis/aggregations/search-aggregations-bucket-histogram-aggregation.md) parameter). To do so, you will need to take into account how the language handles expressions within the `STATS` command: if these contain functions or arithmetic operators, a virtual `EVAL` is inserted before and/or after the `STATS` command. Consequently, a double compensation is needed to adjust the bucketed date value before the aggregation and then again after. For instance, inserting a negative offset of `1 hour` to buckets of `1 year` looks like this: +Sometimes you need to change the start value of each bucket by a given duration (similar to date histogram +aggregation’s [`offset`](/reference/data-analysis/aggregations/search-aggregations-bucket-histogram-aggregation.md) parameter). To do so, you will need to +take into account how the language handles expressions within the `STATS` command: if these contain functions or +arithmetic operators, a virtual `EVAL` is inserted before and/or after the `STATS` command. Consequently, a double +compensation is needed to adjust the bucketed date value before the aggregation and then again after. For instance, +inserting a negative offset of `1 hour` to buckets of `1 year` looks like this: ```esql FROM employees diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/categorize.md b/docs/reference/query-languages/esql/_snippets/functions/examples/categorize.md index a985eecacd918..07b6ea37f7793 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/categorize.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/categorize.md @@ -11,6 +11,8 @@ FROM sample_data | count:long | category:keyword | | --- | --- | -| 3 | .**?Connected.+?to.**? | -| 3 | .**?Connection.+?error.**? | -| 1 | .**?Disconnected.**? | +| 3 | .\*?Connected.+?to.\*? | +| 3 | .\*?Connection.+?error.\*? | +| 1 | .\*?Disconnected.\*? | + + diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/count.md b/docs/reference/query-languages/esql/_snippets/functions/examples/count.md index c29ac673ed8b5..9ad53de6570ed 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/count.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/count.md @@ -51,7 +51,7 @@ ROW n=1 | --- | | 0 | -To count the same stream of data based on two different expressions use the pattern `COUNT( OR NULL)`. This builds on the three-valued logic ({{wikipedia}}/Three-valued_logic[3VL]) of the language: `TRUE OR NULL` is `TRUE`, but `FALSE OR NULL` is `NULL`, plus the way COUNT handles `NULL`s: `COUNT(TRUE)` and `COUNT(FALSE)` are both 1, but `COUNT(NULL)` is 0. +To count the same stream of data based on two different expressions use the pattern `COUNT( OR NULL)`. This builds on the three-valued logic ([3VL](https://en.wikipedia.org/wiki/Three-valued_logic)) of the language: `TRUE OR NULL` is `TRUE`, but `FALSE OR NULL` is `NULL`, plus the way COUNT handles `NULL`s: `COUNT(TRUE)` and `COUNT(FALSE)` are both 1, but `COUNT(NULL)` is 0. ```esql ROW n=1 diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/count_distinct.md b/docs/reference/query-languages/esql/_snippets/functions/examples/count_distinct.md index 96a28514c66dc..c6b0b11c21a69 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/count_distinct.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/count_distinct.md @@ -34,26 +34,3 @@ ROW words="foo;bar;baz;qux;quux;foo" | 5 | -### Counts are approximate [esql-agg-count-distinct-approximate] - -Computing exact counts requires loading values into a set and returning its size. This doesn’t scale when working on high-cardinality sets and/or large values as the required memory usage and the need to communicate those per-shard sets between nodes would utilize too many resources of the cluster. - -This `COUNT_DISTINCT` function is based on the [HyperLogLog++](https://static.googleusercontent.com/media/research.google.com/fr//pubs/archive/40671.pdf) algorithm, which counts based on the hashes of the values with some interesting properties: - -* configurable precision, which decides on how to trade memory for accuracy, -* excellent accuracy on low-cardinality sets, -* fixed memory usage: no matter if there are tens or billions of unique values, memory usage only depends on the configured precision. - -For a precision threshold of `c`, the implementation that we are using requires about `c * 8` bytes. - -The following chart shows how the error varies before and after the threshold: - -![cardinality error](/images/cardinality_error.png "") - -For all 3 thresholds, counts have been accurate up to the configured threshold. Although not guaranteed, this is likely to be the case. Accuracy in practice depends on the dataset in question. In general, most datasets show consistently good accuracy. Also note that even with a threshold as low as 100, the error remains very low (1-6% as seen in the above graph) even when counting millions of items. - -The HyperLogLog++ algorithm depends on the leading zeros of hashed values, the exact distributions of hashes in a dataset can affect the accuracy of the cardinality. - -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`. - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/date_diff.md b/docs/reference/query-languages/esql/_snippets/functions/examples/date_diff.md index 26bebb000e7ac..62a3d61e4a5db 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/date_diff.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/date_diff.md @@ -11,7 +11,8 @@ ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), date2 = TO_DATETIME("2023-1 | --- | --- | --- | | 2023-12-02T11:00:00.000Z | 2023-12-02T11:00:00.001Z | 1000 | -When subtracting in calendar units - like year, month a.s.o. - only the fully elapsed units are counted. To avoid this and obtain also remainders, simply switch to the next smaller unit and do the date math accordingly. +When subtracting in calendar units - like year, month a.s.o. - only the fully elapsed units are counted. +To avoid this and obtain also remainders, simply switch to the next smaller unit and do the date math accordingly. ```esql ROW end_23=TO_DATETIME("2023-12-31T23:59:59.999Z"), diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/date_trunc.md b/docs/reference/query-languages/esql/_snippets/functions/examples/date_trunc.md index 5158be8c14b5a..040deec020edc 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/date_trunc.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/date_trunc.md @@ -14,7 +14,8 @@ FROM employees | Amabile | Gomatam | 1992-11-18T00:00:00.000Z | 1992-01-01T00:00:00.000Z | | Anneke | Preusig | 1989-06-02T00:00:00.000Z | 1989-01-01T00:00:00.000Z | -Combine `DATE_TRUNC` with [`STATS`](/reference/query-languages/esql/esql-commands.md#esql-stats-by) to create date histograms. For example, the number of hires per year: +Combine `DATE_TRUNC` with [`STATS`](/reference/query-languages/esql/esql-commands.md#esql-stats-by) to create date histograms. For +example, the number of hires per year: ```esql FROM employees diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/hash.md b/docs/reference/query-languages/esql/_snippets/functions/examples/hash.md index f037c698bbc3d..97b0697feaa3f 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/hash.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/hash.md @@ -6,7 +6,7 @@ FROM sample_data | WHERE message != "Connection error" | EVAL md5 = hash("md5", message), sha256 = hash("sha256", message) -| KEEP message, md5, sha256; +| KEEP message, md5, sha256 ``` | message:keyword | md5:keyword | sha256:keyword | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/ip_prefix.md b/docs/reference/query-languages/esql/_snippets/functions/examples/ip_prefix.md index a5236151722d6..ede555826aa61 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/ip_prefix.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/ip_prefix.md @@ -10,3 +10,5 @@ row ip4 = to_ip("1.2.3.4"), ip6 = to_ip("fe80::cae2:65ff:fece:feb9") | ip4:ip | ip6:ip | ip4_prefix:ip | ip6_prefix:ip | | --- | --- | --- | --- | | 1.2.3.4 | fe80::cae2:65ff:fece:feb9 | 1.2.3.0 | fe80::cae2:65ff:fece:0000 | + + diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/least.md b/docs/reference/query-languages/esql/_snippets/functions/examples/least.md index e56c04d4388c9..86ca95b6bab29 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/least.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/least.md @@ -10,3 +10,5 @@ ROW a = 10, b = 20 | a:integer | b:integer | l:integer | | --- | --- | --- | | 10 | 20 | 10 | + + diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/md5.md b/docs/reference/query-languages/esql/_snippets/functions/examples/md5.md index af0e6094603a8..e0071a71ffae7 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/md5.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/md5.md @@ -6,7 +6,7 @@ FROM sample_data | WHERE message != "Connection error" | EVAL md5 = md5(message) -| KEEP message, md5; +| KEEP message, md5 ``` | message:keyword | md5:keyword | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/median.md b/docs/reference/query-languages/esql/_snippets/functions/examples/median.md index 2938a863048fb..99551b3ae9044 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/median.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/median.md @@ -22,10 +22,4 @@ FROM employees | --- | | 7.69 | -::::{warning} -`MEDIAN` is also [non-deterministic](https://en.wikipedia.org/wiki/Nondeterministic_algorithm). This means you can get slightly different results using the same data. - -:::: - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/median_absolute_deviation.md b/docs/reference/query-languages/esql/_snippets/functions/examples/median_absolute_deviation.md index fdc238858cc5f..a721ce0a92f89 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/median_absolute_deviation.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/median_absolute_deviation.md @@ -22,10 +22,4 @@ FROM employees | --- | | 5.69 | -::::{warning} -`MEDIAN_ABSOLUTE_DEVIATION` is also [non-deterministic](https://en.wikipedia.org/wiki/Nondeterministic_algorithm). This means you can get slightly different results using the same data. - -:::: - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/mv_concat.md b/docs/reference/query-languages/esql/_snippets/functions/examples/mv_concat.md index b50e371269779..4eb02ca402f5f 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/mv_concat.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/mv_concat.md @@ -11,7 +11,7 @@ ROW a=["foo", "zoo", "bar"] | --- | --- | | ["foo", "zoo", "bar"] | "foo, zoo, bar" | -To concat non-string columns, call [`TO_STRING`](../../../esql-functions-operators.md#esql-to_string) first: +To concat non-string columns, call [`TO_STRING`](/reference/query-languages/esql/esql-functions-operators.md#esql-to_string) first: ```esql ROW a=[10, 9, 8] diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/mv_zip.md b/docs/reference/query-languages/esql/_snippets/functions/examples/mv_zip.md index b0a657d7fc1e3..7dd5b21798260 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/mv_zip.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/mv_zip.md @@ -11,3 +11,5 @@ ROW a = ["x", "y", "z"], b = ["1", "2"] | a:keyword | b:keyword | c:keyword | | --- | --- | --- | | [x, y, z] | [1 ,2] | [x-1, y-2, z] | + + diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/now.md b/docs/reference/query-languages/esql/_snippets/functions/examples/now.md index 98513e2d53358..aabe6474beff2 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/now.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/now.md @@ -19,3 +19,5 @@ FROM sample_data | @timestamp:date | client_ip:ip | event_duration:long | message:keyword | | --- | --- | --- | --- | + + diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/percentile.md b/docs/reference/query-languages/esql/_snippets/functions/examples/percentile.md index 26bbf016cfefc..409b2d0d6c46d 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/percentile.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/percentile.md @@ -25,30 +25,3 @@ FROM employees | 12.132 | -### `PERCENTILE` is (usually) approximate [esql-percentile-approximate] - -There are many different algorithms to calculate percentiles. The naive implementation simply stores all the values in a sorted array. To find the 50th percentile, you simply find the value that is at `my_array[count(my_array) * 0.5]`. - -Clearly, the naive implementation does not scale — the sorted array grows linearly with the number of values in your dataset. To calculate percentiles across potentially billions of values in an Elasticsearch cluster, *approximate* percentiles are calculated. - -The algorithm used by the `percentile` metric is called TDigest (introduced by Ted Dunning in [Computing Accurate Quantiles using T-Digests](https://github.com/tdunning/t-digest/blob/master/docs/t-digest-paper/histo.pdf)). - -When using this metric, there are a few guidelines to keep in mind: - -* Accuracy is proportional to `q(1-q)`. This means that extreme percentiles (e.g. 99%) are more accurate than less extreme percentiles, such as the median -* For small sets of values, percentiles are highly accurate (and potentially 100% accurate if the data is small enough). -* As the quantity of values in a bucket grows, the algorithm begins to approximate the percentiles. It is effectively trading accuracy for memory savings. The exact level of inaccuracy is difficult to generalize, since it depends on your data distribution and volume of data being aggregated - -The following chart shows the relative error on a uniform distribution depending on the number of collected values and the requested percentile: - -![percentiles error](/images/percentiles_error.png "") - -It shows how precision is better for extreme percentiles. The reason why error diminishes for large number of values is that the law of large numbers makes the distribution of values more and more uniform and the t-digest tree can do a better job at summarizing it. It would not be the case on more skewed distributions. - -::::{warning} -`PERCENTILE` is also [non-deterministic](https://en.wikipedia.org/wiki/Nondeterministic_algorithm). This means you can get slightly different results using the same data. - -:::: - - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/pow.md b/docs/reference/query-languages/esql/_snippets/functions/examples/pow.md index ab6099227be5d..769090e73025c 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/pow.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/pow.md @@ -11,7 +11,8 @@ ROW base = 2.0, exponent = 2 | --- | --- | --- | | 2.0 | 2 | 4.0 | -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: +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: ```esql ROW base = 4, exponent = 0.5 diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/qstr.md b/docs/reference/query-languages/esql/_snippets/functions/examples/qstr.md index 924b32fd6c351..ca2be86bd49ec 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/qstr.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/qstr.md @@ -17,3 +17,5 @@ FROM books | 2847 | Colleen Faulkner | | 2883 | William Faulkner | | 3293 | Danny Faulkner | + + diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/sha1.md b/docs/reference/query-languages/esql/_snippets/functions/examples/sha1.md index c912f83fccd70..ea63b6462766e 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/sha1.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/sha1.md @@ -6,7 +6,7 @@ FROM sample_data | WHERE message != "Connection error" | EVAL sha1 = sha1(message) -| KEEP message, sha1; +| KEEP message, sha1 ``` | message:keyword | sha1:keyword | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/sha256.md b/docs/reference/query-languages/esql/_snippets/functions/examples/sha256.md index 4800cc5ff3ad8..26b8c54961cab 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/sha256.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/sha256.md @@ -6,7 +6,7 @@ FROM sample_data | WHERE message != "Connection error" | EVAL sha256 = sha256(message) -| KEEP message, sha256; +| KEEP message, sha256 ``` | message:keyword | sha256:keyword | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/st_contains.md b/docs/reference/query-languages/esql/_snippets/functions/examples/st_contains.md index 0ffc8ac08c53e..b690aca5cd395 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/st_contains.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/st_contains.md @@ -10,6 +10,6 @@ FROM airport_city_boundaries | abbrev:keyword | airport:text | region:text | city:keyword | city_location:geo_point | | --- | --- | --- | --- | --- | -| SYX | Sanya Phoenix Int’l | 天涯区 | Sanya | POINT(109.5036 18.2533) | +| SYX | Sanya Phoenix Int'l | 天涯区 | Sanya | POINT(109.5036 18.2533) | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/st_disjoint.md b/docs/reference/query-languages/esql/_snippets/functions/examples/st_disjoint.md index 2d472dd8021e8..3f5446f26b397 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/st_disjoint.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/st_disjoint.md @@ -10,6 +10,6 @@ FROM airport_city_boundaries | abbrev:keyword | airport:text | region:text | city:keyword | city_location:geo_point | | --- | --- | --- | --- | --- | -| ACA | General Juan N Alvarez Int’l | Acapulco de Juárez | Acapulco de Juárez | POINT (-99.8825 16.8636) | +| ACA | General Juan N Alvarez Int'l | Acapulco de Juárez | Acapulco de Juárez | POINT (-99.8825 16.8636) | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/st_intersects.md b/docs/reference/query-languages/esql/_snippets/functions/examples/st_intersects.md index 5d94d9ecd79b1..71451ab026a20 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/st_intersects.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/st_intersects.md @@ -9,6 +9,6 @@ FROM airports | abbrev:keyword | city:keyword | city_location:geo_point | country:keyword | location:geo_point | name:text | scalerank:i | type:k | | --- | --- | --- | --- | --- | --- | --- | --- | -| HOD | Al Ḩudaydah | POINT(42.9511 14.8022) | Yemen | POINT(42.97109630194 14.7552534413725) | Hodeidah Int’l | 9 | mid | +| HOD | Al Ḩudaydah | POINT(42.9511 14.8022) | Yemen | POINT(42.97109630194 14.7552534413725) | Hodeidah Int'l | 9 | mid | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/st_within.md b/docs/reference/query-languages/esql/_snippets/functions/examples/st_within.md index 180d43bfef669..9d43a4bcd0e75 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/st_within.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/st_within.md @@ -10,6 +10,6 @@ FROM airport_city_boundaries | abbrev:keyword | airport:text | region:text | city:keyword | city_location:geo_point | | --- | --- | --- | --- | --- | -| SYX | Sanya Phoenix Int’l | 天涯区 | Sanya | POINT(109.5036 18.2533) | +| SYX | Sanya Phoenix Int'l | 天涯区 | Sanya | POINT(109.5036 18.2533) | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/st_ymin.md b/docs/reference/query-languages/esql/_snippets/functions/examples/st_ymin.md index d7895b60f7bfd..c1ae509264984 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/st_ymin.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/st_ymin.md @@ -13,3 +13,5 @@ FROM airport_city_boundaries | abbrev:keyword | airport:text | xmin:double | xmax:double | ymin:double | ymax:double | | --- | --- | --- | --- | --- | --- | | CPH | Copenhagen | 12.453 | 12.6398 | 55.6318 | 55.7327 | + + diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/substring.md b/docs/reference/query-languages/esql/_snippets/functions/examples/substring.md index 9beb25fe622f8..5e97ece5cc6a0 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/substring.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/substring.md @@ -18,7 +18,8 @@ FROM employees | Bamford | Bam | | Bernatsky | Ber | -A negative start position is interpreted as being relative to the end of the string. This example returns the last three characters of of every last name: +A negative start position is interpreted as being relative to the end of the string. +This example returns the last three characters of every last name: ```esql FROM employees @@ -34,7 +35,8 @@ FROM employees | Bamford | ord | | Bernatsky | sky | -If length is omitted, substring returns the remainder of the string. This example returns all characters except for the first: +If length is omitted, substring returns the remainder of the string. +This example returns all characters except for the first: ```esql FROM employees diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/tau.md b/docs/reference/query-languages/esql/_snippets/functions/examples/tau.md index 97d35d8c14201..4ab8a617caef0 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/tau.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/tau.md @@ -9,3 +9,5 @@ ROW TAU() | TAU():double | | --- | | 6.283185307179586 | + + diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/term.md b/docs/reference/query-languages/esql/_snippets/functions/examples/term.md new file mode 100644 index 0000000000000..bebe560cef2d1 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/term.md @@ -0,0 +1,18 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +**Example** + +```esql +FROM books +| WHERE TERM(author, "gabriel") +| KEEP book_no, title +| LIMIT 3 +``` + +| book_no:keyword | title:text | +| --- | --- | +| 4814 | El Coronel No Tiene Quien Le Escriba / No One Writes to the Colonel (Spanish Edition) | +| 4917 | Autumn of the Patriarch | +| 6380 | La hojarasca (Spanish Edition) | + + diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/to_cartesianshape.md b/docs/reference/query-languages/esql/_snippets/functions/examples/to_cartesianshape.md index 5483c9976734b..74dd6eebd7864 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/to_cartesianshape.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/to_cartesianshape.md @@ -11,6 +11,6 @@ ROW wkt = ["POINT(4297.11 -1475.53)", "POLYGON ((3339584.72 1118889.97, 4452779. | wkt:keyword | geom:cartesian_shape | | --- | --- | | "POINT(4297.11 -1475.53)" | POINT(4297.11 -1475.53) | -| "POLYGON 3339584.72 1118889.97, 4452779.63 4865942.27, 2226389.81 4865942.27, 1113194.90 2273030.92, 3339584.72 1118889.97" | POLYGON 3339584.72 1118889.97, 4452779.63 4865942.27, 2226389.81 4865942.27, 1113194.90 2273030.92, 3339584.72 1118889.97 | +| "POLYGON ((3339584.72 1118889.97, 4452779.63 4865942.27, 2226389.81 4865942.27, 1113194.90 2273030.92, 3339584.72 1118889.97))" | POLYGON ((3339584.72 1118889.97, 4452779.63 4865942.27, 2226389.81 4865942.27, 1113194.90 2273030.92, 3339584.72 1118889.97)) | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/to_datetime.md b/docs/reference/query-languages/esql/_snippets/functions/examples/to_datetime.md index fd83bc9a12111..5118fb43c5418 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/to_datetime.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/to_datetime.md @@ -11,15 +11,21 @@ ROW string = ["1953-09-02T00:00:00.000Z", "1964-06-02T00:00:00.000Z", "1964-06-0 | --- | --- | | ["1953-09-02T00:00:00.000Z", "1964-06-02T00:00:00.000Z", "1964-06-02 00:00:00"] | [1953-09-02T00:00:00.000Z, 1964-06-02T00:00:00.000Z] | -Note that in this example, the last value in the source multi-valued field has not been converted. The reason being that if the date format is not respected, the conversion will result in a **null** value. When this happens 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 value in the source multi-valued field has not been converted. +The reason being that if the date format is not respected, the conversion will result in a `null` value. +When this happens a _Warning_ header is added to the response. +The header will provide information on the source of the failure: `"Line 1:112: evaluation of [TO_DATETIME(string)] failed, treating result as null. "Only first 20 failures recorded."` 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']"` +`"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 [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). For example: +If the input parameter is of a numeric type, +its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). For example: ```esql ROW int = [0, 1] diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/to_double.md b/docs/reference/query-languages/esql/_snippets/functions/examples/to_double.md index 3cb5024544994..70d389964281b 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/to_double.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/to_double.md @@ -11,10 +11,14 @@ ROW str1 = "5.20128E11", str2 = "foo" | --- | --- | --- | --- | --- | | 5.20128E11 | foo | 5.20128E11 | 5.20128E11 | null | -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""` +A following header will contain the failure reason and the offending value: +`"java.lang.NumberFormatException: For input string: "foo""` diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/to_geoshape.md b/docs/reference/query-languages/esql/_snippets/functions/examples/to_geoshape.md index e653be92b0959..4f9f722f5b7c6 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/to_geoshape.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/to_geoshape.md @@ -9,6 +9,6 @@ ROW wkt = "POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))" | wkt:keyword | geom:geo_shape | | --- | --- | -| "POLYGON 30 10, 40 40, 20 40, 10 20, 30 10" | POLYGON 30 10, 40 40, 20 40, 10 20, 30 10 | +| "POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))" | POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10)) | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/to_integer.md b/docs/reference/query-languages/esql/_snippets/functions/examples/to_integer.md index c5a3dce155a92..f706a2330aa1a 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/to_integer.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/to_integer.md @@ -11,7 +11,10 @@ ROW long = [5013792, 2147483647, 501379200000] | --- | --- | | [5013792, 2147483647, 501379200000] | [5013792, 2147483647] | -Note that in this example, the last value of the multi-valued field cannot be converted as an integer. 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 value of the multi-valued field cannot be converted as an integer. +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:61: evaluation of [TO_INTEGER(long)] failed, treating result as null. Only first 20 failures recorded."` diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/to_ip.md b/docs/reference/query-languages/esql/_snippets/functions/examples/to_ip.md index 3d6e30818b8e7..7f4256e24282e 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/to_ip.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/to_ip.md @@ -12,7 +12,10 @@ ROW str1 = "1.1.1.1", str2 = "foo" | --- | --- | --- | --- | | 1.1.1.1 | foo | 1.1.1.1 | null | -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:68: evaluation of [TO_IP(str2)] failed, treating result as null. Only first 20 failures recorded."` diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/to_long.md b/docs/reference/query-languages/esql/_snippets/functions/examples/to_long.md index 97bb968bfbe4e..64df98e16e10a 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/to_long.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/to_long.md @@ -11,7 +11,10 @@ ROW str1 = "2147483648", str2 = "2147483648.2", str3 = "foo" | --- | --- | --- | --- | --- | --- | | 2147483648 | 2147483648.2 | foo | 2147483648 | 2147483648 | null | -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:113: evaluation of [TO_LONG(str3)] failed, treating result as null. Only first 20 failures recorded."` diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/to_unsigned_long.md b/docs/reference/query-languages/esql/_snippets/functions/examples/to_unsigned_long.md index 2b1c61be69238..b8e95e3b08b45 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/to_unsigned_long.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/to_unsigned_long.md @@ -11,12 +11,16 @@ ROW str1 = "2147483648", str2 = "2147483648.2", str3 = "foo" | --- | --- | --- | --- | --- | --- | | 2147483648 | 2147483648.2 | foo | 2147483648 | 2147483648 | null | -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:133: evaluation of [TO_UL(str3)] 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: Character f is neither a decimal digit number, decimal point, + "nor "e" notation exponential mark."` +`"java.lang.NumberFormatException: Character f is neither a decimal digit number, decimal point, ++ "nor "e" notation exponential mark."` diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/to_version.md b/docs/reference/query-languages/esql/_snippets/functions/examples/to_version.md index 9810046c9e45e..b3a178fa457a7 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/to_version.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/to_version.md @@ -9,3 +9,5 @@ ROW v = TO_VERSION("1.2.3") | v:version | | --- | | 1.2.3 | + + diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/trim.md b/docs/reference/query-languages/esql/_snippets/functions/examples/trim.md index eaacece0ccc1d..109e6e0daad8a 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/trim.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/trim.md @@ -11,3 +11,5 @@ ROW message = " some text ", color = " red " | message:s | color:s | | --- | --- | | some text | red | + + diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/values.md b/docs/reference/query-languages/esql/_snippets/functions/examples/values.md index 9415f4c3e0642..07332d9fcada8 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/values.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/values.md @@ -36,10 +36,4 @@ | [Zhongwei, Zvonko] | Z | | null | null | -::::{warning} -This can use a significant amount of memory and ES|QL doesn’t yet grow aggregations beyond memory. So this aggregation will work until it is used to collect more values than can fit into memory. Once it collects too many values it will fail the query with a [Circuit Breaker Error](docs-content://troubleshoot/elasticsearch/circuit-breaker-errors.md). - -:::: - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/weighted_avg.md b/docs/reference/query-languages/esql/_snippets/functions/examples/weighted_avg.md index 6c3b3361fabb6..3d1f3c9d827d7 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/weighted_avg.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/weighted_avg.md @@ -18,3 +18,5 @@ FROM employees | 47990.0 | 4 | | 42119.0 | 5 | | 52142.0 | null | + + diff --git a/docs/reference/query-languages/esql/_snippets/functions/exp.md b/docs/reference/query-languages/esql/_snippets/functions/exp.md deleted file mode 100644 index d16aab8db1d33..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/exp.md +++ /dev/null @@ -1,39 +0,0 @@ -## `EXP` [esql-exp] - -**Syntax** - -:::{image} ../../../../../images/exp.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the value of e raised to the power of the given number. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW d = 5.0 -| EVAL s = EXP(d) -``` - -| d: double | s:double | -| --- | --- | -| 5.0 | 148.413159102576603 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/floor.md b/docs/reference/query-languages/esql/_snippets/functions/floor.md deleted file mode 100644 index 56b5b07f77b48..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/floor.md +++ /dev/null @@ -1,44 +0,0 @@ -## `FLOOR` [esql-floor] - -**Syntax** - -:::{image} ../../../../../images/floor.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Round 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 [Math.floor](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Math.md#floor(double)). -:::: - - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | integer | -| long | long | -| unsigned_long | unsigned_long | - -**Example** - -```esql -ROW a=1.8 -| EVAL a=FLOOR(a) -``` - -| a:double | -| --- | -| 1 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/from_base64.md b/docs/reference/query-languages/esql/_snippets/functions/from_base64.md deleted file mode 100644 index 96b4709ea2994..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/from_base64.md +++ /dev/null @@ -1,37 +0,0 @@ -## `FROM_BASE64` [esql-from_base64] - -**Syntax** - -:::{image} ../../../../../images/from_base64.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: A base64 string. - -**Description** - -Decode a base64 string. - -**Supported types** - -| string | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -row a = "ZWxhc3RpYw==" -| eval d = from_base64(a) -``` - -| a:keyword | d:keyword | -| --- | --- | -| ZWxhc3RpYw== | elastic | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/functionNamedParameters/match.md b/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/match.md similarity index 99% rename from docs/reference/query-languages/esql/_snippets/functions/functionNamedParameters/match.md rename to docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/match.md index bcbedd5d7e4c4..dbb8a77939618 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/functionNamedParameters/match.md +++ b/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/match.md @@ -16,4 +16,3 @@ | lenient | [boolean] | If false, format-based errors, such as providing a text query value for a numeric field, are returned. | | operator | [keyword] | Boolean logic used to interpret text in the query value. | | max_expansions | [integer] | Maximum number of terms to which the query will expand. | - diff --git a/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/qstr.md b/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/qstr.md new file mode 100644 index 0000000000000..bd5f495920052 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/qstr.md @@ -0,0 +1,27 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +**Supported function named parameters** + +| name | types | description | +| --- | --- | --- | +| max_determinized_states | [integer] | Maximum number of automaton states required for the query. Default is 10000. | +| fuzziness | [keyword] | Maximum edit distance allowed for matching. | +| auto_generate_synonyms_phrase_query | [boolean] | If true, match phrase queries are automatically created for multi-term synonyms. Defaults to true. | +| phrase_slop | [integer] | Maximum number of positions allowed between matching tokens for phrases. Defaults to 0 (which means exact matches are required). | +| default_field | [keyword] | Default field to search if no field is provided in the query string. Supports wildcards (*). | +| allow_leading_wildcard | [boolean] | If true, the wildcard characters * and ? are allowed as the first character of the query string. Defaults to true. | +| minimum_should_match | [string] | Minimum number of clauses that must match for a document to be returned. | +| fuzzy_transpositions | [boolean] | If true, edits for fuzzy matching include transpositions of two adjacent characters (ab → ba). Defaults to true. | +| fuzzy_prefix_length | [integer] | Number of beginning characters left unchanged for fuzzy matching. Defaults to 0. | +| time_zone | [keyword] | Coordinated Universal Time (UTC) offset or IANA time zone used to convert date values in the query string to UTC. | +| lenient | [boolean] | If false, format-based errors, such as providing a text query value for a numeric field, are returned. Defaults to false. | +| rewrite | [keyword] | Method used to rewrite the query. | +| default_operator | [keyword] | Default boolean logic used to interpret text in the query string if no operators are specified. | +| analyzer | [keyword] | Analyzer used to convert the text in the query value into token. Defaults to the index-time analyzer mapped for the default_field. | +| fuzzy_max_expansions | [integer] | Maximum number of terms to which the query expands for fuzzy matching. Defaults to 50. | +| quote_analyzer | [keyword] | Analyzer used to convert quoted text in the query string into tokens. Defaults to the search_quote_analyzer mapped for the default_field. | +| allow_wildcard | [boolean] | If true, the query attempts to analyze wildcard terms in the query string. Defaults to false. | +| boost | [float] | Floating point number used to decrease or increase the relevance scores of the query. | +| quote_field_suffix | [keyword] | Suffix appended to quoted text in the query string. | +| enable_position_increments | [boolean] | If true, enable position increments in queries constructed from a query_string search. Defaults to true. | +| fields | [keyword] | Array of fields to search. Supports wildcards (*). | diff --git a/docs/reference/query-languages/esql/_snippets/functions/greatest.md b/docs/reference/query-languages/esql/_snippets/functions/greatest.md deleted file mode 100644 index e599751f54996..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/greatest.md +++ /dev/null @@ -1,58 +0,0 @@ -## `GREATEST` [esql-greatest] - -**Syntax** - -:::{image} ../../../../../images/greatest.svg -:alt: Embedded -:class: text-center -::: - -**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 [`MV_MAX`](../../esql-functions-operators.md#esql-mv_max) 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** - -| first | rest | result | -| --- | --- | --- | -| boolean | boolean | boolean | -| boolean | | boolean | -| date | date | date | -| date_nanos | date_nanos | date_nanos | -| double | double | double | -| integer | integer | integer | -| integer | | integer | -| ip | ip | ip | -| keyword | keyword | keyword | -| keyword | | keyword | -| long | long | long | -| long | | long | -| text | text | keyword | -| text | | keyword | -| version | version | version | - -**Example** - -```esql -ROW a = 10, b = 20 -| EVAL g = GREATEST(a, b) -``` - -| a:integer | b:integer | g:integer | -| --- | --- | --- | -| 10 | 20 | 20 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/hash.md b/docs/reference/query-languages/esql/_snippets/functions/hash.md deleted file mode 100644 index d435c1be2e0d2..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/hash.md +++ /dev/null @@ -1,47 +0,0 @@ -## `HASH` [esql-hash] - -**Syntax** - -:::{image} ../../../../../images/hash.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`algorithm` -: Hash algorithm to use. - -`input` -: Input to hash. - -**Description** - -Computes the hash of the input using various algorithms such as MD5, SHA, SHA-224, SHA-256, SHA-384, SHA-512. - -**Supported types** - -| algorithm | input | result | -| --- | --- | --- | -| keyword | keyword | keyword | -| keyword | text | keyword | -| text | keyword | keyword | -| text | text | keyword | - -**Example** - -```esql -FROM sample_data -| WHERE message != "Connection error" -| EVAL md5 = hash("md5", message), sha256 = hash("sha256", message) -| KEEP message, md5, sha256; -``` - -| message:keyword | md5:keyword | sha256:keyword | -| --- | --- | --- | -| Connected to 10.1.0.1 | abd7d1ce2bb636842a29246b3512dcae | 6d8372129ad78770f7185554dd39864749a62690216460752d6c075fa38ad85c | -| Connected to 10.1.0.2 | 8f8f1cb60832d153f5b9ec6dc828b93f | b0db24720f15857091b3c99f4c4833586d0ea3229911b8777efb8d917cf27e9a | -| Connected to 10.1.0.3 | 912b6dc13503165a15de43304bb77c78 | 75b0480188db8acc4d5cc666a51227eb2bc5b989cd8ca912609f33e0846eff57 | -| Disconnected | ef70e46fd3bbc21e3e1f0b6815e750c0 | 04dfac3671b494ad53fcd152f7a14511bfb35747278aad8ce254a0d6e4ba4718 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/hypot.md b/docs/reference/query-languages/esql/_snippets/functions/hypot.md deleted file mode 100644 index 004ef8fb82fcd..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/hypot.md +++ /dev/null @@ -1,54 +0,0 @@ -## `HYPOT` [esql-hypot] - -**Syntax** - -:::{image} ../../../../../images/hypot.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number1` -: Numeric expression. If `null`, the function returns `null`. - -`number2` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the hypotenuse of two numbers. The input can be any numeric values, the return value is always a double. Hypotenuses of infinities are null. - -**Supported types** - -| number1 | number2 | 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 | - -**Example** - -```esql -ROW a = 3.0, b = 4.0 -| EVAL c = HYPOT(a, b) -``` - -| a:double | b:double | c:double | -| --- | --- | --- | -| 3.0 | 4.0 | 5.0 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/ip_prefix.md b/docs/reference/query-languages/esql/_snippets/functions/ip_prefix.md deleted file mode 100644 index 26f2f98a8d4a5..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/ip_prefix.md +++ /dev/null @@ -1,40 +0,0 @@ -## `IP_PREFIX` [esql-ip_prefix] - -**Syntax** - -:::{image} ../../../../../images/ip_prefix.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`ip` -: IP address of type `ip` (both IPv4 and IPv6 are supported). - -`prefixLengthV4` -: Prefix length for IPv4 addresses. - -`prefixLengthV6` -: Prefix length for IPv6 addresses. - -**Description** - -Truncates an IP to a given prefix length. - -**Supported types** - -| ip | prefixLengthV4 | prefixLengthV6 | result | -| --- | --- | --- | --- | -| ip | integer | integer | ip | - -**Example** - -```esql -row ip4 = to_ip("1.2.3.4"), ip6 = to_ip("fe80::cae2:65ff:fece:feb9") -| eval ip4_prefix = ip_prefix(ip4, 24, 0), ip6_prefix = ip_prefix(ip6, 0, 112); -``` - -| ip4:ip | ip6:ip | ip4_prefix:ip | ip6_prefix:ip | -| --- | --- | --- | --- | -| 1.2.3.4 | fe80::cae2:65ff:fece:feb9 | 1.2.3.0 | fe80::cae2:65ff:fece:0000 | diff --git a/docs/reference/query-languages/esql/_snippets/functions/kql.md b/docs/reference/query-languages/esql/_snippets/functions/kql.md deleted file mode 100644 index 369b36bc233ad..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/kql.md +++ /dev/null @@ -1,49 +0,0 @@ -## `KQL` [esql-kql] - -::::{warning} -Do not use 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. -:::: - - -**Syntax** - -:::{image} ../../../../../images/kql.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`query` -: Query string in KQL query string format. - -**Description** - -Performs a KQL query. Returns true if the provided KQL query string matches the row. - -**Supported types** - -| query | result | -| --- | --- | -| keyword | boolean | -| text | boolean | - -**Example** - -```esql -FROM books -| WHERE KQL("author: Faulkner") -| KEEP book_no, author -| SORT book_no -| LIMIT 5 -``` - -| book_no:keyword | author:text | -| --- | --- | -| 2378 | [Carol Faulkner, Holly Byers Ochoa, Lucretia Mott] | -| 2713 | William Faulkner | -| 2847 | Colleen Faulkner | -| 2883 | William Faulkner | -| 3293 | Danny Faulkner | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/categorize.md b/docs/reference/query-languages/esql/_snippets/functions/layout/categorize.md index 4ec45c8167fbc..68a55dc513205 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/categorize.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/categorize.md @@ -1,12 +1,12 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. ## `CATEGORIZE` [esql-categorize] - ::::{warning} -Do not use 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. +Do not use 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. :::: - **Syntax** :::{image} ../../../images/functions/categorize.svg diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/count_distinct.md b/docs/reference/query-languages/esql/_snippets/functions/layout/count_distinct.md index b41712aaabb3e..b95500db4bec9 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/count_distinct.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/count_distinct.md @@ -21,3 +21,6 @@ :::{include} ../examples/count_distinct.md ::: + +:::{include} ../appendix/count_distinct.md +::: diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/kql.md b/docs/reference/query-languages/esql/_snippets/functions/layout/kql.md index 85da54720c862..cf61e572cd6cc 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/kql.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/kql.md @@ -1,12 +1,12 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. ## `KQL` [esql-kql] - ::::{warning} -Do not use 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. +Do not use 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. :::: - **Syntax** :::{image} ../../../images/functions/kql.svg diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/match.md b/docs/reference/query-languages/esql/_snippets/functions/layout/match.md index 4a547a497dc1a..3dfadc4b6d44d 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/match.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/match.md @@ -1,12 +1,12 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. ## `MATCH` [esql-match] - ::::{warning} -Do not use 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. +Do not use 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. :::: - **Syntax** :::{image} ../../../images/functions/match.svg @@ -24,7 +24,7 @@ Do not use on production environments. This functionality is in technical previe :::{include} ../types/match.md ::: -:::{include} ../functionNamedParameters/match.md +:::{include} ../functionNamedParams/match.md ::: :::{include} ../examples/match.md diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/median.md b/docs/reference/query-languages/esql/_snippets/functions/layout/median.md index 208f3aa9df12a..64e5646069ffe 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/median.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/median.md @@ -21,3 +21,6 @@ :::{include} ../examples/median.md ::: + +:::{include} ../appendix/median.md +::: diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/median_absolute_deviation.md b/docs/reference/query-languages/esql/_snippets/functions/layout/median_absolute_deviation.md index f76f8387829ed..85659eab40269 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/median_absolute_deviation.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/median_absolute_deviation.md @@ -21,3 +21,6 @@ :::{include} ../examples/median_absolute_deviation.md ::: + +:::{include} ../appendix/median_absolute_deviation.md +::: diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/percentile.md b/docs/reference/query-languages/esql/_snippets/functions/layout/percentile.md index a9d7066375012..12401b5486a8d 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/percentile.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/percentile.md @@ -21,3 +21,6 @@ :::{include} ../examples/percentile.md ::: + +:::{include} ../appendix/percentile.md +::: diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/qstr.md b/docs/reference/query-languages/esql/_snippets/functions/layout/qstr.md index 9049ad7b293df..9423c004211c9 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/qstr.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/qstr.md @@ -1,12 +1,12 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. ## `QSTR` [esql-qstr] - ::::{warning} -Do not use 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. +Do not use 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. :::: - **Syntax** :::{image} ../../../images/functions/qstr.svg diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/term.md b/docs/reference/query-languages/esql/_snippets/functions/layout/term.md new file mode 100644 index 0000000000000..fe886f769b84a --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/term.md @@ -0,0 +1,28 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +## `TERM` [esql-term] +::::{warning} +Do not use 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. +:::: + +**Syntax** + +:::{image} ../../../images/functions/term.svg +:alt: Embedded +:class: text-center +::: + + +:::{include} ../parameters/term.md +::: + +:::{include} ../description/term.md +::: + +:::{include} ../types/term.md +::: + +:::{include} ../examples/term.md +::: diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/values.md b/docs/reference/query-languages/esql/_snippets/functions/layout/values.md index 4ff8e030805a3..4dbd9b6f84c58 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/values.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/values.md @@ -1,12 +1,12 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. ## `VALUES` [esql-values] - ::::{warning} -Do not use 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. +Do not use 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. :::: - **Syntax** :::{image} ../../../images/functions/values.svg @@ -26,3 +26,6 @@ Do not use on production environments. This functionality is in technical previe :::{include} ../examples/values.md ::: + +:::{include} ../appendix/values.md +::: diff --git a/docs/reference/query-languages/esql/_snippets/functions/least.md b/docs/reference/query-languages/esql/_snippets/functions/least.md deleted file mode 100644 index 27c3e2a8b4788..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/least.md +++ /dev/null @@ -1,51 +0,0 @@ -## `LEAST` [esql-least] - -**Syntax** - -:::{image} ../../../../../images/least.svg -:alt: Embedded -:class: text-center -::: - -**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 [`MV_MIN`](../../esql-functions-operators.md#esql-mv_min) except it is intended to run on multiple columns at once. - -**Supported types** - -| first | rest | result | -| --- | --- | --- | -| boolean | boolean | boolean | -| boolean | | boolean | -| date | date | date | -| date_nanos | date_nanos | date_nanos | -| double | double | double | -| integer | integer | integer | -| integer | | integer | -| ip | ip | ip | -| keyword | keyword | keyword | -| keyword | | keyword | -| long | long | long | -| long | | long | -| text | text | keyword | -| text | | keyword | -| version | version | version | - -**Example** - -```esql -ROW a = 10, b = 20 -| EVAL l = LEAST(a, b) -``` - -| a:integer | b:integer | l:integer | -| --- | --- | --- | -| 10 | 20 | 10 | diff --git a/docs/reference/query-languages/esql/_snippets/functions/left.md b/docs/reference/query-languages/esql/_snippets/functions/left.md deleted file mode 100644 index 3b0db9dbdeda1..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/left.md +++ /dev/null @@ -1,47 +0,0 @@ -## `LEFT` [esql-left] - -**Syntax** - -:::{image} ../../../../../images/left.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: The string from which to return a substring. - -`length` -: The number of characters to return. - -**Description** - -Returns the substring that extracts *length* chars from *string* starting from the left. - -**Supported types** - -| string | length | result | -| --- | --- | --- | -| keyword | integer | keyword | -| text | integer | keyword | - -**Example** - -```esql -FROM employees -| KEEP last_name -| EVAL left = LEFT(last_name, 3) -| SORT last_name ASC -| LIMIT 5 -``` - -| last_name:keyword | left:keyword | -| --- | --- | -| Awdeh | Awd | -| Azuma | Azu | -| Baek | Bae | -| Bamford | Bam | -| Bernatsky | Ber | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/length.md b/docs/reference/query-languages/esql/_snippets/functions/length.md deleted file mode 100644 index 42d3d0023da18..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/length.md +++ /dev/null @@ -1,46 +0,0 @@ -## `LENGTH` [esql-length] - -**Syntax** - -:::{image} ../../../../../images/length.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. If `null`, the function returns `null`. - -**Description** - -Returns the character length of a string. - -::::{note} -All strings are in UTF-8, so a single character can use multiple bytes. -:::: - - -**Supported types** - -| string | result | -| --- | --- | -| keyword | integer | -| text | integer | - -**Example** - -```esql -FROM airports -| WHERE country == "India" -| KEEP city -| EVAL fn_length = LENGTH(city) -``` - -| city:keyword | fn_length:integer | -| --- | --- | -| Agwār | 5 | -| Ahmedabad | 9 | -| Bangalore | 9 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/locate.md b/docs/reference/query-languages/esql/_snippets/functions/locate.md deleted file mode 100644 index e42bca9f227e5..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/locate.md +++ /dev/null @@ -1,49 +0,0 @@ -## `LOCATE` [esql-locate] - -**Syntax** - -:::{image} ../../../../../images/locate.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: An input string - -`substring` -: A substring to locate in the input string - -`start` -: The start index - -**Description** - -Returns an integer that indicates the position of a keyword substring within another string. Returns `0` if the substring cannot be found. Note that string positions start from `1`. - -**Supported types** - -| string | substring | start | result | -| --- | --- | --- | --- | -| keyword | keyword | integer | integer | -| keyword | keyword | | integer | -| keyword | text | integer | integer | -| keyword | text | | integer | -| text | keyword | integer | integer | -| text | keyword | | integer | -| text | text | integer | integer | -| text | text | | integer | - -**Example** - -```esql -row a = "hello" -| eval a_ll = locate(a, "ll") -``` - -| a:keyword | a_ll:integer | -| --- | --- | -| hello | 3 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/log.md b/docs/reference/query-languages/esql/_snippets/functions/log.md deleted file mode 100644 index 1dc373f4f4158..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/log.md +++ /dev/null @@ -1,67 +0,0 @@ -## `LOG` [esql-log] - -**Syntax** - -:::{image} ../../../../../images/log.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`base` -: Base of logarithm. If `null`, the function returns `null`. If not provided, this function returns the natural logarithm (base e) of a value. - -`number` -: 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, and base of one return `null` as well as a warning. - -**Supported types** - -| base | number | result | -| --- | --- | --- | -| double | double | double | -| double | integer | double | -| double | long | double | -| double | unsigned_long | double | -| double | | double | -| integer | double | double | -| integer | integer | double | -| integer | long | double | -| integer | unsigned_long | double | -| integer | | double | -| long | double | double | -| long | integer | double | -| long | long | double | -| long | unsigned_long | double | -| long | | double | -| unsigned_long | double | double | -| unsigned_long | integer | double | -| unsigned_long | long | double | -| unsigned_long | unsigned_long | double | -| unsigned_long | | double | - -**Examples** - -```esql -ROW base = 2.0, value = 8.0 -| EVAL s = LOG(base, value) -``` - -| base: double | value: double | s:double | -| --- | --- | --- | -| 2.0 | 8.0 | 3.0 | - -```esql -row value = 100 -| EVAL s = LOG(value); -``` - -| value: integer | s:double | -| --- | --- | -| 100 | 4.605170185988092 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/log10.md b/docs/reference/query-languages/esql/_snippets/functions/log10.md deleted file mode 100644 index 5f72ace630e71..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/log10.md +++ /dev/null @@ -1,39 +0,0 @@ -## `LOG10` [esql-log10] - -**Syntax** - -:::{image} ../../../../../images/log10.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the logarithm of a value to base 10. The input can be any numeric value, the return value is always a double. Logs of 0 and negative numbers return `null` as well as a warning. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW d = 1000.0 -| EVAL s = LOG10(d) -``` - -| d: double | s:double | -| --- | --- | -| 1000.0 | 3.0 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/ltrim.md b/docs/reference/query-languages/esql/_snippets/functions/ltrim.md deleted file mode 100644 index 3f8ff625f14b5..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/ltrim.md +++ /dev/null @@ -1,40 +0,0 @@ -## `LTRIM` [esql-ltrim] - -**Syntax** - -:::{image} ../../../../../images/ltrim.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. If `null`, the function returns `null`. - -**Description** - -Removes leading whitespaces from a string. - -**Supported types** - -| string | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -ROW message = " some text ", color = " red " -| EVAL message = LTRIM(message) -| EVAL color = LTRIM(color) -| EVAL message = CONCAT("'", message, "'") -| EVAL color = CONCAT("'", color, "'") -``` - -| message:keyword | color:keyword | -| --- | --- | -| 'some text ' | 'red ' | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/match.md b/docs/reference/query-languages/esql/_snippets/functions/match.md deleted file mode 100644 index 798ae85648653..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/match.md +++ /dev/null @@ -1,109 +0,0 @@ -## `MATCH` [esql-match] - -::::{warning} -Do not use 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. -:::: - - -**Syntax** - -:::{image} ../../../../../images/match.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Field that the query will target. - -`query` -: Value to find in the provided field. - -`options` -: (Optional) Match additional options as [function named parameters](/reference/query-languages/esql/esql-syntax.md#esql-function-named-params). See [match query](/reference/query-languages/query-dsl-match-query.md) for more information. - -**Description** - -Use `MATCH` to perform a [match query](/reference/query-languages/query-dsl-match-query.md) on the specified field. Using `MATCH` is equivalent to using the `match` query in the Elasticsearch Query DSL. Match can be used on fields from the text family like [text](/reference/elasticsearch/mapping-reference/text.md) and [semantic_text](/reference/elasticsearch/mapping-reference/semantic-text.md), as well as other field types like keyword, boolean, dates, and numeric types. Match can use [function named parameters](/reference/query-languages/esql/esql-syntax.md#esql-function-named-params) to specify additional options for the match query. All [match query parameters](/reference/query-languages/query-dsl-match-query.md#match-field-params) are supported. For a simplified syntax, you can use the [match operator](../../esql-functions-operators.md#esql-search-operators) `:` operator instead of `MATCH`. `MATCH` returns true if the provided query matches the row. - -**Supported types** - -| field | query | options | result | -| --- | --- | --- | --- | -| boolean | boolean | named parameters | boolean | -| boolean | keyword | named parameters | boolean | -| date | date | named parameters | boolean | -| date | keyword | named parameters | boolean | -| date_nanos | date_nanos | named parameters | boolean | -| date_nanos | keyword | named parameters | boolean | -| double | double | named parameters | boolean | -| double | integer | named parameters | boolean | -| double | keyword | named parameters | boolean | -| double | long | named parameters | boolean | -| integer | double | named parameters | boolean | -| integer | integer | named parameters | boolean | -| integer | keyword | named parameters | boolean | -| integer | long | named parameters | boolean | -| ip | ip | named parameters | boolean | -| ip | keyword | named parameters | boolean | -| keyword | keyword | named parameters | boolean | -| long | double | named parameters | boolean | -| long | integer | named parameters | boolean | -| long | keyword | named parameters | boolean | -| long | long | named parameters | boolean | -| text | keyword | named parameters | boolean | -| unsigned_long | double | named parameters | boolean | -| unsigned_long | integer | named parameters | boolean | -| unsigned_long | keyword | named parameters | boolean | -| unsigned_long | long | named parameters | boolean | -| unsigned_long | unsigned_long | named parameters | boolean | -| version | keyword | named parameters | boolean | -| version | version | named parameters | boolean | - -**Supported function named parameters** - -| name | types | description | -| --- | --- | --- | -| fuzziness | [keyword] | Maximum edit distance allowed for matching. | -| auto_generate_synonyms_phrase_query | [boolean] | If true, match phrase queries are automatically created for multi-term synonyms. | -| analyzer | [keyword] | Analyzer used to convert the text in the query value into token. | -| minimum_should_match | [integer] | Minimum number of clauses that must match for a document to be returned. | -| zero_terms_query | [keyword] | Number of beginning characters left unchanged for fuzzy matching. | -| boost | [float] | Floating point number used to decrease or increase the relevance scores of the query. | -| fuzzy_transpositions | [boolean] | If true, edits for fuzzy matching include transpositions of two adjacent characters (ab → ba). | -| fuzzy_rewrite | [keyword] | Method used to rewrite the query. See the rewrite parameter for valid values and more information. | -| prefix_length | [integer] | Number of beginning characters left unchanged for fuzzy matching. | -| lenient | [boolean] | If false, format-based errors, such as providing a text query value for a numeric field, are returned. | -| operator | [keyword] | Boolean logic used to interpret text in the query value. | -| max_expansions | [integer] | Maximum number of terms to which the query will expand. | - -**Examples** - -```esql -FROM books -| WHERE MATCH(author, "Faulkner") -| KEEP book_no, author -| SORT book_no -| LIMIT 5 -``` - -| book_no:keyword | author:text | -| --- | --- | -| 2378 | [Carol Faulkner, Holly Byers Ochoa, Lucretia Mott] | -| 2713 | William Faulkner | -| 2847 | Colleen Faulkner | -| 2883 | William Faulkner | -| 3293 | Danny Faulkner | - -```esql -FROM books -| WHERE MATCH(title, "Hobbit Back Again", {"operator": "AND"}) -| KEEP title; -``` - -| title:text | -| --- | -| The Hobbit or There and Back Again | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/max.md b/docs/reference/query-languages/esql/_snippets/functions/max.md deleted file mode 100644 index 972bd6d184b34..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/max.md +++ /dev/null @@ -1,54 +0,0 @@ -## `MAX` [esql-max] - -**Syntax** - -:::{image} ../../../../../images/max.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -The maximum value of a field. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| date | date | -| date_nanos | date_nanos | -| double | double | -| integer | integer | -| ip | ip | -| keyword | keyword | -| long | long | -| text | keyword | -| version | version | - -**Examples** - -```esql -FROM employees -| STATS MAX(languages) -``` - -| MAX(languages):integer | -| --- | -| 5 | - -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 - -```esql -FROM employees -| STATS max_avg_salary_change = MAX(MV_AVG(salary_change)) -``` - -| max_avg_salary_change:double | -| --- | -| 13.75 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/md5.md b/docs/reference/query-languages/esql/_snippets/functions/md5.md deleted file mode 100644 index 1c4f8af49fb52..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/md5.md +++ /dev/null @@ -1,42 +0,0 @@ -## `MD5` [esql-md5] - -**Syntax** - -:::{image} ../../../../../images/md5.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`input` -: Input to hash. - -**Description** - -Computes the MD5 hash of the input. - -**Supported types** - -| input | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -FROM sample_data -| WHERE message != "Connection error" -| EVAL md5 = md5(message) -| KEEP message, md5; -``` - -| message:keyword | md5:keyword | -| --- | --- | -| Connected to 10.1.0.1 | abd7d1ce2bb636842a29246b3512dcae | -| Connected to 10.1.0.2 | 8f8f1cb60832d153f5b9ec6dc828b93f | -| Connected to 10.1.0.3 | 912b6dc13503165a15de43304bb77c78 | -| Disconnected | ef70e46fd3bbc21e3e1f0b6815e750c0 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/median.md b/docs/reference/query-languages/esql/_snippets/functions/median.md deleted file mode 100644 index 896334bccd8d5..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/median.md +++ /dev/null @@ -1,58 +0,0 @@ -## `MEDIAN` [esql-median] - -**Syntax** - -:::{image} ../../../../../images/median.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -The value that is greater than half of all values and less than half of all values, also known as the 50% [`PERCENTILE`](../../esql-functions-operators.md#esql-percentile). - -::::{note} -Like [`PERCENTILE`](../../esql-functions-operators.md#esql-percentile), `MEDIAN` is [usually approximate](../../esql-functions-operators.md#esql-percentile-approximate). -:::: - - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | - -**Examples** - -```esql -FROM employees -| STATS MEDIAN(salary), PERCENTILE(salary, 50) -``` - -| MEDIAN(salary):double | PERCENTILE(salary, 50):double | -| --- | --- | -| 47003 | 47003 | - -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 - -```esql -FROM employees -| STATS median_max_salary_change = MEDIAN(MV_MAX(salary_change)) -``` - -| median_max_salary_change:double | -| --- | -| 7.69 | - -::::{warning} -`MEDIAN` is also [non-deterministic](https://en.wikipedia.org/wiki/Nondeterministic_algorithm). This means you can get slightly different results using the same data. - -:::: - - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/median_absolute_deviation.md b/docs/reference/query-languages/esql/_snippets/functions/median_absolute_deviation.md deleted file mode 100644 index 48d29d34e1932..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/median_absolute_deviation.md +++ /dev/null @@ -1,58 +0,0 @@ -## `MEDIAN_ABSOLUTE_DEVIATION` [esql-median_absolute_deviation] - -**Syntax** - -:::{image} ../../../../../images/median_absolute_deviation.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**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 [`PERCENTILE`](../../esql-functions-operators.md#esql-percentile), `MEDIAN_ABSOLUTE_DEVIATION` is [usually approximate](../../esql-functions-operators.md#esql-percentile-approximate). -:::: - - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | - -**Examples** - -```esql -FROM employees -| STATS MEDIAN(salary), MEDIAN_ABSOLUTE_DEVIATION(salary) -``` - -| MEDIAN(salary):double | MEDIAN_ABSOLUTE_DEVIATION(salary):double | -| --- | --- | -| 47003 | 10096.5 | - -The expression can use inline functions. For example, to calculate 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 - -```esql -FROM employees -| STATS m_a_d_max_salary_change = MEDIAN_ABSOLUTE_DEVIATION(MV_MAX(salary_change)) -``` - -| m_a_d_max_salary_change:double | -| --- | -| 5.69 | - -::::{warning} -`MEDIAN_ABSOLUTE_DEVIATION` is also [non-deterministic](https://en.wikipedia.org/wiki/Nondeterministic_algorithm). This means you can get slightly different results using the same data. - -:::: - - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/min.md b/docs/reference/query-languages/esql/_snippets/functions/min.md deleted file mode 100644 index d1bff0a91cc3e..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/min.md +++ /dev/null @@ -1,54 +0,0 @@ -## `MIN` [esql-min] - -**Syntax** - -:::{image} ../../../../../images/min.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -The minimum value of a field. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| date | date | -| date_nanos | date_nanos | -| double | double | -| integer | integer | -| ip | ip | -| keyword | keyword | -| long | long | -| text | keyword | -| version | version | - -**Examples** - -```esql -FROM employees -| STATS MIN(languages) -``` - -| MIN(languages):integer | -| --- | -| 1 | - -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 - -```esql -FROM employees -| STATS min_avg_salary_change = MIN(MV_AVG(salary_change)) -``` - -| min_avg_salary_change:double | -| --- | -| -8.46 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/mv_append.md b/docs/reference/query-languages/esql/_snippets/functions/mv_append.md deleted file mode 100644 index 4e05cd7204b8b..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/mv_append.md +++ /dev/null @@ -1,39 +0,0 @@ -## `MV_APPEND` [esql-mv_append] - -**Syntax** - -:::{image} ../../../../../images/mv_append.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -Concatenates values of two multi-value fields. - -**Supported types** - -| field1 | field2 | result | -| --- | --- | --- | -| boolean | boolean | boolean | -| cartesian_point | cartesian_point | cartesian_point | -| cartesian_shape | cartesian_shape | cartesian_shape | -| date | date | date | -| date_nanos | date_nanos | date_nanos | -| double | double | double | -| geo_point | geo_point | geo_point | -| geo_shape | geo_shape | geo_shape | -| integer | integer | integer | -| ip | ip | ip | -| keyword | keyword | keyword | -| keyword | text | keyword | -| long | long | long | -| text | keyword | keyword | -| text | text | keyword | -| unsigned_long | unsigned_long | unsigned_long | -| version | version | version | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/mv_avg.md b/docs/reference/query-languages/esql/_snippets/functions/mv_avg.md deleted file mode 100644 index cdcfaec5a13cb..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/mv_avg.md +++ /dev/null @@ -1,39 +0,0 @@ -## `MV_AVG` [esql-mv_avg] - -**Syntax** - -:::{image} ../../../../../images/mv_avg.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Multivalue expression. - -**Description** - -Converts a multivalued field into a single valued field containing the average of all of the values. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=[3, 5, 1, 6] -| EVAL avg_a = MV_AVG(a) -``` - -| a:integer | avg_a:double | -| --- | --- | -| [3, 5, 1, 6] | 3.75 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/mv_concat.md b/docs/reference/query-languages/esql/_snippets/functions/mv_concat.md deleted file mode 100644 index b7ee22745dc44..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/mv_concat.md +++ /dev/null @@ -1,53 +0,0 @@ -## `MV_CONCAT` [esql-mv_concat] - -**Syntax** - -:::{image} ../../../../../images/mv_concat.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: 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** - -| string | delim | result | -| --- | --- | --- | -| keyword | keyword | keyword | -| keyword | text | keyword | -| text | keyword | keyword | -| text | text | keyword | - -**Examples** - -```esql -ROW a=["foo", "zoo", "bar"] -| EVAL j = MV_CONCAT(a, ", ") -``` - -| a:keyword | j:keyword | -| --- | --- | -| ["foo", "zoo", "bar"] | "foo, zoo, bar" | - -To concat non-string columns, call [`TO_STRING`](../../esql-functions-operators.md#esql-to_string) first: - -```esql -ROW a=[10, 9, 8] -| EVAL j = MV_CONCAT(TO_STRING(a), ", ") -``` - -| a:integer | j:keyword | -| --- | --- | -| [10, 9, 8] | "10, 9, 8" | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/mv_count.md b/docs/reference/query-languages/esql/_snippets/functions/mv_count.md deleted file mode 100644 index a193621d6da2e..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/mv_count.md +++ /dev/null @@ -1,50 +0,0 @@ -## `MV_COUNT` [esql-mv_count] - -**Syntax** - -:::{image} ../../../../../images/mv_count.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Multivalue expression. - -**Description** - -Converts a multivalued expression into a single valued column containing a count of the number of values. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | integer | -| cartesian_point | integer | -| cartesian_shape | integer | -| date | integer | -| date_nanos | integer | -| double | integer | -| geo_point | integer | -| geo_shape | integer | -| integer | integer | -| ip | integer | -| keyword | integer | -| long | integer | -| text | integer | -| unsigned_long | integer | -| version | integer | - -**Example** - -```esql -ROW a=["foo", "zoo", "bar"] -| EVAL count_a = MV_COUNT(a) -``` - -| a:keyword | count_a:integer | -| --- | --- | -| ["foo", "zoo", "bar"] | 3 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/mv_dedupe.md b/docs/reference/query-languages/esql/_snippets/functions/mv_dedupe.md deleted file mode 100644 index 2b42466a69e3f..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/mv_dedupe.md +++ /dev/null @@ -1,55 +0,0 @@ -## `MV_DEDUPE` [esql-mv_dedupe] - -**Syntax** - -:::{image} ../../../../../images/mv_dedupe.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Multivalue expression. - -**Description** - -Remove duplicate values from a multivalued field. - -::::{note} -`MV_DEDUPE` may, but won’t always, sort the values in the column. -:::: - - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| cartesian_point | cartesian_point | -| cartesian_shape | cartesian_shape | -| date | date | -| date_nanos | date_nanos | -| double | double | -| geo_point | geo_point | -| geo_shape | geo_shape | -| integer | integer | -| ip | ip | -| keyword | keyword | -| long | long | -| text | keyword | -| unsigned_long | unsigned_long | -| version | version | - -**Example** - -```esql -ROW a=["foo", "foo", "bar", "foo"] -| EVAL dedupe_a = MV_DEDUPE(a) -``` - -| a:keyword | dedupe_a:keyword | -| --- | --- | -| ["foo", "foo", "bar", "foo"] | ["foo", "bar"] | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/mv_first.md b/docs/reference/query-languages/esql/_snippets/functions/mv_first.md deleted file mode 100644 index 8c3f0b1b4dd80..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/mv_first.md +++ /dev/null @@ -1,52 +0,0 @@ -## `MV_FIRST` [esql-mv_first] - -**Syntax** - -:::{image} ../../../../../images/mv_first.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: 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 [`SPLIT`](../../esql-functions-operators.md#esql-split). - -The order that [multivalued fields](/reference/query-languages/esql/esql-multivalued-fields.md) 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 [`MV_MIN`](../../esql-functions-operators.md#esql-mv_min) instead of `MV_FIRST`. `MV_MIN` has optimizations for sorted values so there isn’t a performance benefit to `MV_FIRST`. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| cartesian_point | cartesian_point | -| cartesian_shape | cartesian_shape | -| date | date | -| date_nanos | date_nanos | -| double | double | -| geo_point | geo_point | -| geo_shape | geo_shape | -| integer | integer | -| ip | ip | -| keyword | keyword | -| long | long | -| text | keyword | -| unsigned_long | unsigned_long | -| version | version | - -**Example** - -```esql -ROW a="foo;bar;baz" -| EVAL first_a = MV_FIRST(SPLIT(a, ";")) -``` - -| a:keyword | first_a:keyword | -| --- | --- | -| foo;bar;baz | "foo" | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/mv_last.md b/docs/reference/query-languages/esql/_snippets/functions/mv_last.md deleted file mode 100644 index 4f4f04ff6f52c..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/mv_last.md +++ /dev/null @@ -1,52 +0,0 @@ -## `MV_LAST` [esql-mv_last] - -**Syntax** - -:::{image} ../../../../../images/mv_last.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: 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 [`SPLIT`](../../esql-functions-operators.md#esql-split). - -The order that [multivalued fields](/reference/query-languages/esql/esql-multivalued-fields.md) 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 [`MV_MAX`](../../esql-functions-operators.md#esql-mv_max) instead of `MV_LAST`. `MV_MAX` has optimizations for sorted values so there isn’t a performance benefit to `MV_LAST`. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| cartesian_point | cartesian_point | -| cartesian_shape | cartesian_shape | -| date | date | -| date_nanos | date_nanos | -| double | double | -| geo_point | geo_point | -| geo_shape | geo_shape | -| integer | integer | -| ip | ip | -| keyword | keyword | -| long | long | -| text | keyword | -| unsigned_long | unsigned_long | -| version | version | - -**Example** - -```esql -ROW a="foo;bar;baz" -| EVAL last_a = MV_LAST(SPLIT(a, ";")) -``` - -| a:keyword | last_a:keyword | -| --- | --- | -| foo;bar;baz | "baz" | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/mv_max.md b/docs/reference/query-languages/esql/_snippets/functions/mv_max.md deleted file mode 100644 index 98c92233ef831..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/mv_max.md +++ /dev/null @@ -1,57 +0,0 @@ -## `MV_MAX` [esql-mv_max] - -**Syntax** - -:::{image} ../../../../../images/mv_max.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Multivalue expression. - -**Description** - -Converts a multivalued expression into a single valued column containing the maximum value. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| date | date | -| date_nanos | date_nanos | -| double | double | -| integer | integer | -| ip | ip | -| keyword | keyword | -| long | long | -| text | keyword | -| unsigned_long | unsigned_long | -| version | version | - -**Examples** - -```esql -ROW a=[3, 5, 1] -| EVAL max_a = MV_MAX(a) -``` - -| a:integer | max_a:integer | -| --- | --- | -| [3, 5, 1] | 5 | - -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: - -```esql -ROW a=["foo", "zoo", "bar"] -| EVAL max_a = MV_MAX(a) -``` - -| a:keyword | max_a:keyword | -| --- | --- | -| ["foo", "zoo", "bar"] | "zoo" | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/mv_median.md b/docs/reference/query-languages/esql/_snippets/functions/mv_median.md deleted file mode 100644 index 774ec6d232093..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/mv_median.md +++ /dev/null @@ -1,50 +0,0 @@ -## `MV_MEDIAN` [esql-mv_median] - -**Syntax** - -:::{image} ../../../../../images/mv_median.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Multivalue expression. - -**Description** - -Converts a multivalued field into a single valued field containing the median value. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | integer | -| long | long | -| unsigned_long | unsigned_long | - -**Examples** - -```esql -ROW a=[3, 5, 1] -| EVAL median_a = MV_MEDIAN(a) -``` - -| a:integer | median_a:integer | -| --- | --- | -| [3, 5, 1] | 3 | - -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**: - -```esql -ROW a=[3, 7, 1, 6] -| EVAL median_a = MV_MEDIAN(a) -``` - -| a:integer | median_a:integer | -| --- | --- | -| [3, 7, 1, 6] | 4 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/mv_median_absolute_deviation.md b/docs/reference/query-languages/esql/_snippets/functions/mv_median_absolute_deviation.md deleted file mode 100644 index 5e93efd5b704a..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/mv_median_absolute_deviation.md +++ /dev/null @@ -1,44 +0,0 @@ -## `MV_MEDIAN_ABSOLUTE_DEVIATION` [esql-mv_median_absolute_deviation] - -**Syntax** - -:::{image} ../../../../../images/mv_median_absolute_deviation.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Multivalue expression. - -**Description** - -Converts a multivalued field into a single valued field containing the median absolute 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} -If the field has an even number of values, the medians will be calculated as the average of the middle two values. If the value is not a floating point number, the averages are rounded towards 0. -:::: - - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | integer | -| long | long | -| unsigned_long | unsigned_long | - -**Example** - -```esql -ROW values = [0, 2, 5, 6] -| EVAL median_absolute_deviation = MV_MEDIAN_ABSOLUTE_DEVIATION(values), median = MV_MEDIAN(values) -``` - -| values:integer | median_absolute_deviation:integer | median:integer | -| --- | --- | --- | -| [0, 2, 5, 6] | 2 | 3 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/mv_min.md b/docs/reference/query-languages/esql/_snippets/functions/mv_min.md deleted file mode 100644 index 67cc07dfdd820..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/mv_min.md +++ /dev/null @@ -1,57 +0,0 @@ -## `MV_MIN` [esql-mv_min] - -**Syntax** - -:::{image} ../../../../../images/mv_min.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Multivalue expression. - -**Description** - -Converts a multivalued expression into a single valued column containing the minimum value. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| date | date | -| date_nanos | date_nanos | -| double | double | -| integer | integer | -| ip | ip | -| keyword | keyword | -| long | long | -| text | keyword | -| unsigned_long | unsigned_long | -| version | version | - -**Examples** - -```esql -ROW a=[2, 1] -| EVAL min_a = MV_MIN(a) -``` - -| a:integer | min_a:integer | -| --- | --- | -| [2, 1] | 1 | - -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: - -```esql -ROW a=["foo", "bar"] -| EVAL min_a = MV_MIN(a) -``` - -| a:keyword | min_a:keyword | -| --- | --- | -| ["foo", "bar"] | "bar" | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/mv_percentile.md b/docs/reference/query-languages/esql/_snippets/functions/mv_percentile.md deleted file mode 100644 index f3f596db54641..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/mv_percentile.md +++ /dev/null @@ -1,47 +0,0 @@ -## `MV_PERCENTILE` [esql-mv_percentile] - -**Syntax** - -:::{image} ../../../../../images/mv_percentile.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Multivalue expression. - -`percentile` -: The percentile to calculate. Must be a number between 0 and 100. Numbers out of range will return a null instead. - -**Description** - -Converts a multivalued field into a single valued field containing the value at which a certain percentage of observed values occur. - -**Supported types** - -| number | percentile | result | -| --- | --- | --- | -| double | double | double | -| double | integer | double | -| double | long | double | -| integer | double | integer | -| integer | integer | integer | -| integer | long | integer | -| long | double | long | -| long | integer | long | -| long | long | long | - -**Example** - -```esql -ROW values = [5, 5, 10, 12, 5000] -| EVAL p50 = MV_PERCENTILE(values, 50), median = MV_MEDIAN(values) -``` - -| values:integer | p50:integer | median:integer | -| --- | --- | --- | -| [5, 5, 10, 12, 5000] | 10 | 10 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/mv_pseries_weighted_sum.md b/docs/reference/query-languages/esql/_snippets/functions/mv_pseries_weighted_sum.md deleted file mode 100644 index f3bc647702431..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/mv_pseries_weighted_sum.md +++ /dev/null @@ -1,40 +0,0 @@ -## `MV_PSERIES_WEIGHTED_SUM` [esql-mv_pseries_weighted_sum] - -**Syntax** - -:::{image} ../../../../../images/mv_pseries_weighted_sum.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Multivalue expression. - -`p` -: It is a constant number that represents the *p* parameter in the P-Series. It impacts every element’s contribution to the weighted sum. - -**Description** - -Converts a multivalued expression into a single-valued column by multiplying every element on the input list by its corresponding term in P-Series and computing the sum. - -**Supported types** - -| number | p | result | -| --- | --- | --- | -| double | double | double | - -**Example** - -```esql -ROW a = [70.0, 45.0, 21.0, 21.0, 21.0] -| EVAL sum = MV_PSERIES_WEIGHTED_SUM(a, 1.5) -| KEEP sum -``` - -| sum:double | -| --- | -| 94.45465156212452 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/mv_slice.md b/docs/reference/query-languages/esql/_snippets/functions/mv_slice.md deleted file mode 100644 index 2214f4ce4c16e..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/mv_slice.md +++ /dev/null @@ -1,67 +0,0 @@ -## `MV_SLICE` [esql-mv_slice] - -**Syntax** - -:::{image} ../../../../../images/mv_slice.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Multivalue expression. If `null`, the function returns `null`. - -`start` -: Start position. If `null`, the function returns `null`. The start argument can be negative. An index of -1 is used to specify the last value in the list. - -`end` -: End position(included). Optional; if omitted, the position at `start` is returned. The end argument can be negative. An index of -1 is used to specify the last value in the list. - -**Description** - -Returns a subset of the multivalued field using the start and end index values. This is most useful when reading from a function that emits multivalued columns in a known order like [`SPLIT`](../../esql-functions-operators.md#esql-split) or [`MV_SORT`](../../esql-functions-operators.md#esql-mv_sort). - -The order that [multivalued fields](/reference/query-languages/esql/esql-multivalued-fields.md) are read from underlying storage is not guaranteed. It is **frequently** ascending, but don’t rely on that. - -**Supported types** - -| field | start | end | result | -| --- | --- | --- | --- | -| boolean | integer | integer | boolean | -| cartesian_point | integer | integer | cartesian_point | -| cartesian_shape | integer | integer | cartesian_shape | -| date | integer | integer | date | -| date_nanos | integer | integer | date_nanos | -| double | integer | integer | double | -| geo_point | integer | integer | geo_point | -| geo_shape | integer | integer | geo_shape | -| integer | integer | integer | integer | -| ip | integer | integer | ip | -| keyword | integer | integer | keyword | -| long | integer | integer | long | -| text | integer | integer | keyword | -| unsigned_long | integer | integer | unsigned_long | -| version | integer | integer | version | - -**Examples** - -```esql -row a = [1, 2, 2, 3] -| eval a1 = mv_slice(a, 1), a2 = mv_slice(a, 2, 3) -``` - -| a:integer | a1:integer | a2:integer | -| --- | --- | --- | -| [1, 2, 2, 3] | 2 | [2, 3] | - -```esql -row a = [1, 2, 2, 3] -| eval a1 = mv_slice(a, -2), a2 = mv_slice(a, -3, -1) -``` - -| a:integer | a1:integer | a2:integer | -| --- | --- | --- | -| [1, 2, 2, 3] | 2 | [2, 2, 3] | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/mv_sort.md b/docs/reference/query-languages/esql/_snippets/functions/mv_sort.md deleted file mode 100644 index d68414c8baf5c..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/mv_sort.md +++ /dev/null @@ -1,48 +0,0 @@ -## `MV_SORT` [esql-mv_sort] - -**Syntax** - -:::{image} ../../../../../images/mv_sort.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Multivalue expression. If `null`, the function returns `null`. - -`order` -: Sort order. The valid options are ASC and DESC, the default is ASC. - -**Description** - -Sorts a multivalued field in lexicographical order. - -**Supported types** - -| field | order | result | -| --- | --- | --- | -| boolean | keyword | boolean | -| date | keyword | date | -| date_nanos | keyword | date_nanos | -| double | keyword | double | -| integer | keyword | integer | -| ip | keyword | ip | -| keyword | keyword | keyword | -| long | keyword | long | -| text | keyword | keyword | -| version | keyword | version | - -**Example** - -```esql -ROW a = [4, 2, -3, 2] -| EVAL sa = mv_sort(a), sd = mv_sort(a, "DESC") -``` - -| a:integer | sa:integer | sd:integer | -| --- | --- | --- | -| [4, 2, -3, 2] | [-3, 2, 2, 4] | [4, 2, 2, -3] | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/mv_sum.md b/docs/reference/query-languages/esql/_snippets/functions/mv_sum.md deleted file mode 100644 index f98a19c533d68..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/mv_sum.md +++ /dev/null @@ -1,39 +0,0 @@ -## `MV_SUM` [esql-mv_sum] - -**Syntax** - -:::{image} ../../../../../images/mv_sum.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Multivalue expression. - -**Description** - -Converts a multivalued field into a single valued field containing the sum of all of the values. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | integer | -| long | long | -| unsigned_long | unsigned_long | - -**Example** - -```esql -ROW a=[3, 5, 6] -| EVAL sum_a = MV_SUM(a) -``` - -| a:integer | sum_a:integer | -| --- | --- | -| [3, 5, 6] | 14 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/mv_zip.md b/docs/reference/query-languages/esql/_snippets/functions/mv_zip.md deleted file mode 100644 index c650028850387..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/mv_zip.md +++ /dev/null @@ -1,52 +0,0 @@ -## `MV_ZIP` [esql-mv_zip] - -**Syntax** - -:::{image} ../../../../../images/mv_zip.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string1` -: Multivalue expression. - -`string2` -: Multivalue expression. - -`delim` -: Delimiter. Optional; if omitted, `,` is used as a default delimiter. - -**Description** - -Combines the values from two multivalued fields with a delimiter that joins them together. - -**Supported types** - -| string1 | string2 | delim | result | -| --- | --- | --- | --- | -| keyword | keyword | keyword | keyword | -| keyword | keyword | text | keyword | -| keyword | keyword | | keyword | -| keyword | text | keyword | keyword | -| keyword | text | text | keyword | -| keyword | text | | keyword | -| text | keyword | keyword | keyword | -| text | keyword | text | keyword | -| text | keyword | | keyword | -| text | text | keyword | keyword | -| text | text | text | keyword | -| text | text | | keyword | - -**Example** - -```esql -ROW a = ["x", "y", "z"], b = ["1", "2"] -| EVAL c = mv_zip(a, b, "-") -| KEEP a, b, c -``` - -| a:keyword | b:keyword | c:keyword | -| --- | --- | --- | -| [x, y, z] | [1 ,2] | [x-1, y-2, z] | diff --git a/docs/reference/query-languages/esql/_snippets/functions/now.md b/docs/reference/query-languages/esql/_snippets/functions/now.md deleted file mode 100644 index ddd8c9d3a2f06..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/now.md +++ /dev/null @@ -1,40 +0,0 @@ -## `NOW` [esql-now] - -**Syntax** - -:::{image} ../../../../../images/now.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -**Description** - -Returns current date and time. - -**Supported types** - -| result | -| --- | -| date | - -**Examples** - -```esql -ROW current_date = NOW() -``` - -| y:keyword | -| --- | -| 20 | - -To retrieve logs from the last hour: - -```esql -FROM sample_data -| WHERE @timestamp > NOW() - 1 hour -``` - -| @timestamp:date | client_ip:ip | event_duration:long | message:keyword | -| --- | --- | --- | --- | diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/avg.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/avg.md index fcdef31b7d399..e7b94d1bcf58e 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/parameters/avg.md +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/avg.md @@ -2,4 +2,6 @@ **Parameters** -true +`number` +: Expression that outputs values to average. + diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/count_distinct.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/count_distinct.md index 3cbd20238b144..bd4cc3a7c256d 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/parameters/count_distinct.md +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/count_distinct.md @@ -6,5 +6,5 @@ : Column or literal for which to count the number of distinct values. `precision` -: Precision threshold. Refer to [Counts are approximate](../../../esql-functions-operators.md#esql-agg-count-distinct-approximate). 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. +: Precision threshold. Refer to [`AGG-COUNT-DISTINCT-APPROXIMATE`](/reference/query-languages/esql/esql-functions-operators.md#esql-agg-count-distinct-approximate). 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. diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/date_extract.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/date_extract.md index 2d27891eaa092..d012764bdc2e6 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/parameters/date_extract.md +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/date_extract.md @@ -3,7 +3,7 @@ **Parameters** `datePart` -: 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 [java.time.temporal.ChronoField](https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoField.md) for a description of these values. If `null`, the function returns `null`. +: 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 [java.time.temporal.ChronoField](https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoField.html) for a description of these values. If `null`, the function returns `null`. `date` : Date expression. If `null`, the function returns `null`. diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/date_parse.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/date_parse.md index c047d03738bd4..d6d9989791a93 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/parameters/date_parse.md +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/date_parse.md @@ -3,7 +3,7 @@ **Parameters** `datePattern` -: The date format. Refer to the [`DateTimeFormatter` documentation](https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.md) for the syntax. If `null`, the function returns `null`. +: The date format. Refer to the [`DateTimeFormatter` documentation](https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html) for the syntax. If `null`, the function returns `null`. `dateString` : Date expression as a string. If `null` or an empty string, the function returns `null`. diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/max.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/max.md index fcdef31b7d399..dfc1ab45f403e 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/parameters/max.md +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/max.md @@ -2,4 +2,6 @@ **Parameters** -true +`field` +: + diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/median.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/median.md index fcdef31b7d399..29f5fc9d81a32 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/parameters/median.md +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/median.md @@ -2,4 +2,6 @@ **Parameters** -true +`number` +: Expression that outputs values to calculate the median of. + diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/median_absolute_deviation.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/median_absolute_deviation.md index fcdef31b7d399..9c8b3b3d004bb 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/parameters/median_absolute_deviation.md +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/median_absolute_deviation.md @@ -2,4 +2,6 @@ **Parameters** -true +`number` +: + diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/min.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/min.md index fcdef31b7d399..dfc1ab45f403e 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/parameters/min.md +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/min.md @@ -2,4 +2,6 @@ **Parameters** -true +`field` +: + diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/mv_append.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/mv_append.md index fcdef31b7d399..99bd3bf00d519 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/parameters/mv_append.md +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/mv_append.md @@ -2,4 +2,9 @@ **Parameters** -true +`field1` +: + +`field2` +: + diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/percentile.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/percentile.md index fcdef31b7d399..f68e30979e0bc 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/parameters/percentile.md +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/percentile.md @@ -2,4 +2,9 @@ **Parameters** -true +`number` +: + +`percentile` +: + diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/st_centroid_agg.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/st_centroid_agg.md index fcdef31b7d399..dfc1ab45f403e 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/parameters/st_centroid_agg.md +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/st_centroid_agg.md @@ -2,4 +2,6 @@ **Parameters** -true +`field` +: + diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/st_extent_agg.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/st_extent_agg.md index fcdef31b7d399..dfc1ab45f403e 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/parameters/st_extent_agg.md +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/st_extent_agg.md @@ -2,4 +2,6 @@ **Parameters** -true +`field` +: + diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/std_dev.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/std_dev.md index fcdef31b7d399..9c8b3b3d004bb 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/parameters/std_dev.md +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/std_dev.md @@ -2,4 +2,6 @@ **Parameters** -true +`number` +: + diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/sum.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/sum.md index fcdef31b7d399..9c8b3b3d004bb 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/parameters/sum.md +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/sum.md @@ -2,4 +2,6 @@ **Parameters** -true +`number` +: + diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/term.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/term.md new file mode 100644 index 0000000000000..156e01fdab550 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/term.md @@ -0,0 +1,10 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +**Parameters** + +`field` +: Field that the query will target. + +`query` +: Term you wish to find in the provided field. + diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/values.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/values.md index fcdef31b7d399..dfc1ab45f403e 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/parameters/values.md +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/values.md @@ -2,4 +2,6 @@ **Parameters** -true +`field` +: + diff --git a/docs/reference/query-languages/esql/_snippets/functions/pi.md b/docs/reference/query-languages/esql/_snippets/functions/pi.md deleted file mode 100644 index e860c3e5476ff..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/pi.md +++ /dev/null @@ -1,32 +0,0 @@ -## `PI` [esql-pi] - -**Syntax** - -:::{image} ../../../../../images/pi.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -**Description** - -Returns [Pi](https://en.wikipedia.org/wiki/Pi), the ratio of a circle’s circumference to its diameter. - -**Supported types** - -| result | -| --- | -| double | - -**Example** - -```esql -ROW PI() -``` - -| PI():double | -| --- | -| 3.141592653589793 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/pow.md b/docs/reference/query-languages/esql/_snippets/functions/pow.md deleted file mode 100644 index 13db5f93e0a3b..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/pow.md +++ /dev/null @@ -1,70 +0,0 @@ -## `POW` [esql-pow] - -**Syntax** - -:::{image} ../../../../../images/pow.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`base` -: Numeric expression for the base. If `null`, the function returns `null`. - -`exponent` -: Numeric expression for the exponent. If `null`, the function returns `null`. - -**Description** - -Returns the value of `base` raised to the power of `exponent`. - -::::{note} -It is still possible to overflow a double result here; in that case, null will be returned. -:::: - - -**Supported types** - -| base | exponent | 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 | - -**Examples** - -```esql -ROW base = 2.0, exponent = 2 -| EVAL result = POW(base, exponent) -``` - -| base:double | exponent:integer | result:double | -| --- | --- | --- | -| 2.0 | 2 | 4.0 | - -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: - -```esql -ROW base = 4, exponent = 0.5 -| EVAL s = POW(base, exponent) -``` - -| base:integer | exponent:double | s:double | -| --- | --- | --- | -| 4 | 0.5 | 2.0 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/qstr.md b/docs/reference/query-languages/esql/_snippets/functions/qstr.md deleted file mode 100644 index 76b913dc1e97a..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/qstr.md +++ /dev/null @@ -1,47 +0,0 @@ -## `QSTR` [esql-qstr] - -::::{warning} -Do not use 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. -:::: - - -**Syntax** - -:::{image} ../../../../../images/qstr.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`query` -: Query string in Lucene query string format. - -**Description** - -Performs a [query string query](/reference/query-languages/query-dsl-query-string-query.md). Returns true if the provided query string matches the row. - -**Supported types** - -| query | result | -| --- | --- | -| keyword | boolean | -| text | boolean | - -**Example** - -```esql -FROM books -| WHERE QSTR("author: Faulkner") -| KEEP book_no, author -| SORT book_no -| LIMIT 5 -``` - -| book_no:keyword | author:text | -| --- | --- | -| 2378 | [Carol Faulkner, Holly Byers Ochoa, Lucretia Mott] | -| 2713 | William Faulkner | -| 2847 | Colleen Faulkner | -| 2883 | William Faulkner | -| 3293 | Danny Faulkner | diff --git a/docs/reference/query-languages/esql/_snippets/functions/repeat.md b/docs/reference/query-languages/esql/_snippets/functions/repeat.md deleted file mode 100644 index 40a3adb6f0701..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/repeat.md +++ /dev/null @@ -1,40 +0,0 @@ -## `REPEAT` [esql-repeat] - -**Syntax** - -:::{image} ../../../../../images/repeat.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. - -`number` -: Number times to repeat. - -**Description** - -Returns a string constructed by concatenating `string` with itself the specified `number` of times. - -**Supported types** - -| string | number | result | -| --- | --- | --- | -| keyword | integer | keyword | -| text | integer | keyword | - -**Example** - -```esql -ROW a = "Hello!" -| EVAL triple_a = REPEAT(a, 3) -``` - -| a:keyword | triple_a:keyword | -| --- | --- | -| Hello! | Hello!Hello!Hello! | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/replace.md b/docs/reference/query-languages/esql/_snippets/functions/replace.md deleted file mode 100644 index e64f3bb664a4e..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/replace.md +++ /dev/null @@ -1,52 +0,0 @@ -## `REPLACE` [esql-replace] - -**Syntax** - -:::{image} ../../../../../images/replace.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. - -`regex` -: Regular expression. - -`newString` -: Replacement string. - -**Description** - -The function substitutes in the string `str` any match of the regular expression `regex` with the replacement string `newStr`. - -**Supported types** - -| string | regex | newString | result | -| --- | --- | --- | --- | -| keyword | keyword | keyword | keyword | -| keyword | keyword | text | keyword | -| keyword | text | keyword | keyword | -| keyword | text | text | keyword | -| text | keyword | keyword | keyword | -| text | keyword | text | keyword | -| text | text | keyword | keyword | -| text | text | text | keyword | - -**Example** - -This example replaces any occurrence of the word "World" with the word "Universe": - -```esql -ROW str = "Hello World" -| EVAL str = REPLACE(str, "World", "Universe") -| KEEP str -``` - -| str:keyword | -| --- | -| Hello Universe | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/reverse.md b/docs/reference/query-languages/esql/_snippets/functions/reverse.md deleted file mode 100644 index d68f2334e2cf2..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/reverse.md +++ /dev/null @@ -1,46 +0,0 @@ -## `REVERSE` [esql-reverse] - -**Syntax** - -:::{image} ../../../../../images/reverse.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`str` -: String expression. If `null`, the function returns `null`. - -**Description** - -Returns a new string representing the input string in reverse order. - -**Supported types** - -| str | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Examples** - -```esql -ROW message = "Some Text" | EVAL message_reversed = REVERSE(message); -``` - -| message:keyword | message_reversed:keyword | -| --- | --- | -| Some Text | txeT emoS | - -`REVERSE` works with unicode, too! It keeps unicode grapheme clusters together during reversal. - -```esql -ROW bending_arts = "💧🪨🔥💨" | EVAL bending_arts_reversed = REVERSE(bending_arts); -``` - -| bending_arts:keyword | bending_arts_reversed:keyword | -| --- | --- | -| 💧🪨🔥💨 | 💨🔥🪨💧 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/right.md b/docs/reference/query-languages/esql/_snippets/functions/right.md deleted file mode 100644 index 7b40f104cd980..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/right.md +++ /dev/null @@ -1,47 +0,0 @@ -## `RIGHT` [esql-right] - -**Syntax** - -:::{image} ../../../../../images/right.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: 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** - -| string | length | result | -| --- | --- | --- | -| keyword | integer | keyword | -| text | integer | keyword | - -**Example** - -```esql -FROM employees -| KEEP last_name -| EVAL right = RIGHT(last_name, 3) -| SORT last_name ASC -| LIMIT 5 -``` - -| last_name:keyword | right:keyword | -| --- | --- | -| Awdeh | deh | -| Azuma | uma | -| Baek | aek | -| Bamford | ord | -| Bernatsky | sky | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/round.md b/docs/reference/query-languages/esql/_snippets/functions/round.md deleted file mode 100644 index 7d8be072180b2..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/round.md +++ /dev/null @@ -1,53 +0,0 @@ -## `ROUND` [esql-round] - -**Syntax** - -:::{image} ../../../../../images/round.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: The numeric value to round. If `null`, the function returns `null`. - -`decimals` -: The number of decimal places to round to. Defaults to 0. If `null`, the function returns `null`. - -**Description** - -Rounds a number to the specified number of decimal places. Defaults to 0, which returns the nearest integer. If the precision is a negative number, rounds to the number of digits left of the decimal point. - -**Supported types** - -| number | decimals | result | -| --- | --- | --- | -| double | integer | double | -| double | long | double | -| double | | double | -| integer | integer | integer | -| integer | long | integer | -| integer | | integer | -| long | integer | long | -| long | long | long | -| long | | long | -| unsigned_long | integer | unsigned_long | -| unsigned_long | long | unsigned_long | -| unsigned_long | | unsigned_long | - -**Example** - -```esql -FROM employees -| KEEP first_name, last_name, height -| EVAL height_ft = ROUND(height * 3.281, 1) -``` - -| first_name:keyword | last_name:keyword | height:double | height_ft:double | -| --- | --- | --- | --- | -| Arumugam | Ossenbruggen | 2.1 | 6.9 | -| Kwee | Schusler | 2.1 | 6.9 | -| Saniya | Kalloufi | 2.1 | 6.9 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/rtrim.md b/docs/reference/query-languages/esql/_snippets/functions/rtrim.md deleted file mode 100644 index 804c1e20d3562..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/rtrim.md +++ /dev/null @@ -1,40 +0,0 @@ -## `RTRIM` [esql-rtrim] - -**Syntax** - -:::{image} ../../../../../images/rtrim.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. If `null`, the function returns `null`. - -**Description** - -Removes trailing whitespaces from a string. - -**Supported types** - -| string | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -ROW message = " some text ", color = " red " -| EVAL message = RTRIM(message) -| EVAL color = RTRIM(color) -| EVAL message = CONCAT("'", message, "'") -| EVAL color = CONCAT("'", color, "'") -``` - -| message:keyword | color:keyword | -| --- | --- | -| ' some text' | ' red' | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/sha1.md b/docs/reference/query-languages/esql/_snippets/functions/sha1.md deleted file mode 100644 index 6ada5110970a1..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/sha1.md +++ /dev/null @@ -1,42 +0,0 @@ -## `SHA1` [esql-sha1] - -**Syntax** - -:::{image} ../../../../../images/sha1.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`input` -: Input to hash. - -**Description** - -Computes the SHA1 hash of the input. - -**Supported types** - -| input | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -FROM sample_data -| WHERE message != "Connection error" -| EVAL sha1 = sha1(message) -| KEEP message, sha1; -``` - -| message:keyword | sha1:keyword | -| --- | --- | -| Connected to 10.1.0.1 | 42b85531a79088036a17759db7d2de292b92f57f | -| Connected to 10.1.0.2 | d30db445da2e9237c9718d0c7e4fb7cbbe9c2cb4 | -| Connected to 10.1.0.3 | 2733848d943809f0b10cad3e980763e88afb9853 | -| Disconnected | 771e05f27b99fd59f638f41a7a4e977b1d4691fe | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/sha256.md b/docs/reference/query-languages/esql/_snippets/functions/sha256.md deleted file mode 100644 index 4c5736dc7d3bf..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/sha256.md +++ /dev/null @@ -1,42 +0,0 @@ -## `SHA256` [esql-sha256] - -**Syntax** - -:::{image} ../../../../../images/sha256.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`input` -: Input to hash. - -**Description** - -Computes the SHA256 hash of the input. - -**Supported types** - -| input | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -FROM sample_data -| WHERE message != "Connection error" -| EVAL sha256 = sha256(message) -| KEEP message, sha256; -``` - -| message:keyword | sha256:keyword | -| --- | --- | -| Connected to 10.1.0.1 | 6d8372129ad78770f7185554dd39864749a62690216460752d6c075fa38ad85c | -| Connected to 10.1.0.2 | b0db24720f15857091b3c99f4c4833586d0ea3229911b8777efb8d917cf27e9a | -| Connected to 10.1.0.3 | 75b0480188db8acc4d5cc666a51227eb2bc5b989cd8ca912609f33e0846eff57 | -| Disconnected | 04dfac3671b494ad53fcd152f7a14511bfb35747278aad8ce254a0d6e4ba4718 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/signum.md b/docs/reference/query-languages/esql/_snippets/functions/signum.md deleted file mode 100644 index f442874e42e10..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/signum.md +++ /dev/null @@ -1,39 +0,0 @@ -## `SIGNUM` [esql-signum] - -**Syntax** - -:::{image} ../../../../../images/signum.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the sign of the given number. It returns `-1` for negative numbers, `0` for `0` and `1` for positive numbers. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW d = 100.0 -| EVAL s = SIGNUM(d) -``` - -| d: double | s:double | -| --- | --- | -| 100 | 1.0 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/sin.md b/docs/reference/query-languages/esql/_snippets/functions/sin.md deleted file mode 100644 index 74433e4358e6c..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/sin.md +++ /dev/null @@ -1,39 +0,0 @@ -## `SIN` [esql-sin] - -**Syntax** - -:::{image} ../../../../../images/sin.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`angle` -: An angle, in radians. If `null`, the function returns `null`. - -**Description** - -Returns the [sine](https://en.wikipedia.org/wiki/Sine_and_cosine) of an angle. - -**Supported types** - -| angle | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=1.8 -| EVAL sin=SIN(a) -``` - -| a:double | sin:double | -| --- | --- | -| 1.8 | 0.9738476308781951 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/sinh.md b/docs/reference/query-languages/esql/_snippets/functions/sinh.md deleted file mode 100644 index ede499bdec4ff..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/sinh.md +++ /dev/null @@ -1,39 +0,0 @@ -## `SINH` [esql-sinh] - -**Syntax** - -:::{image} ../../../../../images/sinh.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the [hyperbolic sine](https://en.wikipedia.org/wiki/Hyperbolic_functions) of a number. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=1.8 -| EVAL sinh=SINH(a) -``` - -| a:double | sinh:double | -| --- | --- | -| 1.8 | 2.94217428809568 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/space.md b/docs/reference/query-languages/esql/_snippets/functions/space.md deleted file mode 100644 index 4cab255371ba1..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/space.md +++ /dev/null @@ -1,35 +0,0 @@ -## `SPACE` [esql-space] - -**Syntax** - -:::{image} ../../../../../images/space.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Number of spaces in result. - -**Description** - -Returns a string made of `number` spaces. - -**Supported types** - -| number | result | -| --- | --- | -| integer | keyword | - -**Example** - -```esql -ROW message = CONCAT("Hello", SPACE(1), "World!"); -``` - -| message:keyword | -| --- | -| Hello World! | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/split.md b/docs/reference/query-languages/esql/_snippets/functions/split.md deleted file mode 100644 index 4e2a27bb25ec0..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/split.md +++ /dev/null @@ -1,42 +0,0 @@ -## `SPLIT` [esql-split] - -**Syntax** - -:::{image} ../../../../../images/split.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. If `null`, the function returns `null`. - -`delim` -: Delimiter. Only single byte delimiters are currently supported. - -**Description** - -Split a single valued string into multiple strings. - -**Supported types** - -| string | delim | result | -| --- | --- | --- | -| keyword | keyword | keyword | -| keyword | text | keyword | -| text | keyword | keyword | -| text | text | keyword | - -**Example** - -```esql -ROW words="foo;bar;baz;qux;quux;corge" -| EVAL word = SPLIT(words, ";") -``` - -| words:keyword | word:keyword | -| --- | --- | -| foo;bar;baz;qux;quux;corge | [foo,bar,baz,qux,quux,corge] | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/sqrt.md b/docs/reference/query-languages/esql/_snippets/functions/sqrt.md deleted file mode 100644 index 3bf81d45b9cce..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/sqrt.md +++ /dev/null @@ -1,39 +0,0 @@ -## `SQRT` [esql-sqrt] - -**Syntax** - -:::{image} ../../../../../images/sqrt.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: 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 and infinities are null. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW d = 100.0 -| EVAL s = SQRT(d) -``` - -| d: double | s:double | -| --- | --- | -| 100.0 | 10.0 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/st_centroid_agg.md b/docs/reference/query-languages/esql/_snippets/functions/st_centroid_agg.md deleted file mode 100644 index ede265126ed4f..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/st_centroid_agg.md +++ /dev/null @@ -1,35 +0,0 @@ -## `ST_CENTROID_AGG` [esql-st_centroid_agg] - -**Syntax** - -:::{image} ../../../../../images/st_centroid_agg.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -Calculate the spatial centroid over a field with spatial point geometry type. - -**Supported types** - -| field | result | -| --- | --- | -| cartesian_point | cartesian_point | -| geo_point | geo_point | - -**Example** - -```esql -FROM airports -| STATS centroid=ST_CENTROID_AGG(location) -``` - -| centroid:geo_point | -| --- | -| POINT(-0.030548143003023033 24.37553649504829) | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/st_contains.md b/docs/reference/query-languages/esql/_snippets/functions/st_contains.md deleted file mode 100644 index 823e19494ed70..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/st_contains.md +++ /dev/null @@ -1,47 +0,0 @@ -## `ST_CONTAINS` [esql-st_contains] - -**Syntax** - -:::{image} ../../../../../images/st_contains.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`geomA` -: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. - -`geomB` -: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine `geo_*` and `cartesian_*` parameters. - -**Description** - -Returns whether the first geometry contains the second geometry. This is the inverse of the [ST_WITHIN](../../esql-functions-operators.md#esql-st_within) function. - -**Supported types** - -| geomA | geomB | result | -| --- | --- | --- | -| cartesian_point | cartesian_point | boolean | -| cartesian_point | cartesian_shape | boolean | -| cartesian_shape | cartesian_point | boolean | -| cartesian_shape | cartesian_shape | boolean | -| geo_point | geo_point | boolean | -| geo_point | geo_shape | boolean | -| geo_shape | geo_point | boolean | -| geo_shape | geo_shape | boolean | - -**Example** - -```esql -FROM airport_city_boundaries -| WHERE ST_CONTAINS(city_boundary, TO_GEOSHAPE("POLYGON((109.35 18.3, 109.45 18.3, 109.45 18.4, 109.35 18.4, 109.35 18.3))")) -| KEEP abbrev, airport, region, city, city_location -``` - -| abbrev:keyword | airport:text | region:text | city:keyword | city_location:geo_point | -| --- | --- | --- | --- | --- | -| SYX | Sanya Phoenix Int’l | 天涯区 | Sanya | POINT(109.5036 18.2533) | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/st_disjoint.md b/docs/reference/query-languages/esql/_snippets/functions/st_disjoint.md deleted file mode 100644 index 90bafb1fa7493..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/st_disjoint.md +++ /dev/null @@ -1,47 +0,0 @@ -## `ST_DISJOINT` [esql-st_disjoint] - -**Syntax** - -:::{image} ../../../../../images/st_disjoint.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`geomA` -: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. - -`geomB` -: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine `geo_*` and `cartesian_*` parameters. - -**Description** - -Returns whether the two geometries or geometry columns are disjoint. This is the inverse of the [ST_INTERSECTS](../../esql-functions-operators.md#esql-st_intersects) function. In mathematical terms: ST_Disjoint(A, B) ⇔ A ⋂ B = ∅ - -**Supported types** - -| geomA | geomB | result | -| --- | --- | --- | -| cartesian_point | cartesian_point | boolean | -| cartesian_point | cartesian_shape | boolean | -| cartesian_shape | cartesian_point | boolean | -| cartesian_shape | cartesian_shape | boolean | -| geo_point | geo_point | boolean | -| geo_point | geo_shape | boolean | -| geo_shape | geo_point | boolean | -| geo_shape | geo_shape | boolean | - -**Example** - -```esql -FROM airport_city_boundaries -| WHERE ST_DISJOINT(city_boundary, TO_GEOSHAPE("POLYGON((-10 -60, 120 -60, 120 60, -10 60, -10 -60))")) -| KEEP abbrev, airport, region, city, city_location -``` - -| abbrev:keyword | airport:text | region:text | city:keyword | city_location:geo_point | -| --- | --- | --- | --- | --- | -| ACA | General Juan N Alvarez Int’l | Acapulco de Juárez | Acapulco de Juárez | POINT (-99.8825 16.8636) | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/st_distance.md b/docs/reference/query-languages/esql/_snippets/functions/st_distance.md deleted file mode 100644 index ac7b38bdf1b01..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/st_distance.md +++ /dev/null @@ -1,42 +0,0 @@ -## `ST_DISTANCE` [esql-st_distance] - -**Syntax** - -:::{image} ../../../../../images/st_distance.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`geomA` -: Expression of type `geo_point` or `cartesian_point`. If `null`, the function returns `null`. - -`geomB` -: Expression of type `geo_point` or `cartesian_point`. If `null`, the function returns `null`. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine `geo_point` and `cartesian_point` parameters. - -**Description** - -Computes the distance between two points. For cartesian geometries, this is the pythagorean distance in the same units as the original coordinates. For geographic geometries, this is the circular distance along the great circle in meters. - -**Supported types** - -| geomA | geomB | result | -| --- | --- | --- | -| cartesian_point | cartesian_point | double | -| geo_point | geo_point | double | - -**Example** - -```esql -FROM airports -| WHERE abbrev == "CPH" -| EVAL distance = ST_DISTANCE(location, city_location) -| KEEP abbrev, name, location, city_location, distance -``` - -| abbrev:k | name:text | location:geo_point | city_location:geo_point | distance:d | -| --- | --- | --- | --- | --- | -| CPH | Copenhagen | POINT(12.6493508684508 55.6285017221528) | POINT(12.5683 55.6761) | 7339.573896618216 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/st_envelope.md b/docs/reference/query-languages/esql/_snippets/functions/st_envelope.md deleted file mode 100644 index 15a627bdf1872..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/st_envelope.md +++ /dev/null @@ -1,41 +0,0 @@ -## `ST_ENVELOPE` [esql-st_envelope] - -**Syntax** - -:::{image} ../../../../../images/st_envelope.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`geometry` -: Expression of type `geo_point`, `geo_shape`, `cartesian_point` or `cartesian_shape`. If `null`, the function returns `null`. - -**Description** - -Determines the minimum bounding box of the supplied geometry. - -**Supported types** - -| geometry | result | -| --- | --- | -| cartesian_point | cartesian_shape | -| cartesian_shape | cartesian_shape | -| geo_point | geo_shape | -| geo_shape | geo_shape | - -**Example** - -```esql -FROM airport_city_boundaries -| WHERE abbrev == "CPH" -| EVAL envelope = ST_ENVELOPE(city_boundary) -| KEEP abbrev, airport, envelope -``` - -| abbrev:keyword | airport:text | envelope:geo_shape | -| --- | --- | --- | -| CPH | Copenhagen | BBOX(12.453, 12.6398, 55.7327, 55.6318) | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/st_extent_agg.md b/docs/reference/query-languages/esql/_snippets/functions/st_extent_agg.md deleted file mode 100644 index 96ee06baf30c9..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/st_extent_agg.md +++ /dev/null @@ -1,38 +0,0 @@ -## `ST_EXTENT_AGG` [esql-st_extent_agg] - -**Syntax** - -:::{image} ../../../../../images/st_extent_agg.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -Calculate the spatial extent over a field with geometry type. Returns a bounding box for all values of the field. - -**Supported types** - -| field | result | -| --- | --- | -| cartesian_point | cartesian_shape | -| cartesian_shape | cartesian_shape | -| geo_point | geo_shape | -| geo_shape | geo_shape | - -**Example** - -```esql -FROM airports -| WHERE country == "India" -| STATS extent = ST_EXTENT_AGG(location) -``` - -| extent:geo_shape | -| --- | -| BBOX (70.77995480038226, 91.5882289968431, 33.9830909203738, 8.47650992218405) | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/st_intersects.md b/docs/reference/query-languages/esql/_snippets/functions/st_intersects.md deleted file mode 100644 index 7d030689d6725..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/st_intersects.md +++ /dev/null @@ -1,46 +0,0 @@ -## `ST_INTERSECTS` [esql-st_intersects] - -**Syntax** - -:::{image} ../../../../../images/st_intersects.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`geomA` -: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. - -`geomB` -: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine `geo_*` and `cartesian_*` parameters. - -**Description** - -Returns true if two geometries intersect. They intersect if they have any point in common, including their interior points (points along lines or within polygons). This is the inverse of the [ST_DISJOINT](../../esql-functions-operators.md#esql-st_disjoint) function. In mathematical terms: ST_Intersects(A, B) ⇔ A ⋂ B ≠ ∅ - -**Supported types** - -| geomA | geomB | result | -| --- | --- | --- | -| cartesian_point | cartesian_point | boolean | -| cartesian_point | cartesian_shape | boolean | -| cartesian_shape | cartesian_point | boolean | -| cartesian_shape | cartesian_shape | boolean | -| geo_point | geo_point | boolean | -| geo_point | geo_shape | boolean | -| geo_shape | geo_point | boolean | -| geo_shape | geo_shape | boolean | - -**Example** - -```esql -FROM airports -| WHERE ST_INTERSECTS(location, TO_GEOSHAPE("POLYGON((42 14, 43 14, 43 15, 42 15, 42 14))")) -``` - -| abbrev:keyword | city:keyword | city_location:geo_point | country:keyword | location:geo_point | name:text | scalerank:i | type:k | -| --- | --- | --- | --- | --- | --- | --- | --- | -| HOD | Al Ḩudaydah | POINT(42.9511 14.8022) | Yemen | POINT(42.97109630194 14.7552534413725) | Hodeidah Int’l | 9 | mid | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/st_within.md b/docs/reference/query-languages/esql/_snippets/functions/st_within.md deleted file mode 100644 index 21d7386db01b7..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/st_within.md +++ /dev/null @@ -1,47 +0,0 @@ -## `ST_WITHIN` [esql-st_within] - -**Syntax** - -:::{image} ../../../../../images/st_within.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`geomA` -: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. - -`geomB` -: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine `geo_*` and `cartesian_*` parameters. - -**Description** - -Returns whether the first geometry is within the second geometry. This is the inverse of the [ST_CONTAINS](../../esql-functions-operators.md#esql-st_contains) function. - -**Supported types** - -| geomA | geomB | result | -| --- | --- | --- | -| cartesian_point | cartesian_point | boolean | -| cartesian_point | cartesian_shape | boolean | -| cartesian_shape | cartesian_point | boolean | -| cartesian_shape | cartesian_shape | boolean | -| geo_point | geo_point | boolean | -| geo_point | geo_shape | boolean | -| geo_shape | geo_point | boolean | -| geo_shape | geo_shape | boolean | - -**Example** - -```esql -FROM airport_city_boundaries -| WHERE ST_WITHIN(city_boundary, TO_GEOSHAPE("POLYGON((109.1 18.15, 109.6 18.15, 109.6 18.65, 109.1 18.65, 109.1 18.15))")) -| KEEP abbrev, airport, region, city, city_location -``` - -| abbrev:keyword | airport:text | region:text | city:keyword | city_location:geo_point | -| --- | --- | --- | --- | --- | -| SYX | Sanya Phoenix Int’l | 天涯区 | Sanya | POINT(109.5036 18.2533) | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/st_x.md b/docs/reference/query-languages/esql/_snippets/functions/st_x.md deleted file mode 100644 index 8f12121b72dc7..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/st_x.md +++ /dev/null @@ -1,37 +0,0 @@ -## `ST_X` [esql-st_x] - -**Syntax** - -:::{image} ../../../../../images/st_x.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`point` -: Expression of type `geo_point` or `cartesian_point`. If `null`, the function returns `null`. - -**Description** - -Extracts the `x` coordinate from the supplied point. If the points is of type `geo_point` this is equivalent to extracting the `longitude` value. - -**Supported types** - -| point | result | -| --- | --- | -| cartesian_point | double | -| geo_point | double | - -**Example** - -```esql -ROW point = TO_GEOPOINT("POINT(42.97109629958868 14.7552534006536)") -| EVAL x = ST_X(point), y = ST_Y(point) -``` - -| point:geo_point | x:double | y:double | -| --- | --- | --- | -| POINT(42.97109629958868 14.7552534006536) | 42.97109629958868 | 14.7552534006536 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/st_xmax.md b/docs/reference/query-languages/esql/_snippets/functions/st_xmax.md deleted file mode 100644 index 9b34d361918f4..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/st_xmax.md +++ /dev/null @@ -1,42 +0,0 @@ -## `ST_XMAX` [esql-st_xmax] - -**Syntax** - -:::{image} ../../../../../images/st_xmax.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`point` -: Expression of type `geo_point`, `geo_shape`, `cartesian_point` or `cartesian_shape`. If `null`, the function returns `null`. - -**Description** - -Extracts the maximum value of the `x` coordinates from the supplied geometry. If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the maximum `longitude` value. - -**Supported types** - -| point | result | -| --- | --- | -| cartesian_point | double | -| cartesian_shape | double | -| geo_point | double | -| geo_shape | double | - -**Example** - -```esql -FROM airport_city_boundaries -| WHERE abbrev == "CPH" -| EVAL envelope = ST_ENVELOPE(city_boundary) -| EVAL xmin = ST_XMIN(envelope), xmax = ST_XMAX(envelope), ymin = ST_YMIN(envelope), ymax = ST_YMAX(envelope) -| KEEP abbrev, airport, xmin, xmax, ymin, ymax -``` - -| abbrev:keyword | airport:text | xmin:double | xmax:double | ymin:double | ymax:double | -| --- | --- | --- | --- | --- | --- | -| CPH | Copenhagen | 12.453 | 12.6398 | 55.6318 | 55.7327 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/st_xmin.md b/docs/reference/query-languages/esql/_snippets/functions/st_xmin.md deleted file mode 100644 index 11fd9e09736e5..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/st_xmin.md +++ /dev/null @@ -1,42 +0,0 @@ -## `ST_XMIN` [esql-st_xmin] - -**Syntax** - -:::{image} ../../../../../images/st_xmin.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`point` -: Expression of type `geo_point`, `geo_shape`, `cartesian_point` or `cartesian_shape`. If `null`, the function returns `null`. - -**Description** - -Extracts the minimum value of the `x` coordinates from the supplied geometry. If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the minimum `longitude` value. - -**Supported types** - -| point | result | -| --- | --- | -| cartesian_point | double | -| cartesian_shape | double | -| geo_point | double | -| geo_shape | double | - -**Example** - -```esql -FROM airport_city_boundaries -| WHERE abbrev == "CPH" -| EVAL envelope = ST_ENVELOPE(city_boundary) -| EVAL xmin = ST_XMIN(envelope), xmax = ST_XMAX(envelope), ymin = ST_YMIN(envelope), ymax = ST_YMAX(envelope) -| KEEP abbrev, airport, xmin, xmax, ymin, ymax -``` - -| abbrev:keyword | airport:text | xmin:double | xmax:double | ymin:double | ymax:double | -| --- | --- | --- | --- | --- | --- | -| CPH | Copenhagen | 12.453 | 12.6398 | 55.6318 | 55.7327 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/st_y.md b/docs/reference/query-languages/esql/_snippets/functions/st_y.md deleted file mode 100644 index 47e62de3e3c1a..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/st_y.md +++ /dev/null @@ -1,37 +0,0 @@ -## `ST_Y` [esql-st_y] - -**Syntax** - -:::{image} ../../../../../images/st_y.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`point` -: Expression of type `geo_point` or `cartesian_point`. If `null`, the function returns `null`. - -**Description** - -Extracts the `y` coordinate from the supplied point. If the points is of type `geo_point` this is equivalent to extracting the `latitude` value. - -**Supported types** - -| point | result | -| --- | --- | -| cartesian_point | double | -| geo_point | double | - -**Example** - -```esql -ROW point = TO_GEOPOINT("POINT(42.97109629958868 14.7552534006536)") -| EVAL x = ST_X(point), y = ST_Y(point) -``` - -| point:geo_point | x:double | y:double | -| --- | --- | --- | -| POINT(42.97109629958868 14.7552534006536) | 42.97109629958868 | 14.7552534006536 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/st_ymax.md b/docs/reference/query-languages/esql/_snippets/functions/st_ymax.md deleted file mode 100644 index c25b079474cdb..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/st_ymax.md +++ /dev/null @@ -1,42 +0,0 @@ -## `ST_YMAX` [esql-st_ymax] - -**Syntax** - -:::{image} ../../../../../images/st_ymax.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`point` -: Expression of type `geo_point`, `geo_shape`, `cartesian_point` or `cartesian_shape`. If `null`, the function returns `null`. - -**Description** - -Extracts the maximum value of the `y` coordinates from the supplied geometry. If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the maximum `latitude` value. - -**Supported types** - -| point | result | -| --- | --- | -| cartesian_point | double | -| cartesian_shape | double | -| geo_point | double | -| geo_shape | double | - -**Example** - -```esql -FROM airport_city_boundaries -| WHERE abbrev == "CPH" -| EVAL envelope = ST_ENVELOPE(city_boundary) -| EVAL xmin = ST_XMIN(envelope), xmax = ST_XMAX(envelope), ymin = ST_YMIN(envelope), ymax = ST_YMAX(envelope) -| KEEP abbrev, airport, xmin, xmax, ymin, ymax -``` - -| abbrev:keyword | airport:text | xmin:double | xmax:double | ymin:double | ymax:double | -| --- | --- | --- | --- | --- | --- | -| CPH | Copenhagen | 12.453 | 12.6398 | 55.6318 | 55.7327 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/st_ymin.md b/docs/reference/query-languages/esql/_snippets/functions/st_ymin.md deleted file mode 100644 index 59605a314176f..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/st_ymin.md +++ /dev/null @@ -1,40 +0,0 @@ -## `ST_YMIN` [esql-st_ymin] - -**Syntax** - -:::{image} ../../../../../images/st_ymin.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`point` -: Expression of type `geo_point`, `geo_shape`, `cartesian_point` or `cartesian_shape`. If `null`, the function returns `null`. - -**Description** - -Extracts the minimum value of the `y` coordinates from the supplied geometry. If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the minimum `latitude` value. - -**Supported types** - -| point | result | -| --- | --- | -| cartesian_point | double | -| cartesian_shape | double | -| geo_point | double | -| geo_shape | double | - -**Example** - -```esql -FROM airport_city_boundaries -| WHERE abbrev == "CPH" -| EVAL envelope = ST_ENVELOPE(city_boundary) -| EVAL xmin = ST_XMIN(envelope), xmax = ST_XMAX(envelope), ymin = ST_YMIN(envelope), ymax = ST_YMAX(envelope) -| KEEP abbrev, airport, xmin, xmax, ymin, ymax -``` - -| abbrev:keyword | airport:text | xmin:double | xmax:double | ymin:double | ymax:double | -| --- | --- | --- | --- | --- | --- | -| CPH | Copenhagen | 12.453 | 12.6398 | 55.6318 | 55.7327 | diff --git a/docs/reference/query-languages/esql/_snippets/functions/starts_with.md b/docs/reference/query-languages/esql/_snippets/functions/starts_with.md deleted file mode 100644 index 669e01c8049ee..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/starts_with.md +++ /dev/null @@ -1,47 +0,0 @@ -## `STARTS_WITH` [esql-starts_with] - -**Syntax** - -:::{image} ../../../../../images/starts_with.svg -:alt: Embedded -:class: text-center -::: - -**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. - -**Supported types** - -| str | prefix | result | -| --- | --- | --- | -| keyword | keyword | boolean | -| keyword | text | boolean | -| text | keyword | boolean | -| text | text | boolean | - -**Example** - -```esql -FROM employees -| KEEP last_name -| EVAL ln_S = STARTS_WITH(last_name, "B") -``` - -| last_name:keyword | ln_S:boolean | -| --- | --- | -| Awdeh | false | -| Azuma | false | -| Baek | true | -| Bamford | true | -| Bernatsky | true | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/std_dev.md b/docs/reference/query-languages/esql/_snippets/functions/std_dev.md deleted file mode 100644 index 2a7d740397f31..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/std_dev.md +++ /dev/null @@ -1,47 +0,0 @@ -## `STD_DEV` [esql-std_dev] - -**Syntax** - -:::{image} ../../../../../images/std_dev.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -The standard deviation of a numeric field. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | - -**Examples** - -```esql -FROM employees -| STATS STD_DEV(height) -``` - -| STD_DEV(height):double | -| --- | -| 0.20637044362020449 | - -The expression can use inline functions. For example, to calculate the standard deviation of each employee’s maximum salary changes, first use `MV_MAX` on each row, and then use `STD_DEV` on the result - -```esql -FROM employees -| STATS stddev_salary_change = STD_DEV(MV_MAX(salary_change)) -``` - -| stddev_salary_change:double | -| --- | -| 6.875829592924112 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/substring.md b/docs/reference/query-languages/esql/_snippets/functions/substring.md deleted file mode 100644 index b4546196ff1b4..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/substring.md +++ /dev/null @@ -1,82 +0,0 @@ -## `SUBSTRING` [esql-substring] - -**Syntax** - -:::{image} ../../../../../images/substring.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: 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. - -**Supported types** - -| string | start | length | result | -| --- | --- | --- | --- | -| keyword | integer | integer | keyword | -| text | integer | integer | keyword | - -**Examples** - -This example returns the first three characters of every last name: - -```esql -FROM employees -| KEEP last_name -| EVAL ln_sub = SUBSTRING(last_name, 1, 3) -``` - -| last_name:keyword | ln_sub:keyword | -| --- | --- | -| Awdeh | Awd | -| Azuma | Azu | -| Baek | Bae | -| Bamford | Bam | -| Bernatsky | Ber | - -A negative start position is interpreted as being relative to the end of the string. This example returns the last three characters of of every last name: - -```esql -FROM employees -| KEEP last_name -| EVAL ln_sub = SUBSTRING(last_name, -3, 3) -``` - -| last_name:keyword | ln_sub:keyword | -| --- | --- | -| Awdeh | deh | -| Azuma | uma | -| Baek | aek | -| Bamford | ord | -| Bernatsky | sky | - -If length is omitted, substring returns the remainder of the string. This example returns all characters except for the first: - -```esql -FROM employees -| KEEP last_name -| EVAL ln_sub = SUBSTRING(last_name, 2) -``` - -| last_name:keyword | ln_sub:keyword | -| --- | --- | -| Awdeh | wdeh | -| Azuma | zuma | -| Baek | aek | -| Bamford | amford | -| Bernatsky | ernatsky | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/sum.md b/docs/reference/query-languages/esql/_snippets/functions/sum.md deleted file mode 100644 index 2bd438949ffad..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/sum.md +++ /dev/null @@ -1,47 +0,0 @@ -## `SUM` [esql-sum] - -**Syntax** - -:::{image} ../../../../../images/sum.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -The sum of a numeric expression. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | long | -| long | long | - -**Examples** - -```esql -FROM employees -| STATS SUM(languages) -``` - -| SUM(languages):long | -| --- | -| 281 | - -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 - -```esql -FROM employees -| STATS total_salary_changes = SUM(MV_MAX(salary_change)) -``` - -| total_salary_changes:double | -| --- | -| 446.75 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/tan.md b/docs/reference/query-languages/esql/_snippets/functions/tan.md deleted file mode 100644 index 06216e22d79d0..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/tan.md +++ /dev/null @@ -1,39 +0,0 @@ -## `TAN` [esql-tan] - -**Syntax** - -:::{image} ../../../../../images/tan.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`angle` -: An angle, in radians. If `null`, the function returns `null`. - -**Description** - -Returns the [tangent](https://en.wikipedia.org/wiki/Sine_and_cosine) of an angle. - -**Supported types** - -| angle | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=1.8 -| EVAL tan=TAN(a) -``` - -| a:double | tan:double | -| --- | --- | -| 1.8 | -4.286261674628062 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/tanh.md b/docs/reference/query-languages/esql/_snippets/functions/tanh.md deleted file mode 100644 index fa40ed36dab93..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/tanh.md +++ /dev/null @@ -1,39 +0,0 @@ -## `TANH` [esql-tanh] - -**Syntax** - -:::{image} ../../../../../images/tanh.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the [hyperbolic tangent](https://en.wikipedia.org/wiki/Hyperbolic_functions) of a number. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=1.8 -| EVAL tanh=TANH(a) -``` - -| a:double | tanh:double | -| --- | --- | -| 1.8 | 0.9468060128462683 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/tau.md b/docs/reference/query-languages/esql/_snippets/functions/tau.md deleted file mode 100644 index 826deded66641..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/tau.md +++ /dev/null @@ -1,30 +0,0 @@ -## `TAU` [esql-tau] - -**Syntax** - -:::{image} ../../../../../images/tau.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -**Description** - -Returns the [ratio](https://tauday.com/tau-manifesto) of a circle’s circumference to its radius. - -**Supported types** - -| result | -| --- | -| double | - -**Example** - -```esql -ROW TAU() -``` - -| TAU():double | -| --- | -| 6.283185307179586 | diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_base64.md b/docs/reference/query-languages/esql/_snippets/functions/to_base64.md deleted file mode 100644 index aa08b27ccb044..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_base64.md +++ /dev/null @@ -1,37 +0,0 @@ -## `TO_BASE64` [esql-to_base64] - -**Syntax** - -:::{image} ../../../../../images/to_base64.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: A string. - -**Description** - -Encode a string to a base64 string. - -**Supported types** - -| string | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -row a = "elastic" -| eval e = to_base64(a) -``` - -| a:keyword | e:keyword | -| --- | --- | -| elastic | ZWxhc3RpYw== | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_boolean.md b/docs/reference/query-languages/esql/_snippets/functions/to_boolean.md deleted file mode 100644 index b128d5f5ddcec..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_boolean.md +++ /dev/null @@ -1,42 +0,0 @@ -## `TO_BOOLEAN` [esql-to_boolean] - -**Syntax** - -:::{image} ../../../../../images/to_boolean.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: 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**. The numerical value of **0** will be converted to **false**, anything else will be converted to **true**. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| double | boolean | -| integer | boolean | -| keyword | boolean | -| long | boolean | -| text | boolean | -| unsigned_long | boolean | - -**Example** - -```esql -ROW str = ["true", "TRuE", "false", "", "yes", "1"] -| EVAL bool = TO_BOOLEAN(str) -``` - -| str:keyword | bool:boolean | -| --- | --- | -| ["true", "TRuE", "false", "", "yes", "1"] | [true, true, false, false, false, false] | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_cartesianpoint.md b/docs/reference/query-languages/esql/_snippets/functions/to_cartesianpoint.md deleted file mode 100644 index 36d795dccb953..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_cartesianpoint.md +++ /dev/null @@ -1,40 +0,0 @@ -## `TO_CARTESIANPOINT` [esql-to_cartesianpoint] - -**Syntax** - -:::{image} ../../../../../images/to_cartesianpoint.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input value to a `cartesian_point` value. A string will only be successfully converted if it respects the [WKT Point](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -**Supported types** - -| field | result | -| --- | --- | -| cartesian_point | cartesian_point | -| keyword | cartesian_point | -| text | cartesian_point | - -**Example** - -```esql -ROW wkt = ["POINT(4297.11 -1475.53)", "POINT(7580.93 2272.77)"] -| MV_EXPAND wkt -| EVAL pt = TO_CARTESIANPOINT(wkt) -``` - -| wkt:keyword | pt:cartesian_point | -| --- | --- | -| "POINT(4297.11 -1475.53)" | POINT(4297.11 -1475.53) | -| "POINT(7580.93 2272.77)" | POINT(7580.93 2272.77) | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_cartesianshape.md b/docs/reference/query-languages/esql/_snippets/functions/to_cartesianshape.md deleted file mode 100644 index 1f1ab3248a5e5..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_cartesianshape.md +++ /dev/null @@ -1,41 +0,0 @@ -## `TO_CARTESIANSHAPE` [esql-to_cartesianshape] - -**Syntax** - -:::{image} ../../../../../images/to_cartesianshape.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input value to a `cartesian_shape` value. A string will only be successfully converted if it respects the [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -**Supported types** - -| field | result | -| --- | --- | -| cartesian_point | cartesian_shape | -| cartesian_shape | cartesian_shape | -| keyword | cartesian_shape | -| text | cartesian_shape | - -**Example** - -```esql -ROW wkt = ["POINT(4297.11 -1475.53)", "POLYGON ((3339584.72 1118889.97, 4452779.63 4865942.27, 2226389.81 4865942.27, 1113194.90 2273030.92, 3339584.72 1118889.97))"] -| MV_EXPAND wkt -| EVAL geom = TO_CARTESIANSHAPE(wkt) -``` - -| wkt:keyword | geom:cartesian_shape | -| --- | --- | -| "POINT(4297.11 -1475.53)" | POINT(4297.11 -1475.53) | -| "POLYGON 3339584.72 1118889.97, 4452779.63 4865942.27, 2226389.81 4865942.27, 1113194.90 2273030.92, 3339584.72 1118889.97" | POLYGON 3339584.72 1118889.97, 4452779.63 4865942.27, 2226389.81 4865942.27, 1113194.90 2273030.92, 3339584.72 1118889.97 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_date_nanos.md b/docs/reference/query-languages/esql/_snippets/functions/to_date_nanos.md deleted file mode 100644 index ec55cbdc24b9b..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_date_nanos.md +++ /dev/null @@ -1,36 +0,0 @@ -## `TO_DATE_NANOS` [esql-to_date_nanos] - -**Syntax** - -:::{image} ../../../../../images/to_date_nanos.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input to a nanosecond-resolution date value (aka date_nanos). - -::::{note} -The range for date nanos is 1970-01-01T00:00:00.000000000Z to 2262-04-11T23:47:16.854775807Z, attepting to convertvalues outside of that range will result in null with a warning.. Additionally, integers cannot be converted into date nanos, as the range of integer nanoseconds only covers about 2 seconds after epoch. -:::: - - -**Supported types** - -| field | result | -| --- | --- | -| date | date_nanos | -| date_nanos | date_nanos | -| double | date_nanos | -| keyword | date_nanos | -| long | date_nanos | -| text | date_nanos | -| unsigned_long | date_nanos | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_dateperiod.md b/docs/reference/query-languages/esql/_snippets/functions/to_dateperiod.md deleted file mode 100644 index 00226436ee25c..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_dateperiod.md +++ /dev/null @@ -1,37 +0,0 @@ -## `TO_DATEPERIOD` [esql-to_dateperiod] - -**Syntax** - -:::{image} ../../../../../images/to_dateperiod.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input is a valid constant date period expression. - -**Description** - -Converts an input value into a `date_period` value. - -**Supported types** - -| field | result | -| --- | --- | -| date_period | date_period | -| keyword | date_period | -| text | date_period | - -**Example** - -```esql -row x = "2024-01-01"::datetime | eval y = x + "3 DAYS"::date_period, z = x - to_dateperiod("3 days"); -``` - -| x:datetime | y:datetime | z:datetime | -| --- | --- | --- | -| 2024-01-01 | 2024-01-04 | 2023-12-29 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_datetime.md b/docs/reference/query-languages/esql/_snippets/functions/to_datetime.md deleted file mode 100644 index 1920333097795..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_datetime.md +++ /dev/null @@ -1,67 +0,0 @@ -## `TO_DATETIME` [esql-to_datetime] - -**Syntax** - -:::{image} ../../../../../images/to_datetime.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: 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 [`DATE_PARSE`](../../esql-functions-operators.md#esql-date_parse). - -::::{note} -Note that when converting from nanosecond resolution to millisecond resolution with this function, the nanosecond date is truncated, not rounded. -:::: - - -**Supported types** - -| field | result | -| --- | --- | -| date | date | -| date_nanos | date | -| double | date | -| integer | date | -| keyword | date | -| long | date | -| text | date | -| unsigned_long | date | - -**Examples** - -```esql -ROW string = ["1953-09-02T00:00:00.000Z", "1964-06-02T00:00:00.000Z", "1964-06-02 00:00:00"] -| EVAL datetime = TO_DATETIME(string) -``` - -| string:keyword | datetime:date | -| --- | --- | -| ["1953-09-02T00:00:00.000Z", "1964-06-02T00:00:00.000Z", "1964-06-02 00:00:00"] | [1953-09-02T00:00:00.000Z, 1964-06-02T00:00:00.000Z] | - -Note that in this example, the last value in the source multi-valued field has not been converted. The reason being that if the date format is not respected, the conversion will result in a **null** value. When this happens a *Warning* header is added to the response. The header will provide information on the source of the failure: - -`"Line 1:112: evaluation of [TO_DATETIME(string)] failed, treating result as null. "Only first 20 failures recorded."` - -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 [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). For example: - -```esql -ROW int = [0, 1] -| EVAL dt = TO_DATETIME(int) -``` - -| int:integer | dt:date | -| --- | --- | -| [0, 1] | [1970-01-01T00:00:00.000Z, 1970-01-01T00:00:00.001Z] | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_degrees.md b/docs/reference/query-languages/esql/_snippets/functions/to_degrees.md deleted file mode 100644 index 554f703d730df..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_degrees.md +++ /dev/null @@ -1,39 +0,0 @@ -## `TO_DEGREES` [esql-to_degrees] - -**Syntax** - -:::{image} ../../../../../images/to_degrees.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts a number in [radians](https://en.wikipedia.org/wiki/Radian) to [degrees](https://en.wikipedia.org/wiki/Degree_(angle)). - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW rad = [1.57, 3.14, 4.71] -| EVAL deg = TO_DEGREES(rad) -``` - -| rad:double | deg:double | -| --- | --- | -| [1.57, 3.14, 4.71] | [89.95437383553924, 179.9087476710785, 269.86312150661774] | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_double.md b/docs/reference/query-languages/esql/_snippets/functions/to_double.md deleted file mode 100644 index 1be1cba98863e..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_double.md +++ /dev/null @@ -1,52 +0,0 @@ -## `TO_DOUBLE` [esql-to_double] - -**Syntax** - -:::{image} ../../../../../images/to_double.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input value to a double value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to double. Boolean **true** will be converted to double **1.0**, **false** to **0.0**. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | double | -| counter_double | double | -| counter_integer | double | -| counter_long | double | -| date | double | -| double | double | -| integer | double | -| keyword | double | -| long | double | -| text | double | -| unsigned_long | double | - -**Example** - -```esql -ROW str1 = "5.20128E11", str2 = "foo" -| EVAL dbl = TO_DOUBLE("520128000000"), dbl1 = TO_DOUBLE(str1), dbl2 = TO_DOUBLE(str2) -``` - -| str1:keyword | str2:keyword | dbl:double | dbl1:double | dbl2:double | -| --- | --- | --- | --- | --- | -| 5.20128E11 | foo | 5.20128E11 | 5.20128E11 | null | - -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""` - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_geopoint.md b/docs/reference/query-languages/esql/_snippets/functions/to_geopoint.md deleted file mode 100644 index 9ac53053a19f3..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_geopoint.md +++ /dev/null @@ -1,38 +0,0 @@ -## `TO_GEOPOINT` [esql-to_geopoint] - -**Syntax** - -:::{image} ../../../../../images/to_geopoint.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input value to a `geo_point` value. A string will only be successfully converted if it respects the [WKT Point](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -**Supported types** - -| field | result | -| --- | --- | -| geo_point | geo_point | -| keyword | geo_point | -| text | geo_point | - -**Example** - -```esql -ROW wkt = "POINT(42.97109630194 14.7552534413725)" -| EVAL pt = TO_GEOPOINT(wkt) -``` - -| wkt:keyword | pt:geo_point | -| --- | --- | -| "POINT(42.97109630194 14.7552534413725)" | POINT(42.97109630194 14.7552534413725) | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_geoshape.md b/docs/reference/query-languages/esql/_snippets/functions/to_geoshape.md deleted file mode 100644 index a64779cda26c0..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_geoshape.md +++ /dev/null @@ -1,39 +0,0 @@ -## `TO_GEOSHAPE` [esql-to_geoshape] - -**Syntax** - -:::{image} ../../../../../images/to_geoshape.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input value to a `geo_shape` value. A string will only be successfully converted if it respects the [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -**Supported types** - -| field | result | -| --- | --- | -| geo_point | geo_shape | -| geo_shape | geo_shape | -| keyword | geo_shape | -| text | geo_shape | - -**Example** - -```esql -ROW wkt = "POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))" -| EVAL geom = TO_GEOSHAPE(wkt) -``` - -| wkt:keyword | geom:geo_shape | -| --- | --- | -| "POLYGON 30 10, 40 40, 20 40, 10 20, 30 10" | POLYGON 30 10, 40 40, 20 40, 10 20, 30 10 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_integer.md b/docs/reference/query-languages/esql/_snippets/functions/to_integer.md deleted file mode 100644 index ab06dabc68079..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_integer.md +++ /dev/null @@ -1,52 +0,0 @@ -## `TO_INTEGER` [esql-to_integer] - -**Syntax** - -:::{image} ../../../../../images/to_integer.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input value to an integer value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to integer. Boolean **true** will be converted to integer **1**, **false** to **0**. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | integer | -| counter_integer | integer | -| date | integer | -| double | integer | -| integer | integer | -| keyword | integer | -| long | integer | -| text | integer | -| unsigned_long | integer | - -**Example** - -```esql -ROW long = [5013792, 2147483647, 501379200000] -| EVAL int = TO_INTEGER(long) -``` - -| long:long | int:integer | -| --- | --- | -| [5013792, 2147483647, 501379200000] | [5013792, 2147483647] | - -Note that in this example, the last value of the multi-valued field cannot be converted as an integer. 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:61: evaluation of [TO_INTEGER(long)] failed, treating result as null. Only first 20 failures recorded."` - -A following header will contain the failure reason and the offending value: - -`"org.elasticsearch.xpack.esql.core.InvalidArgumentException: [501379200000] out of [integer] range"` - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_ip.md b/docs/reference/query-languages/esql/_snippets/functions/to_ip.md deleted file mode 100644 index 0c68e8b24e492..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_ip.md +++ /dev/null @@ -1,47 +0,0 @@ -## `TO_IP` [esql-to_ip] - -**Syntax** - -:::{image} ../../../../../images/to_ip.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input string to an IP value. - -**Supported types** - -| field | result | -| --- | --- | -| ip | ip | -| keyword | ip | -| text | ip | - -**Example** - -```esql -ROW str1 = "1.1.1.1", str2 = "foo" -| EVAL ip1 = TO_IP(str1), ip2 = TO_IP(str2) -| WHERE CIDR_MATCH(ip1, "1.0.0.0/8") -``` - -| str1:keyword | str2:keyword | ip1:ip | ip2:ip | -| --- | --- | --- | --- | -| 1.1.1.1 | foo | 1.1.1.1 | null | - -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."` - -A following header will contain the failure reason and the offending value: - -`"java.lang.IllegalArgumentException: 'foo' is not an IP string literal."` - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_long.md b/docs/reference/query-languages/esql/_snippets/functions/to_long.md deleted file mode 100644 index 3df147023b25c..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_long.md +++ /dev/null @@ -1,54 +0,0 @@ -## `TO_LONG` [esql-to_long] - -**Syntax** - -:::{image} ../../../../../images/to_long.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input value to a long value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to long. Boolean **true** will be converted to long **1**, **false** to **0**. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | long | -| counter_integer | long | -| counter_long | long | -| date | long | -| date_nanos | long | -| double | long | -| integer | long | -| keyword | long | -| long | long | -| text | long | -| unsigned_long | long | - -**Example** - -```esql -ROW str1 = "2147483648", str2 = "2147483648.2", str3 = "foo" -| EVAL long1 = TO_LONG(str1), long2 = TO_LONG(str2), long3 = TO_LONG(str3) -``` - -| str1:keyword | str2:keyword | str3:keyword | long1:long | long2:long | long3:long | -| --- | --- | --- | --- | --- | --- | -| 2147483648 | 2147483648.2 | foo | 2147483648 | 2147483648 | null | - -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:113: evaluation of [TO_LONG(str3)] 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""` - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_lower.md b/docs/reference/query-languages/esql/_snippets/functions/to_lower.md deleted file mode 100644 index 0e8fff8c5d661..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_lower.md +++ /dev/null @@ -1,37 +0,0 @@ -## `TO_LOWER` [esql-to_lower] - -**Syntax** - -:::{image} ../../../../../images/to_lower.svg -:alt: Embedded -:class: text-center -::: - -**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** - -| str | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -ROW message = "Some Text" -| EVAL message_lower = TO_LOWER(message) -``` - -| message:keyword | message_lower:keyword | -| --- | --- | -| Some Text | some text | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_radians.md b/docs/reference/query-languages/esql/_snippets/functions/to_radians.md deleted file mode 100644 index 100c92fbd3719..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_radians.md +++ /dev/null @@ -1,39 +0,0 @@ -## `TO_RADIANS` [esql-to_radians] - -**Syntax** - -:::{image} ../../../../../images/to_radians.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts a number in [degrees](https://en.wikipedia.org/wiki/Degree_(angle)) to [radians](https://en.wikipedia.org/wiki/Radian). - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW deg = [90.0, 180.0, 270.0] -| EVAL rad = TO_RADIANS(deg) -``` - -| deg:double | rad:double | -| --- | --- | -| [90.0, 180.0, 270.0] | [1.5707963267948966, 3.141592653589793, 4.71238898038469] | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_string.md b/docs/reference/query-languages/esql/_snippets/functions/to_string.md deleted file mode 100644 index 63960617650cc..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_string.md +++ /dev/null @@ -1,61 +0,0 @@ -## `TO_STRING` [esql-to_string] - -**Syntax** - -:::{image} ../../../../../images/to_string.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: 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** - -| field | result | -| --- | --- | -| boolean | keyword | -| cartesian_point | keyword | -| cartesian_shape | keyword | -| date | keyword | -| date_nanos | keyword | -| double | keyword | -| geo_point | keyword | -| geo_shape | keyword | -| integer | keyword | -| ip | keyword | -| keyword | keyword | -| long | keyword | -| text | keyword | -| unsigned_long | keyword | -| version | keyword | - -**Examples** - -```esql -ROW a=10 -| EVAL j = TO_STRING(a) -``` - -| a:integer | j:keyword | -| --- | --- | -| 10 | "10" | - -It also works fine on multivalued fields: - -```esql -ROW a=[10, 9, 8] -| EVAL j = TO_STRING(a) -``` - -| a:integer | j:keyword | -| --- | --- | -| [10, 9, 8] | ["10", "9", "8"] | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_timeduration.md b/docs/reference/query-languages/esql/_snippets/functions/to_timeduration.md deleted file mode 100644 index 46be6e2f69adc..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_timeduration.md +++ /dev/null @@ -1,37 +0,0 @@ -## `TO_TIMEDURATION` [esql-to_timeduration] - -**Syntax** - -:::{image} ../../../../../images/to_timeduration.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input is a valid constant time duration expression. - -**Description** - -Converts an input value into a `time_duration` value. - -**Supported types** - -| field | result | -| --- | --- | -| keyword | time_duration | -| text | time_duration | -| time_duration | time_duration | - -**Example** - -```esql -row x = "2024-01-01"::datetime | eval y = x + "3 hours"::time_duration, z = x - to_timeduration("3 hours"); -``` - -| x:datetime | y:datetime | z:datetime | -| --- | --- | --- | -| 2024-01-01 | 2024-01-01T03:00:00.000Z | 2023-12-31T21:00:00.000Z | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_unsigned_long.md b/docs/reference/query-languages/esql/_snippets/functions/to_unsigned_long.md deleted file mode 100644 index 53a277b6b41cf..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_unsigned_long.md +++ /dev/null @@ -1,51 +0,0 @@ -## `TO_UNSIGNED_LONG` [esql-to_unsigned_long] - -**Syntax** - -:::{image} ../../../../../images/to_unsigned_long.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: 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. If the input parameter is of a date type, its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to unsigned long. Boolean **true** will be converted to unsigned long **1**, **false** to **0**. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | unsigned_long | -| date | unsigned_long | -| double | unsigned_long | -| integer | unsigned_long | -| keyword | unsigned_long | -| long | unsigned_long | -| text | unsigned_long | -| unsigned_long | unsigned_long | - -**Example** - -```esql -ROW str1 = "2147483648", str2 = "2147483648.2", str3 = "foo" -| EVAL long1 = TO_UNSIGNED_LONG(str1), long2 = TO_ULONG(str2), long3 = TO_UL(str3) -``` - -| str1:keyword | str2:keyword | str3:keyword | long1:unsigned_long | long2:unsigned_long | long3:unsigned_long | -| --- | --- | --- | --- | --- | --- | -| 2147483648 | 2147483648.2 | foo | 2147483648 | 2147483648 | null | - -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:133: evaluation of [TO_UL(str3)] 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: Character f is neither a decimal digit number, decimal point, + "nor "e" notation exponential mark."` - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_upper.md b/docs/reference/query-languages/esql/_snippets/functions/to_upper.md deleted file mode 100644 index 22b86a9369c9b..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_upper.md +++ /dev/null @@ -1,37 +0,0 @@ -## `TO_UPPER` [esql-to_upper] - -**Syntax** - -:::{image} ../../../../../images/to_upper.svg -:alt: Embedded -:class: text-center -::: - -**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** - -| str | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -ROW message = "Some Text" -| EVAL message_upper = TO_UPPER(message) -``` - -| message:keyword | message_upper:keyword | -| --- | --- | -| Some Text | SOME TEXT | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/to_version.md b/docs/reference/query-languages/esql/_snippets/functions/to_version.md deleted file mode 100644 index 6d66fecc33a60..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/to_version.md +++ /dev/null @@ -1,35 +0,0 @@ -## `TO_VERSION` [esql-to_version] - -**Syntax** - -:::{image} ../../../../../images/to_version.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: 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** - -| field | result | -| --- | --- | -| keyword | version | -| text | version | -| version | version | - -**Example** - -```esql -ROW v = TO_VERSION("1.2.3") -``` - -| v:version | -| --- | -| 1.2.3 | diff --git a/docs/reference/query-languages/esql/_snippets/functions/top.md b/docs/reference/query-languages/esql/_snippets/functions/top.md deleted file mode 100644 index ba7e6fa9e87d7..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/top.md +++ /dev/null @@ -1,49 +0,0 @@ -## `TOP` [esql-top] - -**Syntax** - -:::{image} ../../../../../images/top.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: The field to collect the top values for. - -`limit` -: The maximum number of values to collect. - -`order` -: The order to calculate the top values. Either `asc` or `desc`. - -**Description** - -Collects the top values for a field. Includes repeated values. - -**Supported types** - -| field | limit | order | result | -| --- | --- | --- | --- | -| boolean | integer | keyword | boolean | -| date | integer | keyword | date | -| double | integer | keyword | double | -| integer | integer | keyword | integer | -| ip | integer | keyword | ip | -| keyword | integer | keyword | keyword | -| long | integer | keyword | long | -| text | integer | keyword | keyword | - -**Example** - -```esql -FROM employees -| STATS top_salaries = TOP(salary, 3, "desc"), top_salary = MAX(salary) -``` - -| top_salaries:integer | top_salary:integer | -| --- | --- | -| [74999, 74970, 74572] | 74999 | - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/trim.md b/docs/reference/query-languages/esql/_snippets/functions/trim.md deleted file mode 100644 index 84c4ca89c6161..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/trim.md +++ /dev/null @@ -1,36 +0,0 @@ -## `TRIM` [esql-trim] - -**Syntax** - -:::{image} ../../../../../images/trim.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. If `null`, the function returns `null`. - -**Description** - -Removes leading and trailing whitespaces from a string. - -**Supported types** - -| string | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -ROW message = " some text ", color = " red " -| EVAL message = TRIM(message) -| EVAL color = TRIM(color) -``` - -| message:s | color:s | -| --- | --- | -| some text | red | diff --git a/docs/reference/query-languages/esql/_snippets/functions/types/bucket.md b/docs/reference/query-languages/esql/_snippets/functions/types/bucket.md index 54605103483e7..d39ae63703316 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/types/bucket.md +++ b/docs/reference/query-languages/esql/_snippets/functions/types/bucket.md @@ -4,7 +4,7 @@ | field | buckets | from | to | result | | --- | --- | --- | --- | --- | -| date | date_period | | | date | +| date | date_period | | | date | | date | integer | date | date | date | | date | integer | date | keyword | date | | date | integer | date | text | date | @@ -14,8 +14,8 @@ | date | integer | text | date | date | | date | integer | text | keyword | date | | date | integer | text | text | date | -| date | time_duration | | | date | -| date_nanos | date_period | | | date_nanos | +| date | time_duration | | | date | +| date_nanos | date_period | | | date_nanos | | date_nanos | integer | date | date | date_nanos | | date_nanos | integer | date | keyword | date_nanos | | date_nanos | integer | date | text | date_nanos | @@ -25,8 +25,8 @@ | date_nanos | integer | text | date | date_nanos | | date_nanos | integer | text | keyword | date_nanos | | date_nanos | integer | text | text | date_nanos | -| date_nanos | time_duration | | | date_nanos | -| double | double | | | double | +| date_nanos | time_duration | | | date_nanos | +| double | double | | | double | | double | integer | double | double | double | | double | integer | double | integer | double | | double | integer | double | long | double | @@ -36,9 +36,9 @@ | double | integer | long | double | double | | double | integer | long | integer | double | | double | integer | long | long | double | -| double | integer | | | double | -| double | long | | | double | -| integer | double | | | double | +| double | integer | | | double | +| double | long | | | double | +| integer | double | | | double | | integer | integer | double | double | double | | integer | integer | double | integer | double | | integer | integer | double | long | double | @@ -48,9 +48,9 @@ | integer | integer | long | double | double | | integer | integer | long | integer | double | | integer | integer | long | long | double | -| integer | integer | | | double | -| integer | long | | | double | -| long | double | | | double | +| integer | integer | | | double | +| integer | long | | | double | +| long | double | | | double | | long | integer | double | double | double | | long | integer | double | integer | double | | long | integer | double | long | double | @@ -60,6 +60,6 @@ | long | integer | long | double | double | | long | integer | long | integer | double | | long | integer | long | long | double | -| long | integer | | | double | -| long | long | | | double | +| long | integer | | | double | +| long | long | | | double | diff --git a/docs/reference/query-languages/esql/_snippets/functions/types/case.md b/docs/reference/query-languages/esql/_snippets/functions/types/case.md index 2cb4ed44c3541..7ad667add42b8 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/types/case.md +++ b/docs/reference/query-languages/esql/_snippets/functions/types/case.md @@ -5,35 +5,35 @@ | condition | trueValue | elseValue | result | | --- | --- | --- | --- | | boolean | boolean | boolean | boolean | -| boolean | boolean | | boolean | +| boolean | boolean | | boolean | | boolean | cartesian_point | cartesian_point | cartesian_point | -| boolean | cartesian_point | | cartesian_point | +| boolean | cartesian_point | | cartesian_point | | boolean | cartesian_shape | cartesian_shape | cartesian_shape | -| boolean | cartesian_shape | | cartesian_shape | +| boolean | cartesian_shape | | cartesian_shape | | boolean | date | date | date | -| boolean | date | | date | +| boolean | date | | date | | boolean | date_nanos | date_nanos | date_nanos | -| boolean | date_nanos | | date_nanos | +| boolean | date_nanos | | date_nanos | | boolean | double | double | double | -| boolean | double | | double | +| boolean | double | | double | | boolean | geo_point | geo_point | geo_point | -| boolean | geo_point | | geo_point | +| boolean | geo_point | | geo_point | | boolean | geo_shape | geo_shape | geo_shape | -| boolean | geo_shape | | geo_shape | +| boolean | geo_shape | | geo_shape | | boolean | integer | integer | integer | -| boolean | integer | | integer | +| boolean | integer | | integer | | boolean | ip | ip | ip | -| boolean | ip | | ip | +| boolean | ip | | ip | | boolean | keyword | keyword | keyword | | boolean | keyword | text | keyword | -| boolean | keyword | | keyword | +| boolean | keyword | | keyword | | boolean | long | long | long | -| boolean | long | | long | +| boolean | long | | long | | boolean | text | keyword | keyword | | boolean | text | text | keyword | -| boolean | text | | keyword | +| boolean | text | | keyword | | boolean | unsigned_long | unsigned_long | unsigned_long | -| boolean | unsigned_long | | unsigned_long | +| boolean | unsigned_long | | unsigned_long | | boolean | version | version | version | -| boolean | version | | version | +| boolean | version | | version | diff --git a/docs/reference/query-languages/esql/_snippets/functions/types/coalesce.md b/docs/reference/query-languages/esql/_snippets/functions/types/coalesce.md index 3e4205985d37d..b7cbbd850fe3e 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/types/coalesce.md +++ b/docs/reference/query-languages/esql/_snippets/functions/types/coalesce.md @@ -5,7 +5,7 @@ | first | rest | result | | --- | --- | --- | | boolean | boolean | boolean | -| boolean | | boolean | +| boolean | | boolean | | cartesian_point | cartesian_point | cartesian_point | | cartesian_shape | cartesian_shape | cartesian_shape | | date | date | date | @@ -13,13 +13,13 @@ | geo_point | geo_point | geo_point | | geo_shape | geo_shape | geo_shape | | integer | integer | integer | -| integer | | integer | +| integer | | integer | | ip | ip | ip | | keyword | keyword | keyword | -| keyword | | keyword | +| keyword | | keyword | | long | long | long | -| long | | long | +| long | | long | | text | text | keyword | -| text | | keyword | +| text | | keyword | | version | version | version | diff --git a/docs/reference/query-languages/esql/_snippets/functions/types/count_distinct.md b/docs/reference/query-languages/esql/_snippets/functions/types/count_distinct.md index ab086dde70a4f..6194280ae78f7 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/types/count_distinct.md +++ b/docs/reference/query-languages/esql/_snippets/functions/types/count_distinct.md @@ -7,41 +7,41 @@ | boolean | integer | long | | boolean | long | long | | boolean | unsigned_long | long | -| boolean | | long | +| boolean | | long | | date | integer | long | | date | long | long | | date | unsigned_long | long | -| date | | long | +| date | | long | | date_nanos | integer | long | | date_nanos | long | long | | date_nanos | unsigned_long | long | -| date_nanos | | long | +| date_nanos | | long | | double | integer | long | | double | long | long | | double | unsigned_long | long | -| double | | long | +| double | | long | | integer | integer | long | | integer | long | long | | integer | unsigned_long | long | -| integer | | long | +| integer | | long | | ip | integer | long | | ip | long | long | | ip | unsigned_long | long | -| ip | | long | +| ip | | long | | keyword | integer | long | | keyword | long | long | | keyword | unsigned_long | long | -| keyword | | long | +| keyword | | long | | long | integer | long | | long | long | long | | long | unsigned_long | long | -| long | | long | +| long | | long | | text | integer | long | | text | long | long | | text | unsigned_long | long | -| text | | long | +| text | | long | | version | integer | long | | version | long | long | | version | unsigned_long | long | -| version | | long | +| version | | long | diff --git a/docs/reference/query-languages/esql/_snippets/functions/types/date_format.md b/docs/reference/query-languages/esql/_snippets/functions/types/date_format.md index 182a10d12f473..6a7c6efb67ee3 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/types/date_format.md +++ b/docs/reference/query-languages/esql/_snippets/functions/types/date_format.md @@ -4,8 +4,8 @@ | dateFormat | date | result | | --- | --- | --- | -| date | | keyword | -| date_nanos | | keyword | +| date | | keyword | +| date_nanos | | keyword | | keyword | date | keyword | | keyword | date_nanos | keyword | | text | date | keyword | diff --git a/docs/reference/query-languages/esql/_snippets/functions/types/greatest.md b/docs/reference/query-languages/esql/_snippets/functions/types/greatest.md index 0a406c8e9610f..4f34a8ff02c98 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/types/greatest.md +++ b/docs/reference/query-languages/esql/_snippets/functions/types/greatest.md @@ -5,18 +5,18 @@ | first | rest | result | | --- | --- | --- | | boolean | boolean | boolean | -| boolean | | boolean | +| boolean | | boolean | | date | date | date | | date_nanos | date_nanos | date_nanos | | double | double | double | | integer | integer | integer | -| integer | | integer | +| integer | | integer | | ip | ip | ip | | keyword | keyword | keyword | -| keyword | | keyword | +| keyword | | keyword | | long | long | long | -| long | | long | +| long | | long | | text | text | keyword | -| text | | keyword | +| text | | keyword | | version | version | version | diff --git a/docs/reference/query-languages/esql/_snippets/functions/types/least.md b/docs/reference/query-languages/esql/_snippets/functions/types/least.md index 0a406c8e9610f..4f34a8ff02c98 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/types/least.md +++ b/docs/reference/query-languages/esql/_snippets/functions/types/least.md @@ -5,18 +5,18 @@ | first | rest | result | | --- | --- | --- | | boolean | boolean | boolean | -| boolean | | boolean | +| boolean | | boolean | | date | date | date | | date_nanos | date_nanos | date_nanos | | double | double | double | | integer | integer | integer | -| integer | | integer | +| integer | | integer | | ip | ip | ip | | keyword | keyword | keyword | -| keyword | | keyword | +| keyword | | keyword | | long | long | long | -| long | | long | +| long | | long | | text | text | keyword | -| text | | keyword | +| text | | keyword | | version | version | version | diff --git a/docs/reference/query-languages/esql/_snippets/functions/types/locate.md b/docs/reference/query-languages/esql/_snippets/functions/types/locate.md index 8b4431b776f52..16b50c99c979b 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/types/locate.md +++ b/docs/reference/query-languages/esql/_snippets/functions/types/locate.md @@ -5,11 +5,11 @@ | string | substring | start | result | | --- | --- | --- | --- | | keyword | keyword | integer | integer | -| keyword | keyword | | integer | +| keyword | keyword | | integer | | keyword | text | integer | integer | -| keyword | text | | integer | +| keyword | text | | integer | | text | keyword | integer | integer | -| text | keyword | | integer | +| text | keyword | | integer | | text | text | integer | integer | -| text | text | | integer | +| text | text | | integer | diff --git a/docs/reference/query-languages/esql/_snippets/functions/types/log.md b/docs/reference/query-languages/esql/_snippets/functions/types/log.md index 4db700d3859ba..a12b44e5fea27 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/types/log.md +++ b/docs/reference/query-languages/esql/_snippets/functions/types/log.md @@ -8,20 +8,20 @@ | double | integer | double | | double | long | double | | double | unsigned_long | double | -| double | | double | +| double | | double | | integer | double | double | | integer | integer | double | | integer | long | double | | integer | unsigned_long | double | -| integer | | double | +| integer | | double | | long | double | double | | long | integer | double | | long | long | double | | long | unsigned_long | double | -| long | | double | +| long | | double | | unsigned_long | double | double | | unsigned_long | integer | double | | unsigned_long | long | double | | unsigned_long | unsigned_long | double | -| unsigned_long | | double | +| unsigned_long | | double | diff --git a/docs/reference/query-languages/esql/_snippets/functions/types/mv_append.md b/docs/reference/query-languages/esql/_snippets/functions/types/mv_append.md index cbc90120759f3..de780bf38e00c 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/types/mv_append.md +++ b/docs/reference/query-languages/esql/_snippets/functions/types/mv_append.md @@ -22,4 +22,3 @@ | unsigned_long | unsigned_long | unsigned_long | | version | version | version | - diff --git a/docs/reference/query-languages/esql/_snippets/functions/types/mv_zip.md b/docs/reference/query-languages/esql/_snippets/functions/types/mv_zip.md index 845bb89325fe1..44c0d64e1161f 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/types/mv_zip.md +++ b/docs/reference/query-languages/esql/_snippets/functions/types/mv_zip.md @@ -6,14 +6,14 @@ | --- | --- | --- | --- | | keyword | keyword | keyword | keyword | | keyword | keyword | text | keyword | -| keyword | keyword | | keyword | +| keyword | keyword | | keyword | | keyword | text | keyword | keyword | | keyword | text | text | keyword | -| keyword | text | | keyword | +| keyword | text | | keyword | | text | keyword | keyword | keyword | | text | keyword | text | keyword | -| text | keyword | | keyword | +| text | keyword | | keyword | | text | text | keyword | keyword | | text | text | text | keyword | -| text | text | | keyword | +| text | text | | keyword | diff --git a/docs/reference/query-languages/esql/_snippets/functions/types/round.md b/docs/reference/query-languages/esql/_snippets/functions/types/round.md index 73c3f36defcfe..94b8c01783ed2 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/types/round.md +++ b/docs/reference/query-languages/esql/_snippets/functions/types/round.md @@ -6,14 +6,14 @@ | --- | --- | --- | | double | integer | double | | double | long | double | -| double | | double | +| double | | double | | integer | integer | integer | | integer | long | integer | -| integer | | integer | +| integer | | integer | | long | integer | long | | long | long | long | -| long | | long | +| long | | long | | unsigned_long | integer | unsigned_long | | unsigned_long | long | unsigned_long | -| unsigned_long | | unsigned_long | +| unsigned_long | | unsigned_long | diff --git a/docs/reference/query-languages/esql/_snippets/functions/types/term.md b/docs/reference/query-languages/esql/_snippets/functions/types/term.md new file mode 100644 index 0000000000000..7bb1ad1e7b7b9 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/functions/types/term.md @@ -0,0 +1,11 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +**Supported types** + +| field | query | result | +| --- | --- | --- | +| keyword | keyword | boolean | +| keyword | text | boolean | +| text | keyword | boolean | +| text | text | boolean | + diff --git a/docs/reference/query-languages/esql/_snippets/functions/types/to_date_nanos.md b/docs/reference/query-languages/esql/_snippets/functions/types/to_date_nanos.md index 278ec84cf59eb..0e666d39181d7 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/types/to_date_nanos.md +++ b/docs/reference/query-languages/esql/_snippets/functions/types/to_date_nanos.md @@ -12,4 +12,3 @@ | text | date_nanos | | unsigned_long | date_nanos | - diff --git a/docs/reference/query-languages/esql/_snippets/functions/types/values.md b/docs/reference/query-languages/esql/_snippets/functions/types/values.md index 9f797a661b580..b12103f6f0ab7 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/types/values.md +++ b/docs/reference/query-languages/esql/_snippets/functions/types/values.md @@ -5,9 +5,13 @@ | field | result | | --- | --- | | boolean | boolean | +| cartesian_point | cartesian_point | +| cartesian_shape | cartesian_shape | | date | date | | date_nanos | date_nanos | | double | double | +| geo_point | geo_point | +| geo_shape | geo_shape | | integer | integer | | ip | ip | | keyword | keyword | diff --git a/docs/reference/query-languages/esql/_snippets/functions/values.md b/docs/reference/query-languages/esql/_snippets/functions/values.md deleted file mode 100644 index 046efa8989017..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/values.md +++ /dev/null @@ -1,79 +0,0 @@ -## `VALUES` [esql-values] - -::::{warning} -Do not use 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. -:::: - - -**Syntax** - -:::{image} ../../../../../images/values.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -Returns all values in a group as a multivalued field. The order of the returned values isn’t guaranteed. If you need the values returned in order use [`MV_SORT`](../../esql-functions-operators.md#esql-mv_sort). - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| date | date | -| date_nanos | date_nanos | -| double | double | -| integer | integer | -| ip | ip | -| keyword | keyword | -| long | long | -| text | keyword | -| version | version | - -**Example** - -```esql - FROM employees -| EVAL first_letter = SUBSTRING(first_name, 0, 1) -| STATS first_name=MV_SORT(VALUES(first_name)) BY first_letter -| SORT first_letter -``` - -| first_name:keyword | first_letter:keyword | -| --- | --- | -| [Alejandro, Amabile, Anneke, Anoosh, Arumugam] | A | -| [Basil, Berhard, Berni, Bezalel, Bojan, Breannda, Brendon] | B | -| [Charlene, Chirstian, Claudi, Cristinel] | C | -| [Danel, Divier, Domenick, Duangkaew] | D | -| [Ebbe, Eberhardt, Erez] | E | -| Florian | F | -| [Gao, Georgi, Georgy, Gino, Guoxiang] | G | -| [Heping, Hidefumi, Hilari, Hironobu, Hironoby, Hisao] | H | -| [Jayson, Jungsoon] | J | -| [Kazuhide, Kazuhito, Kendra, Kenroku, Kshitij, Kwee, Kyoichi] | K | -| [Lillian, Lucien] | L | -| [Magy, Margareta, Mary, Mayuko, Mayumi, Mingsen, Mokhtar, Mona, Moss] | M | -| Otmar | O | -| [Parto, Parviz, Patricio, Prasadram, Premal] | P | -| [Ramzi, Remzi, Reuven] | R | -| [Sailaja, Saniya, Sanjiv, Satosi, Shahaf, Shir, Somnath, Sreekrishna, Sudharsan, Sumant, Suzette] | S | -| [Tse, Tuval, Tzvetan] | T | -| [Udi, Uri] | U | -| [Valdiodio, Valter, Vishv] | V | -| Weiyi | W | -| Xinglin | X | -| [Yinghua, Yishay, Yongqiao] | Y | -| [Zhongwei, Zvonko] | Z | -| null | null | - -::::{warning} -This can use a significant amount of memory and ES|QL doesn’t yet grow aggregations beyond memory. So this aggregation will work until it is used to collect more values than can fit into memory. Once it collects too many values it will fail the query with a [Circuit Breaker Error](docs-content://troubleshoot/elasticsearch/circuit-breaker-errors.md). - -:::: - - - diff --git a/docs/reference/query-languages/esql/_snippets/functions/weighted_avg.md b/docs/reference/query-languages/esql/_snippets/functions/weighted_avg.md deleted file mode 100644 index 9b275693c9a7c..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/weighted_avg.md +++ /dev/null @@ -1,53 +0,0 @@ -## `WEIGHTED_AVG` [esql-weighted_avg] - -**Syntax** - -:::{image} ../../../../../images/weighted_avg.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: A numeric value. - -`weight` -: A numeric weight. - -**Description** - -The weighted average of a numeric expression. - -**Supported types** - -| number | weight | result | -| --- | --- | --- | -| double | double | double | -| double | integer | double | -| double | long | double | -| integer | double | double | -| integer | integer | double | -| integer | long | double | -| long | double | double | -| long | integer | double | -| long | long | double | - -**Example** - -```esql -FROM employees -| STATS w_avg = WEIGHTED_AVG(salary, height) by languages -| EVAL w_avg = ROUND(w_avg) -| KEEP w_avg, languages -| SORT languages -``` - -| w_avg:double | languages:integer | -| --- | --- | -| 51464.0 | 1 | -| 48477.0 | 2 | -| 52379.0 | 3 | -| 47990.0 | 4 | -| 42119.0 | 5 | -| 52142.0 | null | diff --git a/docs/reference/query-languages/esql/_snippets/grouping-functions-new.md b/docs/reference/query-languages/esql/_snippets/grouping-functions-new.md deleted file mode 100644 index f12715b635231..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/grouping-functions-new.md +++ /dev/null @@ -1,15 +0,0 @@ -## {{esql}} grouping functions [esql-group-functions] - - -The [`STATS`](/reference/query-languages/esql/esql-commands.md#esql-stats-by) command supports these grouping functions: - -:::{include} lists/grouping-functions.md -::: - - -:::{include} functions/bucket.md -::: - -:::{include} functions/categorize.md -::: - diff --git a/docs/reference/query-languages/esql/_snippets/grouping-functions-orig.md b/docs/reference/query-languages/esql/_snippets/grouping-functions-orig.md deleted file mode 100644 index 6f2a75808c713..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/grouping-functions-orig.md +++ /dev/null @@ -1,355 +0,0 @@ -## {{esql}} grouping functions [esql-group-functions] - - -The [`STATS`](/reference/query-languages/esql/esql-commands.md#esql-stats-by) command supports these grouping functions: - -:::{include} lists/grouping-functions.md -::: - - -## `BUCKET` [esql-bucket] - -**Syntax** - -:::{image} ../../../../images/bucket.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Numeric or date expression from which to derive buckets. - -`buckets` -: Target number of buckets, or desired bucket size if `from` and `to` parameters are omitted. - -`from` -: Start of the range. Can be a number, a date or a date expressed as a string. - -`to` -: End of the range. Can be a number, a date or a date expressed as a string. - -**Description** - -Creates groups of values - buckets - out of a datetime or numeric input. The size of the buckets can either be provided directly, or chosen based on a recommended count and values range. - -**Supported types** - -| field | buckets | from | to | result | -| --- | --- | --- | --- | --- | -| date | date_period | | | date | -| date | integer | date | date | date | -| date | integer | date | keyword | date | -| date | integer | date | text | date | -| date | integer | keyword | date | date | -| date | integer | keyword | keyword | date | -| date | integer | keyword | text | date | -| date | integer | text | date | date | -| date | integer | text | keyword | date | -| date | integer | text | text | date | -| date | time_duration | | | date | -| date_nanos | date_period | | | date_nanos | -| date_nanos | integer | date | date | date_nanos | -| date_nanos | integer | date | keyword | date_nanos | -| date_nanos | integer | date | text | date_nanos | -| date_nanos | integer | keyword | date | date_nanos | -| date_nanos | integer | keyword | keyword | date_nanos | -| date_nanos | integer | keyword | text | date_nanos | -| date_nanos | integer | text | date | date_nanos | -| date_nanos | integer | text | keyword | date_nanos | -| date_nanos | integer | text | text | date_nanos | -| date_nanos | time_duration | | | date_nanos | -| double | double | | | double | -| double | integer | double | double | double | -| double | integer | double | integer | double | -| double | integer | double | long | double | -| double | integer | integer | double | double | -| double | integer | integer | integer | double | -| double | integer | integer | long | double | -| double | integer | long | double | double | -| double | integer | long | integer | double | -| double | integer | long | long | double | -| double | integer | | | double | -| double | long | | | double | -| integer | double | | | double | -| integer | integer | double | double | double | -| integer | integer | double | integer | double | -| integer | integer | double | long | double | -| integer | integer | integer | double | double | -| integer | integer | integer | integer | double | -| integer | integer | integer | long | double | -| integer | integer | long | double | double | -| integer | integer | long | integer | double | -| integer | integer | long | long | double | -| integer | integer | | | double | -| integer | long | | | double | -| long | double | | | double | -| long | integer | double | double | double | -| long | integer | double | integer | double | -| long | integer | double | long | double | -| long | integer | integer | double | double | -| long | integer | integer | integer | double | -| long | integer | integer | long | double | -| long | integer | long | double | double | -| long | integer | long | integer | double | -| long | integer | long | long | double | -| long | integer | | | double | -| long | long | | | double | - -**Examples** - -`BUCKET` can work in two modes: one in which the size of the bucket is computed based on a buckets count recommendation (four parameters) and a range, and another in which the bucket size is provided directly (two parameters). - -Using a target number of buckets, a start of a range, and an end of a range, `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: - -```esql -FROM employees -| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" -| STATS hire_date = MV_SORT(VALUES(hire_date)) BY month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z") -| SORT hire_date -``` - -| hire_date:date | month:date | -| --- | --- | -| [1985-02-18T00:00:00.000Z, 1985-02-24T00:00:00.000Z] | 1985-02-01T00:00:00.000Z | -| 1985-05-13T00:00:00.000Z | 1985-05-01T00:00:00.000Z | -| 1985-07-09T00:00:00.000Z | 1985-07-01T00:00:00.000Z | -| 1985-09-17T00:00:00.000Z | 1985-09-01T00:00:00.000Z | -| [1985-10-14T00:00:00.000Z, 1985-10-20T00:00:00.000Z] | 1985-10-01T00:00:00.000Z | -| [1985-11-19T00:00:00.000Z, 1985-11-20T00:00:00.000Z, 1985-11-21T00:00:00.000Z] | 1985-11-01T00:00:00.000Z | - -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. - -Combine `BUCKET` with an [aggregation](../esql-functions-operators.md#esql-agg-functions) to create a histogram: - -```esql -FROM employees -| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" -| STATS hires_per_month = COUNT(*) BY month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z") -| SORT month -``` - -| hires_per_month:long | month:date | -| --- | --- | -| 2 | 1985-02-01T00:00:00.000Z | -| 1 | 1985-05-01T00:00:00.000Z | -| 1 | 1985-07-01T00:00:00.000Z | -| 1 | 1985-09-01T00:00:00.000Z | -| 2 | 1985-10-01T00:00:00.000Z | -| 4 | 1985-11-01T00:00:00.000Z | - -::::{note} -`BUCKET` does not create buckets that don’t match any documents. That’s why this example is missing `1985-03-01` and other dates. -:::: - - -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: - -```esql -FROM employees -| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" -| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 100, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z") -| SORT week -``` - -| hires_per_week:long | week:date | -| --- | --- | -| 2 | 1985-02-18T00:00:00.000Z | -| 1 | 1985-05-13T00:00:00.000Z | -| 1 | 1985-07-08T00:00:00.000Z | -| 1 | 1985-09-16T00:00:00.000Z | -| 2 | 1985-10-14T00:00:00.000Z | -| 4 | 1985-11-18T00:00:00.000Z | - -::::{note} -`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`BUCKET` with [`WHERE`](/reference/query-languages/esql/esql-commands.md#esql-where) to filter rows. -:::: - - -If the desired bucket size is known in advance, simply provide it as the second argument, leaving the range out: - -```esql -FROM employees -| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" -| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 1 week) -| SORT week -``` - -| hires_per_week:long | week:date | -| --- | --- | -| 2 | 1985-02-18T00:00:00.000Z | -| 1 | 1985-05-13T00:00:00.000Z | -| 1 | 1985-07-08T00:00:00.000Z | -| 1 | 1985-09-16T00:00:00.000Z | -| 2 | 1985-10-14T00:00:00.000Z | -| 4 | 1985-11-18T00:00:00.000Z | - -::::{note} -When providing the bucket size as the second parameter, it must be a time duration or date period. -:::: - - -`BUCKET` can also operate on numeric fields. For example, to create a salary histogram: - -```esql -FROM employees -| STATS COUNT(*) by bs = BUCKET(salary, 20, 25324, 74999) -| SORT bs -``` - -| COUNT(*):long | bs:double | -| --- | --- | -| 9 | 25000.0 | -| 9 | 30000.0 | -| 18 | 35000.0 | -| 11 | 40000.0 | -| 11 | 45000.0 | -| 10 | 50000.0 | -| 7 | 55000.0 | -| 9 | 60000.0 | -| 8 | 65000.0 | -| 8 | 70000.0 | - -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. - -The range can be omitted if the desired bucket size is known in advance. Simply provide it as the second argument: - -```esql -FROM employees -| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" -| STATS c = COUNT(1) BY b = BUCKET(salary, 5000.) -| SORT b -``` - -| c:long | b:double | -| --- | --- | -| 1 | 25000.0 | -| 1 | 30000.0 | -| 1 | 40000.0 | -| 2 | 45000.0 | -| 2 | 50000.0 | -| 1 | 55000.0 | -| 1 | 60000.0 | -| 1 | 65000.0 | -| 1 | 70000.0 | - -Create hourly buckets for the last 24 hours, and calculate the number of events per hour: - -```esql -FROM sample_data -| WHERE @timestamp >= NOW() - 1 day and @timestamp < NOW() -| STATS COUNT(*) BY bucket = BUCKET(@timestamp, 25, NOW() - 1 day, NOW()) -``` - -| COUNT(*):long | bucket:date | -| --- | --- | - -Create monthly buckets for the year 1985, and calculate the average salary by hiring month - -```esql -FROM employees -| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" -| STATS AVG(salary) BY bucket = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z") -| SORT bucket -``` - -| AVG(salary):double | bucket:date | -| --- | --- | -| 46305.0 | 1985-02-01T00:00:00.000Z | -| 44817.0 | 1985-05-01T00:00:00.000Z | -| 62405.0 | 1985-07-01T00:00:00.000Z | -| 49095.0 | 1985-09-01T00:00:00.000Z | -| 51532.0 | 1985-10-01T00:00:00.000Z | -| 54539.75 | 1985-11-01T00:00:00.000Z | - -`BUCKET` may be used in both the aggregating and grouping part of the [STATS …​ BY …​](/reference/query-languages/esql/esql-commands.md#esql-stats-by) command provided that in the aggregating part the function is referenced by an alias defined in the grouping part, or that it is invoked with the exact same expression: - -```esql -FROM employees -| STATS s1 = b1 + 1, s2 = BUCKET(salary / 1000 + 999, 50.) + 2 BY b1 = BUCKET(salary / 100 + 99, 50.), b2 = BUCKET(salary / 1000 + 999, 50.) -| SORT b1, b2 -| KEEP s1, b1, s2, b2 -``` - -| s1:double | b1:double | s2:double | b2:double | -| --- | --- | --- | --- | -| 351.0 | 350.0 | 1002.0 | 1000.0 | -| 401.0 | 400.0 | 1002.0 | 1000.0 | -| 451.0 | 450.0 | 1002.0 | 1000.0 | -| 501.0 | 500.0 | 1002.0 | 1000.0 | -| 551.0 | 550.0 | 1002.0 | 1000.0 | -| 601.0 | 600.0 | 1002.0 | 1000.0 | -| 601.0 | 600.0 | 1052.0 | 1050.0 | -| 651.0 | 650.0 | 1052.0 | 1050.0 | -| 701.0 | 700.0 | 1052.0 | 1050.0 | -| 751.0 | 750.0 | 1052.0 | 1050.0 | -| 801.0 | 800.0 | 1052.0 | 1050.0 | - -Sometimes you need to change the start value of each bucket by a given duration (similar to date histogram aggregation’s [`offset`](/reference/data-analysis/aggregations/search-aggregations-bucket-histogram-aggregation.md) parameter). To do so, you will need to take into account how the language handles expressions within the `STATS` command: if these contain functions or arithmetic operators, a virtual `EVAL` is inserted before and/or after the `STATS` command. Consequently, a double compensation is needed to adjust the bucketed date value before the aggregation and then again after. For instance, inserting a negative offset of `1 hour` to buckets of `1 year` looks like this: - -```esql -FROM employees -| STATS dates = MV_SORT(VALUES(birth_date)) BY b = BUCKET(birth_date + 1 HOUR, 1 YEAR) - 1 HOUR -| EVAL d_count = MV_COUNT(dates) -| SORT d_count, b -| LIMIT 3 -``` - -| dates:date | b:date | d_count:integer | -| --- | --- | --- | -| 1965-01-03T00:00:00.000Z | 1964-12-31T23:00:00.000Z | 1 | -| [1955-01-21T00:00:00.000Z, 1955-08-20T00:00:00.000Z, 1955-08-28T00:00:00.000Z, 1955-10-04T00:00:00.000Z] | 1954-12-31T23:00:00.000Z | 4 | -| [1957-04-04T00:00:00.000Z, 1957-05-23T00:00:00.000Z, 1957-05-25T00:00:00.000Z, 1957-12-03T00:00:00.000Z] | 1956-12-31T23:00:00.000Z | 4 | - - -## `CATEGORIZE` [esql-categorize] - -::::{warning} -Do not use 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. -:::: - - -**Syntax** - -:::{image} ../../../../images/categorize.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Expression to categorize - -**Description** - -Groups text messages into categories of similarly formatted text values. - -`CATEGORIZE` has the following limitations: - -* can’t be used within other expressions -* can’t be used with multiple groupings -* can’t be used or referenced within aggregate functions - -**Supported types** - -| field | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -This example categorizes server logs messages into categories and aggregates their counts. - -```esql -FROM sample_data -| STATS count=COUNT() BY category=CATEGORIZE(message) -``` - -| count:long | category:keyword | -| --- | --- | -| 3 | .**?Connected.+?to.**? | -| 3 | .**?Connection.+?error.**? | -| 1 | .**?Disconnected.**? | diff --git a/docs/reference/query-languages/esql/_snippets/ip-functions-new.md b/docs/reference/query-languages/esql/_snippets/ip-functions-new.md deleted file mode 100644 index b76bfb88e8f8b..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/ip-functions-new.md +++ /dev/null @@ -1,15 +0,0 @@ -## {{esql}} IP functions [esql-ip-functions] - - -{{esql}} supports these IP functions: - -:::{include} lists/ip-functions.md -::: - - -:::{include} functions/cidr_match.md -::: - -:::{include} functions/ip_prefix.md -::: - diff --git a/docs/reference/query-languages/esql/_snippets/ip-functions-orig.md b/docs/reference/query-languages/esql/_snippets/ip-functions-orig.md deleted file mode 100644 index 9ba55ef52fba9..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/ip-functions-orig.md +++ /dev/null @@ -1,91 +0,0 @@ -## {{esql}} IP functions [esql-ip-functions] - - -{{esql}} supports these IP functions: - -:::{include} lists/ip-functions.md -::: - - -## `CIDR_MATCH` [esql-cidr_match] - -**Syntax** - -:::{image} ../../../../images/cidr_match.svg -:alt: Embedded -:class: text-center -::: - -**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. - -**Supported types** - -| ip | blockX | result | -| --- | --- | --- | -| ip | keyword | boolean | -| ip | text | boolean | - -**Example** - -```esql -FROM hosts -| WHERE CIDR_MATCH(ip1, "127.0.0.2/32", "127.0.0.3/32") -| KEEP card, host, ip0, ip1 -``` - -| card:keyword | host:keyword | ip0:ip | ip1:ip | -| --- | --- | --- | --- | -| eth1 | beta | 127.0.0.1 | 127.0.0.2 | -| eth0 | gamma | fe80::cae2:65ff:fece:feb9 | 127.0.0.3 | - - -## `IP_PREFIX` [esql-ip_prefix] - -**Syntax** - -:::{image} ../../../../images/ip_prefix.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`ip` -: IP address of type `ip` (both IPv4 and IPv6 are supported). - -`prefixLengthV4` -: Prefix length for IPv4 addresses. - -`prefixLengthV6` -: Prefix length for IPv6 addresses. - -**Description** - -Truncates an IP to a given prefix length. - -**Supported types** - -| ip | prefixLengthV4 | prefixLengthV6 | result | -| --- | --- | --- | --- | -| ip | integer | integer | ip | - -**Example** - -```esql -row ip4 = to_ip("1.2.3.4"), ip6 = to_ip("fe80::cae2:65ff:fece:feb9") -| eval ip4_prefix = ip_prefix(ip4, 24, 0), ip6_prefix = ip_prefix(ip6, 0, 112); -``` - -| ip4:ip | ip6:ip | ip4_prefix:ip | ip6_prefix:ip | -| --- | --- | --- | --- | -| 1.2.3.4 | fe80::cae2:65ff:fece:feb9 | 1.2.3.0 | fe80::cae2:65ff:fece:0000 | diff --git a/docs/reference/query-languages/esql/_snippets/lists/search-functions.md b/docs/reference/query-languages/esql/_snippets/lists/search-functions.md index 14d70e3cd1144..1bb1da2772c86 100644 --- a/docs/reference/query-languages/esql/_snippets/lists/search-functions.md +++ b/docs/reference/query-languages/esql/_snippets/lists/search-functions.md @@ -1,3 +1,4 @@ * [preview] [`KQL`](../../esql-functions-operators.md#esql-kql) * [preview] [`MATCH`](../../esql-functions-operators.md#esql-match) * [preview] [`QSTR`](../../esql-functions-operators.md#esql-qstr) +% * [preview] [`TERM`](../../esql-functions-operators.md#esql-term) diff --git a/docs/reference/query-languages/esql/_snippets/math-functions-new.md b/docs/reference/query-languages/esql/_snippets/math-functions-new.md deleted file mode 100644 index df4cc06a6917e..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/math-functions-new.md +++ /dev/null @@ -1,83 +0,0 @@ -## {{esql}} mathematical functions [esql-math-functions] - - -{{esql}} supports these mathematical functions: - -:::{include} lists/math-functions.md -::: - -:::{include} functions/abs.md -::: - -:::{include} functions/acos.md -::: - -:::{include} functions/asin.md -::: - -:::{include} functions/atan.md -::: - -:::{include} functions/atan2.md -::: - -:::{include} functions/cbrt.md -::: - -:::{include} functions/ceil.md -::: - -:::{include} functions/cos.md -::: - -:::{include} functions/cosh.md -::: - -:::{include} functions/e.md -::: - -:::{include} functions/exp.md -::: - -:::{include} functions/floor.md -::: - -:::{include} functions/hypot.md -::: - -:::{include} functions/log.md -::: - -:::{include} functions/log10.md -::: - -:::{include} functions/pi.md -::: - -:::{include} functions/pow.md -::: - -:::{include} functions/round.md -::: - -:::{include} functions/signum.md -::: - -:::{include} functions/sin.md -::: - -:::{include} functions/sinh.md -::: - -:::{include} functions/sqrt.md -::: - -:::{include} functions/tan.md -::: - -:::{include} functions/tanh.md -::: - -:::{include} functions/tau.md -::: - diff --git a/docs/reference/query-languages/esql/_snippets/math-functions-orig.md b/docs/reference/query-languages/esql/_snippets/math-functions-orig.md deleted file mode 100644 index 8c4468ea926d1..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/math-functions-orig.md +++ /dev/null @@ -1,1085 +0,0 @@ -## {{esql}} mathematical functions [esql-math-functions] - - -{{esql}} supports these mathematical functions: - -:::{include} lists/math-functions.md -::: - -## `ABS` [esql-abs] - -**Syntax** - -:::{image} ../../../../images/abs.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the absolute value. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | integer | -| long | long | -| unsigned_long | unsigned_long | - -**Examples** - -```esql -ROW number = -1.0 -| EVAL abs_number = ABS(number) -``` - -| number:double | abs_number:double | -| --- | --- | -| -1.0 | 1.0 | - -```esql -FROM employees -| KEEP first_name, last_name, height -| EVAL abs_height = ABS(0.0 - height) -``` - -| first_name:keyword | last_name:keyword | height:double | abs_height:double | -| --- | --- | --- | --- | -| Alejandro | McAlpine | 1.48 | 1.48 | -| Amabile | Gomatam | 2.09 | 2.09 | -| Anneke | Preusig | 1.56 | 1.56 | - - -## `ACOS` [esql-acos] - -**Syntax** - -:::{image} ../../../../images/acos.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Number between -1 and 1. If `null`, the function returns `null`. - -**Description** - -Returns the [arccosine](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions) of `n` as an angle, expressed in radians. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=.9 -| EVAL acos=ACOS(a) -``` - -| a:double | acos:double | -| --- | --- | -| .9 | 0.45102681179626236 | - - -## `ASIN` [esql-asin] - -**Syntax** - -:::{image} ../../../../images/asin.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Number between -1 and 1. If `null`, the function returns `null`. - -**Description** - -Returns the [arcsine](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions) of the input numeric expression as an angle, expressed in radians. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=.9 -| EVAL asin=ASIN(a) -``` - -| a:double | asin:double | -| --- | --- | -| .9 | 1.1197695149986342 | - - -## `ATAN` [esql-atan] - -**Syntax** - -:::{image} ../../../../images/atan.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the [arctangent](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions) of the input numeric expression as an angle, expressed in radians. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=12.9 -| EVAL atan=ATAN(a) -``` - -| a:double | atan:double | -| --- | --- | -| 12.9 | 1.4934316673669235 | - - -## `ATAN2` [esql-atan2] - -**Syntax** - -:::{image} ../../../../images/atan2.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`y_coordinate` -: y coordinate. If `null`, the function returns `null`. - -`x_coordinate` -: x coordinate. If `null`, the function returns `null`. - -**Description** - -The [angle](https://en.wikipedia.org/wiki/Atan2) 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** - -| y_coordinate | x_coordinate | 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 | - -**Example** - -```esql -ROW y=12.9, x=.6 -| EVAL atan2=ATAN2(y, x) -``` - -| y:double | x:double | atan2:double | -| --- | --- | --- | -| 12.9 | 0.6 | 1.5243181954438936 | - - -## `CBRT` [esql-cbrt] - -**Syntax** - -:::{image} ../../../../images/cbrt.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the cube root of a number. The input can be any numeric value, the return value is always a double. Cube roots of infinities are null. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW d = 1000.0 -| EVAL c = cbrt(d) -``` - -| d: double | c:double | -| --- | --- | -| 1000.0 | 10.0 | - - -## `CEIL` [esql-ceil] - -**Syntax** - -:::{image} ../../../../images/ceil.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: 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 [Math.ceil](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Math.md#ceil(double)). -:::: - - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | integer | -| long | long | -| unsigned_long | unsigned_long | - -**Example** - -```esql -ROW a=1.8 -| EVAL a=CEIL(a) -``` - -| a:double | -| --- | -| 2 | - - -## `COS` [esql-cos] - -**Syntax** - -:::{image} ../../../../images/cos.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`angle` -: An angle, in radians. If `null`, the function returns `null`. - -**Description** - -Returns the [cosine](https://en.wikipedia.org/wiki/Sine_and_cosine) of an angle. - -**Supported types** - -| angle | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=1.8 -| EVAL cos=COS(a) -``` - -| a:double | cos:double | -| --- | --- | -| 1.8 | -0.2272020946930871 | - - -## `COSH` [esql-cosh] - -**Syntax** - -:::{image} ../../../../images/cosh.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the [hyperbolic cosine](https://en.wikipedia.org/wiki/Hyperbolic_functions) of a number. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=1.8 -| EVAL cosh=COSH(a) -``` - -| a:double | cosh:double | -| --- | --- | -| 1.8 | 3.1074731763172667 | - - -## `E` [esql-e] - -**Syntax** - -:::{image} ../../../../images/e.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -**Description** - -Returns [Euler’s number](https://en.wikipedia.org/wiki/E_(mathematical_constant)). - -**Supported types** - -| result | -| --- | -| double | - -**Example** - -```esql -ROW E() -``` - -| E():double | -| --- | -| 2.718281828459045 | - - -## `EXP` [esql-exp] - -**Syntax** - -:::{image} ../../../../images/exp.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the value of e raised to the power of the given number. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW d = 5.0 -| EVAL s = EXP(d) -``` - -| d: double | s:double | -| --- | --- | -| 5.0 | 148.413159102576603 | - - -## `FLOOR` [esql-floor] - -**Syntax** - -:::{image} ../../../../images/floor.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Round 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 [Math.floor](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Math.md#floor(double)). -:::: - - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | integer | -| long | long | -| unsigned_long | unsigned_long | - -**Example** - -```esql -ROW a=1.8 -| EVAL a=FLOOR(a) -``` - -| a:double | -| --- | -| 1 | - - -## `HYPOT` [esql-hypot] - -**Syntax** - -:::{image} ../../../../images/hypot.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number1` -: Numeric expression. If `null`, the function returns `null`. - -`number2` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the hypotenuse of two numbers. The input can be any numeric values, the return value is always a double. Hypotenuses of infinities are null. - -**Supported types** - -| number1 | number2 | 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 | - -**Example** - -```esql -ROW a = 3.0, b = 4.0 -| EVAL c = HYPOT(a, b) -``` - -| a:double | b:double | c:double | -| --- | --- | --- | -| 3.0 | 4.0 | 5.0 | - - -## `LOG` [esql-log] - -**Syntax** - -:::{image} ../../../../images/log.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`base` -: Base of logarithm. If `null`, the function returns `null`. If not provided, this function returns the natural logarithm (base e) of a value. - -`number` -: 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, and base of one return `null` as well as a warning. - -**Supported types** - -| base | number | result | -| --- | --- | --- | -| double | double | double | -| double | integer | double | -| double | long | double | -| double | unsigned_long | double | -| double | | double | -| integer | double | double | -| integer | integer | double | -| integer | long | double | -| integer | unsigned_long | double | -| integer | | double | -| long | double | double | -| long | integer | double | -| long | long | double | -| long | unsigned_long | double | -| long | | double | -| unsigned_long | double | double | -| unsigned_long | integer | double | -| unsigned_long | long | double | -| unsigned_long | unsigned_long | double | -| unsigned_long | | double | - -**Examples** - -```esql -ROW base = 2.0, value = 8.0 -| EVAL s = LOG(base, value) -``` - -| base: double | value: double | s:double | -| --- | --- | --- | -| 2.0 | 8.0 | 3.0 | - -```esql -row value = 100 -| EVAL s = LOG(value); -``` - -| value: integer | s:double | -| --- | --- | -| 100 | 4.605170185988092 | - - -## `LOG10` [esql-log10] - -**Syntax** - -:::{image} ../../../../images/log10.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the logarithm of a value to base 10. The input can be any numeric value, the return value is always a double. Logs of 0 and negative numbers return `null` as well as a warning. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW d = 1000.0 -| EVAL s = LOG10(d) -``` - -| d: double | s:double | -| --- | --- | -| 1000.0 | 3.0 | - - -## `PI` [esql-pi] - -**Syntax** - -:::{image} ../../../../images/pi.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -**Description** - -Returns [Pi](https://en.wikipedia.org/wiki/Pi), the ratio of a circle’s circumference to its diameter. - -**Supported types** - -| result | -| --- | -| double | - -**Example** - -```esql -ROW PI() -``` - -| PI():double | -| --- | -| 3.141592653589793 | - - -## `POW` [esql-pow] - -**Syntax** - -:::{image} ../../../../images/pow.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`base` -: Numeric expression for the base. If `null`, the function returns `null`. - -`exponent` -: Numeric expression for the exponent. If `null`, the function returns `null`. - -**Description** - -Returns the value of `base` raised to the power of `exponent`. - -::::{note} -It is still possible to overflow a double result here; in that case, null will be returned. -:::: - - -**Supported types** - -| base | exponent | 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 | - -**Examples** - -```esql -ROW base = 2.0, exponent = 2 -| EVAL result = POW(base, exponent) -``` - -| base:double | exponent:integer | result:double | -| --- | --- | --- | -| 2.0 | 2 | 4.0 | - -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: - -```esql -ROW base = 4, exponent = 0.5 -| EVAL s = POW(base, exponent) -``` - -| base:integer | exponent:double | s:double | -| --- | --- | --- | -| 4 | 0.5 | 2.0 | - - -## `ROUND` [esql-round] - -**Syntax** - -:::{image} ../../../../images/round.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: The numeric value to round. If `null`, the function returns `null`. - -`decimals` -: The number of decimal places to round to. Defaults to 0. If `null`, the function returns `null`. - -**Description** - -Rounds a number to the specified number of decimal places. Defaults to 0, which returns the nearest integer. If the precision is a negative number, rounds to the number of digits left of the decimal point. - -**Supported types** - -| number | decimals | result | -| --- | --- | --- | -| double | integer | double | -| double | long | double | -| double | | double | -| integer | integer | integer | -| integer | long | integer | -| integer | | integer | -| long | integer | long | -| long | long | long | -| long | | long | -| unsigned_long | integer | unsigned_long | -| unsigned_long | long | unsigned_long | -| unsigned_long | | unsigned_long | - -**Example** - -```esql -FROM employees -| KEEP first_name, last_name, height -| EVAL height_ft = ROUND(height * 3.281, 1) -``` - -| first_name:keyword | last_name:keyword | height:double | height_ft:double | -| --- | --- | --- | --- | -| Arumugam | Ossenbruggen | 2.1 | 6.9 | -| Kwee | Schusler | 2.1 | 6.9 | -| Saniya | Kalloufi | 2.1 | 6.9 | - - -## `SIGNUM` [esql-signum] - -**Syntax** - -:::{image} ../../../../images/signum.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the sign of the given number. It returns `-1` for negative numbers, `0` for `0` and `1` for positive numbers. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW d = 100.0 -| EVAL s = SIGNUM(d) -``` - -| d: double | s:double | -| --- | --- | -| 100 | 1.0 | - - -## `SIN` [esql-sin] - -**Syntax** - -:::{image} ../../../../images/sin.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`angle` -: An angle, in radians. If `null`, the function returns `null`. - -**Description** - -Returns the [sine](https://en.wikipedia.org/wiki/Sine_and_cosine) of an angle. - -**Supported types** - -| angle | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=1.8 -| EVAL sin=SIN(a) -``` - -| a:double | sin:double | -| --- | --- | -| 1.8 | 0.9738476308781951 | - - -## `SINH` [esql-sinh] - -**Syntax** - -:::{image} ../../../../images/sinh.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the [hyperbolic sine](https://en.wikipedia.org/wiki/Hyperbolic_functions) of a number. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=1.8 -| EVAL sinh=SINH(a) -``` - -| a:double | sinh:double | -| --- | --- | -| 1.8 | 2.94217428809568 | - - -## `SQRT` [esql-sqrt] - -**Syntax** - -:::{image} ../../../../images/sqrt.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: 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 and infinities are null. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW d = 100.0 -| EVAL s = SQRT(d) -``` - -| d: double | s:double | -| --- | --- | -| 100.0 | 10.0 | - - -## `TAN` [esql-tan] - -**Syntax** - -:::{image} ../../../../images/tan.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`angle` -: An angle, in radians. If `null`, the function returns `null`. - -**Description** - -Returns the [tangent](https://en.wikipedia.org/wiki/Sine_and_cosine) of an angle. - -**Supported types** - -| angle | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=1.8 -| EVAL tan=TAN(a) -``` - -| a:double | tan:double | -| --- | --- | -| 1.8 | -4.286261674628062 | - - -## `TANH` [esql-tanh] - -**Syntax** - -:::{image} ../../../../images/tanh.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Numeric expression. If `null`, the function returns `null`. - -**Description** - -Returns the [hyperbolic tangent](https://en.wikipedia.org/wiki/Hyperbolic_functions) of a number. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=1.8 -| EVAL tanh=TANH(a) -``` - -| a:double | tanh:double | -| --- | --- | -| 1.8 | 0.9468060128462683 | - - -## `TAU` [esql-tau] - -**Syntax** - -:::{image} ../../../../images/tau.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -**Description** - -Returns the [ratio](https://tauday.com/tau-manifesto) of a circle’s circumference to its radius. - -**Supported types** - -| result | -| --- | -| double | - -**Example** - -```esql -ROW TAU() -``` - -| TAU():double | -| --- | -| 6.283185307179586 | diff --git a/docs/reference/query-languages/esql/_snippets/mv-functions-new.md b/docs/reference/query-languages/esql/_snippets/mv-functions-new.md deleted file mode 100644 index 94910ee2baca3..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/mv-functions-new.md +++ /dev/null @@ -1,59 +0,0 @@ -## {{esql}} multivalue functions [esql-mv-functions] - -{{esql}} supports these multivalue functions: - -:::{include} lists/mv-functions.md -::: - - -:::{include} functions/mv_append.md -::: - -:::{include} functions/mv_avg.md -::: - -:::{include} functions/mv_concat.md -::: - -:::{include} functions/mv_count.md -::: - -:::{include} functions/mv_dedupe.md -::: - -:::{include} functions/mv_first.md -::: - -:::{include} functions/mv_last.md -::: - -:::{include} functions/mv_max.md -::: - -:::{include} functions/mv_median.md -::: - -:::{include} functions/mv_median_absolute_deviation.md -::: - -:::{include} functions/mv_min.md -::: - -:::{include} functions/mv_percentile.md -::: - -:::{include} functions/mv_pseries_weighted_sum.md -::: - -:::{include} functions/mv_slice.md -::: - -:::{include} functions/mv_sort.md -::: - -:::{include} functions/mv_sum.md -::: - -:::{include} functions/mv_zip.md -::: - diff --git a/docs/reference/query-languages/esql/_snippets/mv-functions-orig.md b/docs/reference/query-languages/esql/_snippets/mv-functions-orig.md deleted file mode 100644 index da543f2b75b91..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/mv-functions-orig.md +++ /dev/null @@ -1,849 +0,0 @@ -## {{esql}} multivalue functions [esql-mv-functions] - -{{esql}} supports these multivalue functions: - -:::{include} lists/mv-functions.md -::: - - -## `MV_APPEND` [esql-mv_append] - -**Syntax** - -:::{image} ../../../../images/mv_append.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -true -**Description** - -Concatenates values of two multi-value fields. - -**Supported types** - -| field1 | field2 | result | -| --- | --- | --- | -| boolean | boolean | boolean | -| cartesian_point | cartesian_point | cartesian_point | -| cartesian_shape | cartesian_shape | cartesian_shape | -| date | date | date | -| date_nanos | date_nanos | date_nanos | -| double | double | double | -| geo_point | geo_point | geo_point | -| geo_shape | geo_shape | geo_shape | -| integer | integer | integer | -| ip | ip | ip | -| keyword | keyword | keyword | -| keyword | text | keyword | -| long | long | long | -| text | keyword | keyword | -| text | text | keyword | -| unsigned_long | unsigned_long | unsigned_long | -| version | version | version | - - -## `MV_AVG` [esql-mv_avg] - -**Syntax** - -:::{image} ../../../../images/mv_avg.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Multivalue expression. - -**Description** - -Converts a multivalued field into a single valued field containing the average of all of the values. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW a=[3, 5, 1, 6] -| EVAL avg_a = MV_AVG(a) -``` - -| a:integer | avg_a:double | -| --- | --- | -| [3, 5, 1, 6] | 3.75 | - - -## `MV_CONCAT` [esql-mv_concat] - -**Syntax** - -:::{image} ../../../../images/mv_concat.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: 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** - -| string | delim | result | -| --- | --- | --- | -| keyword | keyword | keyword | -| keyword | text | keyword | -| text | keyword | keyword | -| text | text | keyword | - -**Examples** - -```esql -ROW a=["foo", "zoo", "bar"] -| EVAL j = MV_CONCAT(a, ", ") -``` - -| a:keyword | j:keyword | -| --- | --- | -| ["foo", "zoo", "bar"] | "foo, zoo, bar" | - -To concat non-string columns, call [`TO_STRING`](../esql-functions-operators.md#esql-to_string) first: - -```esql -ROW a=[10, 9, 8] -| EVAL j = MV_CONCAT(TO_STRING(a), ", ") -``` - -| a:integer | j:keyword | -| --- | --- | -| [10, 9, 8] | "10, 9, 8" | - - -## `MV_COUNT` [esql-mv_count] - -**Syntax** - -:::{image} ../../../../images/mv_count.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Multivalue expression. - -**Description** - -Converts a multivalued expression into a single valued column containing a count of the number of values. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | integer | -| cartesian_point | integer | -| cartesian_shape | integer | -| date | integer | -| date_nanos | integer | -| double | integer | -| geo_point | integer | -| geo_shape | integer | -| integer | integer | -| ip | integer | -| keyword | integer | -| long | integer | -| text | integer | -| unsigned_long | integer | -| version | integer | - -**Example** - -```esql -ROW a=["foo", "zoo", "bar"] -| EVAL count_a = MV_COUNT(a) -``` - -| a:keyword | count_a:integer | -| --- | --- | -| ["foo", "zoo", "bar"] | 3 | - - -## `MV_DEDUPE` [esql-mv_dedupe] - -**Syntax** - -:::{image} ../../../../images/mv_dedupe.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Multivalue expression. - -**Description** - -Remove duplicate values from a multivalued field. - -::::{note} -`MV_DEDUPE` may, but won’t always, sort the values in the column. -:::: - - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| cartesian_point | cartesian_point | -| cartesian_shape | cartesian_shape | -| date | date | -| date_nanos | date_nanos | -| double | double | -| geo_point | geo_point | -| geo_shape | geo_shape | -| integer | integer | -| ip | ip | -| keyword | keyword | -| long | long | -| text | keyword | -| unsigned_long | unsigned_long | -| version | version | - -**Example** - -```esql -ROW a=["foo", "foo", "bar", "foo"] -| EVAL dedupe_a = MV_DEDUPE(a) -``` - -| a:keyword | dedupe_a:keyword | -| --- | --- | -| ["foo", "foo", "bar", "foo"] | ["foo", "bar"] | - - -## `MV_FIRST` [esql-mv_first] - -**Syntax** - -:::{image} ../../../../images/mv_first.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: 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 [`SPLIT`](../esql-functions-operators.md#esql-split). - -The order that [multivalued fields](/reference/query-languages/esql/esql-multivalued-fields.md) 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 [`MV_MIN`](../esql-functions-operators.md#esql-mv_min) instead of `MV_FIRST`. `MV_MIN` has optimizations for sorted values so there isn’t a performance benefit to `MV_FIRST`. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| cartesian_point | cartesian_point | -| cartesian_shape | cartesian_shape | -| date | date | -| date_nanos | date_nanos | -| double | double | -| geo_point | geo_point | -| geo_shape | geo_shape | -| integer | integer | -| ip | ip | -| keyword | keyword | -| long | long | -| text | keyword | -| unsigned_long | unsigned_long | -| version | version | - -**Example** - -```esql -ROW a="foo;bar;baz" -| EVAL first_a = MV_FIRST(SPLIT(a, ";")) -``` - -| a:keyword | first_a:keyword | -| --- | --- | -| foo;bar;baz | "foo" | - - -## `MV_LAST` [esql-mv_last] - -**Syntax** - -:::{image} ../../../../images/mv_last.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: 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 [`SPLIT`](../esql-functions-operators.md#esql-split). - -The order that [multivalued fields](/reference/query-languages/esql/esql-multivalued-fields.md) 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 [`MV_MAX`](../esql-functions-operators.md#esql-mv_max) instead of `MV_LAST`. `MV_MAX` has optimizations for sorted values so there isn’t a performance benefit to `MV_LAST`. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| cartesian_point | cartesian_point | -| cartesian_shape | cartesian_shape | -| date | date | -| date_nanos | date_nanos | -| double | double | -| geo_point | geo_point | -| geo_shape | geo_shape | -| integer | integer | -| ip | ip | -| keyword | keyword | -| long | long | -| text | keyword | -| unsigned_long | unsigned_long | -| version | version | - -**Example** - -```esql -ROW a="foo;bar;baz" -| EVAL last_a = MV_LAST(SPLIT(a, ";")) -``` - -| a:keyword | last_a:keyword | -| --- | --- | -| foo;bar;baz | "baz" | - - -## `MV_MAX` [esql-mv_max] - -**Syntax** - -:::{image} ../../../../images/mv_max.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Multivalue expression. - -**Description** - -Converts a multivalued expression into a single valued column containing the maximum value. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| date | date | -| date_nanos | date_nanos | -| double | double | -| integer | integer | -| ip | ip | -| keyword | keyword | -| long | long | -| text | keyword | -| unsigned_long | unsigned_long | -| version | version | - -**Examples** - -```esql -ROW a=[3, 5, 1] -| EVAL max_a = MV_MAX(a) -``` - -| a:integer | max_a:integer | -| --- | --- | -| [3, 5, 1] | 5 | - -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: - -```esql -ROW a=["foo", "zoo", "bar"] -| EVAL max_a = MV_MAX(a) -``` - -| a:keyword | max_a:keyword | -| --- | --- | -| ["foo", "zoo", "bar"] | "zoo" | - - -## `MV_MEDIAN` [esql-mv_median] - -**Syntax** - -:::{image} ../../../../images/mv_median.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Multivalue expression. - -**Description** - -Converts a multivalued field into a single valued field containing the median value. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | integer | -| long | long | -| unsigned_long | unsigned_long | - -**Examples** - -```esql -ROW a=[3, 5, 1] -| EVAL median_a = MV_MEDIAN(a) -``` - -| a:integer | median_a:integer | -| --- | --- | -| [3, 5, 1] | 3 | - -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**: - -```esql -ROW a=[3, 7, 1, 6] -| EVAL median_a = MV_MEDIAN(a) -``` - -| a:integer | median_a:integer | -| --- | --- | -| [3, 7, 1, 6] | 4 | - - -## `MV_MEDIAN_ABSOLUTE_DEVIATION` [esql-mv_median_absolute_deviation] - -**Syntax** - -:::{image} ../../../../images/mv_median_absolute_deviation.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Multivalue expression. - -**Description** - -Converts a multivalued field into a single valued field containing the median absolute 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} -If the field has an even number of values, the medians will be calculated as the average of the middle two values. If the value is not a floating point number, the averages are rounded towards 0. -:::: - - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | integer | -| long | long | -| unsigned_long | unsigned_long | - -**Example** - -```esql -ROW values = [0, 2, 5, 6] -| EVAL median_absolute_deviation = MV_MEDIAN_ABSOLUTE_DEVIATION(values), median = MV_MEDIAN(values) -``` - -| values:integer | median_absolute_deviation:integer | median:integer | -| --- | --- | --- | -| [0, 2, 5, 6] | 2 | 3 | - - -## `MV_MIN` [esql-mv_min] - -**Syntax** - -:::{image} ../../../../images/mv_min.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Multivalue expression. - -**Description** - -Converts a multivalued expression into a single valued column containing the minimum value. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| date | date | -| date_nanos | date_nanos | -| double | double | -| integer | integer | -| ip | ip | -| keyword | keyword | -| long | long | -| text | keyword | -| unsigned_long | unsigned_long | -| version | version | - -**Examples** - -```esql -ROW a=[2, 1] -| EVAL min_a = MV_MIN(a) -``` - -| a:integer | min_a:integer | -| --- | --- | -| [2, 1] | 1 | - -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: - -```esql -ROW a=["foo", "bar"] -| EVAL min_a = MV_MIN(a) -``` - -| a:keyword | min_a:keyword | -| --- | --- | -| ["foo", "bar"] | "bar" | - - -## `MV_PERCENTILE` [esql-mv_percentile] - -**Syntax** - -:::{image} ../../../../images/mv_percentile.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Multivalue expression. - -`percentile` -: The percentile to calculate. Must be a number between 0 and 100. Numbers out of range will return a null instead. - -**Description** - -Converts a multivalued field into a single valued field containing the value at which a certain percentage of observed values occur. - -**Supported types** - -| number | percentile | result | -| --- | --- | --- | -| double | double | double | -| double | integer | double | -| double | long | double | -| integer | double | integer | -| integer | integer | integer | -| integer | long | integer | -| long | double | long | -| long | integer | long | -| long | long | long | - -**Example** - -```esql -ROW values = [5, 5, 10, 12, 5000] -| EVAL p50 = MV_PERCENTILE(values, 50), median = MV_MEDIAN(values) -``` - -| values:integer | p50:integer | median:integer | -| --- | --- | --- | -| [5, 5, 10, 12, 5000] | 10 | 10 | - - -## `MV_PSERIES_WEIGHTED_SUM` [esql-mv_pseries_weighted_sum] - -**Syntax** - -:::{image} ../../../../images/mv_pseries_weighted_sum.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Multivalue expression. - -`p` -: It is a constant number that represents the *p* parameter in the P-Series. It impacts every element’s contribution to the weighted sum. - -**Description** - -Converts a multivalued expression into a single-valued column by multiplying every element on the input list by its corresponding term in P-Series and computing the sum. - -**Supported types** - -| number | p | result | -| --- | --- | --- | -| double | double | double | - -**Example** - -```esql -ROW a = [70.0, 45.0, 21.0, 21.0, 21.0] -| EVAL sum = MV_PSERIES_WEIGHTED_SUM(a, 1.5) -| KEEP sum -``` - -| sum:double | -| --- | -| 94.45465156212452 | - - -## `MV_SLICE` [esql-mv_slice] - -**Syntax** - -:::{image} ../../../../images/mv_slice.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Multivalue expression. If `null`, the function returns `null`. - -`start` -: Start position. If `null`, the function returns `null`. The start argument can be negative. An index of -1 is used to specify the last value in the list. - -`end` -: End position(included). Optional; if omitted, the position at `start` is returned. The end argument can be negative. An index of -1 is used to specify the last value in the list. - -**Description** - -Returns a subset of the multivalued field using the start and end index values. This is most useful when reading from a function that emits multivalued columns in a known order like [`SPLIT`](../esql-functions-operators.md#esql-split) or [`MV_SORT`](../esql-functions-operators.md#esql-mv_sort). - -The order that [multivalued fields](/reference/query-languages/esql/esql-multivalued-fields.md) are read from underlying storage is not guaranteed. It is **frequently** ascending, but don’t rely on that. - -**Supported types** - -| field | start | end | result | -| --- | --- | --- | --- | -| boolean | integer | integer | boolean | -| cartesian_point | integer | integer | cartesian_point | -| cartesian_shape | integer | integer | cartesian_shape | -| date | integer | integer | date | -| date_nanos | integer | integer | date_nanos | -| double | integer | integer | double | -| geo_point | integer | integer | geo_point | -| geo_shape | integer | integer | geo_shape | -| integer | integer | integer | integer | -| ip | integer | integer | ip | -| keyword | integer | integer | keyword | -| long | integer | integer | long | -| text | integer | integer | keyword | -| unsigned_long | integer | integer | unsigned_long | -| version | integer | integer | version | - -**Examples** - -```esql -row a = [1, 2, 2, 3] -| eval a1 = mv_slice(a, 1), a2 = mv_slice(a, 2, 3) -``` - -| a:integer | a1:integer | a2:integer | -| --- | --- | --- | -| [1, 2, 2, 3] | 2 | [2, 3] | - -```esql -row a = [1, 2, 2, 3] -| eval a1 = mv_slice(a, -2), a2 = mv_slice(a, -3, -1) -``` - -| a:integer | a1:integer | a2:integer | -| --- | --- | --- | -| [1, 2, 2, 3] | 2 | [2, 2, 3] | - - -## `MV_SORT` [esql-mv_sort] - -**Syntax** - -:::{image} ../../../../images/mv_sort.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Multivalue expression. If `null`, the function returns `null`. - -`order` -: Sort order. The valid options are ASC and DESC, the default is ASC. - -**Description** - -Sorts a multivalued field in lexicographical order. - -**Supported types** - -| field | order | result | -| --- | --- | --- | -| boolean | keyword | boolean | -| date | keyword | date | -| date_nanos | keyword | date_nanos | -| double | keyword | double | -| integer | keyword | integer | -| ip | keyword | ip | -| keyword | keyword | keyword | -| long | keyword | long | -| text | keyword | keyword | -| version | keyword | version | - -**Example** - -```esql -ROW a = [4, 2, -3, 2] -| EVAL sa = mv_sort(a), sd = mv_sort(a, "DESC") -``` - -| a:integer | sa:integer | sd:integer | -| --- | --- | --- | -| [4, 2, -3, 2] | [-3, 2, 2, 4] | [4, 2, 2, -3] | - - -## `MV_SUM` [esql-mv_sum] - -**Syntax** - -:::{image} ../../../../images/mv_sum.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Multivalue expression. - -**Description** - -Converts a multivalued field into a single valued field containing the sum of all of the values. - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | integer | -| long | long | -| unsigned_long | unsigned_long | - -**Example** - -```esql -ROW a=[3, 5, 6] -| EVAL sum_a = MV_SUM(a) -``` - -| a:integer | sum_a:integer | -| --- | --- | -| [3, 5, 6] | 14 | - - -## `MV_ZIP` [esql-mv_zip] - -**Syntax** - -:::{image} ../../../../images/mv_zip.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string1` -: Multivalue expression. - -`string2` -: Multivalue expression. - -`delim` -: Delimiter. Optional; if omitted, `,` is used as a default delimiter. - -**Description** - -Combines the values from two multivalued fields with a delimiter that joins them together. - -**Supported types** - -| string1 | string2 | delim | result | -| --- | --- | --- | --- | -| keyword | keyword | keyword | keyword | -| keyword | keyword | text | keyword | -| keyword | keyword | | keyword | -| keyword | text | keyword | keyword | -| keyword | text | text | keyword | -| keyword | text | | keyword | -| text | keyword | keyword | keyword | -| text | keyword | text | keyword | -| text | keyword | | keyword | -| text | text | keyword | keyword | -| text | text | text | keyword | -| text | text | | keyword | - -**Example** - -```esql -ROW a = ["x", "y", "z"], b = ["1", "2"] -| EVAL c = mv_zip(a, b, "-") -| KEEP a, b, c -``` - -| a:keyword | b:keyword | c:keyword | -| --- | --- | --- | -| [x, y, z] | [1 ,2] | [x-1, y-2, z] | diff --git a/docs/reference/query-languages/esql/_snippets/operators-new.md b/docs/reference/query-languages/esql/_snippets/operators-new.md deleted file mode 100644 index 7d29eb944b550..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/operators-new.md +++ /dev/null @@ -1,665 +0,0 @@ -## {{esql}} operators [esql-operators] - -Boolean operators for comparing against one or multiple expressions. - -:::{include} lists/operators.md -::: - - -## Binary operators [esql-binary-operators] - - -## Equality [esql-binary-operators-equality] - -:::{image} ../../../../images/equals.svg -:alt: Embedded -:class: text-center -::: - -Check if two fields are equal. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| boolean | boolean | boolean | -| cartesian_point | cartesian_point | boolean | -| cartesian_shape | cartesian_shape | boolean | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| geo_point | geo_point | boolean | -| geo_shape | geo_shape | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Inequality `!=` [_inequality] - -:::{image} ../../../../images/not_equals.svg -:alt: Embedded -:class: text-center -::: - -Check if two fields are unequal. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| boolean | boolean | boolean | -| cartesian_point | cartesian_point | boolean | -| cartesian_shape | cartesian_shape | boolean | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| geo_point | geo_point | boolean | -| geo_shape | geo_shape | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Less than `<` [_less_than] - -:::{image} ../../../../images/less_than.svg -:alt: Embedded -:class: text-center -::: - -Check if one field is less than another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Less than or equal to `<=` [_less_than_or_equal_to] - -:::{image} ../../../../images/less_than_or_equal.svg -:alt: Embedded -:class: text-center -::: - -Check if one field is less than or equal to another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Greater than `>` [_greater_than] - -:::{image} ../../../../images/greater_than.svg -:alt: Embedded -:class: text-center -::: - -Check if one field is greater than another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Greater than or equal to `>=` [_greater_than_or_equal_to] - -:::{image} ../../../../images/greater_than_or_equal.svg -:alt: Embedded -:class: text-center -::: - -Check if one field is greater than or equal to another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Add `+` [esql-add] - -:::{image} ../../../../images/add.svg -:alt: Embedded -:class: text-center -::: - -Add two numbers together. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date_period | date | -| date | time_duration | date | -| date_nanos | date_period | date_nanos | -| date_nanos | time_duration | date_nanos | -| date_period | date | date | -| date_period | date_nanos | date_nanos | -| date_period | date_period | date_period | -| 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 | date | date | -| time_duration | date_nanos | date_nanos | -| time_duration | time_duration | time_duration | -| unsigned_long | unsigned_long | unsigned_long | - - -## Subtract `-` [esql-subtract] - -:::{image} ../../../../images/sub.svg -:alt: Embedded -:class: text-center -::: - -Subtract one number from another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date_period | date | -| date | time_duration | date | -| date_nanos | date_period | date_nanos | -| date_nanos | time_duration | date_nanos | -| date_period | date_nanos | date_nanos | -| date_period | date_period | date_period | -| 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 | date_nanos | date_nanos | -| time_duration | time_duration | time_duration | -| unsigned_long | unsigned_long | unsigned_long | - - -## Multiply `*` [_multiply] - -:::{image} ../../../../images/mul.svg -:alt: Embedded -:class: text-center -::: - -Multiply two numbers together. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| 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 | -| unsigned_long | unsigned_long | unsigned_long | - - -## Divide `/` [_divide] - -:::{image} ../../../../images/div.svg -:alt: Embedded -:class: text-center -::: - -Divide one number by another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -Division of two integer types will yield an integer result, rounding towards 0. If you need floating point division, [`Cast (::)`](../esql-functions-operators.md#esql-cast-operator) one of the arguments to a `DOUBLE`. -:::: - - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| 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 | -| unsigned_long | unsigned_long | unsigned_long | - - -## Modulus `%` [_modulus] - -:::{image} ../../../../images/mod.svg -:alt: Embedded -:class: text-center -::: - -Divide one number by another and return the remainder. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| 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 | -| unsigned_long | unsigned_long | unsigned_long | - - -## Unary operators [esql-unary-operators] - -The only unary operators is negation (`-`): - -:::{image} ../../../../images/neg.svg -:alt: Embedded -:class: text-center -::: - -Supported types: - -**Supported types** - -| field | result | -| --- | --- | -| date_period | date_period | -| double | double | -| integer | integer | -| long | long | -| time_duration | time_duration | - - -## Logical operators [esql-logical-operators] - -The following logical operators are supported: - -* `AND` -* `OR` -* `NOT` - - -## `IS NULL` and `IS NOT NULL` predicates [esql-predicates] - -For NULL comparison, use the `IS NULL` and `IS NOT NULL` predicates: - -```esql -FROM employees -| WHERE birth_date IS NULL -| KEEP first_name, last_name -| SORT first_name -| LIMIT 3 -``` - -| first_name:keyword | last_name:keyword | -| --- | --- | -| Basil | Tramer | -| Florian | Syrotiuk | -| Lucien | Rosenbaum | - -```esql -FROM employees -| WHERE is_rehired IS NOT NULL -| STATS COUNT(emp_no) -``` - -| COUNT(emp_no):long | -| --- | -| 84 | - - -## `Cast (::)` [esql-cast-operator] - -The `::` operator provides a convenient alternative syntax to the TO_ [conversion functions](../esql-functions-operators.md#esql-type-conversion-functions). - -```esql -ROW ver = CONCAT(("0"::INT + 1)::STRING, ".2.3")::VERSION -``` - -| ver:version | -| --- | -| 1.2.3 | - - -## `IN` [esql-in-operator] - -The `IN` operator allows testing whether a field or expression equals an element in a list of literals, fields or expressions: - -```esql -ROW a = 1, b = 4, c = 3 -| WHERE c-a IN (3, b / 2, a) -``` - -| a:integer | b:integer | c:integer | -| --- | --- | --- | -| 1 | 4 | 3 | - - -## `LIKE` [esql-like-operator] - -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 represents the pattern. - -The following wildcard characters are supported: - -* `*` matches zero or more characters. -* `?` matches one character. - -**Supported types** - -| str | pattern | result | -| --- | --- | --- | -| keyword | keyword | boolean | -| text | keyword | boolean | - -```esql -FROM employees -| WHERE first_name LIKE """?b*""" -| KEEP first_name, last_name -``` - -| first_name:keyword | last_name:keyword | -| --- | --- | -| Ebbe | Callaway | -| Eberhardt | Terkki | - -Matching the exact characters `*` and `.` will require escaping. The escape character is backslash `\`. Since also backslash is a special character in string literals, it will require further escaping. - -```esql -ROW message = "foo * bar" -| WHERE message LIKE "foo \\* bar" -``` - -To reduce the overhead of escaping, we suggest using triple quotes strings `"""` - -```esql -ROW message = "foo * bar" -| WHERE message LIKE """foo \* bar""" -``` - - -## `RLIKE` [esql-rlike-operator] - -Use `RLIKE` to filter data based on string patterns using using [regular expressions](/reference/query-languages/regexp-syntax.md). `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. - -**Supported types** - -| str | pattern | result | -| --- | --- | --- | -| keyword | keyword | boolean | -| text | keyword | boolean | - -```esql -FROM employees -| WHERE first_name RLIKE """.leja.*""" -| KEEP first_name, last_name -``` - -| first_name:keyword | last_name:keyword | -| --- | --- | -| Alejandro | McAlpine | - -Matching special characters (eg. `.`, `*`, `(`…​) will require escaping. The escape character is backslash `\`. Since also backslash is a special character in string literals, it will require further escaping. - -```esql -ROW message = "foo ( bar" -| WHERE message RLIKE "foo \\( bar" -``` - -To reduce the overhead of escaping, we suggest using triple quotes strings `"""` - -```esql -ROW message = "foo ( bar" -| WHERE message RLIKE """foo \( bar""" -``` - - -## Search operators [esql-search-operators] - -The only search operator is match (`:`). - -::::{warning} -Do not use 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 match operator performs a [match query](/reference/query-languages/query-dsl-match-query.md) on the specified field. Returns true if the provided query matches the row. - -The match operator is equivalent to the [match function](../esql-functions-operators.md#esql-match). - -For using the function syntax, or adding [match query parameters](/reference/query-languages/query-dsl-match-query.md#match-field-params), you can use the [match function](../esql-functions-operators.md#esql-match). - -:::{image} ../../../../images/match_operator.svg -:alt: Embedded -:class: text-center -::: - -**Supported types** - -| field | query | result | -| --- | --- | --- | -| boolean | boolean | boolean | -| boolean | keyword | boolean | -| date | date | boolean | -| date | keyword | boolean | -| date_nanos | date_nanos | boolean | -| date_nanos | keyword | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | keyword | boolean | -| double | long | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | keyword | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| ip | keyword | boolean | -| keyword | keyword | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | keyword | boolean | -| long | long | boolean | -| text | keyword | boolean | -| unsigned_long | double | boolean | -| unsigned_long | integer | boolean | -| unsigned_long | keyword | boolean | -| unsigned_long | long | boolean | -| unsigned_long | unsigned_long | boolean | -| version | keyword | boolean | -| version | version | boolean | - -```esql -FROM books -| WHERE author:"Faulkner" -| KEEP book_no, author -| SORT book_no -| LIMIT 5 -``` - -| book_no:keyword | author:text | -| --- | --- | -| 2378 | [Carol Faulkner, Holly Byers Ochoa, Lucretia Mott] | -| 2713 | William Faulkner | -| 2847 | Colleen Faulkner | -| 2883 | William Faulkner | -| 3293 | Danny Faulkner | diff --git a/docs/reference/query-languages/esql/_snippets/operators-orig.md b/docs/reference/query-languages/esql/_snippets/operators-orig.md deleted file mode 100644 index 7b5e0c3a74863..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/operators-orig.md +++ /dev/null @@ -1,665 +0,0 @@ -## {{esql}} operators [esql-operators] - -Boolean operators for comparing against one or multiple expressions. - -:::{include} lists/operators.md -::: - - -## Binary operators [esql-binary-operators] - - -## Equality [esql-binary-operators-equality] - -:::{image} ../../../../images/equals.svg -:alt: Embedded -:class: text-center -::: - -Check if two fields are equal. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| boolean | boolean | boolean | -| cartesian_point | cartesian_point | boolean | -| cartesian_shape | cartesian_shape | boolean | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| geo_point | geo_point | boolean | -| geo_shape | geo_shape | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Inequality `!=` [_inequality] - -:::{image} ../../../../images/not_equals.svg -:alt: Embedded -:class: text-center -::: - -Check if two fields are unequal. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| boolean | boolean | boolean | -| cartesian_point | cartesian_point | boolean | -| cartesian_shape | cartesian_shape | boolean | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| geo_point | geo_point | boolean | -| geo_shape | geo_shape | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Less than `<` [_less_than] - -:::{image} ../../../../images/less_than.svg -:alt: Embedded -:class: text-center -::: - -Check if one field is less than another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Less than or equal to `<=` [_less_than_or_equal_to] - -:::{image} ../../../../images/less_than_or_equal.svg -:alt: Embedded -:class: text-center -::: - -Check if one field is less than or equal to another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Greater than `>` [_greater_than] - -:::{image} ../../../../images/greater_than.svg -:alt: Embedded -:class: text-center -::: - -Check if one field is greater than another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Greater than or equal to `>=` [_greater_than_or_equal_to] - -:::{image} ../../../../images/greater_than_or_equal.svg -:alt: Embedded -:class: text-center -::: - -Check if one field is greater than or equal to another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Add `+` [esql-add] - -:::{image} ../../../../images/add.svg -:alt: Embedded -:class: text-center -::: - -Add two numbers together. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date_period | date | -| date | time_duration | date | -| date_nanos | date_period | date_nanos | -| date_nanos | time_duration | date_nanos | -| date_period | date | date | -| date_period | date_nanos | date_nanos | -| date_period | date_period | date_period | -| 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 | date | date | -| time_duration | date_nanos | date_nanos | -| time_duration | time_duration | time_duration | -| unsigned_long | unsigned_long | unsigned_long | - - -## Subtract `-` [esql-subtract] - -:::{image} ../../../../images/sub.svg -:alt: Embedded -:class: text-center -::: - -Subtract one number from another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date_period | date | -| date | time_duration | date | -| date_nanos | date_period | date_nanos | -| date_nanos | time_duration | date_nanos | -| date_period | date_nanos | date_nanos | -| date_period | date_period | date_period | -| 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 | date_nanos | date_nanos | -| time_duration | time_duration | time_duration | -| unsigned_long | unsigned_long | unsigned_long | - - -## Multiply `*` [_multiply] - -:::{image} ../../../../images/mul.svg -:alt: Embedded -:class: text-center -::: - -Multiply two numbers together. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| 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 | -| unsigned_long | unsigned_long | unsigned_long | - - -## Divide `/` [_divide] - -:::{image} ../../../../images/div.svg -:alt: Embedded -:class: text-center -::: - -Divide one number by another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -Division of two integer types will yield an integer result, rounding towards 0. If you need floating point division, [`Cast (::)`](../esql-functions-operators.md#esql-cast-operator) one of the arguments to a `DOUBLE`. -:::: - - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| 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 | -| unsigned_long | unsigned_long | unsigned_long | - - -## Modulus `%` [_modulus] - -:::{image} ../../../../images/mod.svg -:alt: Embedded -:class: text-center -::: - -Divide one number by another and return the remainder. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -Supported types: - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| 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 | -| unsigned_long | unsigned_long | unsigned_long | - - -## Unary operators [esql-unary-operators] - -The only unary operators is negation (`-`): - -:::{image} ../../../../images/neg.svg -:alt: Embedded -:class: text-center -::: - -Supported types: - -**Supported types** - -| field | result | -| --- | --- | -| date_period | date_period | -| double | double | -| integer | integer | -| long | long | -| time_duration | time_duration | - - -## Logical operators [esql-logical-operators] - -The following logical operators are supported: - -* `AND` -* `OR` -* `NOT` - - -## `IS NULL` and `IS NOT NULL` predicates [esql-predicates] - -For NULL comparison, use the `IS NULL` and `IS NOT NULL` predicates: - -```esql -FROM employees -| WHERE birth_date IS NULL -| KEEP first_name, last_name -| SORT first_name -| LIMIT 3 -``` - -| first_name:keyword | last_name:keyword | -| --- | --- | -| Basil | Tramer | -| Florian | Syrotiuk | -| Lucien | Rosenbaum | - -```esql -FROM employees -| WHERE is_rehired IS NOT NULL -| STATS COUNT(emp_no) -``` - -| COUNT(emp_no):long | -| --- | -| 84 | - - -## `Cast (::)` [esql-cast-operator] - -The `::` operator provides a convenient alternative syntax to the TO_ [conversion functions](../esql-functions-operators.md#esql-type-conversion-functions). - -```esql -ROW ver = CONCAT(("0"::INT + 1)::STRING, ".2.3")::VERSION -``` - -| ver:version | -| --- | -| 1.2.3 | - - -## `IN` [esql-in-operator] - -The `IN` operator allows testing whether a field or expression equals an element in a list of literals, fields or expressions: - -```esql -ROW a = 1, b = 4, c = 3 -| WHERE c-a IN (3, b / 2, a) -``` - -| a:integer | b:integer | c:integer | -| --- | --- | --- | -| 1 | 4 | 3 | - - -## `LIKE` [esql-like] - -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 represents the pattern. - -The following wildcard characters are supported: - -* `*` matches zero or more characters. -* `?` matches one character. - -**Supported types** - -| str | pattern | result | -| --- | --- | --- | -| keyword | keyword | boolean | -| text | keyword | boolean | - -```esql -FROM employees -| WHERE first_name LIKE """?b*""" -| KEEP first_name, last_name -``` - -| first_name:keyword | last_name:keyword | -| --- | --- | -| Ebbe | Callaway | -| Eberhardt | Terkki | - -Matching the exact characters `*` and `.` will require escaping. The escape character is backslash `\`. Since also backslash is a special character in string literals, it will require further escaping. - -```esql -ROW message = "foo * bar" -| WHERE message LIKE "foo \\* bar" -``` - -To reduce the overhead of escaping, we suggest using triple quotes strings `"""` - -```esql -ROW message = "foo * bar" -| WHERE message LIKE """foo \* bar""" -``` - - -## `RLIKE` [esql-rlike] - -Use `RLIKE` to filter data based on string patterns using using [regular expressions](/reference/query-languages/regexp-syntax.md). `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. - -**Supported types** - -| str | pattern | result | -| --- | --- | --- | -| keyword | keyword | boolean | -| text | keyword | boolean | - -```esql -FROM employees -| WHERE first_name RLIKE """.leja.*""" -| KEEP first_name, last_name -``` - -| first_name:keyword | last_name:keyword | -| --- | --- | -| Alejandro | McAlpine | - -Matching special characters (eg. `.`, `*`, `(`…​) will require escaping. The escape character is backslash `\`. Since also backslash is a special character in string literals, it will require further escaping. - -```esql -ROW message = "foo ( bar" -| WHERE message RLIKE "foo \\( bar" -``` - -To reduce the overhead of escaping, we suggest using triple quotes strings `"""` - -```esql -ROW message = "foo ( bar" -| WHERE message RLIKE """foo \( bar""" -``` - - -## Search operators [esql-search-operators] - -The only search operator is match (`:`). - -::::{warning} -Do not use 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 match operator performs a [match query](/reference/query-languages/query-dsl-match-query.md) on the specified field. Returns true if the provided query matches the row. - -The match operator is equivalent to the [match function](../esql-functions-operators.md#esql-match). - -For using the function syntax, or adding [match query parameters](/reference/query-languages/query-dsl-match-query.md#match-field-params), you can use the [match function](../esql-functions-operators.md#esql-match). - -:::{image} ../../../../images/match_operator.svg -:alt: Embedded -:class: text-center -::: - -**Supported types** - -| field | query | result | -| --- | --- | --- | -| boolean | boolean | boolean | -| boolean | keyword | boolean | -| date | date | boolean | -| date | keyword | boolean | -| date_nanos | date_nanos | boolean | -| date_nanos | keyword | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | keyword | boolean | -| double | long | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | keyword | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| ip | keyword | boolean | -| keyword | keyword | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | keyword | boolean | -| long | long | boolean | -| text | keyword | boolean | -| unsigned_long | double | boolean | -| unsigned_long | integer | boolean | -| unsigned_long | keyword | boolean | -| unsigned_long | long | boolean | -| unsigned_long | unsigned_long | boolean | -| version | keyword | boolean | -| version | version | boolean | - -```esql -FROM books -| WHERE author:"Faulkner" -| KEEP book_no, author -| SORT book_no -| LIMIT 5 -``` - -| book_no:keyword | author:text | -| --- | --- | -| 2378 | [Carol Faulkner, Holly Byers Ochoa, Lucretia Mott] | -| 2713 | William Faulkner | -| 2847 | Colleen Faulkner | -| 2883 | William Faulkner | -| 3293 | Danny Faulkner | diff --git a/docs/reference/query-languages/esql/_snippets/operators/binary-orig.md b/docs/reference/query-languages/esql/_snippets/operators/binary-orig.md deleted file mode 100644 index d34b21977d275..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/operators/binary-orig.md +++ /dev/null @@ -1,408 +0,0 @@ -## Binary operators [esql-binary-operators] - -:::{include} ../lists/binary-operators.md -::: - -## Equality [esql-equals] - -**Syntax** - -:::{image} ../../../../../images/equals.svg -:alt: Embedded -:class: text-center -::: - -Check if two fields are equal. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| boolean | boolean | boolean | -| cartesian_point | cartesian_point | boolean | -| cartesian_shape | cartesian_shape | boolean | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| geo_point | geo_point | boolean | -| geo_shape | geo_shape | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Inequality `!=` [esql-not_equals] - -:::{image} ../../../../../images/not_equals.svg -:alt: Embedded -:class: text-center -::: - -Check if two fields are unequal. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| boolean | boolean | boolean | -| cartesian_point | cartesian_point | boolean | -| cartesian_shape | cartesian_shape | boolean | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| geo_point | geo_point | boolean | -| geo_shape | geo_shape | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Less than `<` [esql-less_than] - -:::{image} ../../../../../images/less_than.svg -:alt: Embedded -:class: text-center -::: - -Check if one field is less than another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Less than or equal to `<=` [esql-less_than_or_equal] - -:::{image} ../../../../../images/less_than_or_equal.svg -:alt: Embedded -:class: text-center -::: - -Check if one field is less than or equal to another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Greater than `>` [esql-greater_than] - -:::{image} ../../../../../images/greater_than.svg -:alt: Embedded -:class: text-center -::: - -Check if one field is greater than another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Greater than or equal to `>=` [esql-greater_than_or_equal] - -:::{image} ../../../../../images/greater_than_or_equal.svg -:alt: Embedded -:class: text-center -::: - -Check if one field is greater than or equal to another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date | boolean | -| date | date_nanos | boolean | -| date_nanos | date | boolean | -| date_nanos | date_nanos | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | long | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| keyword | keyword | boolean | -| keyword | text | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | long | boolean | -| text | keyword | boolean | -| text | text | boolean | -| unsigned_long | unsigned_long | boolean | -| version | version | boolean | - - -## Add `+` [esql-add] - -:::{image} ../../../../../images/add.svg -:alt: Embedded -:class: text-center -::: - -Add two numbers together. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date_period | date | -| date | time_duration | date | -| date_nanos | date_period | date_nanos | -| date_nanos | time_duration | date_nanos | -| date_period | date | date | -| date_period | date_nanos | date_nanos | -| date_period | date_period | date_period | -| 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 | date | date | -| time_duration | date_nanos | date_nanos | -| time_duration | time_duration | time_duration | -| unsigned_long | unsigned_long | unsigned_long | - - -## Subtract `-` [esql-sub] - -:::{image} ../../../../../images/sub.svg -:alt: Embedded -:class: text-center -::: - -Subtract one number from another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| date | date_period | date | -| date | time_duration | date | -| date_nanos | date_period | date_nanos | -| date_nanos | time_duration | date_nanos | -| date_period | date_nanos | date_nanos | -| date_period | date_period | date_period | -| 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 | date_nanos | date_nanos | -| time_duration | time_duration | time_duration | -| unsigned_long | unsigned_long | unsigned_long | - - -## Multiply `*` [esql-mul] - -:::{image} ../../../../../images/mul.svg -:alt: Embedded -:class: text-center -::: - -Multiply two numbers together. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| 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 | -| unsigned_long | unsigned_long | unsigned_long | - - -## Divide `/` [esql-div] - -:::{image} ../../../../../images/div.svg -:alt: Embedded -:class: text-center -::: - -Divide one number by another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - -::::{note} -Division of two integer types will yield an integer result, rounding towards 0. If you need floating point division, [`Cast (::)`](../esql-functions-operators.md#esql-cast-operator) one of the arguments to a `DOUBLE`. -:::: - - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| 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 | -| unsigned_long | unsigned_long | unsigned_long | - - -## Modulus `%` [esql-mod] - -:::{image} ../../../../../images/mod.svg -:alt: Embedded -:class: text-center -::: - -Divide one number by another and return the remainder. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. - - -**Supported types** - -| lhs | rhs | result | -| --- | --- | --- | -| 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 | -| unsigned_long | unsigned_long | unsigned_long | - diff --git a/docs/reference/query-languages/esql/_snippets/operators/cast-orig.md b/docs/reference/query-languages/esql/_snippets/operators/cast-orig.md deleted file mode 100644 index ae109004b55d9..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/operators/cast-orig.md +++ /dev/null @@ -1,13 +0,0 @@ -## `Cast (::)` [esql-cast-operator] - -The `::` operator provides a convenient alternative syntax to the TO_ [conversion functions](../esql-functions-operators.md#esql-type-conversion-functions). - -**Example** - -```esql -ROW ver = CONCAT(("0"::INT + 1)::STRING, ".2.3")::VERSION -``` - -| ver:version | -| --- | -| 1.2.3 | diff --git a/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/div.md b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/div.md new file mode 100644 index 0000000000000..075b3232b6583 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/div.md @@ -0,0 +1,6 @@ + +::::{note} +Division of two integer types will yield an integer result, rounding towards 0. If you need floating point division, [`Cast (::)`](/reference/query-languages/esql/esql-functions-operators.md#esql-cast-operator) one of the arguments to a `DOUBLE`. +:::: + + diff --git a/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/equals.md b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/equals.md new file mode 100644 index 0000000000000..624dc4965a68b --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/equals.md @@ -0,0 +1,6 @@ + +::::{note} +This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [mapping-index](/reference/elasticsearch/mapping-reference/mapping-index.md) and [doc-values](/reference/elasticsearch/mapping-reference/doc-values.md). +:::: + + diff --git a/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/greater_than.md b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/greater_than.md new file mode 100644 index 0000000000000..624dc4965a68b --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/greater_than.md @@ -0,0 +1,6 @@ + +::::{note} +This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [mapping-index](/reference/elasticsearch/mapping-reference/mapping-index.md) and [doc-values](/reference/elasticsearch/mapping-reference/doc-values.md). +:::: + + diff --git a/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/greater_than_or_equal.md b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/greater_than_or_equal.md new file mode 100644 index 0000000000000..624dc4965a68b --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/greater_than_or_equal.md @@ -0,0 +1,6 @@ + +::::{note} +This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [mapping-index](/reference/elasticsearch/mapping-reference/mapping-index.md) and [doc-values](/reference/elasticsearch/mapping-reference/doc-values.md). +:::: + + diff --git a/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/less_than.md b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/less_than.md new file mode 100644 index 0000000000000..624dc4965a68b --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/less_than.md @@ -0,0 +1,6 @@ + +::::{note} +This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [mapping-index](/reference/elasticsearch/mapping-reference/mapping-index.md) and [doc-values](/reference/elasticsearch/mapping-reference/doc-values.md). +:::: + + diff --git a/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/less_than_or_equal.md b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/less_than_or_equal.md new file mode 100644 index 0000000000000..624dc4965a68b --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/less_than_or_equal.md @@ -0,0 +1,6 @@ + +::::{note} +This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [mapping-index](/reference/elasticsearch/mapping-reference/mapping-index.md) and [doc-values](/reference/elasticsearch/mapping-reference/doc-values.md). +:::: + + diff --git a/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/like.md b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/like.md new file mode 100644 index 0000000000000..823d9762e48b6 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/like.md @@ -0,0 +1,19 @@ + +Matching the exact characters `*` and `.` will require escaping. +The escape character is backslash `\`. Since also backslash is a special character in string literals, +it will require further escaping. + +```esql +ROW message = "foo * bar" +| WHERE message LIKE "foo \\* bar" +``` + + +To reduce the overhead of escaping, we suggest using triple quotes strings `"""` + +```esql +ROW message = "foo * bar" +| WHERE message LIKE """foo \* bar""" +``` + + diff --git a/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/not_equals.md b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/not_equals.md new file mode 100644 index 0000000000000..624dc4965a68b --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/not_equals.md @@ -0,0 +1,6 @@ + +::::{note} +This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [mapping-index](/reference/elasticsearch/mapping-reference/mapping-index.md) and [doc-values](/reference/elasticsearch/mapping-reference/doc-values.md). +:::: + + diff --git a/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/rlike.md b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/rlike.md new file mode 100644 index 0000000000000..77ae2840dad8b --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/rlike.md @@ -0,0 +1,19 @@ + +Matching special characters (eg. `.`, `*`, `(`...) will require escaping. +The escape character is backslash `\`. Since also backslash is a special character in string literals, +it will require further escaping. + +```esql +ROW message = "foo ( bar" +| WHERE message RLIKE "foo \\( bar" +``` + + +To reduce the overhead of escaping, we suggest using triple quotes strings `"""` + +```esql +ROW message = "foo ( bar" +| WHERE message RLIKE """foo \( bar""" +``` + + diff --git a/docs/reference/query-languages/esql/_snippets/operators/examples/in.md b/docs/reference/query-languages/esql/_snippets/operators/examples/in.md index d244221898274..134d637b30a80 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/examples/in.md +++ b/docs/reference/query-languages/esql/_snippets/operators/examples/in.md @@ -10,3 +10,5 @@ ROW a = 1, b = 4, c = 3 | a:integer | b:integer | c:integer | | --- | --- | --- | | 1 | 4 | 3 | + + diff --git a/docs/reference/query-languages/esql/_snippets/operators/examples/like.md b/docs/reference/query-languages/esql/_snippets/operators/examples/like.md index d42e065809536..8f0c0cc8faf81 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/examples/like.md +++ b/docs/reference/query-languages/esql/_snippets/operators/examples/like.md @@ -1,6 +1,6 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. -**Examples** +**Example** ```esql FROM employees @@ -13,17 +13,4 @@ FROM employees | Ebbe | Callaway | | Eberhardt | Terkki | -Matching the exact characters `*` and `.` will require escaping. The escape character is backslash `\`. Since also backslash is a special character in string literals, it will require further escaping. - -```esql -ROW message = "foo * bar" -| WHERE message LIKE "foo \\* bar" -``` - -To reduce the overhead of escaping, we suggest using triple quotes strings `"""` - -```esql -ROW message = "foo * bar" -| WHERE message LIKE """foo \* bar""" -``` diff --git a/docs/reference/query-languages/esql/_snippets/operators/examples/match.md b/docs/reference/query-languages/esql/_snippets/operators/examples/match_operator.md similarity index 92% rename from docs/reference/query-languages/esql/_snippets/operators/examples/match.md rename to docs/reference/query-languages/esql/_snippets/operators/examples/match_operator.md index 0c2612276ac28..a3b3b5386d0c6 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/examples/match.md +++ b/docs/reference/query-languages/esql/_snippets/operators/examples/match_operator.md @@ -4,7 +4,7 @@ ```esql FROM books -| WHERE author:"Faulkner" +| WHERE MATCH(author, "Faulkner") | KEEP book_no, author | SORT book_no | LIMIT 5 @@ -17,3 +17,5 @@ FROM books | 2847 | Colleen Faulkner | | 2883 | William Faulkner | | 3293 | Danny Faulkner | + + diff --git a/docs/reference/query-languages/esql/_snippets/operators/examples/rlike.md b/docs/reference/query-languages/esql/_snippets/operators/examples/rlike.md index 77e371f83ed3e..fad9cb34e662d 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/examples/rlike.md +++ b/docs/reference/query-languages/esql/_snippets/operators/examples/rlike.md @@ -1,6 +1,6 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. -**Examples** +**Example** ```esql FROM employees @@ -12,16 +12,4 @@ FROM employees | --- | --- | | Alejandro | McAlpine | -Matching special characters (eg. `.`, `*`, `(`…​) will require escaping. The escape character is backslash `\`. Since also backslash is a special character in string literals, it will require further escaping. -```esql -ROW message = "foo ( bar" -| WHERE message RLIKE "foo \\( bar" -``` - -To reduce the overhead of escaping, we suggest using triple quotes strings `"""` - -```esql -ROW message = "foo ( bar" -| WHERE message RLIKE """foo \( bar""" -``` diff --git a/docs/reference/query-languages/esql/_snippets/operators/in-orig.md b/docs/reference/query-languages/esql/_snippets/operators/in-orig.md deleted file mode 100644 index 12ce08ea160d9..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/operators/in-orig.md +++ /dev/null @@ -1,14 +0,0 @@ -## `IN` [esql-in-operator] - -The `IN` operator allows testing whether a field or expression equals an element in a list of literals, fields or expressions. - -**Example** - -```esql -ROW a = 1, b = 4, c = 3 -| WHERE c-a IN (3, b / 2, a) -``` - -| a:integer | b:integer | c:integer | -| --- | --- | --- | -| 1 | 4 | 3 | diff --git a/docs/reference/query-languages/esql/_snippets/operators/layout/div.md b/docs/reference/query-languages/esql/_snippets/operators/layout/div.md index 706ca0f57643e..06f5b8b48aec7 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/layout/div.md +++ b/docs/reference/query-languages/esql/_snippets/operators/layout/div.md @@ -9,11 +9,8 @@ Divide one number by another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. -::::{note} -Division of two integer types will yield an integer result, rounding towards 0. If you need floating point division, [`Cast (::)`](../../../esql-functions-operators.md#esql-cast-operator) one of the arguments to a `DOUBLE`. -:::: - - +:::{include} ../detailedDescription/div.md +::: :::{include} ../types/div.md ::: diff --git a/docs/reference/query-languages/esql/_snippets/operators/layout/equals.md b/docs/reference/query-languages/esql/_snippets/operators/layout/equals.md index 8ddf9b6c97440..052ff9d234eba 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/layout/equals.md +++ b/docs/reference/query-languages/esql/_snippets/operators/layout/equals.md @@ -11,11 +11,8 @@ Check if two fields are equal. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - +:::{include} ../detailedDescription/equals.md +::: :::{include} ../types/equals.md ::: diff --git a/docs/reference/query-languages/esql/_snippets/operators/layout/greater_than.md b/docs/reference/query-languages/esql/_snippets/operators/layout/greater_than.md index f2e596302d7a9..fb3db91be5b5c 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/layout/greater_than.md +++ b/docs/reference/query-languages/esql/_snippets/operators/layout/greater_than.md @@ -9,11 +9,8 @@ Check if one field is greater than another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - +:::{include} ../detailedDescription/greater_than.md +::: :::{include} ../types/greater_than.md ::: diff --git a/docs/reference/query-languages/esql/_snippets/operators/layout/greater_than_or_equal.md b/docs/reference/query-languages/esql/_snippets/operators/layout/greater_than_or_equal.md index 5937f3973575b..2378eff45cda1 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/layout/greater_than_or_equal.md +++ b/docs/reference/query-languages/esql/_snippets/operators/layout/greater_than_or_equal.md @@ -9,11 +9,8 @@ Check if one field is greater than or equal to another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - +:::{include} ../detailedDescription/greater_than_or_equal.md +::: :::{include} ../types/greater_than_or_equal.md ::: diff --git a/docs/reference/query-languages/esql/_snippets/operators/layout/less_than.md b/docs/reference/query-languages/esql/_snippets/operators/layout/less_than.md index ce378b4e117cf..6936cdbeb6dae 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/layout/less_than.md +++ b/docs/reference/query-languages/esql/_snippets/operators/layout/less_than.md @@ -9,11 +9,8 @@ Check if one field is less than another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - +:::{include} ../detailedDescription/less_than.md +::: :::{include} ../types/less_than.md ::: diff --git a/docs/reference/query-languages/esql/_snippets/operators/layout/less_than_or_equal.md b/docs/reference/query-languages/esql/_snippets/operators/layout/less_than_or_equal.md index d19322701bfb7..6acf12ba0f2f2 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/layout/less_than_or_equal.md +++ b/docs/reference/query-languages/esql/_snippets/operators/layout/less_than_or_equal.md @@ -9,11 +9,8 @@ Check if one field is less than or equal to another. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - +:::{include} ../detailedDescription/less_than_or_equal.md +::: :::{include} ../types/less_than_or_equal.md ::: diff --git a/docs/reference/query-languages/esql/_snippets/operators/layout/like.md b/docs/reference/query-languages/esql/_snippets/operators/layout/like.md index 2e471fd189600..e7dc0ff3b8af4 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/layout/like.md +++ b/docs/reference/query-languages/esql/_snippets/operators/layout/like.md @@ -15,3 +15,6 @@ The following wildcard characters are supported: :::{include} ../examples/like.md ::: + +:::{include} ../detailedDescription/like.md +::: diff --git a/docs/reference/query-languages/esql/_snippets/operators/layout/match.md b/docs/reference/query-languages/esql/_snippets/operators/layout/match_operator.md similarity index 87% rename from docs/reference/query-languages/esql/_snippets/operators/layout/match.md rename to docs/reference/query-languages/esql/_snippets/operators/layout/match_operator.md index 264ea79ec5d43..1980f5937889d 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/layout/match.md +++ b/docs/reference/query-languages/esql/_snippets/operators/layout/match_operator.md @@ -4,7 +4,7 @@ The only search operator is match (`:`). **Syntax** -:::{image} ../../../images/operators/match.svg +:::{image} ../../../images/operators/match_operator.svg :alt: Embedded :class: text-center ::: @@ -22,8 +22,8 @@ The match operator is equivalent to the [match function](../../../esql-functions For using the function syntax, or adding [match query parameters](/reference/query-languages/query-dsl-match-query.md#match-field-params), you can use the [match function](../../../esql-functions-operators.md#esql-match). -:::{include} ../types/match.md +:::{include} ../types/match_operator.md ::: -:::{include} ../examples/match.md +:::{include} ../examples/match_operator.md ::: diff --git a/docs/reference/query-languages/esql/_snippets/operators/layout/not_equals.md b/docs/reference/query-languages/esql/_snippets/operators/layout/not_equals.md index 0c539b8734d94..ef11bfdb60544 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/layout/not_equals.md +++ b/docs/reference/query-languages/esql/_snippets/operators/layout/not_equals.md @@ -9,11 +9,8 @@ Check if two fields are unequal. If either field is [multivalued](/reference/query-languages/esql/esql-multivalued-fields.md) then the result is `null`. -::::{note} -This is pushed to the underlying search index if one side of the comparison is constant and the other side is a field in the index that has both an [`index`](/reference/elasticsearch/mapping-reference/mapping-index.md) and [`doc_values`](/reference/elasticsearch/mapping-reference/doc-values.md). -:::: - - +:::{include} ../detailedDescription/not_equals.md +::: :::{include} ../types/not_equals.md ::: diff --git a/docs/reference/query-languages/esql/_snippets/operators/layout/rlike.md b/docs/reference/query-languages/esql/_snippets/operators/layout/rlike.md index 4cd88e2d2c29e..e38b437da99c6 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/layout/rlike.md +++ b/docs/reference/query-languages/esql/_snippets/operators/layout/rlike.md @@ -10,3 +10,6 @@ Use `RLIKE` to filter data based on string patterns using using [regular express :::{include} ../examples/rlike.md ::: + +:::{include} ../detailedDescription/rlike.md +::: diff --git a/docs/reference/query-languages/esql/_snippets/operators/like-and-rlike-orig.md b/docs/reference/query-languages/esql/_snippets/operators/like-and-rlike-orig.md deleted file mode 100644 index 38136bbf77968..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/operators/like-and-rlike-orig.md +++ /dev/null @@ -1,84 +0,0 @@ -## `LIKE` and `RLIKE` [esql-like-operators] - -:::{include} ../lists/like-and-rlike-operators.md -::: - -## `LIKE` [esql-like] - -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 represents the pattern. - -The following wildcard characters are supported: - -* `*` matches zero or more characters. -* `?` matches one character. - -**Supported types** - -| str | pattern | result | -| --- | --- | --- | -| keyword | keyword | boolean | -| text | keyword | boolean | - -**Examples** - -```esql -FROM employees -| WHERE first_name LIKE """?b*""" -| KEEP first_name, last_name -``` - -| first_name:keyword | last_name:keyword | -| --- | --- | -| Ebbe | Callaway | -| Eberhardt | Terkki | - -Matching the exact characters `*` and `.` will require escaping. The escape character is backslash `\`. Since also backslash is a special character in string literals, it will require further escaping. - -```esql -ROW message = "foo * bar" -| WHERE message LIKE "foo \\* bar" -``` - -To reduce the overhead of escaping, we suggest using triple quotes strings `"""` - -```esql -ROW message = "foo * bar" -| WHERE message LIKE """foo \* bar""" -``` - -## `RLIKE` [esql-rlike] - -Use `RLIKE` to filter data based on string patterns using using [regular expressions](/reference/query-languages/regexp-syntax.md). `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. - -**Supported types** - -| str | pattern | result | -| --- | --- | --- | -| keyword | keyword | boolean | -| text | keyword | boolean | - -**Examples** - -```esql -FROM employees -| WHERE first_name RLIKE """.leja.*""" -| KEEP first_name, last_name -``` - -| first_name:keyword | last_name:keyword | -| --- | --- | -| Alejandro | McAlpine | - -Matching special characters (eg. `.`, `*`, `(`…​) will require escaping. The escape character is backslash `\`. Since also backslash is a special character in string literals, it will require further escaping. - -```esql -ROW message = "foo ( bar" -| WHERE message RLIKE "foo \\( bar" -``` - -To reduce the overhead of escaping, we suggest using triple quotes strings `"""` - -```esql -ROW message = "foo ( bar" -| WHERE message RLIKE """foo \( bar""" -``` diff --git a/docs/reference/query-languages/esql/_snippets/operators/logical-orig.md b/docs/reference/query-languages/esql/_snippets/operators/logical-orig.md deleted file mode 100644 index 5b8384baa54e2..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/operators/logical-orig.md +++ /dev/null @@ -1,7 +0,0 @@ -## Logical operators [esql-logical-operators] - -The following logical operators are supported: - -* `AND` -* `OR` -* `NOT` diff --git a/docs/reference/query-languages/esql/_snippets/operators/predicates-orig.md b/docs/reference/query-languages/esql/_snippets/operators/predicates-orig.md deleted file mode 100644 index d6e1f142be428..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/operators/predicates-orig.md +++ /dev/null @@ -1,29 +0,0 @@ -## `IS NULL` and `IS NOT NULL` predicates [esql-predicates] - -For NULL comparison, use the `IS NULL` and `IS NOT NULL` predicates. - -**Examples** - -```esql -FROM employees -| WHERE birth_date IS NULL -| KEEP first_name, last_name -| SORT first_name -| LIMIT 3 -``` - -| first_name:keyword | last_name:keyword | -| --- | --- | -| Basil | Tramer | -| Florian | Syrotiuk | -| Lucien | Rosenbaum | - -```esql -FROM employees -| WHERE is_rehired IS NOT NULL -| STATS COUNT(emp_no) -``` - -| COUNT(emp_no):long | -| --- | -| 84 | diff --git a/docs/reference/query-languages/esql/_snippets/operators/search-orig.md b/docs/reference/query-languages/esql/_snippets/operators/search-orig.md deleted file mode 100644 index 0883730c29361..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/operators/search-orig.md +++ /dev/null @@ -1,74 +0,0 @@ -## Search operators [esql-search-operators] - -The only search operator is match (`:`). - -**Syntax** - -:::{image} ../../../../images/match.svg -:alt: Embedded -:class: text-center -::: - - -::::{warning} -Do not use 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 match operator performs a [match query](/reference/query-languages/query-dsl-match-query.md) on the specified field. Returns true if the provided query matches the row. - -The match operator is equivalent to the [match function](../esql-functions-operators.md#esql-match). - -For using the function syntax, or adding [match query parameters](/reference/query-languages/query-dsl-match-query.md#match-field-params), you can use the [match function](../esql-functions-operators.md#esql-match). - -**Supported types** - -| field | query | result | -| --- | --- | --- | -| boolean | boolean | boolean | -| boolean | keyword | boolean | -| date | date | boolean | -| date | keyword | boolean | -| date_nanos | date_nanos | boolean | -| date_nanos | keyword | boolean | -| double | double | boolean | -| double | integer | boolean | -| double | keyword | boolean | -| double | long | boolean | -| integer | double | boolean | -| integer | integer | boolean | -| integer | keyword | boolean | -| integer | long | boolean | -| ip | ip | boolean | -| ip | keyword | boolean | -| keyword | keyword | boolean | -| long | double | boolean | -| long | integer | boolean | -| long | keyword | boolean | -| long | long | boolean | -| text | keyword | boolean | -| unsigned_long | double | boolean | -| unsigned_long | integer | boolean | -| unsigned_long | keyword | boolean | -| unsigned_long | long | boolean | -| unsigned_long | unsigned_long | boolean | -| version | keyword | boolean | -| version | version | boolean | - -**Example** - -```esql -FROM books -| WHERE author:"Faulkner" -| KEEP book_no, author -| SORT book_no -| LIMIT 5 -``` - -| book_no:keyword | author:text | -| --- | --- | -| 2378 | [Carol Faulkner, Holly Byers Ochoa, Lucretia Mott] | -| 2713 | William Faulkner | -| 2847 | Colleen Faulkner | -| 2883 | William Faulkner | -| 3293 | Danny Faulkner | diff --git a/docs/reference/query-languages/esql/_snippets/operators/search.md b/docs/reference/query-languages/esql/_snippets/operators/search.md index a0ba9a618c650..6c629e8335bdd 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/search.md +++ b/docs/reference/query-languages/esql/_snippets/operators/search.md @@ -1,5 +1,5 @@ ## Search operators [esql-search-operators] -:::{include} layout/match.md +:::{include} layout/match_operator.md ::: diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/add.md b/docs/reference/query-languages/esql/_snippets/operators/types/add.md index 8646d3f1f0530..91363f492ad8d 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/types/add.md +++ b/docs/reference/query-languages/esql/_snippets/operators/types/add.md @@ -25,4 +25,3 @@ | time_duration | time_duration | time_duration | | unsigned_long | unsigned_long | unsigned_long | - diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/div.md b/docs/reference/query-languages/esql/_snippets/operators/types/div.md index e98a11fb97a18..137de12a44b80 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/types/div.md +++ b/docs/reference/query-languages/esql/_snippets/operators/types/div.md @@ -15,4 +15,3 @@ | long | long | long | | unsigned_long | unsigned_long | unsigned_long | - diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/equals.md b/docs/reference/query-languages/esql/_snippets/operators/types/equals.md index 9746a6e8fb6eb..9026a298fefd6 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/types/equals.md +++ b/docs/reference/query-languages/esql/_snippets/operators/types/equals.md @@ -30,4 +30,3 @@ | unsigned_long | unsigned_long | boolean | | version | version | boolean | - diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/greater_than.md b/docs/reference/query-languages/esql/_snippets/operators/types/greater_than.md index 42bd436af5416..2329fd0009c51 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/types/greater_than.md +++ b/docs/reference/query-languages/esql/_snippets/operators/types/greater_than.md @@ -25,4 +25,3 @@ | unsigned_long | unsigned_long | boolean | | version | version | boolean | - diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/greater_than_or_equal.md b/docs/reference/query-languages/esql/_snippets/operators/types/greater_than_or_equal.md index 42bd436af5416..2329fd0009c51 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/types/greater_than_or_equal.md +++ b/docs/reference/query-languages/esql/_snippets/operators/types/greater_than_or_equal.md @@ -25,4 +25,3 @@ | unsigned_long | unsigned_long | boolean | | version | version | boolean | - diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/in.md b/docs/reference/query-languages/esql/_snippets/operators/types/in.md new file mode 100644 index 0000000000000..94e024ea85bfa --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/types/in.md @@ -0,0 +1,21 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +**Supported types** + +| field | inlist | result | +| --- | --- | --- | +| boolean | boolean | boolean | +| cartesian_point | cartesian_point | boolean | +| cartesian_shape | cartesian_shape | boolean | +| double | double | boolean | +| geo_point | geo_point | boolean | +| geo_shape | geo_shape | boolean | +| integer | integer | boolean | +| ip | ip | boolean | +| keyword | keyword | boolean | +| keyword | text | boolean | +| long | long | boolean | +| text | keyword | boolean | +| text | text | boolean | +| version | version | boolean | + diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/less_than.md b/docs/reference/query-languages/esql/_snippets/operators/types/less_than.md index 42bd436af5416..2329fd0009c51 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/types/less_than.md +++ b/docs/reference/query-languages/esql/_snippets/operators/types/less_than.md @@ -25,4 +25,3 @@ | unsigned_long | unsigned_long | boolean | | version | version | boolean | - diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/less_than_or_equal.md b/docs/reference/query-languages/esql/_snippets/operators/types/less_than_or_equal.md index 42bd436af5416..2329fd0009c51 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/types/less_than_or_equal.md +++ b/docs/reference/query-languages/esql/_snippets/operators/types/less_than_or_equal.md @@ -25,4 +25,3 @@ | unsigned_long | unsigned_long | boolean | | version | version | boolean | - diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/match.md b/docs/reference/query-languages/esql/_snippets/operators/types/match_operator.md similarity index 100% rename from docs/reference/query-languages/esql/_snippets/operators/types/match.md rename to docs/reference/query-languages/esql/_snippets/operators/types/match_operator.md diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/mul.md b/docs/reference/query-languages/esql/_snippets/operators/types/mul.md index e98a11fb97a18..137de12a44b80 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/types/mul.md +++ b/docs/reference/query-languages/esql/_snippets/operators/types/mul.md @@ -15,4 +15,3 @@ | long | long | long | | unsigned_long | unsigned_long | unsigned_long | - diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/not in.md b/docs/reference/query-languages/esql/_snippets/operators/types/not in.md new file mode 100644 index 0000000000000..94e024ea85bfa --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/types/not in.md @@ -0,0 +1,21 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +**Supported types** + +| field | inlist | result | +| --- | --- | --- | +| boolean | boolean | boolean | +| cartesian_point | cartesian_point | boolean | +| cartesian_shape | cartesian_shape | boolean | +| double | double | boolean | +| geo_point | geo_point | boolean | +| geo_shape | geo_shape | boolean | +| integer | integer | boolean | +| ip | ip | boolean | +| keyword | keyword | boolean | +| keyword | text | boolean | +| long | long | boolean | +| text | keyword | boolean | +| text | text | boolean | +| version | version | boolean | + diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/not like.md b/docs/reference/query-languages/esql/_snippets/operators/types/not like.md new file mode 100644 index 0000000000000..2694da68af814 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/types/not like.md @@ -0,0 +1,9 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +**Supported types** + +| str | pattern | result | +| --- | --- | --- | +| keyword | keyword | boolean | +| text | keyword | boolean | + diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/not rlike.md b/docs/reference/query-languages/esql/_snippets/operators/types/not rlike.md new file mode 100644 index 0000000000000..2694da68af814 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/types/not rlike.md @@ -0,0 +1,9 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +**Supported types** + +| str | pattern | result | +| --- | --- | --- | +| keyword | keyword | boolean | +| text | keyword | boolean | + diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/not_equals.md b/docs/reference/query-languages/esql/_snippets/operators/types/not_equals.md index 9746a6e8fb6eb..9026a298fefd6 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/types/not_equals.md +++ b/docs/reference/query-languages/esql/_snippets/operators/types/not_equals.md @@ -30,4 +30,3 @@ | unsigned_long | unsigned_long | boolean | | version | version | boolean | - diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/not_like.md b/docs/reference/query-languages/esql/_snippets/operators/types/not_like.md new file mode 100644 index 0000000000000..2694da68af814 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/types/not_like.md @@ -0,0 +1,9 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +**Supported types** + +| str | pattern | result | +| --- | --- | --- | +| keyword | keyword | boolean | +| text | keyword | boolean | + diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/not_rlike.md b/docs/reference/query-languages/esql/_snippets/operators/types/not_rlike.md new file mode 100644 index 0000000000000..2694da68af814 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/types/not_rlike.md @@ -0,0 +1,9 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +**Supported types** + +| str | pattern | result | +| --- | --- | --- | +| keyword | keyword | boolean | +| text | keyword | boolean | + diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/sub.md b/docs/reference/query-languages/esql/_snippets/operators/types/sub.md index 543af1a978858..953d380541e77 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/types/sub.md +++ b/docs/reference/query-languages/esql/_snippets/operators/types/sub.md @@ -23,4 +23,3 @@ | time_duration | time_duration | time_duration | | unsigned_long | unsigned_long | unsigned_long | - diff --git a/docs/reference/query-languages/esql/_snippets/operators/unary-orig.md b/docs/reference/query-languages/esql/_snippets/operators/unary-orig.md deleted file mode 100644 index 87aa26a733a43..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/operators/unary-orig.md +++ /dev/null @@ -1,21 +0,0 @@ -## Unary operators [esql-unary-operators] - -The only unary operator is negation (`-`): - -**Syntax** - -:::{image} ../../../../images/neg.svg -:alt: Embedded -:class: text-center -::: - -**Supported types** - -| field | result | -| --- | --- | -| date_period | date_period | -| double | double | -| integer | integer | -| long | long | -| time_duration | time_duration | - diff --git a/docs/reference/query-languages/esql/_snippets/search-functions-new.md b/docs/reference/query-languages/esql/_snippets/search-functions-new.md deleted file mode 100644 index 420f303af196d..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/search-functions-new.md +++ /dev/null @@ -1,26 +0,0 @@ -## {{esql}} Full-text search functions [esql-search-functions] - - -Full text functions are used to search for text in fields. [Text analysis](docs-content://manage-data/data-store/text-analysis.md) is used to analyze the query before it is searched. - -Full text functions can be used to match [multivalued fields](/reference/query-languages/esql/esql-multivalued-fields.md). A multivalued field that contains a value that matches a full text query is considered to match the query. - -Full text functions are significantly more performant for text search use cases on large data sets than using pattern matching or regular expressions with `LIKE` or `RLIKE` - -See [full text search limitations](/reference/query-languages/esql/limitations.md#esql-limitations-full-text-search) for information on the limitations of full text search. - -{{esql}} supports these full-text search functions: - -:::{include} lists/search-functions.md -::: - - -:::{include} functions/kql.md -::: - -:::{include} functions/match.md -::: - -:::{include} functions/qstr.md -::: - diff --git a/docs/reference/query-languages/esql/_snippets/search-functions-orig.md b/docs/reference/query-languages/esql/_snippets/search-functions-orig.md deleted file mode 100644 index 92e176507c147..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/search-functions-orig.md +++ /dev/null @@ -1,222 +0,0 @@ -## {{esql}} Full-text search functions [esql-search-functions] - - -Full text functions are used to search for text in fields. [Text analysis](docs-content://manage-data/data-store/text-analysis.md) is used to analyze the query before it is searched. - -Full text functions can be used to match [multivalued fields](/reference/query-languages/esql/esql-multivalued-fields.md). A multivalued field that contains a value that matches a full text query is considered to match the query. - -Full text functions are significantly more performant for text search use cases on large data sets than using pattern matching or regular expressions with `LIKE` or `RLIKE` - -See [full text search limitations](/reference/query-languages/esql/limitations.md#esql-limitations-full-text-search) for information on the limitations of full text search. - -{{esql}} supports these full-text search functions: - -:::{include} lists/search-functions.md -::: - - -## `KQL` [esql-kql] - -::::{warning} -Do not use 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. -:::: - - -**Syntax** - -:::{image} ../../../../images/kql.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`query` -: Query string in KQL query string format. - -**Description** - -Performs a KQL query. Returns true if the provided KQL query string matches the row. - -**Supported types** - -| query | result | -| --- | --- | -| keyword | boolean | -| text | boolean | - -**Example** - -```esql -FROM books -| WHERE KQL("author: Faulkner") -| KEEP book_no, author -| SORT book_no -| LIMIT 5 -``` - -| book_no:keyword | author:text | -| --- | --- | -| 2378 | [Carol Faulkner, Holly Byers Ochoa, Lucretia Mott] | -| 2713 | William Faulkner | -| 2847 | Colleen Faulkner | -| 2883 | William Faulkner | -| 3293 | Danny Faulkner | - - -## `MATCH` [esql-match] - -::::{warning} -Do not use 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. -:::: - - -**Syntax** - -:::{image} ../../../../images/match.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Field that the query will target. - -`query` -: Value to find in the provided field. - -`options` -: (Optional) Match additional options as [function named parameters](/reference/query-languages/esql/esql-syntax.md#esql-function-named-params). See [match query](/reference/query-languages/query-dsl-match-query.md) for more information. - -**Description** - -Use `MATCH` to perform a [match query](/reference/query-languages/query-dsl-match-query.md) on the specified field. Using `MATCH` is equivalent to using the `match` query in the Elasticsearch Query DSL. Match can be used on fields from the text family like [text](/reference/elasticsearch/mapping-reference/text.md) and [semantic_text](/reference/elasticsearch/mapping-reference/semantic-text.md), as well as other field types like keyword, boolean, dates, and numeric types. Match can use [function named parameters](/reference/query-languages/esql/esql-syntax.md#esql-function-named-params) to specify additional options for the match query. All [match query parameters](/reference/query-languages/query-dsl-match-query.md#match-field-params) are supported. For a simplified syntax, you can use the [match operator](../esql-functions-operators.md#esql-search-operators) `:` operator instead of `MATCH`. `MATCH` returns true if the provided query matches the row. - -**Supported types** - -| field | query | options | result | -| --- | --- | --- | --- | -| boolean | boolean | named parameters | boolean | -| boolean | keyword | named parameters | boolean | -| date | date | named parameters | boolean | -| date | keyword | named parameters | boolean | -| date_nanos | date_nanos | named parameters | boolean | -| date_nanos | keyword | named parameters | boolean | -| double | double | named parameters | boolean | -| double | integer | named parameters | boolean | -| double | keyword | named parameters | boolean | -| double | long | named parameters | boolean | -| integer | double | named parameters | boolean | -| integer | integer | named parameters | boolean | -| integer | keyword | named parameters | boolean | -| integer | long | named parameters | boolean | -| ip | ip | named parameters | boolean | -| ip | keyword | named parameters | boolean | -| keyword | keyword | named parameters | boolean | -| long | double | named parameters | boolean | -| long | integer | named parameters | boolean | -| long | keyword | named parameters | boolean | -| long | long | named parameters | boolean | -| text | keyword | named parameters | boolean | -| unsigned_long | double | named parameters | boolean | -| unsigned_long | integer | named parameters | boolean | -| unsigned_long | keyword | named parameters | boolean | -| unsigned_long | long | named parameters | boolean | -| unsigned_long | unsigned_long | named parameters | boolean | -| version | keyword | named parameters | boolean | -| version | version | named parameters | boolean | - -**Supported function named parameters** - -| name | types | description | -| --- | --- | --- | -| fuzziness | [keyword] | Maximum edit distance allowed for matching. | -| auto_generate_synonyms_phrase_query | [boolean] | If true, match phrase queries are automatically created for multi-term synonyms. | -| analyzer | [keyword] | Analyzer used to convert the text in the query value into token. | -| minimum_should_match | [integer] | Minimum number of clauses that must match for a document to be returned. | -| zero_terms_query | [keyword] | Number of beginning characters left unchanged for fuzzy matching. | -| boost | [float] | Floating point number used to decrease or increase the relevance scores of the query. | -| fuzzy_transpositions | [boolean] | If true, edits for fuzzy matching include transpositions of two adjacent characters (ab → ba). | -| fuzzy_rewrite | [keyword] | Method used to rewrite the query. See the rewrite parameter for valid values and more information. | -| prefix_length | [integer] | Number of beginning characters left unchanged for fuzzy matching. | -| lenient | [boolean] | If false, format-based errors, such as providing a text query value for a numeric field, are returned. | -| operator | [keyword] | Boolean logic used to interpret text in the query value. | -| max_expansions | [integer] | Maximum number of terms to which the query will expand. | - -**Examples** - -```esql -FROM books -| WHERE MATCH(author, "Faulkner") -| KEEP book_no, author -| SORT book_no -| LIMIT 5 -``` - -| book_no:keyword | author:text | -| --- | --- | -| 2378 | [Carol Faulkner, Holly Byers Ochoa, Lucretia Mott] | -| 2713 | William Faulkner | -| 2847 | Colleen Faulkner | -| 2883 | William Faulkner | -| 3293 | Danny Faulkner | - -```esql -FROM books -| WHERE MATCH(title, "Hobbit Back Again", {"operator": "AND"}) -| KEEP title; -``` - -| title:text | -| --- | -| The Hobbit or There and Back Again | - - -## `QSTR` [esql-qstr] - -::::{warning} -Do not use 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. -:::: - - -**Syntax** - -:::{image} ../../../../images/qstr.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`query` -: Query string in Lucene query string format. - -**Description** - -Performs a [query string query](/reference/query-languages/query-dsl-query-string-query.md). Returns true if the provided query string matches the row. - -**Supported types** - -| query | result | -| --- | --- | -| keyword | boolean | -| text | boolean | - -**Example** - -```esql -FROM books -| WHERE QSTR("author: Faulkner") -| KEEP book_no, author -| SORT book_no -| LIMIT 5 -``` - -| book_no:keyword | author:text | -| --- | --- | -| 2378 | [Carol Faulkner, Holly Byers Ochoa, Lucretia Mott] | -| 2713 | William Faulkner | -| 2847 | Colleen Faulkner | -| 2883 | William Faulkner | -| 3293 | Danny Faulkner | diff --git a/docs/reference/query-languages/esql/_snippets/search-functions.md b/docs/reference/query-languages/esql/_snippets/search-functions.md index 4e4235b16c2ec..0c48adf063f6d 100644 --- a/docs/reference/query-languages/esql/_snippets/search-functions.md +++ b/docs/reference/query-languages/esql/_snippets/search-functions.md @@ -24,3 +24,8 @@ See [full text search limitations](/reference/query-languages/esql/limitations.m :::{include} functions/layout/qstr.md ::: +% TERM is currently a hidden feature +% To make it visible again, uncomment this and the line in lists/search-functions.md +% :::{include} functions/layout/term.md +% ::: + diff --git a/docs/reference/query-languages/esql/_snippets/spatial-functions-new.md b/docs/reference/query-languages/esql/_snippets/spatial-functions-new.md deleted file mode 100644 index 032a826334405..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/spatial-functions-new.md +++ /dev/null @@ -1,44 +0,0 @@ -## {{esql}} spatial functions [esql-spatial-functions] - -{{esql}} supports these spatial functions: - -:::{include} lists/spatial-functions.md -::: - - -:::{include} functions/st_distance.md -::: - -:::{include} functions/st_intersects.md -::: - -:::{include} functions/st_disjoint.md -::: - -:::{include} functions/st_contains.md -::: - -:::{include} functions/st_within.md -::: - -:::{include} functions/st_x.md -::: - -:::{include} functions/st_y.md -::: - -:::{include} functions/st_envelope.md -::: - -:::{include} functions/st_xmax.md -::: - -:::{include} functions/st_xmin.md -::: - -:::{include} functions/st_ymax.md -::: - -:::{include} functions/st_ymin.md -::: - diff --git a/docs/reference/query-languages/esql/_snippets/spatial-functions-orig.md b/docs/reference/query-languages/esql/_snippets/spatial-functions-orig.md deleted file mode 100644 index e4a09a1a28642..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/spatial-functions-orig.md +++ /dev/null @@ -1,518 +0,0 @@ -## {{esql}} spatial functions [esql-spatial-functions] - -{{esql}} supports these spatial functions: - -:::{include} lists/spatial-functions.md -::: - - -## `ST_DISTANCE` [esql-st_distance] - -**Syntax** - -:::{image} ../../../../images/st_distance.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`geomA` -: Expression of type `geo_point` or `cartesian_point`. If `null`, the function returns `null`. - -`geomB` -: Expression of type `geo_point` or `cartesian_point`. If `null`, the function returns `null`. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine `geo_point` and `cartesian_point` parameters. - -**Description** - -Computes the distance between two points. For cartesian geometries, this is the pythagorean distance in the same units as the original coordinates. For geographic geometries, this is the circular distance along the great circle in meters. - -**Supported types** - -| geomA | geomB | result | -| --- | --- | --- | -| cartesian_point | cartesian_point | double | -| geo_point | geo_point | double | - -**Example** - -```esql -FROM airports -| WHERE abbrev == "CPH" -| EVAL distance = ST_DISTANCE(location, city_location) -| KEEP abbrev, name, location, city_location, distance -``` - -| abbrev:k | name:text | location:geo_point | city_location:geo_point | distance:d | -| --- | --- | --- | --- | --- | -| CPH | Copenhagen | POINT(12.6493508684508 55.6285017221528) | POINT(12.5683 55.6761) | 7339.573896618216 | - - -## `ST_INTERSECTS` [esql-st_intersects] - -**Syntax** - -:::{image} ../../../../images/st_intersects.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`geomA` -: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. - -`geomB` -: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine `geo_*` and `cartesian_*` parameters. - -**Description** - -Returns true if two geometries intersect. They intersect if they have any point in common, including their interior points (points along lines or within polygons). This is the inverse of the [ST_DISJOINT](../esql-functions-operators.md#esql-st_disjoint) function. In mathematical terms: ST_Intersects(A, B) ⇔ A ⋂ B ≠ ∅ - -**Supported types** - -| geomA | geomB | result | -| --- | --- | --- | -| cartesian_point | cartesian_point | boolean | -| cartesian_point | cartesian_shape | boolean | -| cartesian_shape | cartesian_point | boolean | -| cartesian_shape | cartesian_shape | boolean | -| geo_point | geo_point | boolean | -| geo_point | geo_shape | boolean | -| geo_shape | geo_point | boolean | -| geo_shape | geo_shape | boolean | - -**Example** - -```esql -FROM airports -| WHERE ST_INTERSECTS(location, TO_GEOSHAPE("POLYGON((42 14, 43 14, 43 15, 42 15, 42 14))")) -``` - -| abbrev:keyword | city:keyword | city_location:geo_point | country:keyword | location:geo_point | name:text | scalerank:i | type:k | -| --- | --- | --- | --- | --- | --- | --- | --- | -| HOD | Al Ḩudaydah | POINT(42.9511 14.8022) | Yemen | POINT(42.97109630194 14.7552534413725) | Hodeidah Int’l | 9 | mid | - - -## `ST_DISJOINT` [esql-st_disjoint] - -**Syntax** - -:::{image} ../../../../images/st_disjoint.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`geomA` -: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. - -`geomB` -: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine `geo_*` and `cartesian_*` parameters. - -**Description** - -Returns whether the two geometries or geometry columns are disjoint. This is the inverse of the [ST_INTERSECTS](../esql-functions-operators.md#esql-st_intersects) function. In mathematical terms: ST_Disjoint(A, B) ⇔ A ⋂ B = ∅ - -**Supported types** - -| geomA | geomB | result | -| --- | --- | --- | -| cartesian_point | cartesian_point | boolean | -| cartesian_point | cartesian_shape | boolean | -| cartesian_shape | cartesian_point | boolean | -| cartesian_shape | cartesian_shape | boolean | -| geo_point | geo_point | boolean | -| geo_point | geo_shape | boolean | -| geo_shape | geo_point | boolean | -| geo_shape | geo_shape | boolean | - -**Example** - -```esql -FROM airport_city_boundaries -| WHERE ST_DISJOINT(city_boundary, TO_GEOSHAPE("POLYGON((-10 -60, 120 -60, 120 60, -10 60, -10 -60))")) -| KEEP abbrev, airport, region, city, city_location -``` - -| abbrev:keyword | airport:text | region:text | city:keyword | city_location:geo_point | -| --- | --- | --- | --- | --- | -| ACA | General Juan N Alvarez Int’l | Acapulco de Juárez | Acapulco de Juárez | POINT (-99.8825 16.8636) | - - -## `ST_CONTAINS` [esql-st_contains] - -**Syntax** - -:::{image} ../../../../images/st_contains.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`geomA` -: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. - -`geomB` -: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine `geo_*` and `cartesian_*` parameters. - -**Description** - -Returns whether the first geometry contains the second geometry. This is the inverse of the [ST_WITHIN](../esql-functions-operators.md#esql-st_within) function. - -**Supported types** - -| geomA | geomB | result | -| --- | --- | --- | -| cartesian_point | cartesian_point | boolean | -| cartesian_point | cartesian_shape | boolean | -| cartesian_shape | cartesian_point | boolean | -| cartesian_shape | cartesian_shape | boolean | -| geo_point | geo_point | boolean | -| geo_point | geo_shape | boolean | -| geo_shape | geo_point | boolean | -| geo_shape | geo_shape | boolean | - -**Example** - -```esql -FROM airport_city_boundaries -| WHERE ST_CONTAINS(city_boundary, TO_GEOSHAPE("POLYGON((109.35 18.3, 109.45 18.3, 109.45 18.4, 109.35 18.4, 109.35 18.3))")) -| KEEP abbrev, airport, region, city, city_location -``` - -| abbrev:keyword | airport:text | region:text | city:keyword | city_location:geo_point | -| --- | --- | --- | --- | --- | -| SYX | Sanya Phoenix Int’l | 天涯区 | Sanya | POINT(109.5036 18.2533) | - - -## `ST_WITHIN` [esql-st_within] - -**Syntax** - -:::{image} ../../../../images/st_within.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`geomA` -: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. - -`geomB` -: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine `geo_*` and `cartesian_*` parameters. - -**Description** - -Returns whether the first geometry is within the second geometry. This is the inverse of the [ST_CONTAINS](../esql-functions-operators.md#esql-st_contains) function. - -**Supported types** - -| geomA | geomB | result | -| --- | --- | --- | -| cartesian_point | cartesian_point | boolean | -| cartesian_point | cartesian_shape | boolean | -| cartesian_shape | cartesian_point | boolean | -| cartesian_shape | cartesian_shape | boolean | -| geo_point | geo_point | boolean | -| geo_point | geo_shape | boolean | -| geo_shape | geo_point | boolean | -| geo_shape | geo_shape | boolean | - -**Example** - -```esql -FROM airport_city_boundaries -| WHERE ST_WITHIN(city_boundary, TO_GEOSHAPE("POLYGON((109.1 18.15, 109.6 18.15, 109.6 18.65, 109.1 18.65, 109.1 18.15))")) -| KEEP abbrev, airport, region, city, city_location -``` - -| abbrev:keyword | airport:text | region:text | city:keyword | city_location:geo_point | -| --- | --- | --- | --- | --- | -| SYX | Sanya Phoenix Int’l | 天涯区 | Sanya | POINT(109.5036 18.2533) | - - -## `ST_X` [esql-st_x] - -**Syntax** - -:::{image} ../../../../images/st_x.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`point` -: Expression of type `geo_point` or `cartesian_point`. If `null`, the function returns `null`. - -**Description** - -Extracts the `x` coordinate from the supplied point. If the points is of type `geo_point` this is equivalent to extracting the `longitude` value. - -**Supported types** - -| point | result | -| --- | --- | -| cartesian_point | double | -| geo_point | double | - -**Example** - -```esql -ROW point = TO_GEOPOINT("POINT(42.97109629958868 14.7552534006536)") -| EVAL x = ST_X(point), y = ST_Y(point) -``` - -| point:geo_point | x:double | y:double | -| --- | --- | --- | -| POINT(42.97109629958868 14.7552534006536) | 42.97109629958868 | 14.7552534006536 | - - -## `ST_Y` [esql-st_y] - -**Syntax** - -:::{image} ../../../../images/st_y.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`point` -: Expression of type `geo_point` or `cartesian_point`. If `null`, the function returns `null`. - -**Description** - -Extracts the `y` coordinate from the supplied point. If the points is of type `geo_point` this is equivalent to extracting the `latitude` value. - -**Supported types** - -| point | result | -| --- | --- | -| cartesian_point | double | -| geo_point | double | - -**Example** - -```esql -ROW point = TO_GEOPOINT("POINT(42.97109629958868 14.7552534006536)") -| EVAL x = ST_X(point), y = ST_Y(point) -``` - -| point:geo_point | x:double | y:double | -| --- | --- | --- | -| POINT(42.97109629958868 14.7552534006536) | 42.97109629958868 | 14.7552534006536 | - - -## `ST_ENVELOPE` [esql-st_envelope] - -**Syntax** - -:::{image} ../../../../images/st_envelope.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`geometry` -: Expression of type `geo_point`, `geo_shape`, `cartesian_point` or `cartesian_shape`. If `null`, the function returns `null`. - -**Description** - -Determines the minimum bounding box of the supplied geometry. - -**Supported types** - -| geometry | result | -| --- | --- | -| cartesian_point | cartesian_shape | -| cartesian_shape | cartesian_shape | -| geo_point | geo_shape | -| geo_shape | geo_shape | - -**Example** - -```esql -FROM airport_city_boundaries -| WHERE abbrev == "CPH" -| EVAL envelope = ST_ENVELOPE(city_boundary) -| KEEP abbrev, airport, envelope -``` - -| abbrev:keyword | airport:text | envelope:geo_shape | -| --- | --- | --- | -| CPH | Copenhagen | BBOX(12.453, 12.6398, 55.7327, 55.6318) | - - -## `ST_XMAX` [esql-st_xmax] - -**Syntax** - -:::{image} ../../../../images/st_xmax.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`point` -: Expression of type `geo_point`, `geo_shape`, `cartesian_point` or `cartesian_shape`. If `null`, the function returns `null`. - -**Description** - -Extracts the maximum value of the `x` coordinates from the supplied geometry. If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the maximum `longitude` value. - -**Supported types** - -| point | result | -| --- | --- | -| cartesian_point | double | -| cartesian_shape | double | -| geo_point | double | -| geo_shape | double | - -**Example** - -```esql -FROM airport_city_boundaries -| WHERE abbrev == "CPH" -| EVAL envelope = ST_ENVELOPE(city_boundary) -| EVAL xmin = ST_XMIN(envelope), xmax = ST_XMAX(envelope), ymin = ST_YMIN(envelope), ymax = ST_YMAX(envelope) -| KEEP abbrev, airport, xmin, xmax, ymin, ymax -``` - -| abbrev:keyword | airport:text | xmin:double | xmax:double | ymin:double | ymax:double | -| --- | --- | --- | --- | --- | --- | -| CPH | Copenhagen | 12.453 | 12.6398 | 55.6318 | 55.7327 | - - -## `ST_XMIN` [esql-st_xmin] - -**Syntax** - -:::{image} ../../../../images/st_xmin.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`point` -: Expression of type `geo_point`, `geo_shape`, `cartesian_point` or `cartesian_shape`. If `null`, the function returns `null`. - -**Description** - -Extracts the minimum value of the `x` coordinates from the supplied geometry. If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the minimum `longitude` value. - -**Supported types** - -| point | result | -| --- | --- | -| cartesian_point | double | -| cartesian_shape | double | -| geo_point | double | -| geo_shape | double | - -**Example** - -```esql -FROM airport_city_boundaries -| WHERE abbrev == "CPH" -| EVAL envelope = ST_ENVELOPE(city_boundary) -| EVAL xmin = ST_XMIN(envelope), xmax = ST_XMAX(envelope), ymin = ST_YMIN(envelope), ymax = ST_YMAX(envelope) -| KEEP abbrev, airport, xmin, xmax, ymin, ymax -``` - -| abbrev:keyword | airport:text | xmin:double | xmax:double | ymin:double | ymax:double | -| --- | --- | --- | --- | --- | --- | -| CPH | Copenhagen | 12.453 | 12.6398 | 55.6318 | 55.7327 | - - -## `ST_YMAX` [esql-st_ymax] - -**Syntax** - -:::{image} ../../../../images/st_ymax.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`point` -: Expression of type `geo_point`, `geo_shape`, `cartesian_point` or `cartesian_shape`. If `null`, the function returns `null`. - -**Description** - -Extracts the maximum value of the `y` coordinates from the supplied geometry. If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the maximum `latitude` value. - -**Supported types** - -| point | result | -| --- | --- | -| cartesian_point | double | -| cartesian_shape | double | -| geo_point | double | -| geo_shape | double | - -**Example** - -```esql -FROM airport_city_boundaries -| WHERE abbrev == "CPH" -| EVAL envelope = ST_ENVELOPE(city_boundary) -| EVAL xmin = ST_XMIN(envelope), xmax = ST_XMAX(envelope), ymin = ST_YMIN(envelope), ymax = ST_YMAX(envelope) -| KEEP abbrev, airport, xmin, xmax, ymin, ymax -``` - -| abbrev:keyword | airport:text | xmin:double | xmax:double | ymin:double | ymax:double | -| --- | --- | --- | --- | --- | --- | -| CPH | Copenhagen | 12.453 | 12.6398 | 55.6318 | 55.7327 | - - -## `ST_YMIN` [esql-st_ymin] - -**Syntax** - -:::{image} ../../../../images/st_ymin.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`point` -: Expression of type `geo_point`, `geo_shape`, `cartesian_point` or `cartesian_shape`. If `null`, the function returns `null`. - -**Description** - -Extracts the minimum value of the `y` coordinates from the supplied geometry. If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the minimum `latitude` value. - -**Supported types** - -| point | result | -| --- | --- | -| cartesian_point | double | -| cartesian_shape | double | -| geo_point | double | -| geo_shape | double | - -**Example** - -```esql -FROM airport_city_boundaries -| WHERE abbrev == "CPH" -| EVAL envelope = ST_ENVELOPE(city_boundary) -| EVAL xmin = ST_XMIN(envelope), xmax = ST_XMAX(envelope), ymin = ST_YMIN(envelope), ymax = ST_YMAX(envelope) -| KEEP abbrev, airport, xmin, xmax, ymin, ymax -``` - -| abbrev:keyword | airport:text | xmin:double | xmax:double | ymin:double | ymax:double | -| --- | --- | --- | --- | --- | --- | -| CPH | Copenhagen | 12.453 | 12.6398 | 55.6318 | 55.7327 | diff --git a/docs/reference/query-languages/esql/_snippets/string-functions-new.md b/docs/reference/query-languages/esql/_snippets/string-functions-new.md deleted file mode 100644 index 2ee807f4aa04e..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/string-functions-new.md +++ /dev/null @@ -1,86 +0,0 @@ -## {{esql}} string functions [esql-string-functions] - -{{esql}} supports these string functions: - -:::{include} lists/string-functions.md -::: - - -:::{include} functions/bit_length.md -::: - -:::{include} functions/byte_length.md -::: - -:::{include} functions/concat.md -::: - -:::{include} functions/ends_with.md -::: - -:::{include} functions/from_base64.md -::: - -:::{include} functions/hash.md -::: - -:::{include} functions/left.md -::: - -:::{include} functions/length.md -::: - -:::{include} functions/locate.md -::: - -:::{include} functions/ltrim.md -::: - -:::{include} functions/md5.md -::: - -:::{include} functions/repeat.md -::: - -:::{include} functions/replace.md -::: - -:::{include} functions/reverse.md -::: - -:::{include} functions/right.md -::: - -:::{include} functions/rtrim.md -::: - -:::{include} functions/sha1.md -::: - -:::{include} functions/sha256.md -::: - -:::{include} functions/space.md -::: - -:::{include} functions/split.md -::: - -:::{include} functions/starts_with.md -::: - -:::{include} functions/substring.md -::: - -:::{include} functions/to_base64.md -::: - -:::{include} functions/to_lower.md -::: - -:::{include} functions/to_upper.md -::: - -:::{include} functions/trim.md -::: - diff --git a/docs/reference/query-languages/esql/_snippets/string-functions-orig.md b/docs/reference/query-languages/esql/_snippets/string-functions-orig.md deleted file mode 100644 index a0da3ba5b1af1..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/string-functions-orig.md +++ /dev/null @@ -1,1162 +0,0 @@ -## {{esql}} string functions [esql-string-functions] - -{{esql}} supports these string functions: - -:::{include} lists/string-functions.md -::: - - -## `BIT_LENGTH` [esql-bit_length] - -**Syntax** - -:::{image} ../../../../images/bit_length.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. If `null`, the function returns `null`. - -**Description** - -Returns the bit length of a string. - -::::{note} -All strings are in UTF-8, so a single character can use multiple bytes. -:::: - - -**Supported types** - -| string | result | -| --- | --- | -| keyword | integer | -| text | integer | - -**Example** - -```esql -FROM airports -| WHERE country == "India" -| KEEP city -| EVAL fn_length = LENGTH(city), fn_bit_length = BIT_LENGTH(city) -``` - -| city:keyword | fn_length:integer | fn_bit_length:integer | -| --- | --- | --- | -| Agwār | 5 | 48 | -| Ahmedabad | 9 | 72 | -| Bangalore | 9 | 72 | - - -## `BYTE_LENGTH` [esql-byte_length] - -**Syntax** - -:::{image} ../../../../images/byte_length.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. If `null`, the function returns `null`. - -**Description** - -Returns the byte length of a string. - -::::{note} -All strings are in UTF-8, so a single character can use multiple bytes. -:::: - - -**Supported types** - -| string | result | -| --- | --- | -| keyword | integer | -| text | integer | - -**Example** - -```esql -FROM airports -| WHERE country == "India" -| KEEP city -| EVAL fn_length = LENGTH(city), fn_byte_length = BYTE_LENGTH(city) -``` - -| city:keyword | fn_length:integer | fn_byte_length:integer | -| --- | --- | --- | -| Agwār | 5 | 6 | -| Ahmedabad | 9 | 9 | -| Bangalore | 9 | 9 | - - -## `CONCAT` [esql-concat] - -**Syntax** - -:::{image} ../../../../images/concat.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string1` -: Strings to concatenate. - -`string2` -: Strings to concatenate. - -**Description** - -Concatenates two or more strings. - -**Supported types** - -| string1 | string2 | result | -| --- | --- | --- | -| keyword | keyword | keyword | -| keyword | text | keyword | -| text | keyword | keyword | -| text | text | keyword | - -**Example** - -```esql -FROM employees -| KEEP first_name, last_name -| EVAL fullname = CONCAT(first_name, " ", last_name) -``` - -| first_name:keyword | last_name:keyword | fullname:keyword | -| --- | --- | --- | -| Alejandro | McAlpine | Alejandro McAlpine | -| Amabile | Gomatam | Amabile Gomatam | -| Anneke | Preusig | Anneke Preusig | - - -## `ENDS_WITH` [esql-ends_with] - -**Syntax** - -:::{image} ../../../../images/ends_with.svg -:alt: Embedded -:class: text-center -::: - -**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. - -**Supported types** - -| str | suffix | result | -| --- | --- | --- | -| keyword | keyword | boolean | -| keyword | text | boolean | -| text | keyword | boolean | -| text | text | boolean | - -**Example** - -```esql -FROM employees -| KEEP last_name -| EVAL ln_E = ENDS_WITH(last_name, "d") -``` - -| last_name:keyword | ln_E:boolean | -| --- | --- | -| Awdeh | false | -| Azuma | false | -| Baek | false | -| Bamford | true | -| Bernatsky | false | - - -## `FROM_BASE64` [esql-from_base64] - -**Syntax** - -:::{image} ../../../../images/from_base64.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: A base64 string. - -**Description** - -Decode a base64 string. - -**Supported types** - -| string | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -row a = "ZWxhc3RpYw==" -| eval d = from_base64(a) -``` - -| a:keyword | d:keyword | -| --- | --- | -| ZWxhc3RpYw== | elastic | - - -## `HASH` [esql-hash] - -**Syntax** - -:::{image} ../../../../images/hash.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`algorithm` -: Hash algorithm to use. - -`input` -: Input to hash. - -**Description** - -Computes the hash of the input using various algorithms such as MD5, SHA, SHA-224, SHA-256, SHA-384, SHA-512. - -**Supported types** - -| algorithm | input | result | -| --- | --- | --- | -| keyword | keyword | keyword | -| keyword | text | keyword | -| text | keyword | keyword | -| text | text | keyword | - -**Example** - -```esql -FROM sample_data -| WHERE message != "Connection error" -| EVAL md5 = hash("md5", message), sha256 = hash("sha256", message) -| KEEP message, md5, sha256; -``` - -| message:keyword | md5:keyword | sha256:keyword | -| --- | --- | --- | -| Connected to 10.1.0.1 | abd7d1ce2bb636842a29246b3512dcae | 6d8372129ad78770f7185554dd39864749a62690216460752d6c075fa38ad85c | -| Connected to 10.1.0.2 | 8f8f1cb60832d153f5b9ec6dc828b93f | b0db24720f15857091b3c99f4c4833586d0ea3229911b8777efb8d917cf27e9a | -| Connected to 10.1.0.3 | 912b6dc13503165a15de43304bb77c78 | 75b0480188db8acc4d5cc666a51227eb2bc5b989cd8ca912609f33e0846eff57 | -| Disconnected | ef70e46fd3bbc21e3e1f0b6815e750c0 | 04dfac3671b494ad53fcd152f7a14511bfb35747278aad8ce254a0d6e4ba4718 | - - -## `LEFT` [esql-left] - -**Syntax** - -:::{image} ../../../../images/left.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: The string from which to return a substring. - -`length` -: The number of characters to return. - -**Description** - -Returns the substring that extracts *length* chars from *string* starting from the left. - -**Supported types** - -| string | length | result | -| --- | --- | --- | -| keyword | integer | keyword | -| text | integer | keyword | - -**Example** - -```esql -FROM employees -| KEEP last_name -| EVAL left = LEFT(last_name, 3) -| SORT last_name ASC -| LIMIT 5 -``` - -| last_name:keyword | left:keyword | -| --- | --- | -| Awdeh | Awd | -| Azuma | Azu | -| Baek | Bae | -| Bamford | Bam | -| Bernatsky | Ber | - - -## `LENGTH` [esql-length] - -**Syntax** - -:::{image} ../../../../images/length.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. If `null`, the function returns `null`. - -**Description** - -Returns the character length of a string. - -::::{note} -All strings are in UTF-8, so a single character can use multiple bytes. -:::: - - -**Supported types** - -| string | result | -| --- | --- | -| keyword | integer | -| text | integer | - -**Example** - -```esql -FROM airports -| WHERE country == "India" -| KEEP city -| EVAL fn_length = LENGTH(city) -``` - -| city:keyword | fn_length:integer | -| --- | --- | -| Agwār | 5 | -| Ahmedabad | 9 | -| Bangalore | 9 | - - -## `LOCATE` [esql-locate] - -**Syntax** - -:::{image} ../../../../images/locate.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: An input string - -`substring` -: A substring to locate in the input string - -`start` -: The start index - -**Description** - -Returns an integer that indicates the position of a keyword substring within another string. Returns `0` if the substring cannot be found. Note that string positions start from `1`. - -**Supported types** - -| string | substring | start | result | -| --- | --- | --- | --- | -| keyword | keyword | integer | integer | -| keyword | keyword | | integer | -| keyword | text | integer | integer | -| keyword | text | | integer | -| text | keyword | integer | integer | -| text | keyword | | integer | -| text | text | integer | integer | -| text | text | | integer | - -**Example** - -```esql -row a = "hello" -| eval a_ll = locate(a, "ll") -``` - -| a:keyword | a_ll:integer | -| --- | --- | -| hello | 3 | - - -## `LTRIM` [esql-ltrim] - -**Syntax** - -:::{image} ../../../../images/ltrim.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. If `null`, the function returns `null`. - -**Description** - -Removes leading whitespaces from a string. - -**Supported types** - -| string | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -ROW message = " some text ", color = " red " -| EVAL message = LTRIM(message) -| EVAL color = LTRIM(color) -| EVAL message = CONCAT("'", message, "'") -| EVAL color = CONCAT("'", color, "'") -``` - -| message:keyword | color:keyword | -| --- | --- | -| 'some text ' | 'red ' | - - -## `MD5` [esql-md5] - -**Syntax** - -:::{image} ../../../../images/md5.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`input` -: Input to hash. - -**Description** - -Computes the MD5 hash of the input. - -**Supported types** - -| input | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -FROM sample_data -| WHERE message != "Connection error" -| EVAL md5 = md5(message) -| KEEP message, md5; -``` - -| message:keyword | md5:keyword | -| --- | --- | -| Connected to 10.1.0.1 | abd7d1ce2bb636842a29246b3512dcae | -| Connected to 10.1.0.2 | 8f8f1cb60832d153f5b9ec6dc828b93f | -| Connected to 10.1.0.3 | 912b6dc13503165a15de43304bb77c78 | -| Disconnected | ef70e46fd3bbc21e3e1f0b6815e750c0 | - - -## `REPEAT` [esql-repeat] - -**Syntax** - -:::{image} ../../../../images/repeat.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. - -`number` -: Number times to repeat. - -**Description** - -Returns a string constructed by concatenating `string` with itself the specified `number` of times. - -**Supported types** - -| string | number | result | -| --- | --- | --- | -| keyword | integer | keyword | -| text | integer | keyword | - -**Example** - -```esql -ROW a = "Hello!" -| EVAL triple_a = REPEAT(a, 3) -``` - -| a:keyword | triple_a:keyword | -| --- | --- | -| Hello! | Hello!Hello!Hello! | - - -## `REPLACE` [esql-replace] - -**Syntax** - -:::{image} ../../../../images/replace.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. - -`regex` -: Regular expression. - -`newString` -: Replacement string. - -**Description** - -The function substitutes in the string `str` any match of the regular expression `regex` with the replacement string `newStr`. - -**Supported types** - -| string | regex | newString | result | -| --- | --- | --- | --- | -| keyword | keyword | keyword | keyword | -| keyword | keyword | text | keyword | -| keyword | text | keyword | keyword | -| keyword | text | text | keyword | -| text | keyword | keyword | keyword | -| text | keyword | text | keyword | -| text | text | keyword | keyword | -| text | text | text | keyword | - -**Example** - -This example replaces any occurrence of the word "World" with the word "Universe": - -```esql -ROW str = "Hello World" -| EVAL str = REPLACE(str, "World", "Universe") -| KEEP str -``` - -| str:keyword | -| --- | -| Hello Universe | - - -## `REVERSE` [esql-reverse] - -**Syntax** - -:::{image} ../../../../images/reverse.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`str` -: String expression. If `null`, the function returns `null`. - -**Description** - -Returns a new string representing the input string in reverse order. - -**Supported types** - -| str | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Examples** - -```esql -ROW message = "Some Text" | EVAL message_reversed = REVERSE(message); -``` - -| message:keyword | message_reversed:keyword | -| --- | --- | -| Some Text | txeT emoS | - -`REVERSE` works with unicode, too! It keeps unicode grapheme clusters together during reversal. - -```esql -ROW bending_arts = "💧🪨🔥💨" | EVAL bending_arts_reversed = REVERSE(bending_arts); -``` - -| bending_arts:keyword | bending_arts_reversed:keyword | -| --- | --- | -| 💧🪨🔥💨 | 💨🔥🪨💧 | - - -## `RIGHT` [esql-right] - -**Syntax** - -:::{image} ../../../../images/right.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: 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** - -| string | length | result | -| --- | --- | --- | -| keyword | integer | keyword | -| text | integer | keyword | - -**Example** - -```esql -FROM employees -| KEEP last_name -| EVAL right = RIGHT(last_name, 3) -| SORT last_name ASC -| LIMIT 5 -``` - -| last_name:keyword | right:keyword | -| --- | --- | -| Awdeh | deh | -| Azuma | uma | -| Baek | aek | -| Bamford | ord | -| Bernatsky | sky | - - -## `RTRIM` [esql-rtrim] - -**Syntax** - -:::{image} ../../../../images/rtrim.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. If `null`, the function returns `null`. - -**Description** - -Removes trailing whitespaces from a string. - -**Supported types** - -| string | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -ROW message = " some text ", color = " red " -| EVAL message = RTRIM(message) -| EVAL color = RTRIM(color) -| EVAL message = CONCAT("'", message, "'") -| EVAL color = CONCAT("'", color, "'") -``` - -| message:keyword | color:keyword | -| --- | --- | -| ' some text' | ' red' | - - -## `SHA1` [esql-sha1] - -**Syntax** - -:::{image} ../../../../images/sha1.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`input` -: Input to hash. - -**Description** - -Computes the SHA1 hash of the input. - -**Supported types** - -| input | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -FROM sample_data -| WHERE message != "Connection error" -| EVAL sha1 = sha1(message) -| KEEP message, sha1; -``` - -| message:keyword | sha1:keyword | -| --- | --- | -| Connected to 10.1.0.1 | 42b85531a79088036a17759db7d2de292b92f57f | -| Connected to 10.1.0.2 | d30db445da2e9237c9718d0c7e4fb7cbbe9c2cb4 | -| Connected to 10.1.0.3 | 2733848d943809f0b10cad3e980763e88afb9853 | -| Disconnected | 771e05f27b99fd59f638f41a7a4e977b1d4691fe | - - -## `SHA256` [esql-sha256] - -**Syntax** - -:::{image} ../../../../images/sha256.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`input` -: Input to hash. - -**Description** - -Computes the SHA256 hash of the input. - -**Supported types** - -| input | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -FROM sample_data -| WHERE message != "Connection error" -| EVAL sha256 = sha256(message) -| KEEP message, sha256; -``` - -| message:keyword | sha256:keyword | -| --- | --- | -| Connected to 10.1.0.1 | 6d8372129ad78770f7185554dd39864749a62690216460752d6c075fa38ad85c | -| Connected to 10.1.0.2 | b0db24720f15857091b3c99f4c4833586d0ea3229911b8777efb8d917cf27e9a | -| Connected to 10.1.0.3 | 75b0480188db8acc4d5cc666a51227eb2bc5b989cd8ca912609f33e0846eff57 | -| Disconnected | 04dfac3671b494ad53fcd152f7a14511bfb35747278aad8ce254a0d6e4ba4718 | - - -## `SPACE` [esql-space] - -**Syntax** - -:::{image} ../../../../images/space.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Number of spaces in result. - -**Description** - -Returns a string made of `number` spaces. - -**Supported types** - -| number | result | -| --- | --- | -| integer | keyword | - -**Example** - -```esql -ROW message = CONCAT("Hello", SPACE(1), "World!"); -``` - -| message:keyword | -| --- | -| Hello World! | - - -## `SPLIT` [esql-split] - -**Syntax** - -:::{image} ../../../../images/split.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. If `null`, the function returns `null`. - -`delim` -: Delimiter. Only single byte delimiters are currently supported. - -**Description** - -Split a single valued string into multiple strings. - -**Supported types** - -| string | delim | result | -| --- | --- | --- | -| keyword | keyword | keyword | -| keyword | text | keyword | -| text | keyword | keyword | -| text | text | keyword | - -**Example** - -```esql -ROW words="foo;bar;baz;qux;quux;corge" -| EVAL word = SPLIT(words, ";") -``` - -| words:keyword | word:keyword | -| --- | --- | -| foo;bar;baz;qux;quux;corge | [foo,bar,baz,qux,quux,corge] | - - -## `STARTS_WITH` [esql-starts_with] - -**Syntax** - -:::{image} ../../../../images/starts_with.svg -:alt: Embedded -:class: text-center -::: - -**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. - -**Supported types** - -| str | prefix | result | -| --- | --- | --- | -| keyword | keyword | boolean | -| keyword | text | boolean | -| text | keyword | boolean | -| text | text | boolean | - -**Example** - -```esql -FROM employees -| KEEP last_name -| EVAL ln_S = STARTS_WITH(last_name, "B") -``` - -| last_name:keyword | ln_S:boolean | -| --- | --- | -| Awdeh | false | -| Azuma | false | -| Baek | true | -| Bamford | true | -| Bernatsky | true | - - -## `SUBSTRING` [esql-substring] - -**Syntax** - -:::{image} ../../../../images/substring.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: 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. - -**Supported types** - -| string | start | length | result | -| --- | --- | --- | --- | -| keyword | integer | integer | keyword | -| text | integer | integer | keyword | - -**Examples** - -This example returns the first three characters of every last name: - -```esql -FROM employees -| KEEP last_name -| EVAL ln_sub = SUBSTRING(last_name, 1, 3) -``` - -| last_name:keyword | ln_sub:keyword | -| --- | --- | -| Awdeh | Awd | -| Azuma | Azu | -| Baek | Bae | -| Bamford | Bam | -| Bernatsky | Ber | - -A negative start position is interpreted as being relative to the end of the string. This example returns the last three characters of of every last name: - -```esql -FROM employees -| KEEP last_name -| EVAL ln_sub = SUBSTRING(last_name, -3, 3) -``` - -| last_name:keyword | ln_sub:keyword | -| --- | --- | -| Awdeh | deh | -| Azuma | uma | -| Baek | aek | -| Bamford | ord | -| Bernatsky | sky | - -If length is omitted, substring returns the remainder of the string. This example returns all characters except for the first: - -```esql -FROM employees -| KEEP last_name -| EVAL ln_sub = SUBSTRING(last_name, 2) -``` - -| last_name:keyword | ln_sub:keyword | -| --- | --- | -| Awdeh | wdeh | -| Azuma | zuma | -| Baek | aek | -| Bamford | amford | -| Bernatsky | ernatsky | - - -## `TO_BASE64` [esql-to_base64] - -**Syntax** - -:::{image} ../../../../images/to_base64.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: A string. - -**Description** - -Encode a string to a base64 string. - -**Supported types** - -| string | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -row a = "elastic" -| eval e = to_base64(a) -``` - -| a:keyword | e:keyword | -| --- | --- | -| elastic | ZWxhc3RpYw== | - - -## `TO_LOWER` [esql-to_lower] - -**Syntax** - -:::{image} ../../../../images/to_lower.svg -:alt: Embedded -:class: text-center -::: - -**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** - -| str | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -ROW message = "Some Text" -| EVAL message_lower = TO_LOWER(message) -``` - -| message:keyword | message_lower:keyword | -| --- | --- | -| Some Text | some text | - - -## `TO_UPPER` [esql-to_upper] - -**Syntax** - -:::{image} ../../../../images/to_upper.svg -:alt: Embedded -:class: text-center -::: - -**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** - -| str | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -ROW message = "Some Text" -| EVAL message_upper = TO_UPPER(message) -``` - -| message:keyword | message_upper:keyword | -| --- | --- | -| Some Text | SOME TEXT | - - -## `TRIM` [esql-trim] - -**Syntax** - -:::{image} ../../../../images/trim.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`string` -: String expression. If `null`, the function returns `null`. - -**Description** - -Removes leading and trailing whitespaces from a string. - -**Supported types** - -| string | result | -| --- | --- | -| keyword | keyword | -| text | keyword | - -**Example** - -```esql -ROW message = " some text ", color = " red " -| EVAL message = TRIM(message) -| EVAL color = TRIM(color) -``` - -| message:s | color:s | -| --- | --- | -| some text | red | diff --git a/docs/reference/query-languages/esql/_snippets/test.md b/docs/reference/query-languages/esql/_snippets/test.md deleted file mode 100644 index f52e3396707bb..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/test.md +++ /dev/null @@ -1,4 +0,0 @@ -This is a test - -:::{include} lists/aggregation-functions.md -::: diff --git a/docs/reference/query-languages/esql/_snippets/type-conversion-functions-new.md b/docs/reference/query-languages/esql/_snippets/type-conversion-functions-new.md deleted file mode 100644 index a56d5fdc6067d..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/type-conversion-functions-new.md +++ /dev/null @@ -1,69 +0,0 @@ -## {{esql}} type conversion functions [esql-type-conversion-functions] - - -::::{tip} -{{esql}} supports implicit casting from string literals to certain data types. Refer to [implicit casting](/reference/query-languages/esql/esql-implicit-casting.md) for details. - -:::: - - -{{esql}} supports these type conversion functions: - -:::{include} lists/type-conversion-functions.md -::: - - -:::{include} functions/to_boolean.md -::: - -:::{include} functions/to_cartesianpoint.md -::: - -:::{include} functions/to_cartesianshape.md -::: - -:::{include} functions/to_dateperiod.md -::: - -:::{include} functions/to_datetime.md -::: - -:::{include} functions/to_date_nanos.md -::: - -:::{include} functions/to_degrees.md -::: - -:::{include} functions/to_double.md -::: - -:::{include} functions/to_geopoint.md -::: - -:::{include} functions/to_geoshape.md -::: - -:::{include} functions/to_integer.md -::: - -:::{include} functions/to_ip.md -::: - -:::{include} functions/to_long.md -::: - -:::{include} functions/to_radians.md -::: - -:::{include} functions/to_string.md -::: - -:::{include} functions/to_timeduration.md -::: - -:::{include} functions/to_unsigned_long.md -::: - -:::{include} functions/to_version.md -::: - diff --git a/docs/reference/query-languages/esql/_snippets/type-conversion-functions-orig.md b/docs/reference/query-languages/esql/_snippets/type-conversion-functions-orig.md deleted file mode 100644 index 47d4568e8ee32..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/type-conversion-functions-orig.md +++ /dev/null @@ -1,822 +0,0 @@ -## {{esql}} type conversion functions [esql-type-conversion-functions] - - -::::{tip} -{{esql}} supports implicit casting from string literals to certain data types. Refer to [implicit casting](/reference/query-languages/esql/esql-implicit-casting.md) for details. - -:::: - - -{{esql}} supports these type conversion functions: - -:::{include} lists/type-conversion-functions.md -::: - - -## `TO_BOOLEAN` [esql-to_boolean] - -**Syntax** - -:::{image} ../../../../images/to_boolean.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: 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**. The numerical value of **0** will be converted to **false**, anything else will be converted to **true**. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | boolean | -| double | boolean | -| integer | boolean | -| keyword | boolean | -| long | boolean | -| text | boolean | -| unsigned_long | boolean | - -**Example** - -```esql -ROW str = ["true", "TRuE", "false", "", "yes", "1"] -| EVAL bool = TO_BOOLEAN(str) -``` - -| str:keyword | bool:boolean | -| --- | --- | -| ["true", "TRuE", "false", "", "yes", "1"] | [true, true, false, false, false, false] | - - -## `TO_CARTESIANPOINT` [esql-to_cartesianpoint] - -**Syntax** - -:::{image} ../../../../images/to_cartesianpoint.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input value to a `cartesian_point` value. A string will only be successfully converted if it respects the [WKT Point](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -**Supported types** - -| field | result | -| --- | --- | -| cartesian_point | cartesian_point | -| keyword | cartesian_point | -| text | cartesian_point | - -**Example** - -```esql -ROW wkt = ["POINT(4297.11 -1475.53)", "POINT(7580.93 2272.77)"] -| MV_EXPAND wkt -| EVAL pt = TO_CARTESIANPOINT(wkt) -``` - -| wkt:keyword | pt:cartesian_point | -| --- | --- | -| "POINT(4297.11 -1475.53)" | POINT(4297.11 -1475.53) | -| "POINT(7580.93 2272.77)" | POINT(7580.93 2272.77) | - - -## `TO_CARTESIANSHAPE` [esql-to_cartesianshape] - -**Syntax** - -:::{image} ../../../../images/to_cartesianshape.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input value to a `cartesian_shape` value. A string will only be successfully converted if it respects the [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -**Supported types** - -| field | result | -| --- | --- | -| cartesian_point | cartesian_shape | -| cartesian_shape | cartesian_shape | -| keyword | cartesian_shape | -| text | cartesian_shape | - -**Example** - -```esql -ROW wkt = ["POINT(4297.11 -1475.53)", "POLYGON ((3339584.72 1118889.97, 4452779.63 4865942.27, 2226389.81 4865942.27, 1113194.90 2273030.92, 3339584.72 1118889.97))"] -| MV_EXPAND wkt -| EVAL geom = TO_CARTESIANSHAPE(wkt) -``` - -| wkt:keyword | geom:cartesian_shape | -| --- | --- | -| "POINT(4297.11 -1475.53)" | POINT(4297.11 -1475.53) | -| "POLYGON 3339584.72 1118889.97, 4452779.63 4865942.27, 2226389.81 4865942.27, 1113194.90 2273030.92, 3339584.72 1118889.97" | POLYGON 3339584.72 1118889.97, 4452779.63 4865942.27, 2226389.81 4865942.27, 1113194.90 2273030.92, 3339584.72 1118889.97 | - - -## `TO_DATEPERIOD` [esql-to_dateperiod] - -**Syntax** - -:::{image} ../../../../images/to_dateperiod.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input is a valid constant date period expression. - -**Description** - -Converts an input value into a `date_period` value. - -**Supported types** - -| field | result | -| --- | --- | -| date_period | date_period | -| keyword | date_period | -| text | date_period | - -**Example** - -```esql -row x = "2024-01-01"::datetime | eval y = x + "3 DAYS"::date_period, z = x - to_dateperiod("3 days"); -``` - -| x:datetime | y:datetime | z:datetime | -| --- | --- | --- | -| 2024-01-01 | 2024-01-04 | 2023-12-29 | - - -## `TO_DATETIME` [esql-to_datetime] - -**Syntax** - -:::{image} ../../../../images/to_datetime.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: 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 [`DATE_PARSE`](../esql-functions-operators.md#esql-date_parse). - -::::{note} -Note that when converting from nanosecond resolution to millisecond resolution with this function, the nanosecond date is truncated, not rounded. -:::: - - -**Supported types** - -| field | result | -| --- | --- | -| date | date | -| date_nanos | date | -| double | date | -| integer | date | -| keyword | date | -| long | date | -| text | date | -| unsigned_long | date | - -**Examples** - -```esql -ROW string = ["1953-09-02T00:00:00.000Z", "1964-06-02T00:00:00.000Z", "1964-06-02 00:00:00"] -| EVAL datetime = TO_DATETIME(string) -``` - -| string:keyword | datetime:date | -| --- | --- | -| ["1953-09-02T00:00:00.000Z", "1964-06-02T00:00:00.000Z", "1964-06-02 00:00:00"] | [1953-09-02T00:00:00.000Z, 1964-06-02T00:00:00.000Z] | - -Note that in this example, the last value in the source multi-valued field has not been converted. The reason being that if the date format is not respected, the conversion will result in a **null** value. When this happens a *Warning* header is added to the response. The header will provide information on the source of the failure: - -`"Line 1:112: evaluation of [TO_DATETIME(string)] failed, treating result as null. "Only first 20 failures recorded."` - -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 [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). For example: - -```esql -ROW int = [0, 1] -| EVAL dt = TO_DATETIME(int) -``` - -| int:integer | dt:date | -| --- | --- | -| [0, 1] | [1970-01-01T00:00:00.000Z, 1970-01-01T00:00:00.001Z] | - - -## `TO_DATE_NANOS` [esql-to_date_nanos] - -**Syntax** - -:::{image} ../../../../images/to_date_nanos.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input to a nanosecond-resolution date value (aka date_nanos). - -::::{note} -The range for date nanos is 1970-01-01T00:00:00.000000000Z to 2262-04-11T23:47:16.854775807Z, attepting to convertvalues outside of that range will result in null with a warning.. Additionally, integers cannot be converted into date nanos, as the range of integer nanoseconds only covers about 2 seconds after epoch. -:::: - - -**Supported types** - -| field | result | -| --- | --- | -| date | date_nanos | -| date_nanos | date_nanos | -| double | date_nanos | -| keyword | date_nanos | -| long | date_nanos | -| text | date_nanos | -| unsigned_long | date_nanos | - - -## `TO_DEGREES` [esql-to_degrees] - -**Syntax** - -:::{image} ../../../../images/to_degrees.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts a number in [radians](https://en.wikipedia.org/wiki/Radian) to [degrees](https://en.wikipedia.org/wiki/Degree_(angle)). - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW rad = [1.57, 3.14, 4.71] -| EVAL deg = TO_DEGREES(rad) -``` - -| rad:double | deg:double | -| --- | --- | -| [1.57, 3.14, 4.71] | [89.95437383553924, 179.9087476710785, 269.86312150661774] | - - -## `TO_DOUBLE` [esql-to_double] - -**Syntax** - -:::{image} ../../../../images/to_double.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input value to a double value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to double. Boolean **true** will be converted to double **1.0**, **false** to **0.0**. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | double | -| counter_double | double | -| counter_integer | double | -| counter_long | double | -| date | double | -| double | double | -| integer | double | -| keyword | double | -| long | double | -| text | double | -| unsigned_long | double | - -**Example** - -```esql -ROW str1 = "5.20128E11", str2 = "foo" -| EVAL dbl = TO_DOUBLE("520128000000"), dbl1 = TO_DOUBLE(str1), dbl2 = TO_DOUBLE(str2) -``` - -| str1:keyword | str2:keyword | dbl:double | dbl1:double | dbl2:double | -| --- | --- | --- | --- | --- | -| 5.20128E11 | foo | 5.20128E11 | 5.20128E11 | null | - -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""` - - -## `TO_GEOPOINT` [esql-to_geopoint] - -**Syntax** - -:::{image} ../../../../images/to_geopoint.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input value to a `geo_point` value. A string will only be successfully converted if it respects the [WKT Point](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -**Supported types** - -| field | result | -| --- | --- | -| geo_point | geo_point | -| keyword | geo_point | -| text | geo_point | - -**Example** - -```esql -ROW wkt = "POINT(42.97109630194 14.7552534413725)" -| EVAL pt = TO_GEOPOINT(wkt) -``` - -| wkt:keyword | pt:geo_point | -| --- | --- | -| "POINT(42.97109630194 14.7552534413725)" | POINT(42.97109630194 14.7552534413725) | - - -## `TO_GEOSHAPE` [esql-to_geoshape] - -**Syntax** - -:::{image} ../../../../images/to_geoshape.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input value to a `geo_shape` value. A string will only be successfully converted if it respects the [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. - -**Supported types** - -| field | result | -| --- | --- | -| geo_point | geo_shape | -| geo_shape | geo_shape | -| keyword | geo_shape | -| text | geo_shape | - -**Example** - -```esql -ROW wkt = "POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))" -| EVAL geom = TO_GEOSHAPE(wkt) -``` - -| wkt:keyword | geom:geo_shape | -| --- | --- | -| "POLYGON 30 10, 40 40, 20 40, 10 20, 30 10" | POLYGON 30 10, 40 40, 20 40, 10 20, 30 10 | - - -## `TO_INTEGER` [esql-to_integer] - -**Syntax** - -:::{image} ../../../../images/to_integer.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input value to an integer value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to integer. Boolean **true** will be converted to integer **1**, **false** to **0**. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | integer | -| counter_integer | integer | -| date | integer | -| double | integer | -| integer | integer | -| keyword | integer | -| long | integer | -| text | integer | -| unsigned_long | integer | - -**Example** - -```esql -ROW long = [5013792, 2147483647, 501379200000] -| EVAL int = TO_INTEGER(long) -``` - -| long:long | int:integer | -| --- | --- | -| [5013792, 2147483647, 501379200000] | [5013792, 2147483647] | - -Note that in this example, the last value of the multi-valued field cannot be converted as an integer. 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:61: evaluation of [TO_INTEGER(long)] failed, treating result as null. Only first 20 failures recorded."` - -A following header will contain the failure reason and the offending value: - -`"org.elasticsearch.xpack.esql.core.InvalidArgumentException: [501379200000] out of [integer] range"` - - -## `TO_IP` [esql-to_ip] - -**Syntax** - -:::{image} ../../../../images/to_ip.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input string to an IP value. - -**Supported types** - -| field | result | -| --- | --- | -| ip | ip | -| keyword | ip | -| text | ip | - -**Example** - -```esql -ROW str1 = "1.1.1.1", str2 = "foo" -| EVAL ip1 = TO_IP(str1), ip2 = TO_IP(str2) -| WHERE CIDR_MATCH(ip1, "1.0.0.0/8") -``` - -| str1:keyword | str2:keyword | ip1:ip | ip2:ip | -| --- | --- | --- | --- | -| 1.1.1.1 | foo | 1.1.1.1 | null | - -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."` - -A following header will contain the failure reason and the offending value: - -`"java.lang.IllegalArgumentException: 'foo' is not an IP string literal."` - - -## `TO_LONG` [esql-to_long] - -**Syntax** - -:::{image} ../../../../images/to_long.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts an input value to a long value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to long. Boolean **true** will be converted to long **1**, **false** to **0**. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | long | -| counter_integer | long | -| counter_long | long | -| date | long | -| date_nanos | long | -| double | long | -| integer | long | -| keyword | long | -| long | long | -| text | long | -| unsigned_long | long | - -**Example** - -```esql -ROW str1 = "2147483648", str2 = "2147483648.2", str3 = "foo" -| EVAL long1 = TO_LONG(str1), long2 = TO_LONG(str2), long3 = TO_LONG(str3) -``` - -| str1:keyword | str2:keyword | str3:keyword | long1:long | long2:long | long3:long | -| --- | --- | --- | --- | --- | --- | -| 2147483648 | 2147483648.2 | foo | 2147483648 | 2147483648 | null | - -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:113: evaluation of [TO_LONG(str3)] 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""` - - -## `TO_RADIANS` [esql-to_radians] - -**Syntax** - -:::{image} ../../../../images/to_radians.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`number` -: Input value. The input can be a single- or multi-valued column or an expression. - -**Description** - -Converts a number in [degrees](https://en.wikipedia.org/wiki/Degree_(angle)) to [radians](https://en.wikipedia.org/wiki/Radian). - -**Supported types** - -| number | result | -| --- | --- | -| double | double | -| integer | double | -| long | double | -| unsigned_long | double | - -**Example** - -```esql -ROW deg = [90.0, 180.0, 270.0] -| EVAL rad = TO_RADIANS(deg) -``` - -| deg:double | rad:double | -| --- | --- | -| [90.0, 180.0, 270.0] | [1.5707963267948966, 3.141592653589793, 4.71238898038469] | - - -## `TO_STRING` [esql-to_string] - -**Syntax** - -:::{image} ../../../../images/to_string.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: 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** - -| field | result | -| --- | --- | -| boolean | keyword | -| cartesian_point | keyword | -| cartesian_shape | keyword | -| date | keyword | -| date_nanos | keyword | -| double | keyword | -| geo_point | keyword | -| geo_shape | keyword | -| integer | keyword | -| ip | keyword | -| keyword | keyword | -| long | keyword | -| text | keyword | -| unsigned_long | keyword | -| version | keyword | - -**Examples** - -```esql -ROW a=10 -| EVAL j = TO_STRING(a) -``` - -| a:integer | j:keyword | -| --- | --- | -| 10 | "10" | - -It also works fine on multivalued fields: - -```esql -ROW a=[10, 9, 8] -| EVAL j = TO_STRING(a) -``` - -| a:integer | j:keyword | -| --- | --- | -| [10, 9, 8] | ["10", "9", "8"] | - - -## `TO_TIMEDURATION` [esql-to_timeduration] - -**Syntax** - -:::{image} ../../../../images/to_timeduration.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: Input value. The input is a valid constant time duration expression. - -**Description** - -Converts an input value into a `time_duration` value. - -**Supported types** - -| field | result | -| --- | --- | -| keyword | time_duration | -| text | time_duration | -| time_duration | time_duration | - -**Example** - -```esql -row x = "2024-01-01"::datetime | eval y = x + "3 hours"::time_duration, z = x - to_timeduration("3 hours"); -``` - -| x:datetime | y:datetime | z:datetime | -| --- | --- | --- | -| 2024-01-01 | 2024-01-01T03:00:00.000Z | 2023-12-31T21:00:00.000Z | - - -## `TO_UNSIGNED_LONG` [esql-to_unsigned_long] - -**Syntax** - -:::{image} ../../../../images/to_unsigned_long.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: 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. If the input parameter is of a date type, its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to unsigned long. Boolean **true** will be converted to unsigned long **1**, **false** to **0**. - -**Supported types** - -| field | result | -| --- | --- | -| boolean | unsigned_long | -| date | unsigned_long | -| double | unsigned_long | -| integer | unsigned_long | -| keyword | unsigned_long | -| long | unsigned_long | -| text | unsigned_long | -| unsigned_long | unsigned_long | - -**Example** - -```esql -ROW str1 = "2147483648", str2 = "2147483648.2", str3 = "foo" -| EVAL long1 = TO_UNSIGNED_LONG(str1), long2 = TO_ULONG(str2), long3 = TO_UL(str3) -``` - -| str1:keyword | str2:keyword | str3:keyword | long1:unsigned_long | long2:unsigned_long | long3:unsigned_long | -| --- | --- | --- | --- | --- | --- | -| 2147483648 | 2147483648.2 | foo | 2147483648 | 2147483648 | null | - -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:133: evaluation of [TO_UL(str3)] 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: Character f is neither a decimal digit number, decimal point, + "nor "e" notation exponential mark."` - - -## `TO_VERSION` [esql-to_version] - -**Syntax** - -:::{image} ../../../../images/to_version.svg -:alt: Embedded -:class: text-center -::: - -**Parameters** - -`field` -: 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** - -| field | result | -| --- | --- | -| keyword | version | -| text | version | -| version | version | - -**Example** - -```esql -ROW v = TO_VERSION("1.2.3") -``` - -| v:version | -| --- | -| 1.2.3 | diff --git a/docs/reference/query-languages/esql/esql-commands.md b/docs/reference/query-languages/esql/esql-commands.md index 4202a92986fd1..c39a7a77d2fcb 100644 --- a/docs/reference/query-languages/esql/esql-commands.md +++ b/docs/reference/query-languages/esql/esql-commands.md @@ -12,7 +12,7 @@ mapped_pages: An {{esql}} source command produces a table, typically with data from {{es}}. An {{esql}} query must start with a source command. :::{image} ../../../images/source-command.svg -:alt: A source command producing a table from {es} +:alt: A source command producing a table from {{es}} ::: {{esql}} supports these source commands: diff --git a/docs/reference/query-languages/esql/images/functions/abs.svg b/docs/reference/query-languages/esql/images/functions/abs.svg index c09ba90236a77..e78f044d05554 100644 --- a/docs/reference/query-languages/esql/images/functions/abs.svg +++ b/docs/reference/query-languages/esql/images/functions/abs.svg @@ -1 +1 @@ -ABS(number) +ABS(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/acos.svg b/docs/reference/query-languages/esql/images/functions/acos.svg index 125aa3c80c770..9c983ea7695da 100644 --- a/docs/reference/query-languages/esql/images/functions/acos.svg +++ b/docs/reference/query-languages/esql/images/functions/acos.svg @@ -1 +1 @@ -ACOS(number) +ACOS(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/asin.svg b/docs/reference/query-languages/esql/images/functions/asin.svg index ab4d3bac4c60a..44b5cd5b4cb09 100644 --- a/docs/reference/query-languages/esql/images/functions/asin.svg +++ b/docs/reference/query-languages/esql/images/functions/asin.svg @@ -1 +1 @@ -ASIN(number) +ASIN(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/atan.svg b/docs/reference/query-languages/esql/images/functions/atan.svg index 00491e658320b..5b5be2c5c8276 100644 --- a/docs/reference/query-languages/esql/images/functions/atan.svg +++ b/docs/reference/query-languages/esql/images/functions/atan.svg @@ -1 +1 @@ -ATAN(number) +ATAN(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/atan2.svg b/docs/reference/query-languages/esql/images/functions/atan2.svg index 43d0bf2bcb671..94621282add64 100644 --- a/docs/reference/query-languages/esql/images/functions/atan2.svg +++ b/docs/reference/query-languages/esql/images/functions/atan2.svg @@ -1 +1 @@ -ATAN2(y_coordinate,x_coordinate) +ATAN2(y_coordinate,x_coordinate) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/avg.svg b/docs/reference/query-languages/esql/images/functions/avg.svg index 52ccafeb15139..b5dbdd6308979 100644 --- a/docs/reference/query-languages/esql/images/functions/avg.svg +++ b/docs/reference/query-languages/esql/images/functions/avg.svg @@ -1 +1 @@ -AVG(number) +AVG(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/bit_length.svg b/docs/reference/query-languages/esql/images/functions/bit_length.svg index 36a07d53ce92a..718b7387b6463 100644 --- a/docs/reference/query-languages/esql/images/functions/bit_length.svg +++ b/docs/reference/query-languages/esql/images/functions/bit_length.svg @@ -1 +1 @@ -BIT_LENGTH(string) +BIT_LENGTH(string) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/bucket.svg b/docs/reference/query-languages/esql/images/functions/bucket.svg index b23682fe89c1e..4e34ef16dc027 100644 --- a/docs/reference/query-languages/esql/images/functions/bucket.svg +++ b/docs/reference/query-languages/esql/images/functions/bucket.svg @@ -1 +1 @@ -BUCKET(field,buckets,from,to) +BUCKET(field,buckets,from,to) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/byte_length.svg b/docs/reference/query-languages/esql/images/functions/byte_length.svg index 6343e995594bb..7f8af7c4e3d7b 100644 --- a/docs/reference/query-languages/esql/images/functions/byte_length.svg +++ b/docs/reference/query-languages/esql/images/functions/byte_length.svg @@ -1 +1 @@ -BYTE_LENGTH(string) +BYTE_LENGTH(string) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/case.svg b/docs/reference/query-languages/esql/images/functions/case.svg index f2f8870a88dde..901c959edc9ba 100644 --- a/docs/reference/query-languages/esql/images/functions/case.svg +++ b/docs/reference/query-languages/esql/images/functions/case.svg @@ -1 +1 @@ -CASE(condition,trueValueelseValue) +CASE(condition,trueValueelseValue) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/categorize.svg b/docs/reference/query-languages/esql/images/functions/categorize.svg index 335e1d3797215..bbb2bda7c480b 100644 --- a/docs/reference/query-languages/esql/images/functions/categorize.svg +++ b/docs/reference/query-languages/esql/images/functions/categorize.svg @@ -1 +1 @@ -CATEGORIZE(field) +CATEGORIZE(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/cbrt.svg b/docs/reference/query-languages/esql/images/functions/cbrt.svg index c32336fcd2d42..da5fa5f311b6a 100644 --- a/docs/reference/query-languages/esql/images/functions/cbrt.svg +++ b/docs/reference/query-languages/esql/images/functions/cbrt.svg @@ -1 +1 @@ -CBRT(number) +CBRT(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/ceil.svg b/docs/reference/query-languages/esql/images/functions/ceil.svg index ee9faf199952a..fcb78dc400b34 100644 --- a/docs/reference/query-languages/esql/images/functions/ceil.svg +++ b/docs/reference/query-languages/esql/images/functions/ceil.svg @@ -1 +1 @@ -CEIL(number) +CEIL(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/cidr_match.svg b/docs/reference/query-languages/esql/images/functions/cidr_match.svg index 3500e38e5c8ec..2ef7896c52a33 100644 --- a/docs/reference/query-languages/esql/images/functions/cidr_match.svg +++ b/docs/reference/query-languages/esql/images/functions/cidr_match.svg @@ -1 +1 @@ -CIDR_MATCH(ip,blockX) +CIDR_MATCH(ip,blockX) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/coalesce.svg b/docs/reference/query-languages/esql/images/functions/coalesce.svg index 704d814dba71c..fdd0b501fa2e0 100644 --- a/docs/reference/query-languages/esql/images/functions/coalesce.svg +++ b/docs/reference/query-languages/esql/images/functions/coalesce.svg @@ -1 +1 @@ -COALESCE(first,rest) +COALESCE(first,rest) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/concat.svg b/docs/reference/query-languages/esql/images/functions/concat.svg index 854f77cddc509..edf03d976a4d9 100644 --- a/docs/reference/query-languages/esql/images/functions/concat.svg +++ b/docs/reference/query-languages/esql/images/functions/concat.svg @@ -1 +1 @@ -CONCAT(string1,string2) +CONCAT(string1,string2) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/cos.svg b/docs/reference/query-languages/esql/images/functions/cos.svg index abbb5aad40bdd..311722a90b225 100644 --- a/docs/reference/query-languages/esql/images/functions/cos.svg +++ b/docs/reference/query-languages/esql/images/functions/cos.svg @@ -1 +1 @@ -COS(angle) +COS(angle) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/cosh.svg b/docs/reference/query-languages/esql/images/functions/cosh.svg index 8e5153756cb52..075c0c1625996 100644 --- a/docs/reference/query-languages/esql/images/functions/cosh.svg +++ b/docs/reference/query-languages/esql/images/functions/cosh.svg @@ -1 +1 @@ -COSH(number) +COSH(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/count.svg b/docs/reference/query-languages/esql/images/functions/count.svg index 835cd302d1567..6bc0d7b15848a 100644 --- a/docs/reference/query-languages/esql/images/functions/count.svg +++ b/docs/reference/query-languages/esql/images/functions/count.svg @@ -1 +1 @@ -COUNT(field) +COUNT(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/count_distinct.svg b/docs/reference/query-languages/esql/images/functions/count_distinct.svg index 55c2e0372eb1d..0e65902fb99b5 100644 --- a/docs/reference/query-languages/esql/images/functions/count_distinct.svg +++ b/docs/reference/query-languages/esql/images/functions/count_distinct.svg @@ -1 +1 @@ -COUNT_DISTINCT(field,precision) +COUNT_DISTINCT(field,precision) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/date_diff.svg b/docs/reference/query-languages/esql/images/functions/date_diff.svg index 19e5f55b25f73..6035099bc0949 100644 --- a/docs/reference/query-languages/esql/images/functions/date_diff.svg +++ b/docs/reference/query-languages/esql/images/functions/date_diff.svg @@ -1 +1 @@ -DATE_DIFF(unit,startTimestamp,endTimestamp) +DATE_DIFF(unit,startTimestamp,endTimestamp) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/date_extract.svg b/docs/reference/query-languages/esql/images/functions/date_extract.svg index a1833095a3d23..6d97a6eded4ff 100644 --- a/docs/reference/query-languages/esql/images/functions/date_extract.svg +++ b/docs/reference/query-languages/esql/images/functions/date_extract.svg @@ -1 +1 @@ -DATE_EXTRACT(datePart,date) +DATE_EXTRACT(datePart,date) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/date_format.svg b/docs/reference/query-languages/esql/images/functions/date_format.svg index 8aa53384e6698..92081244e669b 100644 --- a/docs/reference/query-languages/esql/images/functions/date_format.svg +++ b/docs/reference/query-languages/esql/images/functions/date_format.svg @@ -1 +1 @@ -DATE_FORMAT(dateFormat,date) +DATE_FORMAT(dateFormat,date) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/date_parse.svg b/docs/reference/query-languages/esql/images/functions/date_parse.svg index 4ffcb09c626c5..17bfe8607f88e 100644 --- a/docs/reference/query-languages/esql/images/functions/date_parse.svg +++ b/docs/reference/query-languages/esql/images/functions/date_parse.svg @@ -1 +1 @@ -DATE_PARSE(datePattern,dateString) +DATE_PARSE(datePattern,dateString) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/date_trunc.svg b/docs/reference/query-languages/esql/images/functions/date_trunc.svg index d90b410900b4d..c2f070509fe56 100644 --- a/docs/reference/query-languages/esql/images/functions/date_trunc.svg +++ b/docs/reference/query-languages/esql/images/functions/date_trunc.svg @@ -1 +1 @@ -DATE_TRUNC(interval,date) +DATE_TRUNC(interval,date) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/e.svg b/docs/reference/query-languages/esql/images/functions/e.svg index 7665c5f656c93..8e1a675bf3471 100644 --- a/docs/reference/query-languages/esql/images/functions/e.svg +++ b/docs/reference/query-languages/esql/images/functions/e.svg @@ -1 +1 @@ -E() +E() \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/ends_with.svg b/docs/reference/query-languages/esql/images/functions/ends_with.svg index 708373f637a82..1f9ddf2feed14 100644 --- a/docs/reference/query-languages/esql/images/functions/ends_with.svg +++ b/docs/reference/query-languages/esql/images/functions/ends_with.svg @@ -1 +1 @@ -ENDS_WITH(str,suffix) +ENDS_WITH(str,suffix) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/exp.svg b/docs/reference/query-languages/esql/images/functions/exp.svg index 5cd8f8b41b4ac..aad747e4a31b4 100644 --- a/docs/reference/query-languages/esql/images/functions/exp.svg +++ b/docs/reference/query-languages/esql/images/functions/exp.svg @@ -1 +1 @@ -EXP(number) +EXP(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/floor.svg b/docs/reference/query-languages/esql/images/functions/floor.svg index ab1880d882554..2daa6bede7ebb 100644 --- a/docs/reference/query-languages/esql/images/functions/floor.svg +++ b/docs/reference/query-languages/esql/images/functions/floor.svg @@ -1 +1 @@ -FLOOR(number) +FLOOR(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/from_base64.svg b/docs/reference/query-languages/esql/images/functions/from_base64.svg index f5b897fe092b1..fa5148f9e5815 100644 --- a/docs/reference/query-languages/esql/images/functions/from_base64.svg +++ b/docs/reference/query-languages/esql/images/functions/from_base64.svg @@ -1 +1 @@ -FROM_BASE64(string) +FROM_BASE64(string) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/greatest.svg b/docs/reference/query-languages/esql/images/functions/greatest.svg index 40ddda3a94955..d1d98c942f980 100644 --- a/docs/reference/query-languages/esql/images/functions/greatest.svg +++ b/docs/reference/query-languages/esql/images/functions/greatest.svg @@ -1 +1 @@ -GREATEST(first,rest) +GREATEST(first,rest) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/hash.svg b/docs/reference/query-languages/esql/images/functions/hash.svg index 4529dfc92b278..1c6e46e65a85f 100644 --- a/docs/reference/query-languages/esql/images/functions/hash.svg +++ b/docs/reference/query-languages/esql/images/functions/hash.svg @@ -1 +1 @@ -HASH(algorithm,input) +HASH(algorithm,input) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/hypot.svg b/docs/reference/query-languages/esql/images/functions/hypot.svg index 473336ffa7da8..2f1ac9bdd563e 100644 --- a/docs/reference/query-languages/esql/images/functions/hypot.svg +++ b/docs/reference/query-languages/esql/images/functions/hypot.svg @@ -1 +1 @@ -HYPOT(number1,number2) +HYPOT(number1,number2) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/ip_prefix.svg b/docs/reference/query-languages/esql/images/functions/ip_prefix.svg index aa8492f043ab2..30e1dd61b2833 100644 --- a/docs/reference/query-languages/esql/images/functions/ip_prefix.svg +++ b/docs/reference/query-languages/esql/images/functions/ip_prefix.svg @@ -1 +1 @@ -IP_PREFIX(ip,prefixLengthV4,prefixLengthV6) +IP_PREFIX(ip,prefixLengthV4,prefixLengthV6) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/kql.svg b/docs/reference/query-languages/esql/images/functions/kql.svg index 221af001eb2bf..0700b1bf2ce1c 100644 --- a/docs/reference/query-languages/esql/images/functions/kql.svg +++ b/docs/reference/query-languages/esql/images/functions/kql.svg @@ -1 +1 @@ -KQL(query) +KQL(query) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/least.svg b/docs/reference/query-languages/esql/images/functions/least.svg index 70c7ee3909b10..0e323c09303fe 100644 --- a/docs/reference/query-languages/esql/images/functions/least.svg +++ b/docs/reference/query-languages/esql/images/functions/least.svg @@ -1 +1 @@ -LEAST(first,rest) +LEAST(first,rest) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/left.svg b/docs/reference/query-languages/esql/images/functions/left.svg index 18a2f32a0771e..1e4eb41b27178 100644 --- a/docs/reference/query-languages/esql/images/functions/left.svg +++ b/docs/reference/query-languages/esql/images/functions/left.svg @@ -1 +1 @@ -LEFT(string,length) +LEFT(string,length) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/length.svg b/docs/reference/query-languages/esql/images/functions/length.svg index 6d983166d2538..98084807e1dc7 100644 --- a/docs/reference/query-languages/esql/images/functions/length.svg +++ b/docs/reference/query-languages/esql/images/functions/length.svg @@ -1 +1 @@ -LENGTH(string) +LENGTH(string) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/locate.svg b/docs/reference/query-languages/esql/images/functions/locate.svg index 98d34f787731e..011f18cb2995e 100644 --- a/docs/reference/query-languages/esql/images/functions/locate.svg +++ b/docs/reference/query-languages/esql/images/functions/locate.svg @@ -1 +1 @@ -LOCATE(string,substring,start) +LOCATE(string,substring,start) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/log.svg b/docs/reference/query-languages/esql/images/functions/log.svg index ee1c849f4bb4a..b042fe0714b08 100644 --- a/docs/reference/query-languages/esql/images/functions/log.svg +++ b/docs/reference/query-languages/esql/images/functions/log.svg @@ -1 +1 @@ -LOG(base,number) +LOG(base,number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/log10.svg b/docs/reference/query-languages/esql/images/functions/log10.svg index 814d098d8d161..9d96c3c0022d9 100644 --- a/docs/reference/query-languages/esql/images/functions/log10.svg +++ b/docs/reference/query-languages/esql/images/functions/log10.svg @@ -1 +1 @@ -LOG10(number) +LOG10(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/ltrim.svg b/docs/reference/query-languages/esql/images/functions/ltrim.svg index 335fb560f98f5..233858fb4fa05 100644 --- a/docs/reference/query-languages/esql/images/functions/ltrim.svg +++ b/docs/reference/query-languages/esql/images/functions/ltrim.svg @@ -1 +1 @@ -LTRIM(string) +LTRIM(string) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/match.svg b/docs/reference/query-languages/esql/images/functions/match.svg index 7c93db67a3c67..353afb7678350 100644 --- a/docs/reference/query-languages/esql/images/functions/match.svg +++ b/docs/reference/query-languages/esql/images/functions/match.svg @@ -1 +1 @@ -MATCH(field,query,options) +MATCH(field,query,options) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/max.svg b/docs/reference/query-languages/esql/images/functions/max.svg index 2d96d959adbeb..22d9ab3b3bd7a 100644 --- a/docs/reference/query-languages/esql/images/functions/max.svg +++ b/docs/reference/query-languages/esql/images/functions/max.svg @@ -1 +1 @@ -MAX(field) +MAX(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/md5.svg b/docs/reference/query-languages/esql/images/functions/md5.svg index c99c0f5d3b95d..5c2899aba5d91 100644 --- a/docs/reference/query-languages/esql/images/functions/md5.svg +++ b/docs/reference/query-languages/esql/images/functions/md5.svg @@ -1 +1 @@ -MD5(input) +MD5(input) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/median.svg b/docs/reference/query-languages/esql/images/functions/median.svg index dcbc2c4e5177f..341ca83e5bd49 100644 --- a/docs/reference/query-languages/esql/images/functions/median.svg +++ b/docs/reference/query-languages/esql/images/functions/median.svg @@ -1 +1 @@ -MEDIAN(number) +MEDIAN(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/median_absolute_deviation.svg b/docs/reference/query-languages/esql/images/functions/median_absolute_deviation.svg index 9bbba8fd674f7..e0f391b384002 100644 --- a/docs/reference/query-languages/esql/images/functions/median_absolute_deviation.svg +++ b/docs/reference/query-languages/esql/images/functions/median_absolute_deviation.svg @@ -1 +1 @@ -MEDIAN_ABSOLUTE_DEVIATION(number) +MEDIAN_ABSOLUTE_DEVIATION(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/min.svg b/docs/reference/query-languages/esql/images/functions/min.svg index c38013511a66b..805c75822c732 100644 --- a/docs/reference/query-languages/esql/images/functions/min.svg +++ b/docs/reference/query-languages/esql/images/functions/min.svg @@ -1 +1 @@ -MIN(field) +MIN(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_append.svg b/docs/reference/query-languages/esql/images/functions/mv_append.svg index ae0cc61b455a9..a1d9cde63edf0 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_append.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_append.svg @@ -1 +1 @@ -MV_APPEND(field1,field2) +MV_APPEND(field1,field2) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_avg.svg b/docs/reference/query-languages/esql/images/functions/mv_avg.svg index d2f64fffae4b3..87b31ec07f87a 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_avg.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_avg.svg @@ -1 +1 @@ -MV_AVG(number) +MV_AVG(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_concat.svg b/docs/reference/query-languages/esql/images/functions/mv_concat.svg index ecc2c00029d29..f63fd6f493bdf 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_concat.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_concat.svg @@ -1 +1 @@ -MV_CONCAT(string,delim) +MV_CONCAT(string,delim) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_count.svg b/docs/reference/query-languages/esql/images/functions/mv_count.svg index 205a3b3b23529..dab7183d6ffca 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_count.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_count.svg @@ -1 +1 @@ -MV_COUNT(field) +MV_COUNT(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_dedupe.svg b/docs/reference/query-languages/esql/images/functions/mv_dedupe.svg index d0bee528db2db..a40dd3807681e 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_dedupe.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_dedupe.svg @@ -1 +1 @@ -MV_DEDUPE(field) +MV_DEDUPE(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_first.svg b/docs/reference/query-languages/esql/images/functions/mv_first.svg index 75fa00107b9f4..659e9f4058431 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_first.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_first.svg @@ -1 +1 @@ -MV_FIRST(field) +MV_FIRST(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_last.svg b/docs/reference/query-languages/esql/images/functions/mv_last.svg index fde8e94202f0e..c3579e4139c25 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_last.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_last.svg @@ -1 +1 @@ -MV_LAST(field) +MV_LAST(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_max.svg b/docs/reference/query-languages/esql/images/functions/mv_max.svg index 22f9070b05562..9f11b7d86e531 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_max.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_max.svg @@ -1 +1 @@ -MV_MAX(field) +MV_MAX(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_median.svg b/docs/reference/query-languages/esql/images/functions/mv_median.svg index 7a2cfe73319fb..4dd2e35fdbf36 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_median.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_median.svg @@ -1 +1 @@ -MV_MEDIAN(number) +MV_MEDIAN(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_median_absolute_deviation.svg b/docs/reference/query-languages/esql/images/functions/mv_median_absolute_deviation.svg index 9bd6d1efc905c..16736d4dd284f 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_median_absolute_deviation.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_median_absolute_deviation.svg @@ -1 +1 @@ -MV_MEDIAN_ABSOLUTE_DEVIATION(number) +MV_MEDIAN_ABSOLUTE_DEVIATION(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_min.svg b/docs/reference/query-languages/esql/images/functions/mv_min.svg index 0024551f520c8..9bd29fbf6611d 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_min.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_min.svg @@ -1 +1 @@ -MV_MIN(field) +MV_MIN(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_percentile.svg b/docs/reference/query-languages/esql/images/functions/mv_percentile.svg index 5b6fdc947a82c..a1b944444f969 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_percentile.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_percentile.svg @@ -1 +1 @@ -MV_PERCENTILE(number,percentile) +MV_PERCENTILE(number,percentile) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_pseries_weighted_sum.svg b/docs/reference/query-languages/esql/images/functions/mv_pseries_weighted_sum.svg index 0951ab71a3d31..74702c29661c2 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_pseries_weighted_sum.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_pseries_weighted_sum.svg @@ -1 +1 @@ -MV_PSERIES_WEIGHTED_SUM(number,p) +MV_PSERIES_WEIGHTED_SUM(number,p) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_slice.svg b/docs/reference/query-languages/esql/images/functions/mv_slice.svg index 3b369ccd6468e..4ddd627ca362c 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_slice.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_slice.svg @@ -1 +1 @@ -MV_SLICE(field,start,end) +MV_SLICE(field,start,end) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_sort.svg b/docs/reference/query-languages/esql/images/functions/mv_sort.svg index 966a01b7cd5ef..8cebad06fc733 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_sort.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_sort.svg @@ -1 +1 @@ -MV_SORT(field,order) +MV_SORT(field,order) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_sum.svg b/docs/reference/query-languages/esql/images/functions/mv_sum.svg index 7d62fe176ba5a..e28b709d06b5c 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_sum.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_sum.svg @@ -1 +1 @@ -MV_SUM(number) +MV_SUM(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_zip.svg b/docs/reference/query-languages/esql/images/functions/mv_zip.svg index eea47190aacf6..b055bece1eeb6 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_zip.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_zip.svg @@ -1 +1 @@ -MV_ZIP(string1,string2,delim) +MV_ZIP(string1,string2,delim) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/now.svg b/docs/reference/query-languages/esql/images/functions/now.svg index de2fe1b3a5f89..870fe5e40c8a4 100644 --- a/docs/reference/query-languages/esql/images/functions/now.svg +++ b/docs/reference/query-languages/esql/images/functions/now.svg @@ -1 +1 @@ -NOW() +NOW() \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/percentile.svg b/docs/reference/query-languages/esql/images/functions/percentile.svg index ac559190516e1..1211676f00a19 100644 --- a/docs/reference/query-languages/esql/images/functions/percentile.svg +++ b/docs/reference/query-languages/esql/images/functions/percentile.svg @@ -1 +1 @@ -PERCENTILE(number,percentile) +PERCENTILE(number,percentile) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/pi.svg b/docs/reference/query-languages/esql/images/functions/pi.svg index faf2a754f034a..9286355ef7b16 100644 --- a/docs/reference/query-languages/esql/images/functions/pi.svg +++ b/docs/reference/query-languages/esql/images/functions/pi.svg @@ -1 +1 @@ -PI() +PI() \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/pow.svg b/docs/reference/query-languages/esql/images/functions/pow.svg index a37653367ed02..55907316c0a4e 100644 --- a/docs/reference/query-languages/esql/images/functions/pow.svg +++ b/docs/reference/query-languages/esql/images/functions/pow.svg @@ -1 +1 @@ -POW(base,exponent) +POW(base,exponent) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/qstr.svg b/docs/reference/query-languages/esql/images/functions/qstr.svg index b5f9d9d7f6d1f..d77e49a2a3c24 100644 --- a/docs/reference/query-languages/esql/images/functions/qstr.svg +++ b/docs/reference/query-languages/esql/images/functions/qstr.svg @@ -1 +1 @@ -QSTR(query) +QSTR(query) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/repeat.svg b/docs/reference/query-languages/esql/images/functions/repeat.svg index a0ec96899ffe0..49143d669f469 100644 --- a/docs/reference/query-languages/esql/images/functions/repeat.svg +++ b/docs/reference/query-languages/esql/images/functions/repeat.svg @@ -1 +1 @@ -REPEAT(string,number) +REPEAT(string,number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/replace.svg b/docs/reference/query-languages/esql/images/functions/replace.svg index 5139c21d7530f..12827d557bde6 100644 --- a/docs/reference/query-languages/esql/images/functions/replace.svg +++ b/docs/reference/query-languages/esql/images/functions/replace.svg @@ -1 +1 @@ -REPLACE(string,regex,newString) +REPLACE(string,regex,newString) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/reverse.svg b/docs/reference/query-languages/esql/images/functions/reverse.svg index 1731487fdaf2b..f28537876c150 100644 --- a/docs/reference/query-languages/esql/images/functions/reverse.svg +++ b/docs/reference/query-languages/esql/images/functions/reverse.svg @@ -1 +1 @@ -REVERSE(str) +REVERSE(str) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/right.svg b/docs/reference/query-languages/esql/images/functions/right.svg index e9e340b182e3c..997f57fc4b961 100644 --- a/docs/reference/query-languages/esql/images/functions/right.svg +++ b/docs/reference/query-languages/esql/images/functions/right.svg @@ -1 +1 @@ -RIGHT(string,length) +RIGHT(string,length) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/round.svg b/docs/reference/query-languages/esql/images/functions/round.svg index 97ae75c780436..a735dbe622c60 100644 --- a/docs/reference/query-languages/esql/images/functions/round.svg +++ b/docs/reference/query-languages/esql/images/functions/round.svg @@ -1 +1 @@ -ROUND(number,decimals) +ROUND(number,decimals) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/rtrim.svg b/docs/reference/query-languages/esql/images/functions/rtrim.svg index f766696235b8c..4be9553b4b3b9 100644 --- a/docs/reference/query-languages/esql/images/functions/rtrim.svg +++ b/docs/reference/query-languages/esql/images/functions/rtrim.svg @@ -1 +1 @@ -RTRIM(string) +RTRIM(string) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/sha1.svg b/docs/reference/query-languages/esql/images/functions/sha1.svg index c899e29fe14b4..ed330a2ab7b88 100644 --- a/docs/reference/query-languages/esql/images/functions/sha1.svg +++ b/docs/reference/query-languages/esql/images/functions/sha1.svg @@ -1 +1 @@ -SHA1(input) +SHA1(input) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/sha256.svg b/docs/reference/query-languages/esql/images/functions/sha256.svg index a725eb6d28f86..132b178de8387 100644 --- a/docs/reference/query-languages/esql/images/functions/sha256.svg +++ b/docs/reference/query-languages/esql/images/functions/sha256.svg @@ -1 +1 @@ -SHA256(input) +SHA256(input) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/signum.svg b/docs/reference/query-languages/esql/images/functions/signum.svg index 519f8c9539aa3..62e520aca32d3 100644 --- a/docs/reference/query-languages/esql/images/functions/signum.svg +++ b/docs/reference/query-languages/esql/images/functions/signum.svg @@ -1 +1 @@ -SIGNUM(number) +SIGNUM(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/sin.svg b/docs/reference/query-languages/esql/images/functions/sin.svg index 506044cb87f2b..862152025ec3b 100644 --- a/docs/reference/query-languages/esql/images/functions/sin.svg +++ b/docs/reference/query-languages/esql/images/functions/sin.svg @@ -1 +1 @@ -SIN(angle) +SIN(angle) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/sinh.svg b/docs/reference/query-languages/esql/images/functions/sinh.svg index 803cfe27ce1be..0a1232628cd92 100644 --- a/docs/reference/query-languages/esql/images/functions/sinh.svg +++ b/docs/reference/query-languages/esql/images/functions/sinh.svg @@ -1 +1 @@ -SINH(number) +SINH(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/space.svg b/docs/reference/query-languages/esql/images/functions/space.svg index 73b08fed95196..488993f53c4da 100644 --- a/docs/reference/query-languages/esql/images/functions/space.svg +++ b/docs/reference/query-languages/esql/images/functions/space.svg @@ -1 +1 @@ -SPACE(number) +SPACE(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/split.svg b/docs/reference/query-languages/esql/images/functions/split.svg index ce869a6ebb87e..db7f8fb7edc05 100644 --- a/docs/reference/query-languages/esql/images/functions/split.svg +++ b/docs/reference/query-languages/esql/images/functions/split.svg @@ -1 +1 @@ -SPLIT(string,delim) +SPLIT(string,delim) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/sqrt.svg b/docs/reference/query-languages/esql/images/functions/sqrt.svg index 115682ec836ad..50370362e29dd 100644 --- a/docs/reference/query-languages/esql/images/functions/sqrt.svg +++ b/docs/reference/query-languages/esql/images/functions/sqrt.svg @@ -1 +1 @@ -SQRT(number) +SQRT(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/st_centroid_agg.svg b/docs/reference/query-languages/esql/images/functions/st_centroid_agg.svg index a84c1787fc2bc..fe55e81c40947 100644 --- a/docs/reference/query-languages/esql/images/functions/st_centroid_agg.svg +++ b/docs/reference/query-languages/esql/images/functions/st_centroid_agg.svg @@ -1 +1 @@ -ST_CENTROID_AGG(field) +ST_CENTROID_AGG(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/st_contains.svg b/docs/reference/query-languages/esql/images/functions/st_contains.svg index e465573634841..2c6dfc94dc20d 100644 --- a/docs/reference/query-languages/esql/images/functions/st_contains.svg +++ b/docs/reference/query-languages/esql/images/functions/st_contains.svg @@ -1 +1 @@ -ST_CONTAINS(geomA,geomB) +ST_CONTAINS(geomA,geomB) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/st_disjoint.svg b/docs/reference/query-languages/esql/images/functions/st_disjoint.svg index f1393bcead639..0bea10d2bb8f2 100644 --- a/docs/reference/query-languages/esql/images/functions/st_disjoint.svg +++ b/docs/reference/query-languages/esql/images/functions/st_disjoint.svg @@ -1 +1 @@ -ST_DISJOINT(geomA,geomB) +ST_DISJOINT(geomA,geomB) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/st_distance.svg b/docs/reference/query-languages/esql/images/functions/st_distance.svg index 8104973982a11..c957b0160965b 100644 --- a/docs/reference/query-languages/esql/images/functions/st_distance.svg +++ b/docs/reference/query-languages/esql/images/functions/st_distance.svg @@ -1 +1 @@ -ST_DISTANCE(geomA,geomB) +ST_DISTANCE(geomA,geomB) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/st_envelope.svg b/docs/reference/query-languages/esql/images/functions/st_envelope.svg index 7c95ed4952910..1ec9e6fb3de9e 100644 --- a/docs/reference/query-languages/esql/images/functions/st_envelope.svg +++ b/docs/reference/query-languages/esql/images/functions/st_envelope.svg @@ -1 +1 @@ -ST_ENVELOPE(geometry) +ST_ENVELOPE(geometry) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/st_extent_agg.svg b/docs/reference/query-languages/esql/images/functions/st_extent_agg.svg index 1b86c0ec29e4f..8f245edb57742 100644 --- a/docs/reference/query-languages/esql/images/functions/st_extent_agg.svg +++ b/docs/reference/query-languages/esql/images/functions/st_extent_agg.svg @@ -1 +1 @@ -ST_EXTENT_AGG(field) +ST_EXTENT_AGG(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/st_intersects.svg b/docs/reference/query-languages/esql/images/functions/st_intersects.svg index 856c8fffbb460..7e0836000aa91 100644 --- a/docs/reference/query-languages/esql/images/functions/st_intersects.svg +++ b/docs/reference/query-languages/esql/images/functions/st_intersects.svg @@ -1 +1 @@ -ST_INTERSECTS(geomA,geomB) +ST_INTERSECTS(geomA,geomB) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/st_within.svg b/docs/reference/query-languages/esql/images/functions/st_within.svg index c41581e35f228..324d907b1e447 100644 --- a/docs/reference/query-languages/esql/images/functions/st_within.svg +++ b/docs/reference/query-languages/esql/images/functions/st_within.svg @@ -1 +1 @@ -ST_WITHIN(geomA,geomB) +ST_WITHIN(geomA,geomB) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/st_x.svg b/docs/reference/query-languages/esql/images/functions/st_x.svg index dcc86834208de..adbc5fc074559 100644 --- a/docs/reference/query-languages/esql/images/functions/st_x.svg +++ b/docs/reference/query-languages/esql/images/functions/st_x.svg @@ -1 +1 @@ -ST_X(point) +ST_X(point) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/st_xmax.svg b/docs/reference/query-languages/esql/images/functions/st_xmax.svg index c36b7de5905e6..3743d04e0b09e 100644 --- a/docs/reference/query-languages/esql/images/functions/st_xmax.svg +++ b/docs/reference/query-languages/esql/images/functions/st_xmax.svg @@ -1 +1 @@ -ST_XMAX(point) +ST_XMAX(point) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/st_xmin.svg b/docs/reference/query-languages/esql/images/functions/st_xmin.svg index 7211495fdc603..f2e8cebf9f7cc 100644 --- a/docs/reference/query-languages/esql/images/functions/st_xmin.svg +++ b/docs/reference/query-languages/esql/images/functions/st_xmin.svg @@ -1 +1 @@ -ST_XMIN(point) +ST_XMIN(point) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/st_y.svg b/docs/reference/query-languages/esql/images/functions/st_y.svg index 65f2d5b916040..98f648a69470a 100644 --- a/docs/reference/query-languages/esql/images/functions/st_y.svg +++ b/docs/reference/query-languages/esql/images/functions/st_y.svg @@ -1 +1 @@ -ST_Y(point) +ST_Y(point) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/st_ymax.svg b/docs/reference/query-languages/esql/images/functions/st_ymax.svg index ad549df16e293..91686307ce2ff 100644 --- a/docs/reference/query-languages/esql/images/functions/st_ymax.svg +++ b/docs/reference/query-languages/esql/images/functions/st_ymax.svg @@ -1 +1 @@ -ST_YMAX(point) +ST_YMAX(point) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/st_ymin.svg b/docs/reference/query-languages/esql/images/functions/st_ymin.svg index 8c1614d55af28..d00b492eb597b 100644 --- a/docs/reference/query-languages/esql/images/functions/st_ymin.svg +++ b/docs/reference/query-languages/esql/images/functions/st_ymin.svg @@ -1 +1 @@ -ST_YMIN(point) +ST_YMIN(point) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/starts_with.svg b/docs/reference/query-languages/esql/images/functions/starts_with.svg index 4961907cdfe53..feb8ca4a7a39f 100644 --- a/docs/reference/query-languages/esql/images/functions/starts_with.svg +++ b/docs/reference/query-languages/esql/images/functions/starts_with.svg @@ -1 +1 @@ -STARTS_WITH(str,prefix) +STARTS_WITH(str,prefix) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/std_dev.svg b/docs/reference/query-languages/esql/images/functions/std_dev.svg index 44cfcd25eaed0..43032895e40fb 100644 --- a/docs/reference/query-languages/esql/images/functions/std_dev.svg +++ b/docs/reference/query-languages/esql/images/functions/std_dev.svg @@ -1 +1 @@ -STD_DEV(number) +STD_DEV(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/substring.svg b/docs/reference/query-languages/esql/images/functions/substring.svg index 4724c1fa26ba5..2bdef6b29599b 100644 --- a/docs/reference/query-languages/esql/images/functions/substring.svg +++ b/docs/reference/query-languages/esql/images/functions/substring.svg @@ -1 +1 @@ -SUBSTRING(string,start,length) +SUBSTRING(string,start,length) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/sum.svg b/docs/reference/query-languages/esql/images/functions/sum.svg index 9f5427ebbb08e..3fbe70478cd83 100644 --- a/docs/reference/query-languages/esql/images/functions/sum.svg +++ b/docs/reference/query-languages/esql/images/functions/sum.svg @@ -1 +1 @@ -SUM(number) +SUM(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/tan.svg b/docs/reference/query-languages/esql/images/functions/tan.svg index 57a5aa005b245..9c09e6796e085 100644 --- a/docs/reference/query-languages/esql/images/functions/tan.svg +++ b/docs/reference/query-languages/esql/images/functions/tan.svg @@ -1 +1 @@ -TAN(angle) +TAN(angle) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/tanh.svg b/docs/reference/query-languages/esql/images/functions/tanh.svg index 71e9805bedd68..b94babc77d32c 100644 --- a/docs/reference/query-languages/esql/images/functions/tanh.svg +++ b/docs/reference/query-languages/esql/images/functions/tanh.svg @@ -1 +1 @@ -TANH(number) +TANH(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/tau.svg b/docs/reference/query-languages/esql/images/functions/tau.svg index 5ee41f5b8c2ff..9176b599091b7 100644 --- a/docs/reference/query-languages/esql/images/functions/tau.svg +++ b/docs/reference/query-languages/esql/images/functions/tau.svg @@ -1 +1 @@ -TAU() +TAU() \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/term.svg b/docs/reference/query-languages/esql/images/functions/term.svg new file mode 100644 index 0000000000000..e1072c67fe6f2 --- /dev/null +++ b/docs/reference/query-languages/esql/images/functions/term.svg @@ -0,0 +1 @@ +TERM(field,query) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_base64.svg b/docs/reference/query-languages/esql/images/functions/to_base64.svg index 20d7171ec2393..e719b8a1d7f07 100644 --- a/docs/reference/query-languages/esql/images/functions/to_base64.svg +++ b/docs/reference/query-languages/esql/images/functions/to_base64.svg @@ -1 +1 @@ -TO_BASE64(string) +TO_BASE64(string) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_boolean.svg b/docs/reference/query-languages/esql/images/functions/to_boolean.svg index b9995d2fff499..cf9cab8cf576b 100644 --- a/docs/reference/query-languages/esql/images/functions/to_boolean.svg +++ b/docs/reference/query-languages/esql/images/functions/to_boolean.svg @@ -1 +1 @@ -TO_BOOLEAN(field) +TO_BOOLEAN(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_cartesianpoint.svg b/docs/reference/query-languages/esql/images/functions/to_cartesianpoint.svg index 169ebcac6555f..9cb94ccb8d761 100644 --- a/docs/reference/query-languages/esql/images/functions/to_cartesianpoint.svg +++ b/docs/reference/query-languages/esql/images/functions/to_cartesianpoint.svg @@ -1 +1 @@ -TO_CARTESIANPOINT(field) +TO_CARTESIANPOINT(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_cartesianshape.svg b/docs/reference/query-languages/esql/images/functions/to_cartesianshape.svg index 2dc2ba1437c5f..b701c003efaae 100644 --- a/docs/reference/query-languages/esql/images/functions/to_cartesianshape.svg +++ b/docs/reference/query-languages/esql/images/functions/to_cartesianshape.svg @@ -1 +1 @@ -TO_CARTESIANSHAPE(field) +TO_CARTESIANSHAPE(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_date_nanos.svg b/docs/reference/query-languages/esql/images/functions/to_date_nanos.svg index b784ae6b6106b..1ce340ca93caf 100644 --- a/docs/reference/query-languages/esql/images/functions/to_date_nanos.svg +++ b/docs/reference/query-languages/esql/images/functions/to_date_nanos.svg @@ -1 +1 @@ -TO_DATE_NANOS(field) +TO_DATE_NANOS(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_dateperiod.svg b/docs/reference/query-languages/esql/images/functions/to_dateperiod.svg index 3efee93d35f71..8af427c8de9e4 100644 --- a/docs/reference/query-languages/esql/images/functions/to_dateperiod.svg +++ b/docs/reference/query-languages/esql/images/functions/to_dateperiod.svg @@ -1 +1 @@ -TO_DATEPERIOD(field) +TO_DATEPERIOD(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_datetime.svg b/docs/reference/query-languages/esql/images/functions/to_datetime.svg index 06ca6fda22a94..8ffe5cd1bb288 100644 --- a/docs/reference/query-languages/esql/images/functions/to_datetime.svg +++ b/docs/reference/query-languages/esql/images/functions/to_datetime.svg @@ -1 +1 @@ -TO_DATETIME(field) +TO_DATETIME(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_degrees.svg b/docs/reference/query-languages/esql/images/functions/to_degrees.svg index 203e0c341407f..5ef5d67fff17e 100644 --- a/docs/reference/query-languages/esql/images/functions/to_degrees.svg +++ b/docs/reference/query-languages/esql/images/functions/to_degrees.svg @@ -1 +1 @@ -TO_DEGREES(number) +TO_DEGREES(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_double.svg b/docs/reference/query-languages/esql/images/functions/to_double.svg index 569ed73c82412..ba6f4dec690ce 100644 --- a/docs/reference/query-languages/esql/images/functions/to_double.svg +++ b/docs/reference/query-languages/esql/images/functions/to_double.svg @@ -1 +1 @@ -TO_DOUBLE(field) +TO_DOUBLE(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_geopoint.svg b/docs/reference/query-languages/esql/images/functions/to_geopoint.svg index 01ff838f6161f..07aeaa3b7f117 100644 --- a/docs/reference/query-languages/esql/images/functions/to_geopoint.svg +++ b/docs/reference/query-languages/esql/images/functions/to_geopoint.svg @@ -1 +1 @@ -TO_GEOPOINT(field) +TO_GEOPOINT(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_geoshape.svg b/docs/reference/query-languages/esql/images/functions/to_geoshape.svg index 665223101e1f2..ef55d15607063 100644 --- a/docs/reference/query-languages/esql/images/functions/to_geoshape.svg +++ b/docs/reference/query-languages/esql/images/functions/to_geoshape.svg @@ -1 +1 @@ -TO_GEOSHAPE(field) +TO_GEOSHAPE(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_integer.svg b/docs/reference/query-languages/esql/images/functions/to_integer.svg index 98bec02c543fb..346397fdafd8e 100644 --- a/docs/reference/query-languages/esql/images/functions/to_integer.svg +++ b/docs/reference/query-languages/esql/images/functions/to_integer.svg @@ -1 +1 @@ -TO_INTEGER(field) +TO_INTEGER(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_ip.svg b/docs/reference/query-languages/esql/images/functions/to_ip.svg index 72d31a6ab14b8..47cd11f4f6ed2 100644 --- a/docs/reference/query-languages/esql/images/functions/to_ip.svg +++ b/docs/reference/query-languages/esql/images/functions/to_ip.svg @@ -1 +1 @@ -TO_IP(field) +TO_IP(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_long.svg b/docs/reference/query-languages/esql/images/functions/to_long.svg index c0737ed3d6a68..bdbe7f77d69d3 100644 --- a/docs/reference/query-languages/esql/images/functions/to_long.svg +++ b/docs/reference/query-languages/esql/images/functions/to_long.svg @@ -1 +1 @@ -TO_LONG(field) +TO_LONG(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_lower.svg b/docs/reference/query-languages/esql/images/functions/to_lower.svg index 6127347d41aad..98c70e2234142 100644 --- a/docs/reference/query-languages/esql/images/functions/to_lower.svg +++ b/docs/reference/query-languages/esql/images/functions/to_lower.svg @@ -1 +1 @@ -TO_LOWER(str) +TO_LOWER(str) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_radians.svg b/docs/reference/query-languages/esql/images/functions/to_radians.svg index cb1213a0c6c7b..f51abab5cecf5 100644 --- a/docs/reference/query-languages/esql/images/functions/to_radians.svg +++ b/docs/reference/query-languages/esql/images/functions/to_radians.svg @@ -1 +1 @@ -TO_RADIANS(number) +TO_RADIANS(number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_string.svg b/docs/reference/query-languages/esql/images/functions/to_string.svg index 286a8836c52d1..23fd5c1658981 100644 --- a/docs/reference/query-languages/esql/images/functions/to_string.svg +++ b/docs/reference/query-languages/esql/images/functions/to_string.svg @@ -1 +1 @@ -TO_STRING(field) +TO_STRING(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_timeduration.svg b/docs/reference/query-languages/esql/images/functions/to_timeduration.svg index c840de6bb681b..cf1bf7513a0f5 100644 --- a/docs/reference/query-languages/esql/images/functions/to_timeduration.svg +++ b/docs/reference/query-languages/esql/images/functions/to_timeduration.svg @@ -1 +1 @@ -TO_TIMEDURATION(field) +TO_TIMEDURATION(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_unsigned_long.svg b/docs/reference/query-languages/esql/images/functions/to_unsigned_long.svg index c6a2420461499..c531fd67ff1f9 100644 --- a/docs/reference/query-languages/esql/images/functions/to_unsigned_long.svg +++ b/docs/reference/query-languages/esql/images/functions/to_unsigned_long.svg @@ -1 +1 @@ -TO_UNSIGNED_LONG(field) +TO_UNSIGNED_LONG(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_upper.svg b/docs/reference/query-languages/esql/images/functions/to_upper.svg index 554e58147d842..885a60650452c 100644 --- a/docs/reference/query-languages/esql/images/functions/to_upper.svg +++ b/docs/reference/query-languages/esql/images/functions/to_upper.svg @@ -1 +1 @@ -TO_UPPER(str) +TO_UPPER(str) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/to_version.svg b/docs/reference/query-languages/esql/images/functions/to_version.svg index 02f3006012e55..15bfb48c34940 100644 --- a/docs/reference/query-languages/esql/images/functions/to_version.svg +++ b/docs/reference/query-languages/esql/images/functions/to_version.svg @@ -1 +1 @@ -TO_VERSION(field) +TO_VERSION(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/top.svg b/docs/reference/query-languages/esql/images/functions/top.svg index da17c37010cf2..58d720477dd94 100644 --- a/docs/reference/query-languages/esql/images/functions/top.svg +++ b/docs/reference/query-languages/esql/images/functions/top.svg @@ -1 +1 @@ -TOP(field,limit,order) +TOP(field,limit,order) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/trim.svg b/docs/reference/query-languages/esql/images/functions/trim.svg index 4b9b6fcbde678..1fbba7a7e5077 100644 --- a/docs/reference/query-languages/esql/images/functions/trim.svg +++ b/docs/reference/query-languages/esql/images/functions/trim.svg @@ -1 +1 @@ -TRIM(string) +TRIM(string) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/values.svg b/docs/reference/query-languages/esql/images/functions/values.svg index 81ef45c128095..e8dc1faec3acc 100644 --- a/docs/reference/query-languages/esql/images/functions/values.svg +++ b/docs/reference/query-languages/esql/images/functions/values.svg @@ -1 +1 @@ -VALUES(field) +VALUES(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/weighted_avg.svg b/docs/reference/query-languages/esql/images/functions/weighted_avg.svg index fe2bd6e7494ba..b364cd74adc95 100644 --- a/docs/reference/query-languages/esql/images/functions/weighted_avg.svg +++ b/docs/reference/query-languages/esql/images/functions/weighted_avg.svg @@ -1 +1 @@ -WEIGHTED_AVG(number,weight) +WEIGHTED_AVG(number,weight) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/operators/add.svg b/docs/reference/query-languages/esql/images/operators/add.svg index eb4f9fb857dbc..79aed1eb128e7 100644 --- a/docs/reference/query-languages/esql/images/operators/add.svg +++ b/docs/reference/query-languages/esql/images/operators/add.svg @@ -1 +1 @@ -lhs+rhs +lhs+rhs \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/operators/div.svg b/docs/reference/query-languages/esql/images/operators/div.svg index 68b64f8cb5076..6767a66b1c795 100644 --- a/docs/reference/query-languages/esql/images/operators/div.svg +++ b/docs/reference/query-languages/esql/images/operators/div.svg @@ -1 +1 @@ -lhs/rhs +lhs/rhs \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/operators/equals.svg b/docs/reference/query-languages/esql/images/operators/equals.svg index dd7436eeb8b56..3aa36e7dbe65d 100644 --- a/docs/reference/query-languages/esql/images/operators/equals.svg +++ b/docs/reference/query-languages/esql/images/operators/equals.svg @@ -1 +1 @@ -lhs==rhs +lhs==rhs \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/operators/greater_than.svg b/docs/reference/query-languages/esql/images/operators/greater_than.svg index b71bd4355f216..7fe67039f132b 100644 --- a/docs/reference/query-languages/esql/images/operators/greater_than.svg +++ b/docs/reference/query-languages/esql/images/operators/greater_than.svg @@ -1 +1 @@ -lhs>rhs +lhs>rhs \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/operators/greater_than_or_equal.svg b/docs/reference/query-languages/esql/images/operators/greater_than_or_equal.svg index bacb8cbbc8343..b1b936e3fb37e 100644 --- a/docs/reference/query-languages/esql/images/operators/greater_than_or_equal.svg +++ b/docs/reference/query-languages/esql/images/operators/greater_than_or_equal.svg @@ -1 +1 @@ -lhs>=rhs +lhs>=rhs \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/operators/less_than.svg b/docs/reference/query-languages/esql/images/operators/less_than.svg index 62205b0c98318..34df0076943dc 100644 --- a/docs/reference/query-languages/esql/images/operators/less_than.svg +++ b/docs/reference/query-languages/esql/images/operators/less_than.svg @@ -1 +1 @@ -lhs<rhs +lhs<rhs \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/operators/less_than_or_equal.svg b/docs/reference/query-languages/esql/images/operators/less_than_or_equal.svg index e431b7675591f..db93f6a994e5e 100644 --- a/docs/reference/query-languages/esql/images/operators/less_than_or_equal.svg +++ b/docs/reference/query-languages/esql/images/operators/less_than_or_equal.svg @@ -1 +1 @@ -lhs<=rhs +lhs<=rhs \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/operators/match.svg b/docs/reference/query-languages/esql/images/operators/match.svg deleted file mode 100644 index 6a4cf6d6fd9ee..0000000000000 --- a/docs/reference/query-languages/esql/images/operators/match.svg +++ /dev/null @@ -1 +0,0 @@ -field:query diff --git a/docs/reference/query-languages/esql/images/operators/match_operator.svg b/docs/reference/query-languages/esql/images/operators/match_operator.svg new file mode 100644 index 0000000000000..bb2ddcdfe1465 --- /dev/null +++ b/docs/reference/query-languages/esql/images/operators/match_operator.svg @@ -0,0 +1 @@ +field:query \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/operators/mod.svg b/docs/reference/query-languages/esql/images/operators/mod.svg index a5f617eedc8be..6ca9c67bcbb4a 100644 --- a/docs/reference/query-languages/esql/images/operators/mod.svg +++ b/docs/reference/query-languages/esql/images/operators/mod.svg @@ -1 +1 @@ -lhs%rhs +lhs%rhs \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/operators/mul.svg b/docs/reference/query-languages/esql/images/operators/mul.svg index c8e391e312f41..fd264be57ad9b 100644 --- a/docs/reference/query-languages/esql/images/operators/mul.svg +++ b/docs/reference/query-languages/esql/images/operators/mul.svg @@ -1 +1 @@ -lhs*rhs +lhs*rhs \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/operators/neg.svg b/docs/reference/query-languages/esql/images/operators/neg.svg index 7593ee6a7ae07..8aa361d0ec45f 100644 --- a/docs/reference/query-languages/esql/images/operators/neg.svg +++ b/docs/reference/query-languages/esql/images/operators/neg.svg @@ -1 +1 @@ --v +-v \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/operators/not_equals.svg b/docs/reference/query-languages/esql/images/operators/not_equals.svg index 6e25cc63f0267..bba581cd72bb3 100644 --- a/docs/reference/query-languages/esql/images/operators/not_equals.svg +++ b/docs/reference/query-languages/esql/images/operators/not_equals.svg @@ -1 +1 @@ -lhs!=rhs +lhs!=rhs \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/operators/sub.svg b/docs/reference/query-languages/esql/images/operators/sub.svg index bf744f93e1638..906e42ae6a601 100644 --- a/docs/reference/query-languages/esql/images/operators/sub.svg +++ b/docs/reference/query-languages/esql/images/operators/sub.svg @@ -1 +1 @@ -lhs-rhs +lhs-rhs \ No newline at end of file diff --git a/docs/reference/esql/functions/kibana/definition/abs.json b/docs/reference/query-languages/esql/kibana/definition/functions/abs.json similarity index 88% rename from docs/reference/esql/functions/kibana/definition/abs.json rename to docs/reference/query-languages/esql/kibana/definition/functions/abs.json index 888ebf6386401..0e7a138f3f2d4 100644 --- a/docs/reference/esql/functions/kibana/definition/abs.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/abs.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "abs", "description" : "Returns the absolute value.", @@ -54,7 +54,7 @@ } ], "examples" : [ - "ROW number = -1.0 \n| EVAL abs_number = ABS(number)", + "ROW number = -1.0\n| EVAL abs_number = ABS(number)", "FROM employees\n| KEEP first_name, last_name, height\n| EVAL abs_height = ABS(0.0 - height)" ], "preview" : false, diff --git a/docs/reference/esql/functions/kibana/definition/acos.json b/docs/reference/query-languages/esql/kibana/definition/functions/acos.json similarity index 91% rename from docs/reference/esql/functions/kibana/definition/acos.json rename to docs/reference/query-languages/esql/kibana/definition/functions/acos.json index 5b6a5b023f48d..7f32a2e549314 100644 --- a/docs/reference/esql/functions/kibana/definition/acos.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/acos.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "acos", "description" : "Returns the arccosine of `n` as an angle, expressed in radians.", diff --git a/docs/reference/esql/functions/kibana/definition/asin.json b/docs/reference/query-languages/esql/kibana/definition/functions/asin.json similarity index 91% rename from docs/reference/esql/functions/kibana/definition/asin.json rename to docs/reference/query-languages/esql/kibana/definition/functions/asin.json index 293a66a21ab28..a2619a157fc1e 100644 --- a/docs/reference/esql/functions/kibana/definition/asin.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/asin.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "asin", "description" : "Returns the arcsine of the input\nnumeric expression as an angle, expressed in radians.", diff --git a/docs/reference/esql/functions/kibana/definition/atan.json b/docs/reference/query-languages/esql/kibana/definition/functions/atan.json similarity index 91% rename from docs/reference/esql/functions/kibana/definition/atan.json rename to docs/reference/query-languages/esql/kibana/definition/functions/atan.json index afa380ca1d7fa..3d1a119ae039d 100644 --- a/docs/reference/esql/functions/kibana/definition/atan.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/atan.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "atan", "description" : "Returns the arctangent of the input\nnumeric expression as an angle, expressed in radians.", diff --git a/docs/reference/esql/functions/kibana/definition/atan2.json b/docs/reference/query-languages/esql/kibana/definition/functions/atan2.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/atan2.json rename to docs/reference/query-languages/esql/kibana/definition/functions/atan2.json index 8e12198cb60ee..6709ce1045a99 100644 --- a/docs/reference/esql/functions/kibana/definition/atan2.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/atan2.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "atan2", "description" : "The angle between the positive x-axis and the ray from the\norigin to the point (x , y) in the Cartesian plane, expressed in radians.", diff --git a/docs/reference/esql/functions/kibana/definition/avg.json b/docs/reference/query-languages/esql/kibana/definition/functions/avg.json similarity index 72% rename from docs/reference/esql/functions/kibana/definition/avg.json rename to docs/reference/query-languages/esql/kibana/definition/functions/avg.json index 41dad3eb31613..65ae884e178cb 100644 --- a/docs/reference/esql/functions/kibana/definition/avg.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/avg.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "agg", "name" : "avg", "description" : "The average of a numeric field.", @@ -10,7 +10,7 @@ "name" : "number", "type" : "double", "optional" : false, - "description" : "" + "description" : "Expression that outputs values to average." } ], "variadic" : false, @@ -22,7 +22,7 @@ "name" : "number", "type" : "integer", "optional" : false, - "description" : "" + "description" : "Expression that outputs values to average." } ], "variadic" : false, @@ -34,7 +34,7 @@ "name" : "number", "type" : "long", "optional" : false, - "description" : "" + "description" : "Expression that outputs values to average." } ], "variadic" : false, diff --git a/docs/reference/esql/functions/kibana/definition/bit_length.json b/docs/reference/query-languages/esql/kibana/definition/functions/bit_length.json similarity index 88% rename from docs/reference/esql/functions/kibana/definition/bit_length.json rename to docs/reference/query-languages/esql/kibana/definition/functions/bit_length.json index 25a032044ec9c..41bab7e37b53b 100644 --- a/docs/reference/esql/functions/kibana/definition/bit_length.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/bit_length.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "bit_length", "description" : "Returns the bit length of a string.", diff --git a/docs/reference/esql/functions/kibana/definition/bucket.json b/docs/reference/query-languages/esql/kibana/definition/functions/bucket.json similarity index 99% rename from docs/reference/esql/functions/kibana/definition/bucket.json rename to docs/reference/query-languages/esql/kibana/definition/functions/bucket.json index 990f102bac16f..d70ffeec57204 100644 --- a/docs/reference/esql/functions/kibana/definition/bucket.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/bucket.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "grouping", "name" : "bucket", "description" : "Creates groups of values - buckets - out of a datetime or numeric input.\nThe size of the buckets can either be provided directly, or chosen based on a recommended count and values range.", @@ -1596,7 +1596,7 @@ "FROM employees\n| WHERE hire_date >= \"1985-01-01T00:00:00Z\" AND hire_date < \"1986-01-01T00:00:00Z\"\n| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 1 week)\n| SORT week", "FROM employees\n| STATS COUNT(*) by bs = BUCKET(salary, 20, 25324, 74999)\n| SORT bs", "FROM employees\n| WHERE hire_date >= \"1985-01-01T00:00:00Z\" AND hire_date < \"1986-01-01T00:00:00Z\"\n| STATS c = COUNT(1) BY b = BUCKET(salary, 5000.)\n| SORT b", - "FROM sample_data \n| WHERE @timestamp >= NOW() - 1 day and @timestamp < NOW()\n| STATS COUNT(*) BY bucket = BUCKET(@timestamp, 25, NOW() - 1 day, NOW())", + "FROM sample_data\n| WHERE @timestamp >= NOW() - 1 day and @timestamp < NOW()\n| STATS COUNT(*) BY bucket = BUCKET(@timestamp, 25, NOW() - 1 day, NOW())", "FROM employees\n| WHERE hire_date >= \"1985-01-01T00:00:00Z\" AND hire_date < \"1986-01-01T00:00:00Z\"\n| STATS AVG(salary) BY bucket = BUCKET(hire_date, 20, \"1985-01-01T00:00:00Z\", \"1986-01-01T00:00:00Z\")\n| SORT bucket", "FROM employees\n| STATS s1 = b1 + 1, s2 = BUCKET(salary / 1000 + 999, 50.) + 2 BY b1 = BUCKET(salary / 100 + 99, 50.), b2 = BUCKET(salary / 1000 + 999, 50.)\n| SORT b1, b2\n| KEEP s1, b1, s2, b2", "FROM employees\n| STATS dates = MV_SORT(VALUES(birth_date)) BY b = BUCKET(birth_date + 1 HOUR, 1 YEAR) - 1 HOUR\n| EVAL d_count = MV_COUNT(dates)\n| SORT d_count, b\n| LIMIT 3" diff --git a/docs/reference/esql/functions/kibana/definition/byte_length.json b/docs/reference/query-languages/esql/kibana/definition/functions/byte_length.json similarity index 88% rename from docs/reference/esql/functions/kibana/definition/byte_length.json rename to docs/reference/query-languages/esql/kibana/definition/functions/byte_length.json index 6d1a91813221b..4a16d2d523195 100644 --- a/docs/reference/esql/functions/kibana/definition/byte_length.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/byte_length.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "byte_length", "description" : "Returns the byte length of a string.", diff --git a/docs/reference/esql/functions/kibana/definition/case.json b/docs/reference/query-languages/esql/kibana/definition/functions/case.json similarity index 65% rename from docs/reference/esql/functions/kibana/definition/case.json rename to docs/reference/query-languages/esql/kibana/definition/functions/case.json index 4e2d4187712e3..1c6631a1be848 100644 --- a/docs/reference/esql/functions/kibana/definition/case.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/case.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "case", "description" : "Accepts pairs of conditions and values. The function returns the value that\nbelongs to the first condition that evaluates to `true`.\n\nIf the number of arguments is odd, the last argument is the default value which\nis returned when no condition matches. If the number of arguments is even, and\nno condition matches, the function returns `null`.", @@ -16,7 +16,7 @@ "name" : "trueValue", "type" : "boolean", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." } ], "variadic" : true, @@ -34,13 +34,13 @@ "name" : "trueValue", "type" : "boolean", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." }, { "name" : "elseValue", "type" : "boolean", "optional" : true, - "description" : "The value that's returned when no condition evaluates to `true`." + "description" : "The value that’s returned when no condition evaluates to `true`." } ], "variadic" : true, @@ -58,7 +58,7 @@ "name" : "trueValue", "type" : "cartesian_point", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." } ], "variadic" : true, @@ -76,13 +76,13 @@ "name" : "trueValue", "type" : "cartesian_point", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." }, { "name" : "elseValue", "type" : "cartesian_point", "optional" : true, - "description" : "The value that's returned when no condition evaluates to `true`." + "description" : "The value that’s returned when no condition evaluates to `true`." } ], "variadic" : true, @@ -100,7 +100,7 @@ "name" : "trueValue", "type" : "cartesian_shape", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." } ], "variadic" : true, @@ -118,13 +118,13 @@ "name" : "trueValue", "type" : "cartesian_shape", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." }, { "name" : "elseValue", "type" : "cartesian_shape", "optional" : true, - "description" : "The value that's returned when no condition evaluates to `true`." + "description" : "The value that’s returned when no condition evaluates to `true`." } ], "variadic" : true, @@ -142,7 +142,7 @@ "name" : "trueValue", "type" : "date", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." } ], "variadic" : true, @@ -160,13 +160,13 @@ "name" : "trueValue", "type" : "date", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." }, { "name" : "elseValue", "type" : "date", "optional" : true, - "description" : "The value that's returned when no condition evaluates to `true`." + "description" : "The value that’s returned when no condition evaluates to `true`." } ], "variadic" : true, @@ -184,7 +184,7 @@ "name" : "trueValue", "type" : "date_nanos", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." } ], "variadic" : true, @@ -202,13 +202,13 @@ "name" : "trueValue", "type" : "date_nanos", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." }, { "name" : "elseValue", "type" : "date_nanos", "optional" : true, - "description" : "The value that's returned when no condition evaluates to `true`." + "description" : "The value that’s returned when no condition evaluates to `true`." } ], "variadic" : true, @@ -226,7 +226,7 @@ "name" : "trueValue", "type" : "double", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." } ], "variadic" : true, @@ -244,13 +244,13 @@ "name" : "trueValue", "type" : "double", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." }, { "name" : "elseValue", "type" : "double", "optional" : true, - "description" : "The value that's returned when no condition evaluates to `true`." + "description" : "The value that’s returned when no condition evaluates to `true`." } ], "variadic" : true, @@ -268,7 +268,7 @@ "name" : "trueValue", "type" : "geo_point", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." } ], "variadic" : true, @@ -286,13 +286,13 @@ "name" : "trueValue", "type" : "geo_point", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." }, { "name" : "elseValue", "type" : "geo_point", "optional" : true, - "description" : "The value that's returned when no condition evaluates to `true`." + "description" : "The value that’s returned when no condition evaluates to `true`." } ], "variadic" : true, @@ -310,7 +310,7 @@ "name" : "trueValue", "type" : "geo_shape", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." } ], "variadic" : true, @@ -328,13 +328,13 @@ "name" : "trueValue", "type" : "geo_shape", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." }, { "name" : "elseValue", "type" : "geo_shape", "optional" : true, - "description" : "The value that's returned when no condition evaluates to `true`." + "description" : "The value that’s returned when no condition evaluates to `true`." } ], "variadic" : true, @@ -352,7 +352,7 @@ "name" : "trueValue", "type" : "integer", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." } ], "variadic" : true, @@ -370,13 +370,13 @@ "name" : "trueValue", "type" : "integer", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." }, { "name" : "elseValue", "type" : "integer", "optional" : true, - "description" : "The value that's returned when no condition evaluates to `true`." + "description" : "The value that’s returned when no condition evaluates to `true`." } ], "variadic" : true, @@ -394,7 +394,7 @@ "name" : "trueValue", "type" : "ip", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." } ], "variadic" : true, @@ -412,13 +412,13 @@ "name" : "trueValue", "type" : "ip", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." }, { "name" : "elseValue", "type" : "ip", "optional" : true, - "description" : "The value that's returned when no condition evaluates to `true`." + "description" : "The value that’s returned when no condition evaluates to `true`." } ], "variadic" : true, @@ -436,7 +436,7 @@ "name" : "trueValue", "type" : "keyword", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." } ], "variadic" : true, @@ -454,13 +454,13 @@ "name" : "trueValue", "type" : "keyword", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." }, { "name" : "elseValue", "type" : "keyword", "optional" : true, - "description" : "The value that's returned when no condition evaluates to `true`." + "description" : "The value that’s returned when no condition evaluates to `true`." } ], "variadic" : true, @@ -478,13 +478,13 @@ "name" : "trueValue", "type" : "keyword", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." }, { "name" : "elseValue", "type" : "text", "optional" : true, - "description" : "The value that's returned when no condition evaluates to `true`." + "description" : "The value that’s returned when no condition evaluates to `true`." } ], "variadic" : true, @@ -502,7 +502,7 @@ "name" : "trueValue", "type" : "long", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." } ], "variadic" : true, @@ -520,13 +520,13 @@ "name" : "trueValue", "type" : "long", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." }, { "name" : "elseValue", "type" : "long", "optional" : true, - "description" : "The value that's returned when no condition evaluates to `true`." + "description" : "The value that’s returned when no condition evaluates to `true`." } ], "variadic" : true, @@ -544,7 +544,7 @@ "name" : "trueValue", "type" : "text", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." } ], "variadic" : true, @@ -562,13 +562,13 @@ "name" : "trueValue", "type" : "text", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." }, { "name" : "elseValue", "type" : "keyword", "optional" : true, - "description" : "The value that's returned when no condition evaluates to `true`." + "description" : "The value that’s returned when no condition evaluates to `true`." } ], "variadic" : true, @@ -586,13 +586,13 @@ "name" : "trueValue", "type" : "text", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." }, { "name" : "elseValue", "type" : "text", "optional" : true, - "description" : "The value that's returned when no condition evaluates to `true`." + "description" : "The value that’s returned when no condition evaluates to `true`." } ], "variadic" : true, @@ -610,7 +610,7 @@ "name" : "trueValue", "type" : "unsigned_long", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." } ], "variadic" : true, @@ -628,13 +628,13 @@ "name" : "trueValue", "type" : "unsigned_long", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." }, { "name" : "elseValue", "type" : "unsigned_long", "optional" : true, - "description" : "The value that's returned when no condition evaluates to `true`." + "description" : "The value that’s returned when no condition evaluates to `true`." } ], "variadic" : true, @@ -652,7 +652,7 @@ "name" : "trueValue", "type" : "version", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." } ], "variadic" : true, @@ -670,13 +670,13 @@ "name" : "trueValue", "type" : "version", "optional" : false, - "description" : "The value that's returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." + "description" : "The value that’s returned when the corresponding condition is the first to evaluate to `true`. The default value is returned when no condition matches." }, { "name" : "elseValue", "type" : "version", "optional" : true, - "description" : "The value that's returned when no condition evaluates to `true`." + "description" : "The value that’s returned when no condition evaluates to `true`." } ], "variadic" : true, diff --git a/docs/reference/esql/functions/kibana/definition/categorize.json b/docs/reference/query-languages/esql/kibana/definition/functions/categorize.json similarity index 86% rename from docs/reference/esql/functions/kibana/definition/categorize.json rename to docs/reference/query-languages/esql/kibana/definition/functions/categorize.json index 1b7f20405756b..088384a3fa1a8 100644 --- a/docs/reference/esql/functions/kibana/definition/categorize.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/categorize.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "grouping", "name" : "categorize", "description" : "Groups text messages into categories of similarly formatted text values.", diff --git a/docs/reference/esql/functions/kibana/definition/cbrt.json b/docs/reference/query-languages/esql/kibana/definition/functions/cbrt.json similarity index 92% rename from docs/reference/esql/functions/kibana/definition/cbrt.json rename to docs/reference/query-languages/esql/kibana/definition/functions/cbrt.json index f146a864929a8..dabef9cb91a16 100644 --- a/docs/reference/esql/functions/kibana/definition/cbrt.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/cbrt.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "cbrt", "description" : "Returns the cube root of a number. The input can be any numeric value, the return value is always a double.\nCube roots of infinities are null.", diff --git a/docs/reference/esql/functions/kibana/definition/ceil.json b/docs/reference/query-languages/esql/kibana/definition/functions/ceil.json similarity index 92% rename from docs/reference/esql/functions/kibana/definition/ceil.json rename to docs/reference/query-languages/esql/kibana/definition/functions/ceil.json index 4a9e24e9094e8..e301e6bb631e2 100644 --- a/docs/reference/esql/functions/kibana/definition/ceil.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/ceil.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "ceil", "description" : "Round a number up to the nearest integer.", diff --git a/docs/reference/esql/functions/kibana/definition/cidr_match.json b/docs/reference/query-languages/esql/kibana/definition/functions/cidr_match.json similarity index 82% rename from docs/reference/esql/functions/kibana/definition/cidr_match.json rename to docs/reference/query-languages/esql/kibana/definition/functions/cidr_match.json index 9e988623c0fd6..1d7795ddecc15 100644 --- a/docs/reference/esql/functions/kibana/definition/cidr_match.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/cidr_match.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "cidr_match", "description" : "Returns true if the provided IP is contained in one of the provided CIDR blocks.", @@ -42,7 +42,7 @@ } ], "examples" : [ - "FROM hosts \n| WHERE CIDR_MATCH(ip1, \"127.0.0.2/32\", \"127.0.0.3/32\") \n| KEEP card, host, ip0, ip1" + "FROM hosts\n| WHERE CIDR_MATCH(ip1, \"127.0.0.2/32\", \"127.0.0.3/32\")\n| KEEP card, host, ip0, ip1" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/coalesce.json b/docs/reference/query-languages/esql/kibana/definition/functions/coalesce.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/coalesce.json rename to docs/reference/query-languages/esql/kibana/definition/functions/coalesce.json index a507aea3fd0d9..78c339542105f 100644 --- a/docs/reference/esql/functions/kibana/definition/coalesce.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/coalesce.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "coalesce", "description" : "Returns the first of its arguments that is not null. If all arguments are null, it returns `null`.", diff --git a/docs/reference/esql/functions/kibana/definition/concat.json b/docs/reference/query-languages/esql/kibana/definition/functions/concat.json similarity index 93% rename from docs/reference/esql/functions/kibana/definition/concat.json rename to docs/reference/query-languages/esql/kibana/definition/functions/concat.json index b41ebba40b58e..33a4f03c596e7 100644 --- a/docs/reference/esql/functions/kibana/definition/concat.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/concat.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "concat", "description" : "Concatenates two or more strings.", diff --git a/docs/reference/esql/functions/kibana/definition/cos.json b/docs/reference/query-languages/esql/kibana/definition/functions/cos.json similarity index 89% rename from docs/reference/esql/functions/kibana/definition/cos.json rename to docs/reference/query-languages/esql/kibana/definition/functions/cos.json index 8922dd6db555c..294e9ce570ca9 100644 --- a/docs/reference/esql/functions/kibana/definition/cos.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/cos.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "cos", "description" : "Returns the cosine of an angle.", @@ -54,7 +54,7 @@ } ], "examples" : [ - "ROW a=1.8 \n| EVAL cos=COS(a)" + "ROW a=1.8\n| EVAL cos=COS(a)" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/cosh.json b/docs/reference/query-languages/esql/kibana/definition/functions/cosh.json similarity index 89% rename from docs/reference/esql/functions/kibana/definition/cosh.json rename to docs/reference/query-languages/esql/kibana/definition/functions/cosh.json index 458f4ecf04554..c8106546b32a1 100644 --- a/docs/reference/esql/functions/kibana/definition/cosh.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/cosh.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "cosh", "description" : "Returns the hyperbolic cosine of a number.", @@ -54,7 +54,7 @@ } ], "examples" : [ - "ROW a=1.8 \n| EVAL cosh=COSH(a)" + "ROW a=1.8\n| EVAL cosh=COSH(a)" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/count.json b/docs/reference/query-languages/esql/kibana/definition/functions/count.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/count.json rename to docs/reference/query-languages/esql/kibana/definition/functions/count.json index 329a18c4d9d01..db358a61a84ec 100644 --- a/docs/reference/esql/functions/kibana/definition/count.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/count.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "agg", "name" : "count", "description" : "Returns the total number (count) of input values.", diff --git a/docs/reference/esql/functions/kibana/definition/count_distinct.json b/docs/reference/query-languages/esql/kibana/definition/functions/count_distinct.json similarity index 99% rename from docs/reference/esql/functions/kibana/definition/count_distinct.json rename to docs/reference/query-languages/esql/kibana/definition/functions/count_distinct.json index 54b99ee84ce2d..73f964fb36758 100644 --- a/docs/reference/esql/functions/kibana/definition/count_distinct.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/count_distinct.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "agg", "name" : "count_distinct", "description" : "Returns the approximate number of distinct values.", diff --git a/docs/reference/esql/functions/kibana/definition/date_diff.json b/docs/reference/query-languages/esql/kibana/definition/functions/date_diff.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/date_diff.json rename to docs/reference/query-languages/esql/kibana/definition/functions/date_diff.json index dab7f7e0ef2e3..f1cec52c17022 100644 --- a/docs/reference/esql/functions/kibana/definition/date_diff.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/date_diff.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "date_diff", "description" : "Subtracts the `startTimestamp` from the `endTimestamp` and returns the difference in multiples of `unit`.\nIf `startTimestamp` is later than the `endTimestamp`, negative values are returned.", diff --git a/docs/reference/esql/functions/kibana/definition/date_extract.json b/docs/reference/query-languages/esql/kibana/definition/functions/date_extract.json similarity index 80% rename from docs/reference/esql/functions/kibana/definition/date_extract.json rename to docs/reference/query-languages/esql/kibana/definition/functions/date_extract.json index 1778d99dcf342..bec2af44728c1 100644 --- a/docs/reference/esql/functions/kibana/definition/date_extract.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/date_extract.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "date_extract", "description" : "Extracts parts of a date, like year, month, day, hour.", @@ -10,7 +10,7 @@ "name" : "datePart", "type" : "keyword", "optional" : false, - "description" : "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`." + "description" : "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 {javadoc8}/java/time/temporal/ChronoField.html[java.time.temporal.ChronoField] for a description of these values. If `null`, the function returns `null`." }, { "name" : "date", @@ -28,7 +28,7 @@ "name" : "datePart", "type" : "keyword", "optional" : false, - "description" : "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`." + "description" : "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 {javadoc8}/java/time/temporal/ChronoField.html[java.time.temporal.ChronoField] for a description of these values. If `null`, the function returns `null`." }, { "name" : "date", @@ -46,7 +46,7 @@ "name" : "datePart", "type" : "text", "optional" : false, - "description" : "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`." + "description" : "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 {javadoc8}/java/time/temporal/ChronoField.html[java.time.temporal.ChronoField] for a description of these values. If `null`, the function returns `null`." }, { "name" : "date", @@ -64,7 +64,7 @@ "name" : "datePart", "type" : "text", "optional" : false, - "description" : "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`." + "description" : "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 {javadoc8}/java/time/temporal/ChronoField.html[java.time.temporal.ChronoField] for a description of these values. If `null`, the function returns `null`." }, { "name" : "date", diff --git a/docs/reference/esql/functions/kibana/definition/date_format.json b/docs/reference/query-languages/esql/kibana/definition/functions/date_format.json similarity index 96% rename from docs/reference/esql/functions/kibana/definition/date_format.json rename to docs/reference/query-languages/esql/kibana/definition/functions/date_format.json index 633e20444d771..32996810ec642 100644 --- a/docs/reference/esql/functions/kibana/definition/date_format.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/date_format.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "date_format", "description" : "Returns a string representation of a date, in the provided format.", diff --git a/docs/reference/esql/functions/kibana/definition/date_parse.json b/docs/reference/query-languages/esql/kibana/definition/functions/date_parse.json similarity index 64% rename from docs/reference/esql/functions/kibana/definition/date_parse.json rename to docs/reference/query-languages/esql/kibana/definition/functions/date_parse.json index 8e2f15efce829..ce85d1f28b942 100644 --- a/docs/reference/esql/functions/kibana/definition/date_parse.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/date_parse.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "date_parse", "description" : "Returns a date by parsing the second argument using the format specified in the first argument.", @@ -10,7 +10,7 @@ "name" : "datePattern", "type" : "keyword", "optional" : true, - "description" : "The date format. Refer to the https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html[`DateTimeFormatter` documentation] for the syntax. If `null`, the function returns `null`." + "description" : "The date format. Refer to the {javadoc14}/java.base/java/time/format/DateTimeFormatter.html[`DateTimeFormatter` documentation] for the syntax. If `null`, the function returns `null`." }, { "name" : "dateString", @@ -28,7 +28,7 @@ "name" : "datePattern", "type" : "keyword", "optional" : true, - "description" : "The date format. Refer to the https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html[`DateTimeFormatter` documentation] for the syntax. If `null`, the function returns `null`." + "description" : "The date format. Refer to the {javadoc14}/java.base/java/time/format/DateTimeFormatter.html[`DateTimeFormatter` documentation] for the syntax. If `null`, the function returns `null`." }, { "name" : "dateString", @@ -46,7 +46,7 @@ "name" : "datePattern", "type" : "text", "optional" : true, - "description" : "The date format. Refer to the https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html[`DateTimeFormatter` documentation] for the syntax. If `null`, the function returns `null`." + "description" : "The date format. Refer to the {javadoc14}/java.base/java/time/format/DateTimeFormatter.html[`DateTimeFormatter` documentation] for the syntax. If `null`, the function returns `null`." }, { "name" : "dateString", @@ -64,7 +64,7 @@ "name" : "datePattern", "type" : "text", "optional" : true, - "description" : "The date format. Refer to the https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html[`DateTimeFormatter` documentation] for the syntax. If `null`, the function returns `null`." + "description" : "The date format. Refer to the {javadoc14}/java.base/java/time/format/DateTimeFormatter.html[`DateTimeFormatter` documentation] for the syntax. If `null`, the function returns `null`." }, { "name" : "dateString", diff --git a/docs/reference/esql/functions/kibana/definition/date_trunc.json b/docs/reference/query-languages/esql/kibana/definition/functions/date_trunc.json similarity index 94% rename from docs/reference/esql/functions/kibana/definition/date_trunc.json rename to docs/reference/query-languages/esql/kibana/definition/functions/date_trunc.json index 023298d0f8b53..af0b9012aab9c 100644 --- a/docs/reference/esql/functions/kibana/definition/date_trunc.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/date_trunc.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "date_trunc", "description" : "Rounds down a date to the closest interval.", diff --git a/docs/reference/esql/functions/kibana/definition/e.json b/docs/reference/query-languages/esql/kibana/definition/functions/e.json similarity index 54% rename from docs/reference/esql/functions/kibana/definition/e.json rename to docs/reference/query-languages/esql/kibana/definition/functions/e.json index 15bcb0572e2a8..eb0767a616fd5 100644 --- a/docs/reference/esql/functions/kibana/definition/e.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/e.json @@ -1,8 +1,8 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "e", - "description" : "Returns Euler's number.", + "description" : "Returns Euler’s number.", "signatures" : [ { "params" : [ ], diff --git a/docs/reference/esql/functions/kibana/definition/ends_with.json b/docs/reference/query-languages/esql/kibana/definition/functions/ends_with.json similarity index 94% rename from docs/reference/esql/functions/kibana/definition/ends_with.json rename to docs/reference/query-languages/esql/kibana/definition/functions/ends_with.json index eb2e0268214ad..2603da4276371 100644 --- a/docs/reference/esql/functions/kibana/definition/ends_with.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/ends_with.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "ends_with", "description" : "Returns a boolean that indicates whether a keyword string ends with another string.", diff --git a/docs/reference/esql/functions/kibana/definition/exp.json b/docs/reference/query-languages/esql/kibana/definition/functions/exp.json similarity index 91% rename from docs/reference/esql/functions/kibana/definition/exp.json rename to docs/reference/query-languages/esql/kibana/definition/functions/exp.json index 186cde72c7999..379c8bc068270 100644 --- a/docs/reference/esql/functions/kibana/definition/exp.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/exp.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "exp", "description" : "Returns the value of e raised to the power of the given number.", diff --git a/docs/reference/esql/functions/kibana/definition/floor.json b/docs/reference/query-languages/esql/kibana/definition/functions/floor.json similarity index 92% rename from docs/reference/esql/functions/kibana/definition/floor.json rename to docs/reference/query-languages/esql/kibana/definition/functions/floor.json index 6e2deb3dce567..c6927d02847a5 100644 --- a/docs/reference/esql/functions/kibana/definition/floor.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/floor.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "floor", "description" : "Round a number down to the nearest integer.", diff --git a/docs/reference/esql/functions/kibana/definition/from_base64.json b/docs/reference/query-languages/esql/kibana/definition/functions/from_base64.json similarity index 78% rename from docs/reference/esql/functions/kibana/definition/from_base64.json rename to docs/reference/query-languages/esql/kibana/definition/functions/from_base64.json index a94f4a338cb08..2e0f5e9337d32 100644 --- a/docs/reference/esql/functions/kibana/definition/from_base64.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/from_base64.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "from_base64", "description" : "Decode a base64 string.", @@ -30,7 +30,7 @@ } ], "examples" : [ - "row a = \"ZWxhc3RpYw==\" \n| eval d = from_base64(a)" + "row a = \"ZWxhc3RpYw==\"\n| eval d = from_base64(a)" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/greatest.json b/docs/reference/query-languages/esql/kibana/definition/functions/greatest.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/greatest.json rename to docs/reference/query-languages/esql/kibana/definition/functions/greatest.json index af78ca3d02b5d..0c095018d56f5 100644 --- a/docs/reference/esql/functions/kibana/definition/greatest.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/greatest.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "greatest", "description" : "Returns the maximum value from multiple columns. This is similar to <>\nexcept it is intended to run on multiple columns at once.", diff --git a/docs/reference/esql/functions/kibana/definition/hash.json b/docs/reference/query-languages/esql/kibana/definition/functions/hash.json similarity index 86% rename from docs/reference/esql/functions/kibana/definition/hash.json rename to docs/reference/query-languages/esql/kibana/definition/functions/hash.json index 93ee99bf3e9c9..7a66883c0d173 100644 --- a/docs/reference/esql/functions/kibana/definition/hash.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/hash.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "hash", "description" : "Computes the hash of the input using various algorithms such as MD5, SHA, SHA-224, SHA-256, SHA-384, SHA-512.", @@ -78,7 +78,7 @@ } ], "examples" : [ - "FROM sample_data \n| WHERE message != \"Connection error\"\n| EVAL md5 = hash(\"md5\", message), sha256 = hash(\"sha256\", message) \n| KEEP message, md5, sha256;" + "FROM sample_data\n| WHERE message != \"Connection error\"\n| EVAL md5 = hash(\"md5\", message), sha256 = hash(\"sha256\", message)\n| KEEP message, md5, sha256" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/hypot.json b/docs/reference/query-languages/esql/kibana/definition/functions/hypot.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/hypot.json rename to docs/reference/query-languages/esql/kibana/definition/functions/hypot.json index a71f318a286b1..edb9889843797 100644 --- a/docs/reference/esql/functions/kibana/definition/hypot.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/hypot.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "hypot", "description" : "Returns the hypotenuse of two numbers. The input can be any numeric values, the return value is always a double.\nHypotenuses of infinities are null.", diff --git a/docs/reference/esql/functions/kibana/definition/ip_prefix.json b/docs/reference/query-languages/esql/kibana/definition/functions/ip_prefix.json similarity index 88% rename from docs/reference/esql/functions/kibana/definition/ip_prefix.json rename to docs/reference/query-languages/esql/kibana/definition/functions/ip_prefix.json index 0d039a784a7bb..383a8e4e4a58f 100644 --- a/docs/reference/esql/functions/kibana/definition/ip_prefix.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/ip_prefix.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "ip_prefix", "description" : "Truncates an IP to a given prefix length.", diff --git a/docs/reference/esql/functions/kibana/definition/kql.json b/docs/reference/query-languages/esql/kibana/definition/functions/kql.json similarity index 77% rename from docs/reference/esql/functions/kibana/definition/kql.json rename to docs/reference/query-languages/esql/kibana/definition/functions/kql.json index ff0f854f20fa5..f7748ef09455f 100644 --- a/docs/reference/esql/functions/kibana/definition/kql.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/kql.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "kql", "description" : "Performs a KQL query. Returns true if the provided KQL query string matches the row.", @@ -30,7 +30,7 @@ } ], "examples" : [ - "FROM books \n| WHERE KQL(\"author: Faulkner\")\n| KEEP book_no, author \n| SORT book_no \n| LIMIT 5" + "FROM books\n| WHERE KQL(\"author: Faulkner\")\n| KEEP book_no, author\n| SORT book_no\n| LIMIT 5" ], "preview" : true, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/least.json b/docs/reference/query-languages/esql/kibana/definition/functions/least.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/least.json rename to docs/reference/query-languages/esql/kibana/definition/functions/least.json index 30f27b9be0b07..42ad9b567e4c6 100644 --- a/docs/reference/esql/functions/kibana/definition/least.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/least.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "least", "description" : "Returns the minimum value from multiple columns. This is similar to <> except it is intended to run on multiple columns at once.", diff --git a/docs/reference/esql/functions/kibana/definition/left.json b/docs/reference/query-languages/esql/kibana/definition/functions/left.json similarity index 82% rename from docs/reference/esql/functions/kibana/definition/left.json rename to docs/reference/query-languages/esql/kibana/definition/functions/left.json index b367dc9655ec5..1f1bce610f5ab 100644 --- a/docs/reference/esql/functions/kibana/definition/left.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/left.json @@ -1,8 +1,8 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "left", - "description" : "Returns the substring that extracts 'length' chars from 'string' starting from the left.", + "description" : "Returns the substring that extracts *length* chars from *string* starting from the left.", "signatures" : [ { "params" : [ diff --git a/docs/reference/esql/functions/kibana/definition/length.json b/docs/reference/query-languages/esql/kibana/definition/functions/length.json similarity index 88% rename from docs/reference/esql/functions/kibana/definition/length.json rename to docs/reference/query-languages/esql/kibana/definition/functions/length.json index c2eca63e4e1dd..0845c4ae1da1d 100644 --- a/docs/reference/esql/functions/kibana/definition/length.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/length.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "length", "description" : "Returns the character length of a string.", diff --git a/docs/reference/esql/functions/kibana/definition/locate.json b/docs/reference/query-languages/esql/kibana/definition/functions/locate.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/locate.json rename to docs/reference/query-languages/esql/kibana/definition/functions/locate.json index 0322ec1945aa7..165ff9832ee23 100644 --- a/docs/reference/esql/functions/kibana/definition/locate.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/locate.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "locate", "description" : "Returns an integer that indicates the position of a keyword substring within another string.\nReturns `0` if the substring cannot be found.\nNote that string positions start from `1`.", diff --git a/docs/reference/esql/functions/kibana/definition/log.json b/docs/reference/query-languages/esql/kibana/definition/functions/log.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/log.json rename to docs/reference/query-languages/esql/kibana/definition/functions/log.json index c75349a89630d..d2aea8e63919d 100644 --- a/docs/reference/esql/functions/kibana/definition/log.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/log.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "log", "description" : "Returns the logarithm of a value to a base. The input can be any numeric value, the return value is always a double.\n\nLogs of zero, negative numbers, and base of one return `null` as well as a warning.", diff --git a/docs/reference/esql/functions/kibana/definition/log10.json b/docs/reference/query-languages/esql/kibana/definition/functions/log10.json similarity index 89% rename from docs/reference/esql/functions/kibana/definition/log10.json rename to docs/reference/query-languages/esql/kibana/definition/functions/log10.json index 6cc089ae49c4f..ac19a78ae00de 100644 --- a/docs/reference/esql/functions/kibana/definition/log10.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/log10.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "log10", "description" : "Returns the logarithm of a value to base 10. The input can be any numeric value, the return value is always a double.\n\nLogs of 0 and negative numbers return `null` as well as a warning.", @@ -54,7 +54,7 @@ } ], "examples" : [ - "ROW d = 1000.0 \n| EVAL s = LOG10(d)" + "ROW d = 1000.0\n| EVAL s = LOG10(d)" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/ltrim.json b/docs/reference/query-languages/esql/kibana/definition/functions/ltrim.json similarity index 88% rename from docs/reference/esql/functions/kibana/definition/ltrim.json rename to docs/reference/query-languages/esql/kibana/definition/functions/ltrim.json index f0a58dd4f9aea..50984ce5a2c6e 100644 --- a/docs/reference/esql/functions/kibana/definition/ltrim.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/ltrim.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "ltrim", "description" : "Removes leading whitespaces from a string.", diff --git a/docs/reference/esql/functions/kibana/definition/match.json b/docs/reference/query-languages/esql/kibana/definition/functions/match.json similarity index 99% rename from docs/reference/esql/functions/kibana/definition/match.json rename to docs/reference/query-languages/esql/kibana/definition/functions/match.json index 4844382fe04cf..5a1a1e674ac20 100644 --- a/docs/reference/esql/functions/kibana/definition/match.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/match.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "match", "description" : "Use `MATCH` to perform a <> on the specified field.\nUsing `MATCH` is equivalent to using the `match` query in the Elasticsearch Query DSL.\n\nMatch can be used on fields from the text family like <> and <>,\nas well as other field types like keyword, boolean, dates, and numeric types.\n\nMatch can use <> to specify additional options for the match query.\nAll <> are supported.\n\nFor a simplified syntax, you can use the <> `:` operator instead of `MATCH`.\n\n`MATCH` returns true if the provided query matches the row.", @@ -731,8 +731,8 @@ } ], "examples" : [ - "FROM books \n| WHERE MATCH(author, \"Faulkner\")\n| KEEP book_no, author \n| SORT book_no \n| LIMIT 5", - "FROM books \n| WHERE MATCH(title, \"Hobbit Back Again\", {\"operator\": \"AND\"})\n| KEEP title;" + "FROM books\n| WHERE MATCH(author, \"Faulkner\")\n| KEEP book_no, author\n| SORT book_no\n| LIMIT 5", + "FROM books\n| WHERE MATCH(title, \"Hobbit Back Again\", {\"operator\": \"AND\"})\n| KEEP title;" ], "preview" : true, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/max.json b/docs/reference/query-languages/esql/kibana/definition/functions/max.json similarity index 95% rename from docs/reference/esql/functions/kibana/definition/max.json rename to docs/reference/query-languages/esql/kibana/definition/functions/max.json index 7f3d2215ee099..9a609a04746dd 100644 --- a/docs/reference/esql/functions/kibana/definition/max.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/max.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "agg", "name" : "max", "description" : "The maximum value of a field.", diff --git a/docs/reference/esql/functions/kibana/definition/md5.json b/docs/reference/query-languages/esql/kibana/definition/functions/md5.json similarity index 73% rename from docs/reference/esql/functions/kibana/definition/md5.json rename to docs/reference/query-languages/esql/kibana/definition/functions/md5.json index b631f7816cb5f..dcb1a912db73b 100644 --- a/docs/reference/esql/functions/kibana/definition/md5.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/md5.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "md5", "description" : "Computes the MD5 hash of the input.", @@ -30,7 +30,7 @@ } ], "examples" : [ - "FROM sample_data \n| WHERE message != \"Connection error\"\n| EVAL md5 = md5(message)\n| KEEP message, md5;" + "FROM sample_data\n| WHERE message != \"Connection error\"\n| EVAL md5 = md5(message)\n| KEEP message, md5" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/median.json b/docs/reference/query-languages/esql/kibana/definition/functions/median.json similarity index 74% rename from docs/reference/esql/functions/kibana/definition/median.json rename to docs/reference/query-languages/esql/kibana/definition/functions/median.json index c29ae46927163..5abb5d87aafda 100644 --- a/docs/reference/esql/functions/kibana/definition/median.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/median.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "agg", "name" : "median", "description" : "The value that is greater than half of all values and less than half of all values, also known as the 50% <>.", @@ -11,7 +11,7 @@ "name" : "number", "type" : "double", "optional" : false, - "description" : "" + "description" : "Expression that outputs values to calculate the median of." } ], "variadic" : false, @@ -23,7 +23,7 @@ "name" : "number", "type" : "integer", "optional" : false, - "description" : "" + "description" : "Expression that outputs values to calculate the median of." } ], "variadic" : false, @@ -35,7 +35,7 @@ "name" : "number", "type" : "long", "optional" : false, - "description" : "" + "description" : "Expression that outputs values to calculate the median of." } ], "variadic" : false, diff --git a/docs/reference/esql/functions/kibana/definition/median_absolute_deviation.json b/docs/reference/query-languages/esql/kibana/definition/functions/median_absolute_deviation.json similarity index 83% rename from docs/reference/esql/functions/kibana/definition/median_absolute_deviation.json rename to docs/reference/query-languages/esql/kibana/definition/functions/median_absolute_deviation.json index 06fc77d782346..615a9b6543456 100644 --- a/docs/reference/esql/functions/kibana/definition/median_absolute_deviation.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/median_absolute_deviation.json @@ -1,8 +1,8 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "agg", "name" : "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.\n\nIt 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|)`.", + "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.\n\nIt 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 <>.", "signatures" : [ { diff --git a/docs/reference/esql/functions/kibana/definition/min.json b/docs/reference/query-languages/esql/kibana/definition/functions/min.json similarity index 95% rename from docs/reference/esql/functions/kibana/definition/min.json rename to docs/reference/query-languages/esql/kibana/definition/functions/min.json index 74e3fd8208f1b..de1970fafb09a 100644 --- a/docs/reference/esql/functions/kibana/definition/min.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/min.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "agg", "name" : "min", "description" : "The minimum value of a field.", diff --git a/docs/reference/esql/functions/kibana/definition/mv_append.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_append.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/mv_append.json rename to docs/reference/query-languages/esql/kibana/definition/functions/mv_append.json index 7cbcc678464c7..164502358e44a 100644 --- a/docs/reference/esql/functions/kibana/definition/mv_append.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_append.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "mv_append", "description" : "Concatenates values of two multi-value fields.", diff --git a/docs/reference/esql/functions/kibana/definition/mv_avg.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_avg.json similarity index 91% rename from docs/reference/esql/functions/kibana/definition/mv_avg.json rename to docs/reference/query-languages/esql/kibana/definition/functions/mv_avg.json index 65a32cba133ef..65cee20779e9c 100644 --- a/docs/reference/esql/functions/kibana/definition/mv_avg.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_avg.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "mv_avg", "description" : "Converts a multivalued field into a single valued field containing the average of all of the values.", diff --git a/docs/reference/esql/functions/kibana/definition/mv_concat.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_concat.json similarity index 94% rename from docs/reference/esql/functions/kibana/definition/mv_concat.json rename to docs/reference/query-languages/esql/kibana/definition/functions/mv_concat.json index 6855525abfba5..69cd56fc64c07 100644 --- a/docs/reference/esql/functions/kibana/definition/mv_concat.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_concat.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "mv_concat", "description" : "Converts a multivalued string expression into a single valued column containing the concatenation of all values separated by a delimiter.", diff --git a/docs/reference/esql/functions/kibana/definition/mv_count.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_count.json similarity index 96% rename from docs/reference/esql/functions/kibana/definition/mv_count.json rename to docs/reference/query-languages/esql/kibana/definition/functions/mv_count.json index b82b7b382409d..ceda3879abbe1 100644 --- a/docs/reference/esql/functions/kibana/definition/mv_count.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_count.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "mv_count", "description" : "Converts a multivalued expression into a single valued column containing a count of the number of values.", diff --git a/docs/reference/esql/functions/kibana/definition/mv_dedupe.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_dedupe.json similarity index 95% rename from docs/reference/esql/functions/kibana/definition/mv_dedupe.json rename to docs/reference/query-languages/esql/kibana/definition/functions/mv_dedupe.json index fbce83189ef2b..76774d50c3e8f 100644 --- a/docs/reference/esql/functions/kibana/definition/mv_dedupe.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_dedupe.json @@ -1,9 +1,9 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "mv_dedupe", "description" : "Remove duplicate values from a multivalued field.", - "note" : "`MV_DEDUPE` may, but won't always, sort the values in the column.", + "note" : "`MV_DEDUPE` may, but won’t always, sort the values in the column.", "signatures" : [ { "params" : [ diff --git a/docs/reference/esql/functions/kibana/definition/mv_first.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_first.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/mv_first.json rename to docs/reference/query-languages/esql/kibana/definition/functions/mv_first.json index 32525a7c124f3..08fbc425bfaa7 100644 --- a/docs/reference/esql/functions/kibana/definition/mv_first.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_first.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "mv_first", "description" : "Converts a multivalued expression into a single valued column containing the\nfirst value. This is most useful when reading from a function that emits\nmultivalued columns in a known order like <>.", diff --git a/docs/reference/esql/functions/kibana/definition/mv_last.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_last.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/mv_last.json rename to docs/reference/query-languages/esql/kibana/definition/functions/mv_last.json index f11482b69824c..1fd311ed113cc 100644 --- a/docs/reference/esql/functions/kibana/definition/mv_last.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_last.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "mv_last", "description" : "Converts a multivalue expression into a single valued column containing the last\nvalue. This is most useful when reading from a function that emits multivalued\ncolumns in a known order like <>.", diff --git a/docs/reference/esql/functions/kibana/definition/mv_max.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_max.json similarity index 96% rename from docs/reference/esql/functions/kibana/definition/mv_max.json rename to docs/reference/query-languages/esql/kibana/definition/functions/mv_max.json index 65b8d801edabd..f16d11f936020 100644 --- a/docs/reference/esql/functions/kibana/definition/mv_max.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_max.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "mv_max", "description" : "Converts a multivalued expression into a single valued column containing the maximum value.", diff --git a/docs/reference/esql/functions/kibana/definition/mv_median.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_median.json similarity index 91% rename from docs/reference/esql/functions/kibana/definition/mv_median.json rename to docs/reference/query-languages/esql/kibana/definition/functions/mv_median.json index 3ba870023cb47..34fd31625b47f 100644 --- a/docs/reference/esql/functions/kibana/definition/mv_median.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_median.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "mv_median", "description" : "Converts a multivalued field into a single valued field containing the median value.", diff --git a/docs/reference/esql/functions/kibana/definition/mv_median_absolute_deviation.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_median_absolute_deviation.json similarity index 83% rename from docs/reference/esql/functions/kibana/definition/mv_median_absolute_deviation.json rename to docs/reference/query-languages/esql/kibana/definition/functions/mv_median_absolute_deviation.json index e4beb343cd20d..dac77104e3f5c 100644 --- a/docs/reference/esql/functions/kibana/definition/mv_median_absolute_deviation.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_median_absolute_deviation.json @@ -1,8 +1,8 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "mv_median_absolute_deviation", - "description" : "Converts a multivalued field into a single valued field containing the median absolute deviation.\n\nIt 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|)`.", + "description" : "Converts a multivalued field into a single valued field containing the median absolute deviation.\n\nIt 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" : "If the field has an even number of values, the medians will be calculated as the average of the middle two values. If the value is not a floating point number, the averages are rounded towards 0.", "signatures" : [ { diff --git a/docs/reference/esql/functions/kibana/definition/mv_min.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_min.json similarity index 96% rename from docs/reference/esql/functions/kibana/definition/mv_min.json rename to docs/reference/query-languages/esql/kibana/definition/functions/mv_min.json index ef36cee912d5c..ae37a009511f7 100644 --- a/docs/reference/esql/functions/kibana/definition/mv_min.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_min.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "mv_min", "description" : "Converts a multivalued expression into a single valued column containing the minimum value.", diff --git a/docs/reference/esql/functions/kibana/definition/mv_percentile.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_percentile.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/mv_percentile.json rename to docs/reference/query-languages/esql/kibana/definition/functions/mv_percentile.json index 7835241ed68ba..814fc0ef4fac4 100644 --- a/docs/reference/esql/functions/kibana/definition/mv_percentile.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_percentile.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "mv_percentile", "description" : "Converts a multivalued field into a single valued field containing the value at which a certain percentage of observed values occur.", diff --git a/docs/reference/esql/functions/kibana/definition/mv_pseries_weighted_sum.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_pseries_weighted_sum.json similarity index 78% rename from docs/reference/esql/functions/kibana/definition/mv_pseries_weighted_sum.json rename to docs/reference/query-languages/esql/kibana/definition/functions/mv_pseries_weighted_sum.json index 7935afe3338e3..af6197e639615 100644 --- a/docs/reference/esql/functions/kibana/definition/mv_pseries_weighted_sum.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_pseries_weighted_sum.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "mv_pseries_weighted_sum", "description" : "Converts a multivalued expression into a single-valued column by multiplying every element on the input list by its corresponding term in P-Series and computing the sum.", @@ -16,7 +16,7 @@ "name" : "p", "type" : "double", "optional" : false, - "description" : "It is a constant number that represents the 'p' parameter in the P-Series. It impacts every element's contribution to the weighted sum." + "description" : "It is a constant number that represents the *p* parameter in the P-Series. It impacts every element’s contribution to the weighted sum." } ], "variadic" : false, diff --git a/docs/reference/esql/functions/kibana/definition/mv_slice.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_slice.json similarity index 99% rename from docs/reference/esql/functions/kibana/definition/mv_slice.json rename to docs/reference/query-languages/esql/kibana/definition/functions/mv_slice.json index f23c0d089d93b..03ec525a9f847 100644 --- a/docs/reference/esql/functions/kibana/definition/mv_slice.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_slice.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "mv_slice", "description" : "Returns a subset of the multivalued field using the start and end index values.\nThis is most useful when reading from a function that emits multivalued columns\nin a known order like <> or <>.", diff --git a/docs/reference/esql/functions/kibana/definition/mv_sort.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_sort.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/mv_sort.json rename to docs/reference/query-languages/esql/kibana/definition/functions/mv_sort.json index 17a8fb426755c..85ff069163107 100644 --- a/docs/reference/esql/functions/kibana/definition/mv_sort.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_sort.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "mv_sort", "description" : "Sorts a multivalued field in lexicographical order.", diff --git a/docs/reference/esql/functions/kibana/definition/mv_sum.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_sum.json similarity index 91% rename from docs/reference/esql/functions/kibana/definition/mv_sum.json rename to docs/reference/query-languages/esql/kibana/definition/functions/mv_sum.json index 31b0e5e420b70..2577f1fefdff8 100644 --- a/docs/reference/esql/functions/kibana/definition/mv_sum.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_sum.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "mv_sum", "description" : "Converts a multivalued field into a single valued field containing the sum of all of the values.", diff --git a/docs/reference/esql/functions/kibana/definition/mv_zip.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_zip.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/mv_zip.json rename to docs/reference/query-languages/esql/kibana/definition/functions/mv_zip.json index fc573834054b7..60409a23fbd61 100644 --- a/docs/reference/esql/functions/kibana/definition/mv_zip.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_zip.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "mv_zip", "description" : "Combines the values from two multivalued fields with a delimiter that joins them together.", diff --git a/docs/reference/esql/functions/kibana/definition/now.json b/docs/reference/query-languages/esql/kibana/definition/functions/now.json similarity index 72% rename from docs/reference/esql/functions/kibana/definition/now.json rename to docs/reference/query-languages/esql/kibana/definition/functions/now.json index 42831c2faf497..323f7e1d24b40 100644 --- a/docs/reference/esql/functions/kibana/definition/now.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/now.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "now", "description" : "Returns current date and time.", diff --git a/docs/reference/esql/functions/kibana/definition/percentile.json b/docs/reference/query-languages/esql/kibana/definition/functions/percentile.json similarity index 96% rename from docs/reference/esql/functions/kibana/definition/percentile.json rename to docs/reference/query-languages/esql/kibana/definition/functions/percentile.json index ea7a950b33c88..cd1fd8d9cbd78 100644 --- a/docs/reference/esql/functions/kibana/definition/percentile.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/percentile.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "agg", "name" : "percentile", "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 `MEDIAN`.", diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/pi.json b/docs/reference/query-languages/esql/kibana/definition/functions/pi.json new file mode 100644 index 0000000000000..6e21975071e6d --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/definition/functions/pi.json @@ -0,0 +1,17 @@ +{ + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "type" : "scalar", + "name" : "pi", + "description" : "Returns Pi, the ratio of a circle’s circumference to its diameter.", + "signatures" : [ + { + "params" : [ ], + "returnType" : "double" + } + ], + "examples" : [ + "ROW PI()" + ], + "preview" : false, + "snapshot_only" : false +} diff --git a/docs/reference/esql/functions/kibana/definition/pow.json b/docs/reference/query-languages/esql/kibana/definition/functions/pow.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/pow.json rename to docs/reference/query-languages/esql/kibana/definition/functions/pow.json index 93dda492f087b..f4bc5c3d240fa 100644 --- a/docs/reference/esql/functions/kibana/definition/pow.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/pow.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "pow", "description" : "Returns the value of `base` raised to the power of `exponent`.", diff --git a/docs/reference/esql/functions/kibana/definition/qstr.json b/docs/reference/query-languages/esql/kibana/definition/functions/qstr.json similarity index 77% rename from docs/reference/esql/functions/kibana/definition/qstr.json rename to docs/reference/query-languages/esql/kibana/definition/functions/qstr.json index b617f9f9246c6..7d93990f5ec5a 100644 --- a/docs/reference/esql/functions/kibana/definition/qstr.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/qstr.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "qstr", "description" : "Performs a <>. Returns true if the provided query string matches the row.", @@ -30,7 +30,7 @@ } ], "examples" : [ - "FROM books \n| WHERE QSTR(\"author: Faulkner\")\n| KEEP book_no, author \n| SORT book_no \n| LIMIT 5" + "FROM books\n| WHERE QSTR(\"author: Faulkner\")\n| KEEP book_no, author\n| SORT book_no\n| LIMIT 5" ], "preview" : true, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/repeat.json b/docs/reference/query-languages/esql/kibana/definition/functions/repeat.json similarity index 89% rename from docs/reference/esql/functions/kibana/definition/repeat.json rename to docs/reference/query-languages/esql/kibana/definition/functions/repeat.json index 2eb739f0d0bc0..2035f2b5d5537 100644 --- a/docs/reference/esql/functions/kibana/definition/repeat.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/repeat.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "repeat", "description" : "Returns a string constructed by concatenating `string` with itself the specified `number` of times.", diff --git a/docs/reference/esql/functions/kibana/definition/replace.json b/docs/reference/query-languages/esql/kibana/definition/functions/replace.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/replace.json rename to docs/reference/query-languages/esql/kibana/definition/functions/replace.json index b512019a9951a..6744a375c628e 100644 --- a/docs/reference/esql/functions/kibana/definition/replace.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/replace.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "replace", "description" : "The function substitutes in the string `str` any match of the regular expression `regex`\nwith the replacement string `newStr`.", diff --git a/docs/reference/esql/functions/kibana/definition/reverse.json b/docs/reference/query-languages/esql/kibana/definition/functions/reverse.json similarity index 77% rename from docs/reference/esql/functions/kibana/definition/reverse.json rename to docs/reference/query-languages/esql/kibana/definition/functions/reverse.json index 2ebf63fa5787c..6f282a5bb4ce8 100644 --- a/docs/reference/esql/functions/kibana/definition/reverse.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/reverse.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "reverse", "description" : "Returns a new string representing the input string in reverse order.", @@ -31,7 +31,7 @@ ], "examples" : [ "ROW message = \"Some Text\" | EVAL message_reversed = REVERSE(message);", - "ROW bending_arts = \"💧🪨🔥💨\" | EVAL bending_arts_reversed = REVERSE(bending_arts);" + "ROW bending_arts = \"\uD83D\uDCA7\uD83E\uDEA8\uD83D\uDD25\uD83D\uDCA8\" | EVAL bending_arts_reversed = REVERSE(bending_arts);" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/right.json b/docs/reference/query-languages/esql/kibana/definition/functions/right.json similarity index 82% rename from docs/reference/esql/functions/kibana/definition/right.json rename to docs/reference/query-languages/esql/kibana/definition/functions/right.json index 84408f082db5a..eb9e35c526348 100644 --- a/docs/reference/esql/functions/kibana/definition/right.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/right.json @@ -1,8 +1,8 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "right", - "description" : "Return the substring that extracts 'length' chars from 'str' starting from the right.", + "description" : "Return the substring that extracts *length* chars from *str* starting from the right.", "signatures" : [ { "params" : [ diff --git a/docs/reference/esql/functions/kibana/definition/round.json b/docs/reference/query-languages/esql/kibana/definition/functions/round.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/round.json rename to docs/reference/query-languages/esql/kibana/definition/functions/round.json index a364dbbed0b5a..063067a8aaf2b 100644 --- a/docs/reference/esql/functions/kibana/definition/round.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/round.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "round", "description" : "Rounds a number to the specified number of decimal places.\nDefaults to 0, which returns the nearest integer. If the\nprecision is a negative number, rounds to the number of digits left\nof the decimal point.", diff --git a/docs/reference/esql/functions/kibana/definition/rtrim.json b/docs/reference/query-languages/esql/kibana/definition/functions/rtrim.json similarity index 88% rename from docs/reference/esql/functions/kibana/definition/rtrim.json rename to docs/reference/query-languages/esql/kibana/definition/functions/rtrim.json index ef6c93f9fa172..9d5e042bce662 100644 --- a/docs/reference/esql/functions/kibana/definition/rtrim.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/rtrim.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "rtrim", "description" : "Removes trailing whitespaces from a string.", diff --git a/docs/reference/esql/functions/kibana/definition/sha1.json b/docs/reference/query-languages/esql/kibana/definition/functions/sha1.json similarity index 73% rename from docs/reference/esql/functions/kibana/definition/sha1.json rename to docs/reference/query-languages/esql/kibana/definition/functions/sha1.json index 18fa2c33ae0d5..05d037ccaf16e 100644 --- a/docs/reference/esql/functions/kibana/definition/sha1.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/sha1.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "sha1", "description" : "Computes the SHA1 hash of the input.", @@ -30,7 +30,7 @@ } ], "examples" : [ - "FROM sample_data \n| WHERE message != \"Connection error\"\n| EVAL sha1 = sha1(message)\n| KEEP message, sha1;" + "FROM sample_data\n| WHERE message != \"Connection error\"\n| EVAL sha1 = sha1(message)\n| KEEP message, sha1" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/sha256.json b/docs/reference/query-languages/esql/kibana/definition/functions/sha256.json similarity index 73% rename from docs/reference/esql/functions/kibana/definition/sha256.json rename to docs/reference/query-languages/esql/kibana/definition/functions/sha256.json index 7ad0e2c5500da..2408d858aa502 100644 --- a/docs/reference/esql/functions/kibana/definition/sha256.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/sha256.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "sha256", "description" : "Computes the SHA256 hash of the input.", @@ -30,7 +30,7 @@ } ], "examples" : [ - "FROM sample_data \n| WHERE message != \"Connection error\"\n| EVAL sha256 = sha256(message)\n| KEEP message, sha256;" + "FROM sample_data\n| WHERE message != \"Connection error\"\n| EVAL sha256 = sha256(message)\n| KEEP message, sha256" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/signum.json b/docs/reference/query-languages/esql/kibana/definition/functions/signum.json similarity index 91% rename from docs/reference/esql/functions/kibana/definition/signum.json rename to docs/reference/query-languages/esql/kibana/definition/functions/signum.json index 20667b8cb683e..acbbedcb7371f 100644 --- a/docs/reference/esql/functions/kibana/definition/signum.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/signum.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "signum", "description" : "Returns the sign of the given number.\nIt returns `-1` for negative numbers, `0` for `0` and `1` for positive numbers.", diff --git a/docs/reference/esql/functions/kibana/definition/sin.json b/docs/reference/query-languages/esql/kibana/definition/functions/sin.json similarity index 89% rename from docs/reference/esql/functions/kibana/definition/sin.json rename to docs/reference/query-languages/esql/kibana/definition/functions/sin.json index efdf96a3b8d38..244eab124a542 100644 --- a/docs/reference/esql/functions/kibana/definition/sin.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/sin.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "sin", "description" : "Returns the sine of an angle.", @@ -54,7 +54,7 @@ } ], "examples" : [ - "ROW a=1.8 \n| EVAL sin=SIN(a)" + "ROW a=1.8\n| EVAL sin=SIN(a)" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/sinh.json b/docs/reference/query-languages/esql/kibana/definition/functions/sinh.json similarity index 89% rename from docs/reference/esql/functions/kibana/definition/sinh.json rename to docs/reference/query-languages/esql/kibana/definition/functions/sinh.json index 3ed3eaa23c9ca..e6641979a45ca 100644 --- a/docs/reference/esql/functions/kibana/definition/sinh.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/sinh.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "sinh", "description" : "Returns the hyperbolic sine of a number.", @@ -54,7 +54,7 @@ } ], "examples" : [ - "ROW a=1.8 \n| EVAL sinh=SINH(a)" + "ROW a=1.8\n| EVAL sinh=SINH(a)" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/space.json b/docs/reference/query-languages/esql/kibana/definition/functions/space.json similarity index 80% rename from docs/reference/esql/functions/kibana/definition/space.json rename to docs/reference/query-languages/esql/kibana/definition/functions/space.json index cc1223de2cdf2..0a9ed0bd27804 100644 --- a/docs/reference/esql/functions/kibana/definition/space.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/space.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "space", "description" : "Returns a string made of `number` spaces.", diff --git a/docs/reference/esql/functions/kibana/definition/split.json b/docs/reference/query-languages/esql/kibana/definition/functions/split.json similarity index 94% rename from docs/reference/esql/functions/kibana/definition/split.json rename to docs/reference/query-languages/esql/kibana/definition/functions/split.json index 87a7b0a0f87c6..172bc8f6f0642 100644 --- a/docs/reference/esql/functions/kibana/definition/split.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/split.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "split", "description" : "Split a single valued string into multiple strings.", diff --git a/docs/reference/esql/functions/kibana/definition/sqrt.json b/docs/reference/query-languages/esql/kibana/definition/functions/sqrt.json similarity index 92% rename from docs/reference/esql/functions/kibana/definition/sqrt.json rename to docs/reference/query-languages/esql/kibana/definition/functions/sqrt.json index 6985cb20043c7..f32703f2a30c7 100644 --- a/docs/reference/esql/functions/kibana/definition/sqrt.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/sqrt.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "sqrt", "description" : "Returns the square root of a number. The input can be any numeric value, the return value is always a double.\nSquare roots of negative numbers and infinities are null.", diff --git a/docs/reference/esql/functions/kibana/definition/st_centroid_agg.json b/docs/reference/query-languages/esql/kibana/definition/functions/st_centroid_agg.json similarity index 85% rename from docs/reference/esql/functions/kibana/definition/st_centroid_agg.json rename to docs/reference/query-languages/esql/kibana/definition/functions/st_centroid_agg.json index 62bc97475432f..6bf439f1fe4c8 100644 --- a/docs/reference/esql/functions/kibana/definition/st_centroid_agg.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/st_centroid_agg.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "agg", "name" : "st_centroid_agg", "description" : "Calculate the spatial centroid over a field with spatial point geometry type.", diff --git a/docs/reference/esql/functions/kibana/definition/st_contains.json b/docs/reference/query-languages/esql/kibana/definition/functions/st_contains.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/st_contains.json rename to docs/reference/query-languages/esql/kibana/definition/functions/st_contains.json index 7d78518f91da1..18119288422a2 100644 --- a/docs/reference/esql/functions/kibana/definition/st_contains.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/st_contains.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "st_contains", "description" : "Returns whether the first geometry contains the second geometry.\nThis is the inverse of the <> function.", diff --git a/docs/reference/esql/functions/kibana/definition/st_disjoint.json b/docs/reference/query-languages/esql/kibana/definition/functions/st_disjoint.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/st_disjoint.json rename to docs/reference/query-languages/esql/kibana/definition/functions/st_disjoint.json index f0da69103ea68..adf6570b34c7c 100644 --- a/docs/reference/esql/functions/kibana/definition/st_disjoint.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/st_disjoint.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "st_disjoint", "description" : "Returns whether the two geometries or geometry columns are disjoint.\nThis is the inverse of the <> function.\nIn mathematical terms: ST_Disjoint(A, B) ⇔ A ⋂ B = ∅", diff --git a/docs/reference/esql/functions/kibana/definition/st_distance.json b/docs/reference/query-languages/esql/kibana/definition/functions/st_distance.json similarity index 93% rename from docs/reference/esql/functions/kibana/definition/st_distance.json rename to docs/reference/query-languages/esql/kibana/definition/functions/st_distance.json index 74492b6e30742..d1d0e8ddc0f46 100644 --- a/docs/reference/esql/functions/kibana/definition/st_distance.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/st_distance.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "st_distance", "description" : "Computes the distance between two points.\nFor cartesian geometries, this is the pythagorean distance in the same units as the original coordinates.\nFor geographic geometries, this is the circular distance along the great circle in meters.", diff --git a/docs/reference/esql/functions/kibana/definition/st_envelope.json b/docs/reference/query-languages/esql/kibana/definition/functions/st_envelope.json similarity index 93% rename from docs/reference/esql/functions/kibana/definition/st_envelope.json rename to docs/reference/query-languages/esql/kibana/definition/functions/st_envelope.json index 83f4bad5b826f..43be0c46b215d 100644 --- a/docs/reference/esql/functions/kibana/definition/st_envelope.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/st_envelope.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "st_envelope", "description" : "Determines the minimum bounding box of the supplied geometry.", diff --git a/docs/reference/esql/functions/kibana/definition/st_extent_agg.json b/docs/reference/query-languages/esql/kibana/definition/functions/st_extent_agg.json similarity index 91% rename from docs/reference/esql/functions/kibana/definition/st_extent_agg.json rename to docs/reference/query-languages/esql/kibana/definition/functions/st_extent_agg.json index 19afcc59e38a4..fa129eec29da2 100644 --- a/docs/reference/esql/functions/kibana/definition/st_extent_agg.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/st_extent_agg.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "agg", "name" : "st_extent_agg", "description" : "Calculate the spatial extent over a field with geometry type. Returns a bounding box for all values of the field.", diff --git a/docs/reference/esql/functions/kibana/definition/st_intersects.json b/docs/reference/query-languages/esql/kibana/definition/functions/st_intersects.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/st_intersects.json rename to docs/reference/query-languages/esql/kibana/definition/functions/st_intersects.json index b35df6711b338..7c868e1f3c470 100644 --- a/docs/reference/esql/functions/kibana/definition/st_intersects.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/st_intersects.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "st_intersects", "description" : "Returns true if two geometries intersect.\nThey intersect if they have any point in common, including their interior points\n(points along lines or within polygons).\nThis is the inverse of the <> function.\nIn mathematical terms: ST_Intersects(A, B) ⇔ A ⋂ B ≠ ∅", diff --git a/docs/reference/esql/functions/kibana/definition/st_within.json b/docs/reference/query-languages/esql/kibana/definition/functions/st_within.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/st_within.json rename to docs/reference/query-languages/esql/kibana/definition/functions/st_within.json index 3ab419683f021..8ad01022634cf 100644 --- a/docs/reference/esql/functions/kibana/definition/st_within.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/st_within.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "st_within", "description" : "Returns whether the first geometry is within the second geometry.\nThis is the inverse of the <> function.", diff --git a/docs/reference/esql/functions/kibana/definition/st_x.json b/docs/reference/query-languages/esql/kibana/definition/functions/st_x.json similarity index 89% rename from docs/reference/esql/functions/kibana/definition/st_x.json rename to docs/reference/query-languages/esql/kibana/definition/functions/st_x.json index 27378edd25ff8..ef59e71c24987 100644 --- a/docs/reference/esql/functions/kibana/definition/st_x.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/st_x.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "st_x", "description" : "Extracts the `x` coordinate from the supplied point.\nIf the points is of type `geo_point` this is equivalent to extracting the `longitude` value.", diff --git a/docs/reference/esql/functions/kibana/definition/st_xmax.json b/docs/reference/query-languages/esql/kibana/definition/functions/st_xmax.json similarity index 94% rename from docs/reference/esql/functions/kibana/definition/st_xmax.json rename to docs/reference/query-languages/esql/kibana/definition/functions/st_xmax.json index c1223ecae7349..3bf0d73aacf25 100644 --- a/docs/reference/esql/functions/kibana/definition/st_xmax.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/st_xmax.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "st_xmax", "description" : "Extracts the maximum value of the `x` coordinates from the supplied geometry.\nIf the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the maximum `longitude` value.", diff --git a/docs/reference/esql/functions/kibana/definition/st_xmin.json b/docs/reference/query-languages/esql/kibana/definition/functions/st_xmin.json similarity index 94% rename from docs/reference/esql/functions/kibana/definition/st_xmin.json rename to docs/reference/query-languages/esql/kibana/definition/functions/st_xmin.json index 20c4bd8cca79f..1f6180eb6a1b0 100644 --- a/docs/reference/esql/functions/kibana/definition/st_xmin.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/st_xmin.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "st_xmin", "description" : "Extracts the minimum value of the `x` coordinates from the supplied geometry.\nIf the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the minimum `longitude` value.", diff --git a/docs/reference/esql/functions/kibana/definition/st_y.json b/docs/reference/query-languages/esql/kibana/definition/functions/st_y.json similarity index 89% rename from docs/reference/esql/functions/kibana/definition/st_y.json rename to docs/reference/query-languages/esql/kibana/definition/functions/st_y.json index 42f37d0346b1f..fce10da385b69 100644 --- a/docs/reference/esql/functions/kibana/definition/st_y.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/st_y.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "st_y", "description" : "Extracts the `y` coordinate from the supplied point.\nIf the points is of type `geo_point` this is equivalent to extracting the `latitude` value.", diff --git a/docs/reference/esql/functions/kibana/definition/st_ymax.json b/docs/reference/query-languages/esql/kibana/definition/functions/st_ymax.json similarity index 94% rename from docs/reference/esql/functions/kibana/definition/st_ymax.json rename to docs/reference/query-languages/esql/kibana/definition/functions/st_ymax.json index 83a8070834e1a..b8392650d1123 100644 --- a/docs/reference/esql/functions/kibana/definition/st_ymax.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/st_ymax.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "st_ymax", "description" : "Extracts the maximum value of the `y` coordinates from the supplied geometry.\nIf the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the maximum `latitude` value.", diff --git a/docs/reference/esql/functions/kibana/definition/st_ymin.json b/docs/reference/query-languages/esql/kibana/definition/functions/st_ymin.json similarity index 94% rename from docs/reference/esql/functions/kibana/definition/st_ymin.json rename to docs/reference/query-languages/esql/kibana/definition/functions/st_ymin.json index 21051d02cb6d3..071d44d4557e1 100644 --- a/docs/reference/esql/functions/kibana/definition/st_ymin.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/st_ymin.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "st_ymin", "description" : "Extracts the minimum value of the `y` coordinates from the supplied geometry.\nIf the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the minimum `latitude` value.", diff --git a/docs/reference/esql/functions/kibana/definition/starts_with.json b/docs/reference/query-languages/esql/kibana/definition/functions/starts_with.json similarity index 94% rename from docs/reference/esql/functions/kibana/definition/starts_with.json rename to docs/reference/query-languages/esql/kibana/definition/functions/starts_with.json index bad7fa1d34b69..a1460062a3aa9 100644 --- a/docs/reference/esql/functions/kibana/definition/starts_with.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/starts_with.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "starts_with", "description" : "Returns a boolean that indicates whether a keyword string starts with another string.", diff --git a/docs/reference/esql/functions/kibana/definition/std_dev.json b/docs/reference/query-languages/esql/kibana/definition/functions/std_dev.json similarity index 88% rename from docs/reference/esql/functions/kibana/definition/std_dev.json rename to docs/reference/query-languages/esql/kibana/definition/functions/std_dev.json index f31d3345421d9..e866688e3f451 100644 --- a/docs/reference/esql/functions/kibana/definition/std_dev.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/std_dev.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "agg", "name" : "std_dev", "description" : "The standard deviation of a numeric field.", diff --git a/docs/reference/esql/functions/kibana/definition/substring.json b/docs/reference/query-languages/esql/kibana/definition/functions/substring.json similarity index 93% rename from docs/reference/esql/functions/kibana/definition/substring.json rename to docs/reference/query-languages/esql/kibana/definition/functions/substring.json index c6260c5040e58..5a2a5a8bdd319 100644 --- a/docs/reference/esql/functions/kibana/definition/substring.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/substring.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "substring", "description" : "Returns a substring of a string, specified by a start position and an optional length.", diff --git a/docs/reference/esql/functions/kibana/definition/sum.json b/docs/reference/query-languages/esql/kibana/definition/functions/sum.json similarity index 88% rename from docs/reference/esql/functions/kibana/definition/sum.json rename to docs/reference/query-languages/esql/kibana/definition/functions/sum.json index 385a2e4d41399..4327f4d4a7e3f 100644 --- a/docs/reference/esql/functions/kibana/definition/sum.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/sum.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "agg", "name" : "sum", "description" : "The sum of a numeric expression.", diff --git a/docs/reference/esql/functions/kibana/definition/tan.json b/docs/reference/query-languages/esql/kibana/definition/functions/tan.json similarity index 89% rename from docs/reference/esql/functions/kibana/definition/tan.json rename to docs/reference/query-languages/esql/kibana/definition/functions/tan.json index af28eace4c591..0b5ea9657178e 100644 --- a/docs/reference/esql/functions/kibana/definition/tan.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/tan.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "tan", "description" : "Returns the tangent of an angle.", @@ -54,7 +54,7 @@ } ], "examples" : [ - "ROW a=1.8 \n| EVAL tan=TAN(a)" + "ROW a=1.8\n| EVAL tan=TAN(a)" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/tanh.json b/docs/reference/query-languages/esql/kibana/definition/functions/tanh.json similarity index 89% rename from docs/reference/esql/functions/kibana/definition/tanh.json rename to docs/reference/query-languages/esql/kibana/definition/functions/tanh.json index a36edcc1e88f4..e741315b0841c 100644 --- a/docs/reference/esql/functions/kibana/definition/tanh.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/tanh.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "tanh", "description" : "Returns the hyperbolic tangent of a number.", @@ -54,7 +54,7 @@ } ], "examples" : [ - "ROW a=1.8 \n| EVAL tanh=TANH(a)" + "ROW a=1.8\n| EVAL tanh=TANH(a)" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/tau.json b/docs/reference/query-languages/esql/kibana/definition/functions/tau.json new file mode 100644 index 0000000000000..b70980a729b57 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/definition/functions/tau.json @@ -0,0 +1,17 @@ +{ + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "type" : "scalar", + "name" : "tau", + "description" : "Returns the [ratio](https://tauday.com/tau-manifesto) of a circle’s circumference to its radius.", + "signatures" : [ + { + "params" : [ ], + "returnType" : "double" + } + ], + "examples" : [ + "ROW TAU()" + ], + "preview" : false, + "snapshot_only" : false +} diff --git a/docs/reference/esql/functions/kibana/definition/term.json b/docs/reference/query-languages/esql/kibana/definition/functions/term.json similarity index 90% rename from docs/reference/esql/functions/kibana/definition/term.json rename to docs/reference/query-languages/esql/kibana/definition/functions/term.json index 1a0ea7bf8a4ee..17ecff4943129 100644 --- a/docs/reference/esql/functions/kibana/definition/term.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/term.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "term", "description" : "Performs a Term query on the specified field. Returns true if the provided term matches the row.", @@ -78,7 +78,7 @@ } ], "examples" : [ - "FROM books \n| WHERE TERM(author, \"gabriel\") \n| KEEP book_no, title\n| LIMIT 3;" + "FROM books\n| WHERE TERM(author, \"gabriel\")\n| KEEP book_no, title\n| LIMIT 3" ], "preview" : true, "snapshot_only" : true diff --git a/docs/reference/esql/functions/kibana/definition/to_base64.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_base64.json similarity index 79% rename from docs/reference/esql/functions/kibana/definition/to_base64.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_base64.json index 39014ceb9a5c2..64f8f900551b3 100644 --- a/docs/reference/esql/functions/kibana/definition/to_base64.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_base64.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_base64", "description" : "Encode a string to a base64 string.", @@ -30,7 +30,7 @@ } ], "examples" : [ - "row a = \"elastic\" \n| eval e = to_base64(a)" + "row a = \"elastic\"\n| eval e = to_base64(a)" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/to_boolean.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_boolean.json similarity index 86% rename from docs/reference/esql/functions/kibana/definition/to_boolean.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_boolean.json index d295c826f5767..5212e67bcfca1 100644 --- a/docs/reference/esql/functions/kibana/definition/to_boolean.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_boolean.json @@ -1,8 +1,8 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_boolean", - "description" : "Converts an input value to a boolean value.\nA string value of *true* will be case-insensitive converted to the Boolean *true*.\nFor anything else, including the empty string, the function will return *false*.\nThe numerical value of *0* will be converted to *false*, anything else will be converted to *true*.", + "description" : "Converts an input value to a boolean value.\nA string value of `true` will be case-insensitive converted to the Boolean `true`.\nFor anything else, including the empty string, the function will return `false`.\nThe numerical value of `0` will be converted to `false`, anything else will be converted to `true`.", "signatures" : [ { "params" : [ diff --git a/docs/reference/esql/functions/kibana/definition/to_cartesianpoint.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_cartesianpoint.json similarity index 91% rename from docs/reference/esql/functions/kibana/definition/to_cartesianpoint.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_cartesianpoint.json index f7303457120f4..34db5304c9cac 100644 --- a/docs/reference/esql/functions/kibana/definition/to_cartesianpoint.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_cartesianpoint.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_cartesianpoint", "description" : "Converts an input value to a `cartesian_point` value.\nA string will only be successfully converted if it respects WKT Point format.", diff --git a/docs/reference/esql/functions/kibana/definition/to_cartesianshape.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_cartesianshape.json similarity index 93% rename from docs/reference/esql/functions/kibana/definition/to_cartesianshape.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_cartesianshape.json index 6a08d531523ad..5e7764b8b4410 100644 --- a/docs/reference/esql/functions/kibana/definition/to_cartesianshape.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_cartesianshape.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_cartesianshape", "description" : "Converts an input value to a `cartesian_shape` value.\nA string will only be successfully converted if it respects WKT format.", diff --git a/docs/reference/esql/functions/kibana/definition/to_date_nanos.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_date_nanos.json similarity index 95% rename from docs/reference/esql/functions/kibana/definition/to_date_nanos.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_date_nanos.json index bc74476a4867c..fccac7edd232d 100644 --- a/docs/reference/esql/functions/kibana/definition/to_date_nanos.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_date_nanos.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_date_nanos", "description" : "Converts an input to a nanosecond-resolution date value (aka date_nanos).", diff --git a/docs/reference/esql/functions/kibana/definition/to_dateperiod.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_dateperiod.json similarity index 90% rename from docs/reference/esql/functions/kibana/definition/to_dateperiod.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_dateperiod.json index 790c7ec92401c..ef139c2cd2029 100644 --- a/docs/reference/esql/functions/kibana/definition/to_dateperiod.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_dateperiod.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_dateperiod", "description" : "Converts an input value into a `date_period` value.", diff --git a/docs/reference/esql/functions/kibana/definition/to_datetime.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_datetime.json similarity index 91% rename from docs/reference/esql/functions/kibana/definition/to_datetime.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_datetime.json index 90c683cf3767f..fe58cefb2bb3f 100644 --- a/docs/reference/esql/functions/kibana/definition/to_datetime.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_datetime.json @@ -1,8 +1,8 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_datetime", - "description" : "Converts an input value to a date value.\nA string will only be successfully converted if it's respecting the format `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`.\nTo convert dates in other formats, use <>.", + "description" : "Converts an input value to a date value.\nA string will only be successfully converted if it’s respecting the format `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`.\nTo convert dates in other formats, use <>.", "note" : "Note that when converting from nanosecond resolution to millisecond resolution with this function, the nanosecond date is truncated, not rounded.", "signatures" : [ { diff --git a/docs/reference/esql/functions/kibana/definition/to_degrees.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_degrees.json similarity index 92% rename from docs/reference/esql/functions/kibana/definition/to_degrees.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_degrees.json index 7b1cc51809704..53ade3f4d3f4b 100644 --- a/docs/reference/esql/functions/kibana/definition/to_degrees.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_degrees.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_degrees", "description" : "Converts a number in radians to degrees.", diff --git a/docs/reference/esql/functions/kibana/definition/to_double.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_double.json similarity index 95% rename from docs/reference/esql/functions/kibana/definition/to_double.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_double.json index 09d5341a62a1d..7780d35e5f6f2 100644 --- a/docs/reference/esql/functions/kibana/definition/to_double.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_double.json @@ -1,8 +1,8 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_double", - "description" : "Converts an input value to a double value. If the input parameter is of a date type,\nits value will be interpreted as milliseconds since the Unix epoch,\nconverted to double. Boolean *true* will be converted to double *1.0*, *false* to *0.0*.", + "description" : "Converts an input value to a double value. If the input parameter is of a date type,\nits value will be interpreted as milliseconds since the Unix epoch,\nconverted to double. Boolean `true` will be converted to double `1.0`, `false` to `0.0`.", "signatures" : [ { "params" : [ diff --git a/docs/reference/esql/functions/kibana/definition/to_geopoint.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_geopoint.json similarity index 91% rename from docs/reference/esql/functions/kibana/definition/to_geopoint.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_geopoint.json index 2c465fcfc2f8d..86d905b1d2235 100644 --- a/docs/reference/esql/functions/kibana/definition/to_geopoint.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_geopoint.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_geopoint", "description" : "Converts an input value to a `geo_point` value.\nA string will only be successfully converted if it respects WKT Point format.", diff --git a/docs/reference/esql/functions/kibana/definition/to_geoshape.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_geoshape.json similarity index 92% rename from docs/reference/esql/functions/kibana/definition/to_geoshape.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_geoshape.json index dc05f12e6ee3e..4379222f8b308 100644 --- a/docs/reference/esql/functions/kibana/definition/to_geoshape.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_geoshape.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_geoshape", "description" : "Converts an input value to a `geo_shape` value.\nA string will only be successfully converted if it respects WKT format.", diff --git a/docs/reference/esql/functions/kibana/definition/to_integer.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_integer.json similarity index 94% rename from docs/reference/esql/functions/kibana/definition/to_integer.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_integer.json index 0228d6baaf507..fdf3c073fed6b 100644 --- a/docs/reference/esql/functions/kibana/definition/to_integer.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_integer.json @@ -1,8 +1,8 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_integer", - "description" : "Converts an input value to an integer value.\nIf the input parameter is of a date type, its value will be interpreted as milliseconds\nsince the Unix epoch, converted to integer.\nBoolean *true* will be converted to integer *1*, *false* to *0*.", + "description" : "Converts an input value to an integer value.\nIf the input parameter is of a date type, its value will be interpreted as milliseconds\nsince the Unix epoch, converted to integer.\nBoolean `true` will be converted to integer `1`, `false` to `0`.", "signatures" : [ { "params" : [ diff --git a/docs/reference/esql/functions/kibana/definition/to_ip.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_ip.json similarity index 90% rename from docs/reference/esql/functions/kibana/definition/to_ip.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_ip.json index 4ec424442c2c1..50fbcd339e26f 100644 --- a/docs/reference/esql/functions/kibana/definition/to_ip.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_ip.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_ip", "description" : "Converts an input string to an IP value.", diff --git a/docs/reference/esql/functions/kibana/definition/to_long.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_long.json similarity index 95% rename from docs/reference/esql/functions/kibana/definition/to_long.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_long.json index 5cd920092473f..05b2682bb364a 100644 --- a/docs/reference/esql/functions/kibana/definition/to_long.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_long.json @@ -1,8 +1,8 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_long", - "description" : "Converts an input value to a long value. If the input parameter is of a date type,\nits value will be interpreted as milliseconds since the Unix epoch, converted to long.\nBoolean *true* will be converted to long *1*, *false* to *0*.", + "description" : "Converts an input value to a long value. If the input parameter is of a date type,\nits value will be interpreted as milliseconds since the Unix epoch, converted to long.\nBoolean `true` will be converted to long `1`, `false` to `0`.", "signatures" : [ { "params" : [ diff --git a/docs/reference/esql/functions/kibana/definition/to_lower.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_lower.json similarity index 87% rename from docs/reference/esql/functions/kibana/definition/to_lower.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_lower.json index 22fd8f4fc1b11..1b77709586a59 100644 --- a/docs/reference/esql/functions/kibana/definition/to_lower.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_lower.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_lower", "description" : "Returns a new string representing the input string converted to lower case.", diff --git a/docs/reference/esql/functions/kibana/definition/to_radians.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_radians.json similarity index 92% rename from docs/reference/esql/functions/kibana/definition/to_radians.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_radians.json index 638ef8ec13e8c..ad5f80fbc3a0f 100644 --- a/docs/reference/esql/functions/kibana/definition/to_radians.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_radians.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_radians", "description" : "Converts a number in degrees to radians.", diff --git a/docs/reference/esql/functions/kibana/definition/to_string.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_string.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/to_string.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_string.json index 40e9588b03f85..4dccefb59c436 100644 --- a/docs/reference/esql/functions/kibana/definition/to_string.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_string.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_string", "description" : "Converts an input value into a string.", diff --git a/docs/reference/esql/functions/kibana/definition/to_timeduration.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_timeduration.json similarity index 90% rename from docs/reference/esql/functions/kibana/definition/to_timeduration.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_timeduration.json index 923aa2024f335..314fe7460393d 100644 --- a/docs/reference/esql/functions/kibana/definition/to_timeduration.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_timeduration.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_timeduration", "description" : "Converts an input value into a `time_duration` value.", diff --git a/docs/reference/esql/functions/kibana/definition/to_unsigned_long.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_unsigned_long.json similarity index 93% rename from docs/reference/esql/functions/kibana/definition/to_unsigned_long.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_unsigned_long.json index f7725311b298a..0d5483fc80e5b 100644 --- a/docs/reference/esql/functions/kibana/definition/to_unsigned_long.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_unsigned_long.json @@ -1,8 +1,8 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_unsigned_long", - "description" : "Converts an input value to an unsigned long value. If the input parameter is of a date type,\nits value will be interpreted as milliseconds since the Unix epoch, converted to unsigned long.\nBoolean *true* will be converted to unsigned long *1*, *false* to *0*.", + "description" : "Converts an input value to an unsigned long value. If the input parameter is of a date type,\nits value will be interpreted as milliseconds since the Unix epoch, converted to unsigned long.\nBoolean `true` will be converted to unsigned long `1`, `false` to `0`.", "signatures" : [ { "params" : [ diff --git a/docs/reference/esql/functions/kibana/definition/to_upper.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_upper.json similarity index 87% rename from docs/reference/esql/functions/kibana/definition/to_upper.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_upper.json index ac0494b1fb9ec..efd6885ad350a 100644 --- a/docs/reference/esql/functions/kibana/definition/to_upper.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_upper.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_upper", "description" : "Returns a new string representing the input string converted to upper case.", diff --git a/docs/reference/esql/functions/kibana/definition/to_version.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_version.json similarity index 90% rename from docs/reference/esql/functions/kibana/definition/to_version.json rename to docs/reference/query-languages/esql/kibana/definition/functions/to_version.json index 41ad00dc20c9e..b72cd2901df53 100644 --- a/docs/reference/esql/functions/kibana/definition/to_version.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_version.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "to_version", "description" : "Converts an input string to a version value.", diff --git a/docs/reference/esql/functions/kibana/definition/top.json b/docs/reference/query-languages/esql/kibana/definition/functions/top.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/top.json rename to docs/reference/query-languages/esql/kibana/definition/functions/top.json index 82bd80636152c..adc1daff65856 100644 --- a/docs/reference/esql/functions/kibana/definition/top.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/top.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "agg", "name" : "top", "description" : "Collects the top values for a field. Includes repeated values.", diff --git a/docs/reference/esql/functions/kibana/definition/trim.json b/docs/reference/query-languages/esql/kibana/definition/functions/trim.json similarity index 87% rename from docs/reference/esql/functions/kibana/definition/trim.json rename to docs/reference/query-languages/esql/kibana/definition/functions/trim.json index eb72d5d041d0f..1003a6bc1d7f1 100644 --- a/docs/reference/esql/functions/kibana/definition/trim.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/trim.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "scalar", "name" : "trim", "description" : "Removes leading and trailing whitespaces from a string.", diff --git a/docs/reference/esql/functions/kibana/definition/values.json b/docs/reference/query-languages/esql/kibana/definition/functions/values.json similarity index 93% rename from docs/reference/esql/functions/kibana/definition/values.json rename to docs/reference/query-languages/esql/kibana/definition/functions/values.json index 0ac74c61cf73d..7150375988188 100644 --- a/docs/reference/esql/functions/kibana/definition/values.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/values.json @@ -1,8 +1,8 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "agg", "name" : "values", - "description" : "Returns all values in a group as a multivalued field. The order of the returned values isn't guaranteed. If you need the values returned in order use <>.", + "description" : "Returns all values in a group as a multivalued field. The order of the returned values isn’t guaranteed. If you need the values returned in order use <>.", "signatures" : [ { "params" : [ diff --git a/docs/reference/esql/functions/kibana/definition/weighted_avg.json b/docs/reference/query-languages/esql/kibana/definition/functions/weighted_avg.json similarity index 96% rename from docs/reference/esql/functions/kibana/definition/weighted_avg.json rename to docs/reference/query-languages/esql/kibana/definition/functions/weighted_avg.json index a14af5345758e..6b0e8bb687df7 100644 --- a/docs/reference/esql/functions/kibana/definition/weighted_avg.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/weighted_avg.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "agg", "name" : "weighted_avg", "description" : "The weighted average of a numeric expression.", diff --git a/docs/reference/esql/functions/kibana/definition/add.json b/docs/reference/query-languages/esql/kibana/definition/operators/add.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/add.json rename to docs/reference/query-languages/esql/kibana/definition/operators/add.json index e362f76d3d66c..dbf28679d196e 100644 --- a/docs/reference/esql/functions/kibana/definition/add.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/add.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", "operator" : "+", "name" : "add", diff --git a/docs/reference/esql/functions/kibana/definition/div.json b/docs/reference/query-languages/esql/kibana/definition/operators/div.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/div.json rename to docs/reference/query-languages/esql/kibana/definition/operators/div.json index 0ff7d7f413f7e..93ddd93f973af 100644 --- a/docs/reference/esql/functions/kibana/definition/div.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/div.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", "operator" : "/", "name" : "div", diff --git a/docs/reference/esql/functions/kibana/definition/equals.json b/docs/reference/query-languages/esql/kibana/definition/operators/equals.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/equals.json rename to docs/reference/query-languages/esql/kibana/definition/operators/equals.json index 035adb826107e..33735e3379eba 100644 --- a/docs/reference/esql/functions/kibana/definition/equals.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/equals.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", "operator" : "==", "name" : "equals", diff --git a/docs/reference/esql/functions/kibana/definition/greater_than.json b/docs/reference/query-languages/esql/kibana/definition/operators/greater_than.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/greater_than.json rename to docs/reference/query-languages/esql/kibana/definition/operators/greater_than.json index 3f8be68f76cae..3fa7c689a96f1 100644 --- a/docs/reference/esql/functions/kibana/definition/greater_than.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/greater_than.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", "operator" : ">", "name" : "greater_than", diff --git a/docs/reference/esql/functions/kibana/definition/greater_than_or_equal.json b/docs/reference/query-languages/esql/kibana/definition/operators/greater_than_or_equal.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/greater_than_or_equal.json rename to docs/reference/query-languages/esql/kibana/definition/operators/greater_than_or_equal.json index 8f68e2af02073..1de820d71480e 100644 --- a/docs/reference/esql/functions/kibana/definition/greater_than_or_equal.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/greater_than_or_equal.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", "operator" : ">=", "name" : "greater_than_or_equal", diff --git a/docs/reference/esql/functions/kibana/definition/in.json b/docs/reference/query-languages/esql/kibana/definition/operators/in.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/in.json rename to docs/reference/query-languages/esql/kibana/definition/operators/in.json index fa041e79df451..adadcb8a6e293 100644 --- a/docs/reference/esql/functions/kibana/definition/in.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/in.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", "operator" : "IN", "name" : "in", diff --git a/docs/reference/esql/functions/kibana/definition/less_than.json b/docs/reference/query-languages/esql/kibana/definition/operators/less_than.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/less_than.json rename to docs/reference/query-languages/esql/kibana/definition/operators/less_than.json index 1572b34534ac2..eaefe5a16ebbd 100644 --- a/docs/reference/esql/functions/kibana/definition/less_than.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/less_than.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", "operator" : "<", "name" : "less_than", diff --git a/docs/reference/esql/functions/kibana/definition/less_than_or_equal.json b/docs/reference/query-languages/esql/kibana/definition/operators/less_than_or_equal.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/less_than_or_equal.json rename to docs/reference/query-languages/esql/kibana/definition/operators/less_than_or_equal.json index 62fd3d69fe143..da354e5e2efdb 100644 --- a/docs/reference/esql/functions/kibana/definition/less_than_or_equal.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/less_than_or_equal.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", "operator" : "<=", "name" : "less_than_or_equal", diff --git a/docs/reference/esql/functions/kibana/definition/like.json b/docs/reference/query-languages/esql/kibana/definition/operators/like.json similarity index 91% rename from docs/reference/esql/functions/kibana/definition/like.json rename to docs/reference/query-languages/esql/kibana/definition/operators/like.json index 4a26dca276696..1e77883eb4948 100644 --- a/docs/reference/esql/functions/kibana/definition/like.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/like.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", "operator" : "LIKE", "name" : "like", diff --git a/docs/reference/esql/functions/kibana/definition/match_operator.json b/docs/reference/query-languages/esql/kibana/definition/operators/match_operator.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/match_operator.json rename to docs/reference/query-languages/esql/kibana/definition/operators/match_operator.json index 98f1a8d73d35e..9c47c56d0a7a3 100644 --- a/docs/reference/esql/functions/kibana/definition/match_operator.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/match_operator.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", "operator" : ":", "name" : "match_operator", @@ -529,7 +529,7 @@ } ], "examples" : [ - "FROM books \n| WHERE MATCH(author, \"Faulkner\")\n| KEEP book_no, author \n| SORT book_no \n| LIMIT 5" + "FROM books\n| WHERE MATCH(author, \"Faulkner\")\n| KEEP book_no, author\n| SORT book_no\n| LIMIT 5" ], "preview" : true, "snapshot_only" : false diff --git a/docs/reference/esql/functions/kibana/definition/mod.json b/docs/reference/query-languages/esql/kibana/definition/operators/mod.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/mod.json rename to docs/reference/query-languages/esql/kibana/definition/operators/mod.json index 194cbdcc4eb9e..69ecc4e40388f 100644 --- a/docs/reference/esql/functions/kibana/definition/mod.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/mod.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", "operator" : "%", "name" : "mod", diff --git a/docs/reference/esql/functions/kibana/definition/mul.json b/docs/reference/query-languages/esql/kibana/definition/operators/mul.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/mul.json rename to docs/reference/query-languages/esql/kibana/definition/operators/mul.json index e62da0a6d0721..163623e03e960 100644 --- a/docs/reference/esql/functions/kibana/definition/mul.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/mul.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", "operator" : "*", "name" : "mul", diff --git a/docs/reference/esql/functions/kibana/definition/neg.json b/docs/reference/query-languages/esql/kibana/definition/operators/neg.json similarity index 92% rename from docs/reference/esql/functions/kibana/definition/neg.json rename to docs/reference/query-languages/esql/kibana/definition/operators/neg.json index 7074ad204d3b0..6b8c450ab9fb7 100644 --- a/docs/reference/esql/functions/kibana/definition/neg.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/neg.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", "operator" : "-", "name" : "neg", diff --git a/docs/reference/esql/functions/kibana/definition/not_in.json b/docs/reference/query-languages/esql/kibana/definition/operators/not in.json similarity index 97% rename from docs/reference/esql/functions/kibana/definition/not_in.json rename to docs/reference/query-languages/esql/kibana/definition/operators/not in.json index 3fa25d793b503..7958e14806bbf 100644 --- a/docs/reference/esql/functions/kibana/definition/not_in.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/not in.json @@ -1,7 +1,7 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", - "operator" : "NOT IN", + "operator" : "not in", "name" : "not_in", "description" : "The `NOT IN` operator allows testing whether a field or expression does *not* equal any element in a list of literals, fields or expressions.", "signatures" : [ diff --git a/docs/reference/esql/functions/kibana/definition/not_like.json b/docs/reference/query-languages/esql/kibana/definition/operators/not like.json similarity index 61% rename from docs/reference/esql/functions/kibana/definition/not_like.json rename to docs/reference/query-languages/esql/kibana/definition/operators/not like.json index bba70d14d7cb7..9aef4aae08acb 100644 --- a/docs/reference/esql/functions/kibana/definition/not_like.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/not like.json @@ -1,9 +1,9 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", - "operator" : "NOT LIKE", + "operator" : "not like", "name" : "not_like", - "description" : "Use `NOT LIKE` to filter data based on string patterns using wildcards. `NOT LIKE`\nusually acts on a field placed on the left-hand side of the operator, but it can\nalso act on a constant (literal) expression. The right-hand side of the operator\nrepresents the pattern.\n\nThe following wildcard characters are supported:\n\n* `*` matches zero or more characters.\n* `?` matches one character.", + "description" : "Use `LIKE` to filter data based on string patterns using wildcards. `LIKE`\nusually acts on a field placed on the left-hand side of the operator, but it can\nalso act on a constant (literal) expression. The right-hand side of the operator\nrepresents the pattern.\n\nThe following wildcard characters are supported:\n\n* `*` matches zero or more characters.\n* `?` matches one character.", "signatures" : [ { "params" : [ diff --git a/docs/reference/esql/functions/kibana/definition/not_rlike.json b/docs/reference/query-languages/esql/kibana/definition/operators/not rlike.json similarity index 65% rename from docs/reference/esql/functions/kibana/definition/not_rlike.json rename to docs/reference/query-languages/esql/kibana/definition/operators/not rlike.json index 09abd5ab567e8..8ef2462be874a 100644 --- a/docs/reference/esql/functions/kibana/definition/not_rlike.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/not rlike.json @@ -1,9 +1,9 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", - "operator" : "NOT RLIKE", + "operator" : "not rlike", "name" : "not_rlike", - "description" : "Use `NOT RLIKE` to filter data based on string patterns using using\n<>. `NOT RLIKE` usually acts on a field placed on\nthe left-hand side of the operator, but it can also act on a constant (literal)\nexpression. The right-hand side of the operator represents the pattern.", + "description" : "Use `RLIKE` to filter data based on string patterns using using\n<>. `RLIKE` usually acts on a field placed on\nthe left-hand side of the operator, but it can also act on a constant (literal)\nexpression. The right-hand side of the operator represents the pattern.", "signatures" : [ { "params" : [ diff --git a/docs/reference/esql/functions/kibana/definition/not_equals.json b/docs/reference/query-languages/esql/kibana/definition/operators/not_equals.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/not_equals.json rename to docs/reference/query-languages/esql/kibana/definition/operators/not_equals.json index 42220168d3b03..c4dddf0268c6b 100644 --- a/docs/reference/esql/functions/kibana/definition/not_equals.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/not_equals.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", "operator" : "!=", "name" : "not_equals", diff --git a/docs/reference/esql/functions/kibana/definition/rlike.json b/docs/reference/query-languages/esql/kibana/definition/operators/rlike.json similarity index 91% rename from docs/reference/esql/functions/kibana/definition/rlike.json rename to docs/reference/query-languages/esql/kibana/definition/operators/rlike.json index 88d6c7d6bb9b2..5d1ddf2cafa24 100644 --- a/docs/reference/esql/functions/kibana/definition/rlike.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/rlike.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", "operator" : "RLIKE", "name" : "rlike", diff --git a/docs/reference/esql/functions/kibana/definition/sub.json b/docs/reference/query-languages/esql/kibana/definition/operators/sub.json similarity index 98% rename from docs/reference/esql/functions/kibana/definition/sub.json rename to docs/reference/query-languages/esql/kibana/definition/operators/sub.json index 4555e12a00dd4..63db4a47dadb2 100644 --- a/docs/reference/esql/functions/kibana/definition/sub.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/sub.json @@ -1,5 +1,5 @@ { - "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "operator", "operator" : "-", "name" : "sub", diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/abs.md b/docs/reference/query-languages/esql/kibana/docs/functions/abs.md new file mode 100644 index 0000000000000..aa3ce9af95076 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/abs.md @@ -0,0 +1,11 @@ + + +### ABS +Returns the absolute value. + +``` +ROW number = -1.0 +| EVAL abs_number = ABS(number) +``` diff --git a/docs/reference/esql/functions/kibana/docs/acos.md b/docs/reference/query-languages/esql/kibana/docs/functions/acos.md similarity index 51% rename from docs/reference/esql/functions/kibana/docs/acos.md rename to docs/reference/query-languages/esql/kibana/docs/functions/acos.md index d9c05875631d9..eaf89ca7562e8 100644 --- a/docs/reference/esql/functions/kibana/docs/acos.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/acos.md @@ -1,5 +1,5 @@ ### ACOS diff --git a/docs/reference/esql/functions/kibana/docs/asin.md b/docs/reference/query-languages/esql/kibana/docs/functions/asin.md similarity index 55% rename from docs/reference/esql/functions/kibana/docs/asin.md rename to docs/reference/query-languages/esql/kibana/docs/functions/asin.md index b26eee366351f..2c6b3a7908732 100644 --- a/docs/reference/esql/functions/kibana/docs/asin.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/asin.md @@ -1,5 +1,5 @@ ### ASIN diff --git a/docs/reference/esql/functions/kibana/docs/atan.md b/docs/reference/query-languages/esql/kibana/docs/functions/atan.md similarity index 56% rename from docs/reference/esql/functions/kibana/docs/atan.md rename to docs/reference/query-languages/esql/kibana/docs/functions/atan.md index 9be6e2dbefd11..34c2af6e29ce0 100644 --- a/docs/reference/esql/functions/kibana/docs/atan.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/atan.md @@ -1,5 +1,5 @@ ### ATAN diff --git a/docs/reference/esql/functions/kibana/docs/atan2.md b/docs/reference/query-languages/esql/kibana/docs/functions/atan2.md similarity index 64% rename from docs/reference/esql/functions/kibana/docs/atan2.md rename to docs/reference/query-languages/esql/kibana/docs/functions/atan2.md index e3129264d6999..f8c5123ca6dd4 100644 --- a/docs/reference/esql/functions/kibana/docs/atan2.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/atan2.md @@ -1,5 +1,5 @@ ### ATAN2 diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/avg.md b/docs/reference/query-languages/esql/kibana/docs/functions/avg.md new file mode 100644 index 0000000000000..f8b386a9a631c --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/avg.md @@ -0,0 +1,11 @@ + + +### AVG +The average of a numeric field. + +``` +FROM employees +| STATS AVG(height) +``` diff --git a/docs/reference/esql/functions/kibana/docs/bit_length.md b/docs/reference/query-languages/esql/kibana/docs/functions/bit_length.md similarity index 70% rename from docs/reference/esql/functions/kibana/docs/bit_length.md rename to docs/reference/query-languages/esql/kibana/docs/functions/bit_length.md index b1d8e24c4de76..2656c92277bef 100644 --- a/docs/reference/esql/functions/kibana/docs/bit_length.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/bit_length.md @@ -1,5 +1,5 @@ ### BIT_LENGTH diff --git a/docs/reference/esql/functions/kibana/docs/bucket.md b/docs/reference/query-languages/esql/kibana/docs/functions/bucket.md similarity index 80% rename from docs/reference/esql/functions/kibana/docs/bucket.md rename to docs/reference/query-languages/esql/kibana/docs/functions/bucket.md index 882e5596f8dac..3837b653df0a4 100644 --- a/docs/reference/esql/functions/kibana/docs/bucket.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/bucket.md @@ -1,5 +1,5 @@ ### BUCKET diff --git a/docs/reference/esql/functions/kibana/docs/byte_length.md b/docs/reference/query-languages/esql/kibana/docs/functions/byte_length.md similarity index 70% rename from docs/reference/esql/functions/kibana/docs/byte_length.md rename to docs/reference/query-languages/esql/kibana/docs/functions/byte_length.md index 9cd4f87c9883b..8db81a761af79 100644 --- a/docs/reference/esql/functions/kibana/docs/byte_length.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/byte_length.md @@ -1,5 +1,5 @@ ### BYTE_LENGTH diff --git a/docs/reference/esql/functions/kibana/docs/case.md b/docs/reference/query-languages/esql/kibana/docs/functions/case.md similarity index 82% rename from docs/reference/esql/functions/kibana/docs/case.md rename to docs/reference/query-languages/esql/kibana/docs/functions/case.md index 8bb31ee972759..497119493439b 100644 --- a/docs/reference/esql/functions/kibana/docs/case.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/case.md @@ -1,5 +1,5 @@ ### CASE diff --git a/docs/reference/esql/functions/kibana/docs/categorize.md b/docs/reference/query-languages/esql/kibana/docs/functions/categorize.md similarity index 60% rename from docs/reference/esql/functions/kibana/docs/categorize.md rename to docs/reference/query-languages/esql/kibana/docs/functions/categorize.md index 80c04b79084e9..b0765767429d0 100644 --- a/docs/reference/esql/functions/kibana/docs/categorize.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/categorize.md @@ -1,5 +1,5 @@ ### CATEGORIZE diff --git a/docs/reference/esql/functions/kibana/docs/cbrt.md b/docs/reference/query-languages/esql/kibana/docs/functions/cbrt.md similarity index 64% rename from docs/reference/esql/functions/kibana/docs/cbrt.md rename to docs/reference/query-languages/esql/kibana/docs/functions/cbrt.md index 50cdad02818e8..b8d0b05271a4c 100644 --- a/docs/reference/esql/functions/kibana/docs/cbrt.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/cbrt.md @@ -1,5 +1,5 @@ ### CBRT diff --git a/docs/reference/esql/functions/kibana/docs/ceil.md b/docs/reference/query-languages/esql/kibana/docs/functions/ceil.md similarity index 68% rename from docs/reference/esql/functions/kibana/docs/ceil.md rename to docs/reference/query-languages/esql/kibana/docs/functions/ceil.md index 7c696cc46bdd1..46a3c244c6ba4 100644 --- a/docs/reference/esql/functions/kibana/docs/ceil.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/ceil.md @@ -1,5 +1,5 @@ ### CEIL diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/cidr_match.md b/docs/reference/query-languages/esql/kibana/docs/functions/cidr_match.md new file mode 100644 index 0000000000000..f8e81019d9685 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/cidr_match.md @@ -0,0 +1,12 @@ + + +### CIDR_MATCH +Returns true if the provided IP is contained in one of the provided CIDR blocks. + +``` +FROM hosts +| WHERE CIDR_MATCH(ip1, "127.0.0.2/32", "127.0.0.3/32") +| KEEP card, host, ip0, ip1 +``` diff --git a/docs/reference/esql/functions/kibana/docs/coalesce.md b/docs/reference/query-languages/esql/kibana/docs/functions/coalesce.md similarity index 60% rename from docs/reference/esql/functions/kibana/docs/coalesce.md rename to docs/reference/query-languages/esql/kibana/docs/functions/coalesce.md index 89cca3f3a286a..050965c68b2d4 100644 --- a/docs/reference/esql/functions/kibana/docs/coalesce.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/coalesce.md @@ -1,5 +1,5 @@ ### COALESCE diff --git a/docs/reference/esql/functions/kibana/docs/concat.md b/docs/reference/query-languages/esql/kibana/docs/functions/concat.md similarity index 58% rename from docs/reference/esql/functions/kibana/docs/concat.md rename to docs/reference/query-languages/esql/kibana/docs/functions/concat.md index 3dcfb62495a15..80af1fb838859 100644 --- a/docs/reference/esql/functions/kibana/docs/concat.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/concat.md @@ -1,5 +1,5 @@ ### CONCAT diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/cos.md b/docs/reference/query-languages/esql/kibana/docs/functions/cos.md new file mode 100644 index 0000000000000..36ea730e08d56 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/cos.md @@ -0,0 +1,11 @@ + + +### COS +Returns the cosine of an angle. + +``` +ROW a=1.8 +| EVAL cos=COS(a) +``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/cosh.md b/docs/reference/query-languages/esql/kibana/docs/functions/cosh.md new file mode 100644 index 0000000000000..30ce89e560efe --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/cosh.md @@ -0,0 +1,11 @@ + + +### COSH +Returns the hyperbolic cosine of a number. + +``` +ROW a=1.8 +| EVAL cosh=COSH(a) +``` diff --git a/docs/reference/esql/functions/kibana/docs/count.md b/docs/reference/query-languages/esql/kibana/docs/functions/count.md similarity index 50% rename from docs/reference/esql/functions/kibana/docs/count.md rename to docs/reference/query-languages/esql/kibana/docs/functions/count.md index dc9c356a847ed..2602476e2d1d6 100644 --- a/docs/reference/esql/functions/kibana/docs/count.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/count.md @@ -1,5 +1,5 @@ ### COUNT diff --git a/docs/reference/esql/functions/kibana/docs/count_distinct.md b/docs/reference/query-languages/esql/kibana/docs/functions/count_distinct.md similarity index 56% rename from docs/reference/esql/functions/kibana/docs/count_distinct.md rename to docs/reference/query-languages/esql/kibana/docs/functions/count_distinct.md index a6b451bf9d38d..8fbc4bbfa2dfd 100644 --- a/docs/reference/esql/functions/kibana/docs/count_distinct.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/count_distinct.md @@ -1,5 +1,5 @@ ### COUNT_DISTINCT diff --git a/docs/reference/esql/functions/kibana/docs/date_diff.md b/docs/reference/query-languages/esql/kibana/docs/functions/date_diff.md similarity index 76% rename from docs/reference/esql/functions/kibana/docs/date_diff.md rename to docs/reference/query-languages/esql/kibana/docs/functions/date_diff.md index 034763ca2206e..750e89e3415b0 100644 --- a/docs/reference/esql/functions/kibana/docs/date_diff.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/date_diff.md @@ -1,5 +1,5 @@ ### DATE_DIFF diff --git a/docs/reference/esql/functions/kibana/docs/date_extract.md b/docs/reference/query-languages/esql/kibana/docs/functions/date_extract.md similarity index 61% rename from docs/reference/esql/functions/kibana/docs/date_extract.md rename to docs/reference/query-languages/esql/kibana/docs/functions/date_extract.md index bb6773a2f55d0..d755dcd1345e3 100644 --- a/docs/reference/esql/functions/kibana/docs/date_extract.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/date_extract.md @@ -1,5 +1,5 @@ ### DATE_EXTRACT diff --git a/docs/reference/esql/functions/kibana/docs/date_format.md b/docs/reference/query-languages/esql/kibana/docs/functions/date_format.md similarity index 64% rename from docs/reference/esql/functions/kibana/docs/date_format.md rename to docs/reference/query-languages/esql/kibana/docs/functions/date_format.md index 7c75f8eb566da..32732ed077498 100644 --- a/docs/reference/esql/functions/kibana/docs/date_format.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/date_format.md @@ -1,5 +1,5 @@ ### DATE_FORMAT diff --git a/docs/reference/esql/functions/kibana/docs/date_parse.md b/docs/reference/query-languages/esql/kibana/docs/functions/date_parse.md similarity index 65% rename from docs/reference/esql/functions/kibana/docs/date_parse.md rename to docs/reference/query-languages/esql/kibana/docs/functions/date_parse.md index c804767e8d756..665d46bdfb8b8 100644 --- a/docs/reference/esql/functions/kibana/docs/date_parse.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/date_parse.md @@ -1,5 +1,5 @@ ### DATE_PARSE diff --git a/docs/reference/esql/functions/kibana/docs/date_trunc.md b/docs/reference/query-languages/esql/kibana/docs/functions/date_trunc.md similarity index 61% rename from docs/reference/esql/functions/kibana/docs/date_trunc.md rename to docs/reference/query-languages/esql/kibana/docs/functions/date_trunc.md index 6aa81ebbac3c3..4bcc003d21257 100644 --- a/docs/reference/esql/functions/kibana/docs/date_trunc.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/date_trunc.md @@ -1,5 +1,5 @@ ### DATE_TRUNC diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/e.md b/docs/reference/query-languages/esql/kibana/docs/functions/e.md new file mode 100644 index 0000000000000..cd7c7abf751e9 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/e.md @@ -0,0 +1,10 @@ + + +### E +Returns Euler’s number. + +``` +ROW E() +``` diff --git a/docs/reference/esql/functions/kibana/docs/ends_with.md b/docs/reference/query-languages/esql/kibana/docs/functions/ends_with.md similarity index 62% rename from docs/reference/esql/functions/kibana/docs/ends_with.md rename to docs/reference/query-languages/esql/kibana/docs/functions/ends_with.md index 51e0ad1faa5ab..28534d340cb75 100644 --- a/docs/reference/esql/functions/kibana/docs/ends_with.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/ends_with.md @@ -1,5 +1,5 @@ ### ENDS_WITH diff --git a/docs/reference/esql/functions/kibana/docs/exp.md b/docs/reference/query-languages/esql/kibana/docs/functions/exp.md similarity index 51% rename from docs/reference/esql/functions/kibana/docs/exp.md rename to docs/reference/query-languages/esql/kibana/docs/functions/exp.md index 0eb6bef5f4247..59e42eed216af 100644 --- a/docs/reference/esql/functions/kibana/docs/exp.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/exp.md @@ -1,5 +1,5 @@ ### EXP diff --git a/docs/reference/esql/functions/kibana/docs/floor.md b/docs/reference/query-languages/esql/kibana/docs/functions/floor.md similarity index 69% rename from docs/reference/esql/functions/kibana/docs/floor.md rename to docs/reference/query-languages/esql/kibana/docs/functions/floor.md index 1f94e0eb74eb6..be9349085e1fb 100644 --- a/docs/reference/esql/functions/kibana/docs/floor.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/floor.md @@ -1,5 +1,5 @@ ### FLOOR diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/from_base64.md b/docs/reference/query-languages/esql/kibana/docs/functions/from_base64.md new file mode 100644 index 0000000000000..68a1d0ede85f6 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/from_base64.md @@ -0,0 +1,11 @@ + + +### FROM_BASE64 +Decode a base64 string. + +``` +row a = "ZWxhc3RpYw==" +| eval d = from_base64(a) +``` diff --git a/docs/reference/esql/functions/kibana/docs/greatest.md b/docs/reference/query-languages/esql/kibana/docs/functions/greatest.md similarity index 77% rename from docs/reference/esql/functions/kibana/docs/greatest.md rename to docs/reference/query-languages/esql/kibana/docs/functions/greatest.md index 4b3b4027381f8..458aabbaeec95 100644 --- a/docs/reference/esql/functions/kibana/docs/greatest.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/greatest.md @@ -1,5 +1,5 @@ ### GREATEST diff --git a/docs/reference/esql/functions/kibana/docs/hash.md b/docs/reference/query-languages/esql/kibana/docs/functions/hash.md similarity index 59% rename from docs/reference/esql/functions/kibana/docs/hash.md rename to docs/reference/query-languages/esql/kibana/docs/functions/hash.md index 4e937778ba67a..9c391b5d7bbf8 100644 --- a/docs/reference/esql/functions/kibana/docs/hash.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/hash.md @@ -1,13 +1,13 @@ ### HASH Computes the hash of the input using various algorithms such as MD5, SHA, SHA-224, SHA-256, SHA-384, SHA-512. ``` -FROM sample_data +FROM sample_data | WHERE message != "Connection error" -| EVAL md5 = hash("md5", message), sha256 = hash("sha256", message) -| KEEP message, md5, sha256; +| EVAL md5 = hash("md5", message), sha256 = hash("sha256", message) +| KEEP message, md5, sha256 ``` diff --git a/docs/reference/esql/functions/kibana/docs/hypot.md b/docs/reference/query-languages/esql/kibana/docs/functions/hypot.md similarity index 66% rename from docs/reference/esql/functions/kibana/docs/hypot.md rename to docs/reference/query-languages/esql/kibana/docs/functions/hypot.md index f0cbea6b88e55..4dc20ac965eec 100644 --- a/docs/reference/esql/functions/kibana/docs/hypot.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/hypot.md @@ -1,5 +1,5 @@ ### HYPOT diff --git a/docs/reference/esql/functions/kibana/docs/ip_prefix.md b/docs/reference/query-languages/esql/kibana/docs/functions/ip_prefix.md similarity index 66% rename from docs/reference/esql/functions/kibana/docs/ip_prefix.md rename to docs/reference/query-languages/esql/kibana/docs/functions/ip_prefix.md index 5c0009528bb68..7b6110d03e093 100644 --- a/docs/reference/esql/functions/kibana/docs/ip_prefix.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/ip_prefix.md @@ -1,5 +1,5 @@ ### IP_PREFIX diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/kql.md b/docs/reference/query-languages/esql/kibana/docs/functions/kql.md new file mode 100644 index 0000000000000..7906cfa920fe1 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/kql.md @@ -0,0 +1,14 @@ + + +### KQL +Performs a KQL query. Returns true if the provided KQL query string matches the row. + +``` +FROM books +| WHERE KQL("author: Faulkner") +| KEEP book_no, author +| SORT book_no +| LIMIT 5 +``` diff --git a/docs/reference/esql/functions/kibana/docs/least.md b/docs/reference/query-languages/esql/kibana/docs/functions/least.md similarity index 65% rename from docs/reference/esql/functions/kibana/docs/least.md rename to docs/reference/query-languages/esql/kibana/docs/functions/least.md index 7bbbcf79bc374..0916f530fafcc 100644 --- a/docs/reference/esql/functions/kibana/docs/least.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/least.md @@ -1,5 +1,5 @@ ### LEAST diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/left.md b/docs/reference/query-languages/esql/kibana/docs/functions/left.md new file mode 100644 index 0000000000000..1e17bc6dd8609 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/left.md @@ -0,0 +1,14 @@ + + +### LEFT +Returns the substring that extracts *length* chars from *string* starting from the left. + +``` +FROM employees +| KEEP last_name +| EVAL left = LEFT(last_name, 3) +| SORT last_name ASC +| LIMIT 5 +``` diff --git a/docs/reference/esql/functions/kibana/docs/length.md b/docs/reference/query-languages/esql/kibana/docs/functions/length.md similarity index 67% rename from docs/reference/esql/functions/kibana/docs/length.md rename to docs/reference/query-languages/esql/kibana/docs/functions/length.md index aed76ee14cedb..9929c19f3b642 100644 --- a/docs/reference/esql/functions/kibana/docs/length.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/length.md @@ -1,5 +1,5 @@ ### LENGTH diff --git a/docs/reference/esql/functions/kibana/docs/locate.md b/docs/reference/query-languages/esql/kibana/docs/functions/locate.md similarity index 69% rename from docs/reference/esql/functions/kibana/docs/locate.md rename to docs/reference/query-languages/esql/kibana/docs/functions/locate.md index 412832e9b1587..6a23d7620769c 100644 --- a/docs/reference/esql/functions/kibana/docs/locate.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/locate.md @@ -1,5 +1,5 @@ ### LOCATE diff --git a/docs/reference/esql/functions/kibana/docs/log.md b/docs/reference/query-languages/esql/kibana/docs/functions/log.md similarity index 71% rename from docs/reference/esql/functions/kibana/docs/log.md rename to docs/reference/query-languages/esql/kibana/docs/functions/log.md index 7ac136d31f720..996c8af30dcfa 100644 --- a/docs/reference/esql/functions/kibana/docs/log.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/log.md @@ -1,5 +1,5 @@ ### LOG diff --git a/docs/reference/esql/functions/kibana/docs/log10.md b/docs/reference/query-languages/esql/kibana/docs/functions/log10.md similarity index 64% rename from docs/reference/esql/functions/kibana/docs/log10.md rename to docs/reference/query-languages/esql/kibana/docs/functions/log10.md index 23ec30643e51e..70b2bf9f2a749 100644 --- a/docs/reference/esql/functions/kibana/docs/log10.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/log10.md @@ -1,5 +1,5 @@ ### LOG10 @@ -8,6 +8,6 @@ Returns the logarithm of a value to base 10. The input can be any numeric value, Logs of 0 and negative numbers return `null` as well as a warning. ``` -ROW d = 1000.0 +ROW d = 1000.0 | EVAL s = LOG10(d) ``` diff --git a/docs/reference/esql/functions/kibana/docs/ltrim.md b/docs/reference/query-languages/esql/kibana/docs/functions/ltrim.md similarity index 69% rename from docs/reference/esql/functions/kibana/docs/ltrim.md rename to docs/reference/query-languages/esql/kibana/docs/functions/ltrim.md index 11617f9ee3073..5f2647169c157 100644 --- a/docs/reference/esql/functions/kibana/docs/ltrim.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/ltrim.md @@ -1,5 +1,5 @@ ### LTRIM diff --git a/docs/reference/esql/functions/kibana/docs/match.md b/docs/reference/query-languages/esql/kibana/docs/functions/match.md similarity index 82% rename from docs/reference/esql/functions/kibana/docs/match.md rename to docs/reference/query-languages/esql/kibana/docs/functions/match.md index 72132533ea82d..4d28c31459bab 100644 --- a/docs/reference/esql/functions/kibana/docs/match.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/match.md @@ -1,5 +1,5 @@ ### MATCH @@ -17,9 +17,9 @@ For a simplified syntax, you can use the < `MATCH` returns true if the provided query matches the row. ``` -FROM books +FROM books | WHERE MATCH(author, "Faulkner") -| KEEP book_no, author -| SORT book_no +| KEEP book_no, author +| SORT book_no | LIMIT 5 ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/max.md b/docs/reference/query-languages/esql/kibana/docs/functions/max.md new file mode 100644 index 0000000000000..d732703698493 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/max.md @@ -0,0 +1,11 @@ + + +### MAX +The maximum value of a field. + +``` +FROM employees +| STATS MAX(languages) +``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/md5.md b/docs/reference/query-languages/esql/kibana/docs/functions/md5.md new file mode 100644 index 0000000000000..4e41a98717e6f --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/md5.md @@ -0,0 +1,13 @@ + + +### MD5 +Computes the MD5 hash of the input. + +``` +FROM sample_data +| WHERE message != "Connection error" +| EVAL md5 = md5(message) +| KEEP message, md5 +``` diff --git a/docs/reference/esql/functions/kibana/docs/median.md b/docs/reference/query-languages/esql/kibana/docs/functions/median.md similarity index 73% rename from docs/reference/esql/functions/kibana/docs/median.md rename to docs/reference/query-languages/esql/kibana/docs/functions/median.md index 7a4370b4d2551..2dd6d5f87b4a7 100644 --- a/docs/reference/esql/functions/kibana/docs/median.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/median.md @@ -1,5 +1,5 @@ ### MEDIAN diff --git a/docs/reference/esql/functions/kibana/docs/median_absolute_deviation.md b/docs/reference/query-languages/esql/kibana/docs/functions/median_absolute_deviation.md similarity index 61% rename from docs/reference/esql/functions/kibana/docs/median_absolute_deviation.md rename to docs/reference/query-languages/esql/kibana/docs/functions/median_absolute_deviation.md index 8db113deb2c49..3a6fc62e886c0 100644 --- a/docs/reference/esql/functions/kibana/docs/median_absolute_deviation.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/median_absolute_deviation.md @@ -1,11 +1,11 @@ ### MEDIAN_ABSOLUTE_DEVIATION 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|)`. +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|)`. ``` FROM employees diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/min.md b/docs/reference/query-languages/esql/kibana/docs/functions/min.md new file mode 100644 index 0000000000000..4e357ae1a555e --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/min.md @@ -0,0 +1,11 @@ + + +### MIN +The minimum value of a field. + +``` +FROM employees +| STATS MIN(languages) +``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_append.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_append.md new file mode 100644 index 0000000000000..d83b12a5c78a4 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_append.md @@ -0,0 +1,7 @@ + + +### MV_APPEND +Concatenates values of two multi-value fields. + diff --git a/docs/reference/esql/functions/kibana/docs/mv_avg.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_avg.md similarity index 60% rename from docs/reference/esql/functions/kibana/docs/mv_avg.md rename to docs/reference/query-languages/esql/kibana/docs/functions/mv_avg.md index c3d7e5423f724..29c19162432a2 100644 --- a/docs/reference/esql/functions/kibana/docs/mv_avg.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_avg.md @@ -1,5 +1,5 @@ ### MV_AVG diff --git a/docs/reference/esql/functions/kibana/docs/mv_concat.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_concat.md similarity index 66% rename from docs/reference/esql/functions/kibana/docs/mv_concat.md rename to docs/reference/query-languages/esql/kibana/docs/functions/mv_concat.md index b6abffbb39a35..ca38a67b81d00 100644 --- a/docs/reference/esql/functions/kibana/docs/mv_concat.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_concat.md @@ -1,5 +1,5 @@ ### MV_CONCAT diff --git a/docs/reference/esql/functions/kibana/docs/mv_count.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_count.md similarity index 63% rename from docs/reference/esql/functions/kibana/docs/mv_count.md rename to docs/reference/query-languages/esql/kibana/docs/functions/mv_count.md index a4c4880c99d17..619606cff6b36 100644 --- a/docs/reference/esql/functions/kibana/docs/mv_count.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_count.md @@ -1,5 +1,5 @@ ### MV_COUNT diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_dedupe.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_dedupe.md new file mode 100644 index 0000000000000..b2b08a17ee8bd --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_dedupe.md @@ -0,0 +1,12 @@ + + +### MV_DEDUPE +Remove duplicate values from a multivalued field. + +``` +ROW a=["foo", "foo", "bar", "foo"] +| EVAL dedupe_a = MV_DEDUPE(a) +``` +Note: `MV_DEDUPE` may, but won’t always, sort the values in the column. diff --git a/docs/reference/esql/functions/kibana/docs/mv_first.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_first.md similarity index 72% rename from docs/reference/esql/functions/kibana/docs/mv_first.md rename to docs/reference/query-languages/esql/kibana/docs/functions/mv_first.md index c50ed7d764020..7f9fbc9148cbc 100644 --- a/docs/reference/esql/functions/kibana/docs/mv_first.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_first.md @@ -1,5 +1,5 @@ ### MV_FIRST diff --git a/docs/reference/esql/functions/kibana/docs/mv_last.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_last.md similarity index 72% rename from docs/reference/esql/functions/kibana/docs/mv_last.md rename to docs/reference/query-languages/esql/kibana/docs/functions/mv_last.md index eeefd929c1359..9719fdc53af64 100644 --- a/docs/reference/esql/functions/kibana/docs/mv_last.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_last.md @@ -1,5 +1,5 @@ ### MV_LAST diff --git a/docs/reference/esql/functions/kibana/docs/mv_max.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_max.md similarity index 58% rename from docs/reference/esql/functions/kibana/docs/mv_max.md rename to docs/reference/query-languages/esql/kibana/docs/functions/mv_max.md index 90cf01de43cb6..c9631ed20bb17 100644 --- a/docs/reference/esql/functions/kibana/docs/mv_max.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_max.md @@ -1,5 +1,5 @@ ### MV_MAX diff --git a/docs/reference/esql/functions/kibana/docs/mv_median.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_median.md similarity index 59% rename from docs/reference/esql/functions/kibana/docs/mv_median.md rename to docs/reference/query-languages/esql/kibana/docs/functions/mv_median.md index 149e6bbd50c49..e8d00213f461c 100644 --- a/docs/reference/esql/functions/kibana/docs/mv_median.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_median.md @@ -1,5 +1,5 @@ ### MV_MEDIAN diff --git a/docs/reference/esql/functions/kibana/docs/mv_median_absolute_deviation.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_median_absolute_deviation.md similarity index 60% rename from docs/reference/esql/functions/kibana/docs/mv_median_absolute_deviation.md rename to docs/reference/query-languages/esql/kibana/docs/functions/mv_median_absolute_deviation.md index 191ce3ce60ae1..9cdda19127c7c 100644 --- a/docs/reference/esql/functions/kibana/docs/mv_median_absolute_deviation.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_median_absolute_deviation.md @@ -1,11 +1,11 @@ ### MV_MEDIAN_ABSOLUTE_DEVIATION Converts a multivalued field into a single valued field containing the median absolute 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|)`. +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|)`. ``` ROW values = [0, 2, 5, 6] diff --git a/docs/reference/esql/functions/kibana/docs/mv_min.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_min.md similarity index 58% rename from docs/reference/esql/functions/kibana/docs/mv_min.md rename to docs/reference/query-languages/esql/kibana/docs/functions/mv_min.md index e039ffee353b2..fa659f8086c8e 100644 --- a/docs/reference/esql/functions/kibana/docs/mv_min.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_min.md @@ -1,5 +1,5 @@ ### MV_MIN diff --git a/docs/reference/esql/functions/kibana/docs/mv_percentile.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_percentile.md similarity index 70% rename from docs/reference/esql/functions/kibana/docs/mv_percentile.md rename to docs/reference/query-languages/esql/kibana/docs/functions/mv_percentile.md index 560a0aefa1dc3..202ca5f718874 100644 --- a/docs/reference/esql/functions/kibana/docs/mv_percentile.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_percentile.md @@ -1,5 +1,5 @@ ### MV_PERCENTILE diff --git a/docs/reference/esql/functions/kibana/docs/mv_pseries_weighted_sum.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_pseries_weighted_sum.md similarity index 73% rename from docs/reference/esql/functions/kibana/docs/mv_pseries_weighted_sum.md rename to docs/reference/query-languages/esql/kibana/docs/functions/mv_pseries_weighted_sum.md index fbeb310449b9b..e8e3a1d464e0c 100644 --- a/docs/reference/esql/functions/kibana/docs/mv_pseries_weighted_sum.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_pseries_weighted_sum.md @@ -1,5 +1,5 @@ ### MV_PSERIES_WEIGHTED_SUM diff --git a/docs/reference/esql/functions/kibana/docs/mv_slice.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_slice.md similarity index 73% rename from docs/reference/esql/functions/kibana/docs/mv_slice.md rename to docs/reference/query-languages/esql/kibana/docs/functions/mv_slice.md index bba7a219960ef..ee0c239de8074 100644 --- a/docs/reference/esql/functions/kibana/docs/mv_slice.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_slice.md @@ -1,5 +1,5 @@ ### MV_SLICE diff --git a/docs/reference/esql/functions/kibana/docs/mv_sort.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_sort.md similarity index 57% rename from docs/reference/esql/functions/kibana/docs/mv_sort.md rename to docs/reference/query-languages/esql/kibana/docs/functions/mv_sort.md index 2dee9c63c09c1..fe3056cb33ed2 100644 --- a/docs/reference/esql/functions/kibana/docs/mv_sort.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_sort.md @@ -1,5 +1,5 @@ ### MV_SORT diff --git a/docs/reference/esql/functions/kibana/docs/mv_sum.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_sum.md similarity index 59% rename from docs/reference/esql/functions/kibana/docs/mv_sum.md rename to docs/reference/query-languages/esql/kibana/docs/functions/mv_sum.md index 16285d3c7229b..de407fe0b3928 100644 --- a/docs/reference/esql/functions/kibana/docs/mv_sum.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_sum.md @@ -1,5 +1,5 @@ ### MV_SUM diff --git a/docs/reference/esql/functions/kibana/docs/mv_zip.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_zip.md similarity index 64% rename from docs/reference/esql/functions/kibana/docs/mv_zip.md rename to docs/reference/query-languages/esql/kibana/docs/functions/mv_zip.md index cd814439f86c2..17e37f39ccdfa 100644 --- a/docs/reference/esql/functions/kibana/docs/mv_zip.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_zip.md @@ -1,5 +1,5 @@ ### MV_ZIP diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/now.md b/docs/reference/query-languages/esql/kibana/docs/functions/now.md new file mode 100644 index 0000000000000..da0c24bfd71dc --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/now.md @@ -0,0 +1,10 @@ + + +### NOW +Returns current date and time. + +``` +ROW current_date = NOW() +``` diff --git a/docs/reference/esql/functions/kibana/docs/percentile.md b/docs/reference/query-languages/esql/kibana/docs/functions/percentile.md similarity index 76% rename from docs/reference/esql/functions/kibana/docs/percentile.md rename to docs/reference/query-languages/esql/kibana/docs/functions/percentile.md index dd907ef817186..8e244faa88f5c 100644 --- a/docs/reference/esql/functions/kibana/docs/percentile.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/percentile.md @@ -1,5 +1,5 @@ ### PERCENTILE diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/pi.md b/docs/reference/query-languages/esql/kibana/docs/functions/pi.md new file mode 100644 index 0000000000000..ce1d39084f4d6 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/pi.md @@ -0,0 +1,10 @@ + + +### PI +Returns Pi, the ratio of a circle’s circumference to its diameter. + +``` +ROW PI() +``` diff --git a/docs/reference/esql/functions/kibana/docs/pow.md b/docs/reference/query-languages/esql/kibana/docs/functions/pow.md similarity index 68% rename from docs/reference/esql/functions/kibana/docs/pow.md rename to docs/reference/query-languages/esql/kibana/docs/functions/pow.md index d214504ce4b03..e0a161ef71558 100644 --- a/docs/reference/esql/functions/kibana/docs/pow.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/pow.md @@ -1,5 +1,5 @@ ### POW diff --git a/docs/reference/esql/functions/kibana/docs/qstr.md b/docs/reference/query-languages/esql/kibana/docs/functions/qstr.md similarity index 54% rename from docs/reference/esql/functions/kibana/docs/qstr.md rename to docs/reference/query-languages/esql/kibana/docs/functions/qstr.md index 374854b805fee..b3b97ac978a95 100644 --- a/docs/reference/esql/functions/kibana/docs/qstr.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/qstr.md @@ -1,14 +1,14 @@ ### QSTR Performs a <>. Returns true if the provided query string matches the row. ``` -FROM books +FROM books | WHERE QSTR("author: Faulkner") -| KEEP book_no, author -| SORT book_no +| KEEP book_no, author +| SORT book_no | LIMIT 5 ``` diff --git a/docs/reference/esql/functions/kibana/docs/repeat.md b/docs/reference/query-languages/esql/kibana/docs/functions/repeat.md similarity index 60% rename from docs/reference/esql/functions/kibana/docs/repeat.md rename to docs/reference/query-languages/esql/kibana/docs/functions/repeat.md index 4949d86a28f46..3b28bbb36685a 100644 --- a/docs/reference/esql/functions/kibana/docs/repeat.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/repeat.md @@ -1,5 +1,5 @@ ### REPEAT diff --git a/docs/reference/esql/functions/kibana/docs/replace.md b/docs/reference/query-languages/esql/kibana/docs/functions/replace.md similarity index 67% rename from docs/reference/esql/functions/kibana/docs/replace.md rename to docs/reference/query-languages/esql/kibana/docs/functions/replace.md index 773416520e421..3462f07be4ac4 100644 --- a/docs/reference/esql/functions/kibana/docs/replace.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/replace.md @@ -1,5 +1,5 @@ ### REPLACE diff --git a/docs/reference/esql/functions/kibana/docs/reverse.md b/docs/reference/query-languages/esql/kibana/docs/functions/reverse.md similarity index 59% rename from docs/reference/esql/functions/kibana/docs/reverse.md rename to docs/reference/query-languages/esql/kibana/docs/functions/reverse.md index cbeade9189d80..aa083518b19f2 100644 --- a/docs/reference/esql/functions/kibana/docs/reverse.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/reverse.md @@ -1,5 +1,5 @@ ### REVERSE diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/right.md b/docs/reference/query-languages/esql/kibana/docs/functions/right.md new file mode 100644 index 0000000000000..76f3cd7ca51b5 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/right.md @@ -0,0 +1,14 @@ + + +### RIGHT +Return the substring that extracts *length* chars from *str* starting from the right. + +``` +FROM employees +| KEEP last_name +| EVAL right = RIGHT(last_name, 3) +| SORT last_name ASC +| LIMIT 5 +``` diff --git a/docs/reference/esql/functions/kibana/docs/round.md b/docs/reference/query-languages/esql/kibana/docs/functions/round.md similarity index 74% rename from docs/reference/esql/functions/kibana/docs/round.md rename to docs/reference/query-languages/esql/kibana/docs/functions/round.md index 97fa33a8845bd..d4f7bae9d1582 100644 --- a/docs/reference/esql/functions/kibana/docs/round.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/round.md @@ -1,5 +1,5 @@ ### ROUND diff --git a/docs/reference/esql/functions/kibana/docs/rtrim.md b/docs/reference/query-languages/esql/kibana/docs/functions/rtrim.md similarity index 69% rename from docs/reference/esql/functions/kibana/docs/rtrim.md rename to docs/reference/query-languages/esql/kibana/docs/functions/rtrim.md index db65d8c2ad85b..3661a025119fb 100644 --- a/docs/reference/esql/functions/kibana/docs/rtrim.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/rtrim.md @@ -1,5 +1,5 @@ ### RTRIM diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/sha1.md b/docs/reference/query-languages/esql/kibana/docs/functions/sha1.md new file mode 100644 index 0000000000000..c488be1a70631 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/sha1.md @@ -0,0 +1,13 @@ + + +### SHA1 +Computes the SHA1 hash of the input. + +``` +FROM sample_data +| WHERE message != "Connection error" +| EVAL sha1 = sha1(message) +| KEEP message, sha1 +``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/sha256.md b/docs/reference/query-languages/esql/kibana/docs/functions/sha256.md new file mode 100644 index 0000000000000..8ebd296fae06f --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/sha256.md @@ -0,0 +1,13 @@ + + +### SHA256 +Computes the SHA256 hash of the input. + +``` +FROM sample_data +| WHERE message != "Connection error" +| EVAL sha256 = sha256(message) +| KEEP message, sha256 +``` diff --git a/docs/reference/esql/functions/kibana/docs/signum.md b/docs/reference/query-languages/esql/kibana/docs/functions/signum.md similarity index 61% rename from docs/reference/esql/functions/kibana/docs/signum.md rename to docs/reference/query-languages/esql/kibana/docs/functions/signum.md index f2e66b84c69c8..ffa3f283794e7 100644 --- a/docs/reference/esql/functions/kibana/docs/signum.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/signum.md @@ -1,5 +1,5 @@ ### SIGNUM diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/sin.md b/docs/reference/query-languages/esql/kibana/docs/functions/sin.md new file mode 100644 index 0000000000000..1f958cd62604c --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/sin.md @@ -0,0 +1,11 @@ + + +### SIN +Returns the sine of an angle. + +``` +ROW a=1.8 +| EVAL sin=SIN(a) +``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/sinh.md b/docs/reference/query-languages/esql/kibana/docs/functions/sinh.md new file mode 100644 index 0000000000000..06032fbb8384e --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/sinh.md @@ -0,0 +1,11 @@ + + +### SINH +Returns the hyperbolic sine of a number. + +``` +ROW a=1.8 +| EVAL sinh=SINH(a) +``` diff --git a/docs/reference/esql/functions/kibana/docs/space.md b/docs/reference/query-languages/esql/kibana/docs/functions/space.md similarity index 51% rename from docs/reference/esql/functions/kibana/docs/space.md rename to docs/reference/query-languages/esql/kibana/docs/functions/space.md index 3112bf953dd65..72235fd64b5a9 100644 --- a/docs/reference/esql/functions/kibana/docs/space.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/space.md @@ -1,5 +1,5 @@ ### SPACE diff --git a/docs/reference/esql/functions/kibana/docs/split.md b/docs/reference/query-languages/esql/kibana/docs/functions/split.md similarity index 57% rename from docs/reference/esql/functions/kibana/docs/split.md rename to docs/reference/query-languages/esql/kibana/docs/functions/split.md index 29c728a194487..44b6173920490 100644 --- a/docs/reference/esql/functions/kibana/docs/split.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/split.md @@ -1,5 +1,5 @@ ### SPLIT diff --git a/docs/reference/esql/functions/kibana/docs/sqrt.md b/docs/reference/query-languages/esql/kibana/docs/functions/sqrt.md similarity index 66% rename from docs/reference/esql/functions/kibana/docs/sqrt.md rename to docs/reference/query-languages/esql/kibana/docs/functions/sqrt.md index fccec95a4884d..c1d34ddbfd13d 100644 --- a/docs/reference/esql/functions/kibana/docs/sqrt.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/sqrt.md @@ -1,5 +1,5 @@ ### SQRT diff --git a/docs/reference/esql/functions/kibana/docs/st_centroid_agg.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_centroid_agg.md similarity index 60% rename from docs/reference/esql/functions/kibana/docs/st_centroid_agg.md rename to docs/reference/query-languages/esql/kibana/docs/functions/st_centroid_agg.md index 306a32a309a64..bf5a364ce52f1 100644 --- a/docs/reference/esql/functions/kibana/docs/st_centroid_agg.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_centroid_agg.md @@ -1,5 +1,5 @@ ### ST_CENTROID_AGG diff --git a/docs/reference/esql/functions/kibana/docs/st_contains.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_contains.md similarity index 76% rename from docs/reference/esql/functions/kibana/docs/st_contains.md rename to docs/reference/query-languages/esql/kibana/docs/functions/st_contains.md index 99f3a19f9df41..17584ae803e13 100644 --- a/docs/reference/esql/functions/kibana/docs/st_contains.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_contains.md @@ -1,5 +1,5 @@ ### ST_CONTAINS diff --git a/docs/reference/esql/functions/kibana/docs/st_disjoint.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_disjoint.md similarity index 78% rename from docs/reference/esql/functions/kibana/docs/st_disjoint.md rename to docs/reference/query-languages/esql/kibana/docs/functions/st_disjoint.md index 4b42954efa5c1..bc747e7b85ba9 100644 --- a/docs/reference/esql/functions/kibana/docs/st_disjoint.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_disjoint.md @@ -1,5 +1,5 @@ ### ST_DISJOINT diff --git a/docs/reference/esql/functions/kibana/docs/st_distance.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_distance.md similarity index 78% rename from docs/reference/esql/functions/kibana/docs/st_distance.md rename to docs/reference/query-languages/esql/kibana/docs/functions/st_distance.md index 7ea2d5a255357..c3c4c31dbf514 100644 --- a/docs/reference/esql/functions/kibana/docs/st_distance.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_distance.md @@ -1,5 +1,5 @@ ### ST_DISTANCE diff --git a/docs/reference/esql/functions/kibana/docs/st_envelope.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_envelope.md similarity index 66% rename from docs/reference/esql/functions/kibana/docs/st_envelope.md rename to docs/reference/query-languages/esql/kibana/docs/functions/st_envelope.md index 5f4c3e4809a82..4aec58cb7de21 100644 --- a/docs/reference/esql/functions/kibana/docs/st_envelope.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_envelope.md @@ -1,5 +1,5 @@ ### ST_ENVELOPE diff --git a/docs/reference/esql/functions/kibana/docs/st_extent_agg.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_extent_agg.md similarity index 67% rename from docs/reference/esql/functions/kibana/docs/st_extent_agg.md rename to docs/reference/query-languages/esql/kibana/docs/functions/st_extent_agg.md index a2e307c5b2c55..94bcc420a52da 100644 --- a/docs/reference/esql/functions/kibana/docs/st_extent_agg.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_extent_agg.md @@ -1,5 +1,5 @@ ### ST_EXTENT_AGG diff --git a/docs/reference/esql/functions/kibana/docs/st_intersects.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_intersects.md similarity index 79% rename from docs/reference/esql/functions/kibana/docs/st_intersects.md rename to docs/reference/query-languages/esql/kibana/docs/functions/st_intersects.md index b0a58b3ab2357..d3e64152c314c 100644 --- a/docs/reference/esql/functions/kibana/docs/st_intersects.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_intersects.md @@ -1,5 +1,5 @@ ### ST_INTERSECTS diff --git a/docs/reference/esql/functions/kibana/docs/st_within.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_within.md similarity index 76% rename from docs/reference/esql/functions/kibana/docs/st_within.md rename to docs/reference/query-languages/esql/kibana/docs/functions/st_within.md index 9ef046e5006f6..282f0ecfa8035 100644 --- a/docs/reference/esql/functions/kibana/docs/st_within.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_within.md @@ -1,5 +1,5 @@ ### ST_WITHIN diff --git a/docs/reference/esql/functions/kibana/docs/st_x.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_x.md similarity index 71% rename from docs/reference/esql/functions/kibana/docs/st_x.md rename to docs/reference/query-languages/esql/kibana/docs/functions/st_x.md index b113f19e1c76c..f6c8596adda4e 100644 --- a/docs/reference/esql/functions/kibana/docs/st_x.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_x.md @@ -1,5 +1,5 @@ ### ST_X diff --git a/docs/reference/esql/functions/kibana/docs/st_xmax.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_xmax.md similarity index 80% rename from docs/reference/esql/functions/kibana/docs/st_xmax.md rename to docs/reference/query-languages/esql/kibana/docs/functions/st_xmax.md index bbde89df76fd0..fdba219c50cfb 100644 --- a/docs/reference/esql/functions/kibana/docs/st_xmax.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_xmax.md @@ -1,5 +1,5 @@ ### ST_XMAX diff --git a/docs/reference/esql/functions/kibana/docs/st_xmin.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_xmin.md similarity index 80% rename from docs/reference/esql/functions/kibana/docs/st_xmin.md rename to docs/reference/query-languages/esql/kibana/docs/functions/st_xmin.md index 1a6cee7dcfd62..287fdb4cbaa35 100644 --- a/docs/reference/esql/functions/kibana/docs/st_xmin.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_xmin.md @@ -1,5 +1,5 @@ ### ST_XMIN diff --git a/docs/reference/esql/functions/kibana/docs/st_y.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_y.md similarity index 71% rename from docs/reference/esql/functions/kibana/docs/st_y.md rename to docs/reference/query-languages/esql/kibana/docs/functions/st_y.md index db88c3ada63bb..eadcbe49e8d1b 100644 --- a/docs/reference/esql/functions/kibana/docs/st_y.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_y.md @@ -1,5 +1,5 @@ ### ST_Y diff --git a/docs/reference/esql/functions/kibana/docs/st_ymax.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_ymax.md similarity index 80% rename from docs/reference/esql/functions/kibana/docs/st_ymax.md rename to docs/reference/query-languages/esql/kibana/docs/functions/st_ymax.md index 61c9b6c288ca5..5dd8ca52ff71c 100644 --- a/docs/reference/esql/functions/kibana/docs/st_ymax.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_ymax.md @@ -1,5 +1,5 @@ ### ST_YMAX diff --git a/docs/reference/esql/functions/kibana/docs/st_ymin.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_ymin.md similarity index 80% rename from docs/reference/esql/functions/kibana/docs/st_ymin.md rename to docs/reference/query-languages/esql/kibana/docs/functions/st_ymin.md index f5817f10f20a5..0f53004c24d27 100644 --- a/docs/reference/esql/functions/kibana/docs/st_ymin.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_ymin.md @@ -1,5 +1,5 @@ ### ST_YMIN diff --git a/docs/reference/esql/functions/kibana/docs/starts_with.md b/docs/reference/query-languages/esql/kibana/docs/functions/starts_with.md similarity index 63% rename from docs/reference/esql/functions/kibana/docs/starts_with.md rename to docs/reference/query-languages/esql/kibana/docs/functions/starts_with.md index 553c8733c6137..51cde3ee47a3c 100644 --- a/docs/reference/esql/functions/kibana/docs/starts_with.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/starts_with.md @@ -1,5 +1,5 @@ ### STARTS_WITH diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/std_dev.md b/docs/reference/query-languages/esql/kibana/docs/functions/std_dev.md new file mode 100644 index 0000000000000..d22052c5f4305 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/std_dev.md @@ -0,0 +1,11 @@ + + +### STD_DEV +The standard deviation of a numeric field. + +``` +FROM employees +| STATS STD_DEV(height) +``` diff --git a/docs/reference/esql/functions/kibana/docs/substring.md b/docs/reference/query-languages/esql/kibana/docs/functions/substring.md similarity index 63% rename from docs/reference/esql/functions/kibana/docs/substring.md rename to docs/reference/query-languages/esql/kibana/docs/functions/substring.md index 5f2601a279f6f..132e4f53f766b 100644 --- a/docs/reference/esql/functions/kibana/docs/substring.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/substring.md @@ -1,5 +1,5 @@ ### SUBSTRING diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/sum.md b/docs/reference/query-languages/esql/kibana/docs/functions/sum.md new file mode 100644 index 0000000000000..b1565e1dc783a --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/sum.md @@ -0,0 +1,11 @@ + + +### SUM +The sum of a numeric expression. + +``` +FROM employees +| STATS SUM(languages) +``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/tan.md b/docs/reference/query-languages/esql/kibana/docs/functions/tan.md new file mode 100644 index 0000000000000..4fe0531519b89 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/tan.md @@ -0,0 +1,11 @@ + + +### TAN +Returns the tangent of an angle. + +``` +ROW a=1.8 +| EVAL tan=TAN(a) +``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/tanh.md b/docs/reference/query-languages/esql/kibana/docs/functions/tanh.md new file mode 100644 index 0000000000000..dc4f38d826c3b --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/tanh.md @@ -0,0 +1,11 @@ + + +### TANH +Returns the hyperbolic tangent of a number. + +``` +ROW a=1.8 +| EVAL tanh=TANH(a) +``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/tau.md b/docs/reference/query-languages/esql/kibana/docs/functions/tau.md new file mode 100644 index 0000000000000..2e30f481a8689 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/tau.md @@ -0,0 +1,10 @@ + + +### TAU +Returns the [ratio](https://tauday.com/tau-manifesto) of a circle’s circumference to its radius. + +``` +ROW TAU() +``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/term.md b/docs/reference/query-languages/esql/kibana/docs/functions/term.md new file mode 100644 index 0000000000000..0579684b3a3ea --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/term.md @@ -0,0 +1,13 @@ + + +### TERM +Performs a Term query on the specified field. Returns true if the provided term matches the row. + +``` +FROM books +| WHERE TERM(author, "gabriel") +| KEEP book_no, title +| LIMIT 3 +``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_base64.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_base64.md new file mode 100644 index 0000000000000..5b5c80dfee96b --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_base64.md @@ -0,0 +1,11 @@ + + +### TO_BASE64 +Encode a string to a base64 string. + +``` +row a = "elastic" +| eval e = to_base64(a) +``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_boolean.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_boolean.md new file mode 100644 index 0000000000000..d0af2e6613753 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_boolean.md @@ -0,0 +1,14 @@ + + +### TO_BOOLEAN +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`. +The numerical value of `0` will be converted to `false`, anything else will be converted to `true`. + +``` +ROW str = ["true", "TRuE", "false", "", "yes", "1"] +| EVAL bool = TO_BOOLEAN(str) +``` diff --git a/docs/reference/esql/functions/kibana/docs/to_cartesianpoint.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_cartesianpoint.md similarity index 71% rename from docs/reference/esql/functions/kibana/docs/to_cartesianpoint.md rename to docs/reference/query-languages/esql/kibana/docs/functions/to_cartesianpoint.md index 87ec2233614a3..917221acd4a91 100644 --- a/docs/reference/esql/functions/kibana/docs/to_cartesianpoint.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_cartesianpoint.md @@ -1,5 +1,5 @@ ### TO_CARTESIANPOINT diff --git a/docs/reference/esql/functions/kibana/docs/to_cartesianshape.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_cartesianshape.md similarity index 77% rename from docs/reference/esql/functions/kibana/docs/to_cartesianshape.md rename to docs/reference/query-languages/esql/kibana/docs/functions/to_cartesianshape.md index 7967fc567e9da..bc1d59b8c883b 100644 --- a/docs/reference/esql/functions/kibana/docs/to_cartesianshape.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_cartesianshape.md @@ -1,5 +1,5 @@ ### TO_CARTESIANSHAPE diff --git a/docs/reference/esql/functions/kibana/docs/to_date_nanos.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_date_nanos.md similarity index 78% rename from docs/reference/esql/functions/kibana/docs/to_date_nanos.md rename to docs/reference/query-languages/esql/kibana/docs/functions/to_date_nanos.md index 1bce8d4fca832..cf08b93b3f4a7 100644 --- a/docs/reference/esql/functions/kibana/docs/to_date_nanos.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_date_nanos.md @@ -1,5 +1,5 @@ ### TO_DATE_NANOS diff --git a/docs/reference/esql/functions/kibana/docs/to_dateperiod.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_dateperiod.md similarity index 62% rename from docs/reference/esql/functions/kibana/docs/to_dateperiod.md rename to docs/reference/query-languages/esql/kibana/docs/functions/to_dateperiod.md index adbbe75783051..932f3dcbf9240 100644 --- a/docs/reference/esql/functions/kibana/docs/to_dateperiod.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_dateperiod.md @@ -1,5 +1,5 @@ ### TO_DATEPERIOD diff --git a/docs/reference/esql/functions/kibana/docs/to_datetime.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_datetime.md similarity index 65% rename from docs/reference/esql/functions/kibana/docs/to_datetime.md rename to docs/reference/query-languages/esql/kibana/docs/functions/to_datetime.md index c194dfd17871a..23c96a0d1e217 100644 --- a/docs/reference/esql/functions/kibana/docs/to_datetime.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_datetime.md @@ -1,10 +1,10 @@ ### TO_DATETIME 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'`. +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 <>. ``` diff --git a/docs/reference/esql/functions/kibana/docs/to_degrees.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_degrees.md similarity index 53% rename from docs/reference/esql/functions/kibana/docs/to_degrees.md rename to docs/reference/query-languages/esql/kibana/docs/functions/to_degrees.md index 81fbba1dd2b2d..aad6faf1bcb38 100644 --- a/docs/reference/esql/functions/kibana/docs/to_degrees.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_degrees.md @@ -1,5 +1,5 @@ ### TO_DEGREES diff --git a/docs/reference/esql/functions/kibana/docs/to_double.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_double.md similarity index 60% rename from docs/reference/esql/functions/kibana/docs/to_double.md rename to docs/reference/query-languages/esql/kibana/docs/functions/to_double.md index 4f769bec9b108..5c754d9dff276 100644 --- a/docs/reference/esql/functions/kibana/docs/to_double.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_double.md @@ -1,11 +1,11 @@ ### TO_DOUBLE Converts an input value to a double value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the Unix epoch, -converted to double. Boolean *true* will be converted to double *1.0*, *false* to *0.0*. +converted to double. Boolean `true` will be converted to double `1.0`, `false` to `0.0`. ``` ROW str1 = "5.20128E11", str2 = "foo" diff --git a/docs/reference/esql/functions/kibana/docs/to_geopoint.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_geopoint.md similarity index 67% rename from docs/reference/esql/functions/kibana/docs/to_geopoint.md rename to docs/reference/query-languages/esql/kibana/docs/functions/to_geopoint.md index 3301acb214c12..1b301df9cdb61 100644 --- a/docs/reference/esql/functions/kibana/docs/to_geopoint.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_geopoint.md @@ -1,5 +1,5 @@ ### TO_GEOPOINT diff --git a/docs/reference/esql/functions/kibana/docs/to_geoshape.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_geoshape.md similarity index 68% rename from docs/reference/esql/functions/kibana/docs/to_geoshape.md rename to docs/reference/query-languages/esql/kibana/docs/functions/to_geoshape.md index c39bd9f73b7cb..33cb3b7208d04 100644 --- a/docs/reference/esql/functions/kibana/docs/to_geoshape.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_geoshape.md @@ -1,5 +1,5 @@ ### TO_GEOSHAPE diff --git a/docs/reference/esql/functions/kibana/docs/to_integer.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_integer.md similarity index 61% rename from docs/reference/esql/functions/kibana/docs/to_integer.md rename to docs/reference/query-languages/esql/kibana/docs/functions/to_integer.md index 238688b88eda7..d26779dc724ed 100644 --- a/docs/reference/esql/functions/kibana/docs/to_integer.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_integer.md @@ -1,12 +1,12 @@ ### TO_INTEGER Converts an input value to an integer value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the Unix epoch, converted to integer. -Boolean *true* will be converted to integer *1*, *false* to *0*. +Boolean `true` will be converted to integer `1`, `false` to `0`. ``` ROW long = [5013792, 2147483647, 501379200000] diff --git a/docs/reference/esql/functions/kibana/docs/to_ip.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_ip.md similarity index 62% rename from docs/reference/esql/functions/kibana/docs/to_ip.md rename to docs/reference/query-languages/esql/kibana/docs/functions/to_ip.md index 6811753b781e4..2b1a862a25fe2 100644 --- a/docs/reference/esql/functions/kibana/docs/to_ip.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_ip.md @@ -1,5 +1,5 @@ ### TO_IP diff --git a/docs/reference/esql/functions/kibana/docs/to_long.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_long.md similarity index 65% rename from docs/reference/esql/functions/kibana/docs/to_long.md rename to docs/reference/query-languages/esql/kibana/docs/functions/to_long.md index f5abb8a469001..a1b629f7b2462 100644 --- a/docs/reference/esql/functions/kibana/docs/to_long.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_long.md @@ -1,11 +1,11 @@ ### TO_LONG Converts an input value to a long value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the Unix epoch, converted to long. -Boolean *true* will be converted to long *1*, *false* to *0*. +Boolean `true` will be converted to long `1`, `false` to `0`. ``` ROW str1 = "2147483648", str2 = "2147483648.2", str3 = "foo" diff --git a/docs/reference/esql/functions/kibana/docs/to_lower.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_lower.md similarity index 60% rename from docs/reference/esql/functions/kibana/docs/to_lower.md rename to docs/reference/query-languages/esql/kibana/docs/functions/to_lower.md index 91d8dd2c6956c..18791a194c429 100644 --- a/docs/reference/esql/functions/kibana/docs/to_lower.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_lower.md @@ -1,5 +1,5 @@ ### TO_LOWER diff --git a/docs/reference/esql/functions/kibana/docs/to_radians.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_radians.md similarity index 54% rename from docs/reference/esql/functions/kibana/docs/to_radians.md rename to docs/reference/query-languages/esql/kibana/docs/functions/to_radians.md index f40387005d753..590c83e09eadc 100644 --- a/docs/reference/esql/functions/kibana/docs/to_radians.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_radians.md @@ -1,5 +1,5 @@ ### TO_RADIANS diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_string.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_string.md new file mode 100644 index 0000000000000..832d79c29fbe9 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_string.md @@ -0,0 +1,11 @@ + + +### TO_STRING +Converts an input value into a string. + +``` +ROW a=10 +| EVAL j = TO_STRING(a) +``` diff --git a/docs/reference/esql/functions/kibana/docs/to_timeduration.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_timeduration.md similarity index 63% rename from docs/reference/esql/functions/kibana/docs/to_timeduration.md rename to docs/reference/query-languages/esql/kibana/docs/functions/to_timeduration.md index 52e32ba97d11c..9554189c6f842 100644 --- a/docs/reference/esql/functions/kibana/docs/to_timeduration.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_timeduration.md @@ -1,5 +1,5 @@ ### TO_TIMEDURATION diff --git a/docs/reference/esql/functions/kibana/docs/to_unsigned_long.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_unsigned_long.md similarity index 66% rename from docs/reference/esql/functions/kibana/docs/to_unsigned_long.md rename to docs/reference/query-languages/esql/kibana/docs/functions/to_unsigned_long.md index 772784f4271f0..84496eba6590b 100644 --- a/docs/reference/esql/functions/kibana/docs/to_unsigned_long.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_unsigned_long.md @@ -1,11 +1,11 @@ ### TO_UNSIGNED_LONG Converts an input value to an unsigned long value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the Unix epoch, converted to unsigned long. -Boolean *true* will be converted to unsigned long *1*, *false* to *0*. +Boolean `true` will be converted to unsigned long `1`, `false` to `0`. ``` ROW str1 = "2147483648", str2 = "2147483648.2", str3 = "foo" diff --git a/docs/reference/esql/functions/kibana/docs/to_upper.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_upper.md similarity index 60% rename from docs/reference/esql/functions/kibana/docs/to_upper.md rename to docs/reference/query-languages/esql/kibana/docs/functions/to_upper.md index 6b1cc44ecdc2d..add8fc703fcf1 100644 --- a/docs/reference/esql/functions/kibana/docs/to_upper.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_upper.md @@ -1,5 +1,5 @@ ### TO_UPPER diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_version.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_version.md new file mode 100644 index 0000000000000..8ad51a21b8b6d --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_version.md @@ -0,0 +1,10 @@ + + +### TO_VERSION +Converts an input string to a version value. + +``` +ROW v = TO_VERSION("1.2.3") +``` diff --git a/docs/reference/esql/functions/kibana/docs/top.md b/docs/reference/query-languages/esql/kibana/docs/functions/top.md similarity index 60% rename from docs/reference/esql/functions/kibana/docs/top.md rename to docs/reference/query-languages/esql/kibana/docs/functions/top.md index 10db4e7ac5b55..a5b1f64e02bc0 100644 --- a/docs/reference/esql/functions/kibana/docs/top.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/top.md @@ -1,5 +1,5 @@ ### TOP diff --git a/docs/reference/esql/functions/kibana/docs/trim.md b/docs/reference/query-languages/esql/kibana/docs/functions/trim.md similarity index 62% rename from docs/reference/esql/functions/kibana/docs/trim.md rename to docs/reference/query-languages/esql/kibana/docs/functions/trim.md index 9ebae1d78947e..21045312f1d02 100644 --- a/docs/reference/esql/functions/kibana/docs/trim.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/trim.md @@ -1,5 +1,5 @@ ### TRIM diff --git a/docs/reference/esql/functions/kibana/docs/values.md b/docs/reference/query-languages/esql/kibana/docs/functions/values.md similarity index 52% rename from docs/reference/esql/functions/kibana/docs/values.md rename to docs/reference/query-languages/esql/kibana/docs/functions/values.md index cba62fc27255e..ae944e383fd7d 100644 --- a/docs/reference/esql/functions/kibana/docs/values.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/values.md @@ -1,9 +1,9 @@ ### VALUES -Returns all values in a group as a multivalued field. The order of the returned values isn't guaranteed. If you need the values returned in order use <>. +Returns all values in a group as a multivalued field. The order of the returned values isn’t guaranteed. If you need the values returned in order use <>. ``` FROM employees diff --git a/docs/reference/esql/functions/kibana/docs/weighted_avg.md b/docs/reference/query-languages/esql/kibana/docs/functions/weighted_avg.md similarity index 66% rename from docs/reference/esql/functions/kibana/docs/weighted_avg.md rename to docs/reference/query-languages/esql/kibana/docs/functions/weighted_avg.md index 6b0b2cc8cd287..39741e8bcc5c6 100644 --- a/docs/reference/esql/functions/kibana/docs/weighted_avg.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/weighted_avg.md @@ -1,5 +1,5 @@ ### WEIGHTED_AVG diff --git a/docs/reference/esql/functions/kibana/docs/add.md b/docs/reference/query-languages/esql/kibana/docs/operators/add.md similarity index 53% rename from docs/reference/esql/functions/kibana/docs/add.md rename to docs/reference/query-languages/esql/kibana/docs/operators/add.md index 3f99bd4c77551..1c19235e5ad75 100644 --- a/docs/reference/esql/functions/kibana/docs/add.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/add.md @@ -1,5 +1,5 @@ ### ADD diff --git a/docs/reference/esql/functions/kibana/docs/div.md b/docs/reference/query-languages/esql/kibana/docs/operators/div.md similarity index 73% rename from docs/reference/esql/functions/kibana/docs/div.md rename to docs/reference/query-languages/esql/kibana/docs/operators/div.md index a8b7b4e58f376..b7288ee59bb53 100644 --- a/docs/reference/esql/functions/kibana/docs/div.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/div.md @@ -1,5 +1,5 @@ ### DIV diff --git a/docs/reference/esql/functions/kibana/docs/equals.md b/docs/reference/query-languages/esql/kibana/docs/operators/equals.md similarity index 74% rename from docs/reference/esql/functions/kibana/docs/equals.md rename to docs/reference/query-languages/esql/kibana/docs/operators/equals.md index b8fcb72c2ccd5..ca46011304dfb 100644 --- a/docs/reference/esql/functions/kibana/docs/equals.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/equals.md @@ -1,5 +1,5 @@ ### EQUALS diff --git a/docs/reference/esql/functions/kibana/docs/greater_than.md b/docs/reference/query-languages/esql/kibana/docs/operators/greater_than.md similarity index 75% rename from docs/reference/esql/functions/kibana/docs/greater_than.md rename to docs/reference/query-languages/esql/kibana/docs/operators/greater_than.md index 67f99eda3aed7..baa0c2aa7f3ed 100644 --- a/docs/reference/esql/functions/kibana/docs/greater_than.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/greater_than.md @@ -1,5 +1,5 @@ ### GREATER_THAN diff --git a/docs/reference/esql/functions/kibana/docs/greater_than_or_equal.md b/docs/reference/query-languages/esql/kibana/docs/operators/greater_than_or_equal.md similarity index 76% rename from docs/reference/esql/functions/kibana/docs/greater_than_or_equal.md rename to docs/reference/query-languages/esql/kibana/docs/operators/greater_than_or_equal.md index 73d3ac6371b07..e2e0ed039739e 100644 --- a/docs/reference/esql/functions/kibana/docs/greater_than_or_equal.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/greater_than_or_equal.md @@ -1,5 +1,5 @@ ### GREATER_THAN_OR_EQUAL diff --git a/docs/reference/esql/functions/kibana/docs/in.md b/docs/reference/query-languages/esql/kibana/docs/operators/in.md similarity index 64% rename from docs/reference/esql/functions/kibana/docs/in.md rename to docs/reference/query-languages/esql/kibana/docs/operators/in.md index e096146374f38..1a6c54976550b 100644 --- a/docs/reference/esql/functions/kibana/docs/in.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/in.md @@ -1,5 +1,5 @@ ### IN diff --git a/docs/reference/esql/functions/kibana/docs/less_than.md b/docs/reference/query-languages/esql/kibana/docs/operators/less_than.md similarity index 75% rename from docs/reference/esql/functions/kibana/docs/less_than.md rename to docs/reference/query-languages/esql/kibana/docs/operators/less_than.md index 0d171d06c68d3..98de0e46dc2db 100644 --- a/docs/reference/esql/functions/kibana/docs/less_than.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/less_than.md @@ -1,5 +1,5 @@ ### LESS_THAN diff --git a/docs/reference/esql/functions/kibana/docs/less_than_or_equal.md b/docs/reference/query-languages/esql/kibana/docs/operators/less_than_or_equal.md similarity index 76% rename from docs/reference/esql/functions/kibana/docs/less_than_or_equal.md rename to docs/reference/query-languages/esql/kibana/docs/operators/less_than_or_equal.md index acb92288c2c46..d9f1feca40268 100644 --- a/docs/reference/esql/functions/kibana/docs/less_than_or_equal.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/less_than_or_equal.md @@ -1,5 +1,5 @@ ### LESS_THAN_OR_EQUAL diff --git a/docs/reference/esql/functions/kibana/docs/like.md b/docs/reference/query-languages/esql/kibana/docs/operators/like.md similarity index 81% rename from docs/reference/esql/functions/kibana/docs/like.md rename to docs/reference/query-languages/esql/kibana/docs/operators/like.md index ea2ac11b6f4b9..423f4e61e7af7 100644 --- a/docs/reference/esql/functions/kibana/docs/like.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/like.md @@ -1,5 +1,5 @@ ### LIKE diff --git a/docs/reference/esql/functions/kibana/docs/match_operator.md b/docs/reference/query-languages/esql/kibana/docs/operators/match_operator.md similarity index 76% rename from docs/reference/esql/functions/kibana/docs/match_operator.md rename to docs/reference/query-languages/esql/kibana/docs/operators/match_operator.md index 59662b36b804f..c458452629f33 100644 --- a/docs/reference/esql/functions/kibana/docs/match_operator.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/match_operator.md @@ -1,5 +1,5 @@ ### MATCH_OPERATOR @@ -14,9 +14,9 @@ For using the function syntax, or adding < ### MOD diff --git a/docs/reference/esql/functions/kibana/docs/mul.md b/docs/reference/query-languages/esql/kibana/docs/operators/mul.md similarity index 54% rename from docs/reference/esql/functions/kibana/docs/mul.md rename to docs/reference/query-languages/esql/kibana/docs/operators/mul.md index 3f24f3b1a67bb..26bb388114b7f 100644 --- a/docs/reference/esql/functions/kibana/docs/mul.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/mul.md @@ -1,5 +1,5 @@ ### MUL diff --git a/docs/reference/query-languages/esql/kibana/docs/operators/neg.md b/docs/reference/query-languages/esql/kibana/docs/operators/neg.md new file mode 100644 index 0000000000000..3a14923e81d03 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/operators/neg.md @@ -0,0 +1,7 @@ + + +### NEG +Returns the negation of the argument. + diff --git a/docs/reference/esql/functions/kibana/docs/not_in.md b/docs/reference/query-languages/esql/kibana/docs/operators/not in.md similarity index 58% rename from docs/reference/esql/functions/kibana/docs/not_in.md rename to docs/reference/query-languages/esql/kibana/docs/operators/not in.md index e9e5a7b384d1c..91d5130fae394 100644 --- a/docs/reference/esql/functions/kibana/docs/not_in.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/not in.md @@ -1,5 +1,5 @@ ### NOT_IN diff --git a/docs/reference/esql/functions/kibana/docs/not_like.md b/docs/reference/query-languages/esql/kibana/docs/operators/not like.md similarity index 62% rename from docs/reference/esql/functions/kibana/docs/not_like.md rename to docs/reference/query-languages/esql/kibana/docs/operators/not like.md index fd1cf7a68630f..f3db44b92f02a 100644 --- a/docs/reference/esql/functions/kibana/docs/not_like.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/not like.md @@ -1,9 +1,9 @@ ### NOT_LIKE -Use `NOT LIKE` to filter data based on string patterns using wildcards. `NOT LIKE` +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 represents the pattern. diff --git a/docs/reference/query-languages/esql/kibana/docs/operators/not rlike.md b/docs/reference/query-languages/esql/kibana/docs/operators/not rlike.md new file mode 100644 index 0000000000000..39f9de28a9731 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/operators/not rlike.md @@ -0,0 +1,10 @@ + + +### NOT_RLIKE +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. + diff --git a/docs/reference/esql/functions/kibana/docs/not_equals.md b/docs/reference/query-languages/esql/kibana/docs/operators/not_equals.md similarity index 74% rename from docs/reference/esql/functions/kibana/docs/not_equals.md rename to docs/reference/query-languages/esql/kibana/docs/operators/not_equals.md index cff2130e766ed..39e536cc8a893 100644 --- a/docs/reference/esql/functions/kibana/docs/not_equals.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/not_equals.md @@ -1,5 +1,5 @@ ### NOT_EQUALS diff --git a/docs/reference/esql/functions/kibana/docs/rlike.md b/docs/reference/query-languages/esql/kibana/docs/operators/rlike.md similarity index 78% rename from docs/reference/esql/functions/kibana/docs/rlike.md rename to docs/reference/query-languages/esql/kibana/docs/operators/rlike.md index 95b57799ffe29..f9ba6ee505a17 100644 --- a/docs/reference/esql/functions/kibana/docs/rlike.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/rlike.md @@ -1,5 +1,5 @@ ### RLIKE diff --git a/docs/reference/esql/functions/kibana/docs/sub.md b/docs/reference/query-languages/esql/kibana/docs/operators/sub.md similarity index 54% rename from docs/reference/esql/functions/kibana/docs/sub.md rename to docs/reference/query-languages/esql/kibana/docs/operators/sub.md index 10746ed81cfe3..314ab9e9d0b5b 100644 --- a/docs/reference/esql/functions/kibana/docs/sub.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/sub.md @@ -1,5 +1,5 @@ ### SUB diff --git a/docs/reference/esql/processing-commands/inlinestats.disabled b/docs/reference/query-languages/esql/processing-commands/inlinestats.disabled similarity index 100% rename from docs/reference/esql/processing-commands/inlinestats.disabled rename to docs/reference/query-languages/esql/processing-commands/inlinestats.disabled diff --git a/docs/reference/esql/processing-commands/lookup.disabled b/docs/reference/query-languages/esql/processing-commands/lookup.disabled similarity index 100% rename from docs/reference/esql/processing-commands/lookup.disabled rename to docs/reference/query-languages/esql/processing-commands/lookup.disabled diff --git a/docs/reference/query-languages/sql-limitations.md b/docs/reference/query-languages/sql-limitations.md index 9ffcbf60a5138..94a66d8eb8e83 100644 --- a/docs/reference/query-languages/sql-limitations.md +++ b/docs/reference/query-languages/sql-limitations.md @@ -3,14 +3,14 @@ ## Large queries may throw `ParsingException` [large-parsing-trees] -Extremely large queries can consume too much memory during the parsing phase, in which case the {es-sql} engine will +Extremely large queries can consume too much memory during the parsing phase, in which case the {{es-sql}} engine will abort parsing and throw an error. In such cases, consider reducing the query to a smaller size by potentially simplifying it or splitting it into smaller queries. ## Nested fields in `SYS COLUMNS` and `DESCRIBE TABLE` [sys-columns-describe-table-nested-fields] -{es} has a special type of relationship fields called `nested` fields. In {es-sql} they can be used by referencing their inner +{{es}} has a special type of relationship fields called `nested` fields. In {{es-sql}} they can be used by referencing their inner sub-fields. Even though `SYS COLUMNS` in non-driver mode (in the CLI and in REST calls) and `DESCRIBE TABLE` will still display them as having the type `NESTED`, they cannot be used in a query. One can only reference its sub-fields in the form: @@ -51,7 +51,7 @@ is supported. ## Multi-nested fields -{es-sql} doesn't support multi-nested documents, so a query cannot reference more than one nested field in an index. +{{es-sql}} doesn't support multi-nested documents, so a query cannot reference more than one nested field in an index. This applies to multi-level nested fields, but also multiple nested fields defined on the same level. For example, for this index: ```sql @@ -66,31 +66,31 @@ nested_B.text |VARCHAR |KEYWORD ``` `nested_A` and `nested_B` cannot be used at the same time, nor `nested_A`/`nested_B` and `nested_A.nested_X` combination. -For such situations, {es-sql} will display an error message. +For such situations, {{es-sql}} will display an error message. ## Paginating nested inner hits -When SELECTing a nested field, pagination will not work as expected, {es-sql} will return __at least__ the page size records. -This is because of the way nested queries work in {es}: the root nested field will be returned and it's matching inner nested fields as well, +When SELECTing a nested field, pagination will not work as expected, {{es-sql}} will return __at least__ the page size records. +This is because of the way nested queries work in {{es}}: the root nested field will be returned and it's matching inner nested fields as well, pagination taking place on the **root nested document and not on its inner hits**. ## Normalized `keyword` fields [normalized-keyword-fields] -`keyword` fields in {es} can be normalized by defining a `normalizer`. Such fields are not supported in {es-sql}. +`keyword` fields in {{es}} can be normalized by defining a `normalizer`. Such fields are not supported in {{es-sql}}. ## Array type of fields -Array fields are not supported due to the "invisible" way in which {es} handles an array of values: the mapping doesn't indicate whether -a field is an array (has multiple values) or not, so without reading all the data, {es-sql} cannot know whether a field is a single or multi value. -When multiple values are returned for a field, by default, {es-sql} will throw an exception. However, it is possible to change this behavior through `field_multi_value_leniency` parameter in REST (disabled by default) or +Array fields are not supported due to the "invisible" way in which {{es}} handles an array of values: the mapping doesn't indicate whether +a field is an array (has multiple values) or not, so without reading all the data, {{es-sql}} cannot know whether a field is a single or multi value. +When multiple values are returned for a field, by default, {{es-sql}} will throw an exception. However, it is possible to change this behavior through `field_multi_value_leniency` parameter in REST (disabled by default) or `field.multi.value.leniency` in drivers (enabled by default). ## Sorting by aggregation -When doing aggregations (`GROUP BY`) {es-sql} relies on {es}'s `composite` aggregation for its support for paginating results. +When doing aggregations (`GROUP BY`) {{es-sql}} relies on {{es}}'s `composite` aggregation for its support for paginating results. However this type of aggregation does come with a limitation: sorting can only be applied on the key used for the aggregation's buckets. -{es-sql} overcomes this limitation by doing client-side sorting however as a safety measure, allows only up to *65535* rows. +{{es-sql}} overcomes this limitation by doing client-side sorting however as a safety measure, allows only up to *65535* rows. It is recommended to use `LIMIT` for queries that use sorting by aggregation, essentially indicating the top N results that are desired: @@ -99,7 +99,7 @@ SELECT * FROM test GROUP BY age ORDER BY COUNT(*) LIMIT 100; ``` It is possible to run the same queries without a `LIMIT` however in that case if the maximum size (*10000*) is passed, -an exception will be returned as {es-sql} is unable to track (and sort) all the results returned. +an exception will be returned as {{es-sql}} is unable to track (and sort) all the results returned. Moreover, the aggregation(s) used in the `ORDER BY` must be only plain aggregate functions. No scalar functions or operators can be used, and therefore no complex columns that combine two ore more aggregate @@ -114,7 +114,7 @@ SELECT age, MAX(salary) - MIN(salary) AS diff FROM test GROUP BY age ORDER BY di ## Using a sub-select Using sub-selects (`SELECT X FROM (SELECT Y)`) is **supported to a small degree**: any sub-select that can be "flattened" into a single -`SELECT` is possible with {es-sql}. For example: +`SELECT` is possible with {{es-sql}}. For example: ```sql include-tagged::{sql-specs}/docs/docs.csv-spec[limitationSubSelect] @@ -169,7 +169,7 @@ Therefore calling `ST_Z` function in the filtering, grouping or sorting will ret ## Retrieving using the `fields` search parameter [using-fields-api] {{es-sql}} retrieves column values using the [search API's `fields` parameter](/reference/elasticsearch/rest-apis/retrieve-selected-fields.md#search-fields-param). Any limitations on the `fields` parameter also apply to -{es-sql} queries. For example, if `_source` is disabled +{{es-sql}} queries. For example, if `_source` is disabled for any of the returned fields or at index level, the values cannot be retrieved. ## Aggregations in the `PIVOT` clause [aggs-in-pivot] diff --git a/x-pack/plugin/esql/build.gradle b/x-pack/plugin/esql/build.gradle index 3337484c5c838..16b7e33a09026 100644 --- a/x-pack/plugin/esql/build.gradle +++ b/x-pack/plugin/esql/build.gradle @@ -9,8 +9,9 @@ plugins { id 'idea' } -import org.elasticsearch.gradle.internal.precommit.CheckForbiddenApisTask; -import org.elasticsearch.gradle.internal.util.SourceDirectoryCommandLineArgumentProvider; + +import org.elasticsearch.gradle.internal.util.SourceDirectoryCommandLineArgumentProvider + import static org.elasticsearch.gradle.util.PlatformUtils.normalize apply plugin: 'elasticsearch.internal-es-plugin' @@ -21,7 +22,7 @@ apply plugin: 'elasticsearch.publish' esplugin { name = 'x-pack-esql' description = 'The plugin that powers ESQL for Elasticsearch' - classname ='org.elasticsearch.xpack.esql.plugin.EsqlPlugin' + classname = 'org.elasticsearch.xpack.esql.plugin.EsqlPlugin' extendedPlugins = ['x-pack-esql-core', 'lang-painless', 'x-pack-ml'] } @@ -45,7 +46,7 @@ dependencies { annotationProcessor project('compute:gen') testImplementation(project('qa:testFixtures')) { - exclude(group:"org.elasticsearch.plugin", module: "esql") + exclude(group: "org.elasticsearch.plugin", module: "esql") } testImplementation project(':test:framework') testImplementation(testArtifact(project(xpackModule('core')))) @@ -79,7 +80,8 @@ idea.module { } interface Injected { - @Inject FileSystemOperations getFs() + @Inject + FileSystemOperations getFs() } tasks.named("test").configure { @@ -88,61 +90,81 @@ tasks.named("test").configure { def injected = project.objects.newInstance(Injected) doFirst { injected.fs.delete { - it.delete("build/testrun/test/temp/esql/functions") + it.delete("build/testrun/test/temp/esql") } } - File functionsFolder = file("build/testrun/test/temp/esql/functions") - File typesFolder = file("build/testrun/test/temp/esql/functions/types") - def functionsDocFolder = file("${rootDir}/docs/reference/esql/functions") - def effectiveProjectDir = projectDir + File imagesFolder = file("build/testrun/test/temp/esql/images") + File snippetsFolder = file("build/testrun/test/temp/esql/_snippets") + File kibanaFolder = file("build/testrun/test/temp/esql/kibana") + def imagesDocFolder = file("${rootDir}/docs/reference/query-languages/esql/images") + def snippetsDocFolder = file("${rootDir}/docs/reference/query-languages/esql/_snippets") + def kibanaDocFolder = file("${rootDir}/docs/reference/query-languages/esql/kibana") doLast { - List types = typesFolder.list().findAll {it.endsWith("asciidoc")} - int count = types == null ? 0 : types.size() - Closure readExample = line -> { - line.replaceAll(/read-example::([^\[]+)\[tag=([^,\]]+)(, ?json)?\]/, { - String file = it[1] - String tag = it[2] - boolean isJson = it[3] - String allExamples = new File("${effectiveProjectDir}/qa/testFixtures/src/main/resources/${file}").text - .replaceAll(System.lineSeparator(), "\n") - int start = allExamples.indexOf("tag::${tag}[]") - int end = allExamples.indexOf("end::${tag}[]", start) - if (start < 0 || end < 0) { - throw new IllegalAccessException("can't find example ${file}::${tag}") - } - // Slice out the newlines - start = allExamples.indexOf('\n', start) + 1 - end = allExamples.lastIndexOf('\n', end) - String example = allExamples.substring(start, end) - if (isJson) { - example = example.replace("\"", "\\\"").replace("\n", "\\n") + List snippets = fileTree(snippetsFolder).matching { + include "**/types/*.md" // Recursively include all types/*.md files (effectively counting functions and operators) + }.files.collect { it.name } + int countSnippets = snippets.size() + if (countSnippets == 0) { + logger.quiet("ESQL Docs: No function/operator snippets created. Skipping sync.") + } else { + logger.quiet("ESQL Docs: Found $countSnippets generated markdown files to patch into docs") + injected.fs.sync { + from snippetsFolder + into snippetsDocFolder + include '**/*.md' + preserve { + // The snippets directory contains generated and static content, so we must preserve all MD files. + include '**/*.md' } - return example; - }) + } } - if (count == 0) { + + List images = fileTree(imagesFolder).matching { + include "**/*.svg" // Recursively include all SVG files + }.files.collect { it.name } + int countImages = images.size() + Closure replaceFont = line -> { + // The es-docs team has a recommended set of fonts for use with code, and they size similarly to the previous Roboto Mono, which is no longer available in the docs webpage + line.replaceAll( + /font-family:\s*Roboto Mono[^;]*;/, + 'font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;' + ) + } + if (countImages == 0) { logger.quiet("ESQL Docs: No function signatures created. Skipping sync.") - } else if (count == 1) { - logger.quiet("ESQL Docs: Only files related to $types, patching them into place") + } else { + logger.quiet("ESQL Docs: Found $countImages generated SVG files to patch into docs") injected.fs.sync { - from functionsFolder - into functionsDocFolder - include '**/*.asciidoc', '**/*.svg', '**/*.md', '**/*.json' + from imagesFolder + into imagesDocFolder + include '**/*.svg' preserve { - include '/*.asciidoc', '**/*.asciidoc', '**/*.md', '**/*.json', '**/*.svg', 'README.md' + // Some operator files are currently static, so we must preserve them all + include '**/*.svg' } - filter readExample + filter replaceFont } + } + + List kibana = fileTree(kibanaFolder).matching { + include "**/*.json" // Recursively include all JSON files + }.files.collect { it.name } + int countKibana = kibana.size() + if (countKibana == 0) { + logger.quiet("ESQL Docs: No function/operator kibana docs created. Skipping sync.") } else { + logger.quiet("ESQL Docs: Found $countKibana generated kibana markdown files to patch into docs") injected.fs.sync { - from functionsFolder - into functionsDocFolder - include '**/*.asciidoc', '**/*.svg', '**/*.md', '**/*.json' - preserve { - include '/*.asciidoc', 'README.md' + from kibanaFolder + into kibanaDocFolder + include '**/*.md', '**/*.json' + if (countKibana <= 100) { + // If we do not run the full test of tests, do not attempt to remove potentially unused files + preserve { + include '**/*.md', '**/*.json' + } } - filter readExample } } } @@ -281,27 +303,27 @@ tasks.register("regen") { tasks.named("spotlessJava") { dependsOn "stringTemplates" } tasks.named('checkstyleMain').configure { - excludes = [ "**/*.java.st" ] + excludes = ["**/*.java.st"] exclude { normalize(it.file.toString()).contains("src/main/generated-src/generated") } exclude { normalize(it.file.toString()).contains("src/main/generated") } } def prop(Name, Type, type, TYPE, BYTES, Array) { return [ - "Name" : Name, - "Type" : Type, - "type" : type, - "TYPE" : TYPE, - "BYTES" : BYTES, - "Array" : Array, - - "int" : type == "int" ? "true" : "", - "long" : type == "long" ? "true" : "", - "double" : type == "double" ? "true" : "", - "BytesRef" : type == "BytesRef" ? "true" : "", - "boolean" : type == "boolean" ? "true" : "", - "nanosMillis" : Name == "NanosMillis" ? "true" : "", - "millisNanos" : Name == "MillisNanos" ? "true" : "", + "Name" : Name, + "Type" : Type, + "type" : type, + "TYPE" : TYPE, + "BYTES" : BYTES, + "Array" : Array, + + "int" : type == "int" ? "true" : "", + "long" : type == "long" ? "true" : "", + "double" : type == "double" ? "true" : "", + "BytesRef" : type == "BytesRef" ? "true" : "", + "boolean" : type == "boolean" ? "true" : "", + "nanosMillis": Name == "NanosMillis" ? "true" : "", + "millisNanos": Name == "MillisNanos" ? "true" : "", ] } @@ -317,64 +339,64 @@ tasks.named('stringTemplates').configure { File inInputFile = file("src/main/java/org/elasticsearch/xpack/esql/expression/predicate/operator/comparison/X-InEvaluator.java.st") template { it.properties = booleanProperties - it.inputFile = inInputFile + it.inputFile = inInputFile it.outputFile = "org/elasticsearch/xpack/esql/expression/predicate/operator/comparison/InBooleanEvaluator.java" } template { it.properties = intProperties - it.inputFile = inInputFile + it.inputFile = inInputFile it.outputFile = "org/elasticsearch/xpack/esql/expression/predicate/operator/comparison/InIntEvaluator.java" } template { it.properties = longProperties - it.inputFile = inInputFile + it.inputFile = inInputFile it.outputFile = "org/elasticsearch/xpack/esql/expression/predicate/operator/comparison/InLongEvaluator.java" } template { it.properties = nanosMillisProperties - it.inputFile = inInputFile + it.inputFile = inInputFile it.outputFile = "org/elasticsearch/xpack/esql/expression/predicate/operator/comparison/InNanosMillisEvaluator.java" } template { it.properties = millisNanosProperties - it.inputFile = inInputFile + it.inputFile = inInputFile it.outputFile = "org/elasticsearch/xpack/esql/expression/predicate/operator/comparison/InMillisNanosEvaluator.java" } template { it.properties = doubleProperties - it.inputFile = inInputFile + it.inputFile = inInputFile it.outputFile = "org/elasticsearch/xpack/esql/expression/predicate/operator/comparison/InDoubleEvaluator.java" } template { it.properties = bytesRefProperties - it.inputFile = inInputFile + it.inputFile = inInputFile it.outputFile = "org/elasticsearch/xpack/esql/expression/predicate/operator/comparison/InBytesRefEvaluator.java" } File coalesceInputFile = file("src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/nulls/X-CoalesceEvaluator.java.st") template { it.properties = booleanProperties - it.inputFile = coalesceInputFile + it.inputFile = coalesceInputFile it.outputFile = "org/elasticsearch/xpack/esql/expression/function/scalar/nulls/CoalesceBooleanEvaluator.java" } template { it.properties = intProperties - it.inputFile = coalesceInputFile + it.inputFile = coalesceInputFile it.outputFile = "org/elasticsearch/xpack/esql/expression/function/scalar/nulls/CoalesceIntEvaluator.java" } template { it.properties = longProperties - it.inputFile = coalesceInputFile + it.inputFile = coalesceInputFile it.outputFile = "org/elasticsearch/xpack/esql/expression/function/scalar/nulls/CoalesceLongEvaluator.java" } template { it.properties = doubleProperties - it.inputFile = coalesceInputFile + it.inputFile = coalesceInputFile it.outputFile = "org/elasticsearch/xpack/esql/expression/function/scalar/nulls/CoalesceDoubleEvaluator.java" } template { it.properties = bytesRefProperties - it.inputFile = coalesceInputFile + it.inputFile = coalesceInputFile it.outputFile = "org/elasticsearch/xpack/esql/expression/function/scalar/nulls/CoalesceBytesRefEvaluator.java" } } diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/floats.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/floats.csv-spec index 3505b52e5599e..587876b1401f1 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/floats.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/floats.csv-spec @@ -258,7 +258,7 @@ emp_no:integer | salary_change:double | a1:double cos // tag::cos[] -ROW a=1.8 +ROW a=1.8 | EVAL cos=COS(a) // end::cos[] ; @@ -271,7 +271,7 @@ a:double | cos:double cosh // tag::cosh[] -ROW a=1.8 +ROW a=1.8 | EVAL cosh=COSH(a) // end::cosh[] ; @@ -308,7 +308,7 @@ a:double | acos:double sin // tag::sin[] -ROW a=1.8 +ROW a=1.8 | EVAL sin=SIN(a) // end::sin[] ; @@ -321,7 +321,7 @@ a:double | sin:double sinh // tag::sinh[] -ROW a=1.8 +ROW a=1.8 | EVAL sinh=SINH(a) // end::sinh[] ; @@ -358,7 +358,7 @@ a:double | asin:double tan // tag::tan[] -ROW a=1.8 +ROW a=1.8 | EVAL tan=TAN(a) // end::tan[] ; @@ -371,7 +371,7 @@ a:double | tan:double tanh // tag::tanh[] -ROW a=1.8 +ROW a=1.8 | EVAL tanh=TANH(a) // end::tanh[] ; diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/hash.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/hash.csv-spec index 2614ff09fed06..eaf047cea3f8d 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/hash.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/hash.csv-spec @@ -2,11 +2,12 @@ hash required_capability: hash_function // tag::hash[] -FROM sample_data +FROM sample_data | WHERE message != "Connection error" -| EVAL md5 = hash("md5", message), sha256 = hash("sha256", message) -| KEEP message, md5, sha256; +| EVAL md5 = hash("md5", message), sha256 = hash("sha256", message) +| KEEP message, md5, sha256 // end::hash[] +; ignoreOrder:true // tag::hash-result[] @@ -15,8 +16,8 @@ Connected to 10.1.0.1 | abd7d1ce2bb636842a29246b3512dcae | 6d8372129ad78770f7185 Connected to 10.1.0.2 | 8f8f1cb60832d153f5b9ec6dc828b93f | b0db24720f15857091b3c99f4c4833586d0ea3229911b8777efb8d917cf27e9a Connected to 10.1.0.3 | 912b6dc13503165a15de43304bb77c78 | 75b0480188db8acc4d5cc666a51227eb2bc5b989cd8ca912609f33e0846eff57 Disconnected | ef70e46fd3bbc21e3e1f0b6815e750c0 | 04dfac3671b494ad53fcd152f7a14511bfb35747278aad8ce254a0d6e4ba4718 -; // end::hash-result[] +; hashOfConvertedType @@ -25,7 +26,8 @@ required_capability: hash_function FROM sample_data | WHERE message != "Connection error" | EVAL input = event_duration::STRING, md5 = hash("md5", input), sha256 = hash("sha256", input) -| KEEP message, input, md5, sha256; +| KEEP message, input, md5, sha256 +; ignoreOrder:true message:keyword | input:keyword | md5:keyword | sha256:keyword @@ -114,11 +116,12 @@ md5Hash required_capability: hash_function_aliases_v1 // tag::md5[] -FROM sample_data +FROM sample_data | WHERE message != "Connection error" | EVAL md5 = md5(message) -| KEEP message, md5; +| KEEP message, md5 // end::md5[] +; ignoreOrder:true // tag::md5-result[] @@ -127,8 +130,8 @@ Connected to 10.1.0.1 | abd7d1ce2bb636842a29246b3512dcae Connected to 10.1.0.2 | 8f8f1cb60832d153f5b9ec6dc828b93f Connected to 10.1.0.3 | 912b6dc13503165a15de43304bb77c78 Disconnected | ef70e46fd3bbc21e3e1f0b6815e750c0 -; // end::md5-result[] +; sha1Hash @@ -138,8 +141,9 @@ required_capability: hash_function_aliases_v1 FROM sample_data | WHERE message != "Connection error" | EVAL sha1 = sha1(message) -| KEEP message, sha1; +| KEEP message, sha1 // end::sha1[] +; ignoreOrder:true // tag::sha1-result[] @@ -148,8 +152,8 @@ Connected to 10.1.0.1 | 42b85531a79088036a17759db7d2de292b92f57f Connected to 10.1.0.2 | d30db445da2e9237c9718d0c7e4fb7cbbe9c2cb4 Connected to 10.1.0.3 | 2733848d943809f0b10cad3e980763e88afb9853 Disconnected | 771e05f27b99fd59f638f41a7a4e977b1d4691fe -; // end::sha1-result[] +; sha256Hash required_capability: hash_function_aliases_v1 @@ -158,8 +162,9 @@ required_capability: hash_function_aliases_v1 FROM sample_data | WHERE message != "Connection error" | EVAL sha256 = sha256(message) -| KEEP message, sha256; +| KEEP message, sha256 // end::sha256[] +; ignoreOrder:true // tag::sha256-result[] @@ -168,5 +173,5 @@ Connected to 10.1.0.1 | 6d8372129ad78770f7185554dd39864749a62690216460752d6c075f Connected to 10.1.0.2 | b0db24720f15857091b3c99f4c4833586d0ea3229911b8777efb8d917cf27e9a Connected to 10.1.0.3 | 75b0480188db8acc4d5cc666a51227eb2bc5b989cd8ca912609f33e0846eff57 Disconnected | 04dfac3671b494ad53fcd152f7a14511bfb35747278aad8ce254a0d6e4ba4718 -; // end::sha256-result[] +; diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/ip.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/ip.csv-spec index 4418f7e0aa7ed..ac211c1e6c49a 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/ip.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/ip.csv-spec @@ -207,8 +207,8 @@ eth2 |epsilon |[fe81::cae2:65ff:fece:feb9, fe82::cae2:65ff:fece cdirMatchMultipleArgs //tag::cdirMatchMultipleArgs[] -FROM hosts -| WHERE CIDR_MATCH(ip1, "127.0.0.2/32", "127.0.0.3/32") +FROM hosts +| WHERE CIDR_MATCH(ip1, "127.0.0.2/32", "127.0.0.3/32") | KEEP card, host, ip0, ip1 //end::cdirMatchMultipleArgs[] ; diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/kql-function.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/kql-function.csv-spec index 3a8dafe2075f6..1a376a671762d 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/kql-function.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/kql-function.csv-spec @@ -6,10 +6,10 @@ kqlWithField required_capability: kql_function // tag::kql-with-field[] -FROM books +FROM books | WHERE KQL("author: Faulkner") -| KEEP book_no, author -| SORT book_no +| KEEP book_no, author +| SORT book_no | LIMIT 5 // end::kql-with-field[] ; diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/match-function.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/match-function.csv-spec index 039174a2f0f2a..d3b113870f153 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/match-function.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/match-function.csv-spec @@ -6,10 +6,10 @@ matchWithField required_capability: match_function // tag::match-with-field[] -FROM books +FROM books | WHERE MATCH(author, "Faulkner") -| KEEP book_no, author -| SORT book_no +| KEEP book_no, author +| SORT book_no | LIMIT 5 // end::match-with-field[] ; @@ -696,7 +696,7 @@ required_capability: match_function required_capability: match_function_options // tag::match-with-named-function-params[] -FROM books +FROM books | WHERE MATCH(title, "Hobbit Back Again", {"operator": "AND"}) | KEEP title; // end::match-with-named-function-params[] diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/math.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/math.csv-spec index 56486b8954abe..8ccd78d04e076 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/math.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/math.csv-spec @@ -526,7 +526,7 @@ null | 19.72282600331636 | 10024 | null | 64675 log10 // tag::log10[] -ROW d = 1000.0 +ROW d = 1000.0 | EVAL s = LOG10(d) // end::log10[] ; @@ -1518,7 +1518,7 @@ emp_no:integer | min_plus_max:integer | are_equal:boolean docsAbs //tag::abs[] -ROW number = -1.0 +ROW number = -1.0 | EVAL abs_number = ABS(number) //end::abs[] ; diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/qstr-function.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/qstr-function.csv-spec index 61c0f9a49e7a8..3abed3b545ad5 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/qstr-function.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/qstr-function.csv-spec @@ -188,3 +188,25 @@ book_no:keyword 7140 2714 ; + +qstrWithFieldAndOptions +required_capability: qstr_function +required_capability: query_string_function_options + +// tag::qstr-with-options[] +FROM books +| WHERE QSTR("title: Hobbjt~", {"fuzziness": 2}) +| KEEP book_no, title +| SORT book_no +| LIMIT 5 +// end::qstr-with-options[] +; +ignoreOrder: true + +// tag::qstr-with-options-result[] +book_no:keyword | title:text +4289 | Poems from the Hobbit +6405 | The Hobbit or There and Back Again +7480 | The Hobbit +// end::qstr-with-options-result[] +; diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/string.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/string.csv-spec index 05805201eaf32..90a8afe725b77 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/string.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/string.csv-spec @@ -1973,7 +1973,7 @@ base64Decode#[skip:-8.13.99,reason:new base64 function added in 8.14] required_capability: base64_decode_encode // tag::from_base64[] -row a = "ZWxhc3RpYw==" +row a = "ZWxhc3RpYw==" | eval d = from_base64(a) // end::from_base64[] ; diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/term-function.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/term-function.csv-spec index 0c72cad02eed1..a0af82fd3c64e 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/term-function.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/term-function.csv-spec @@ -9,14 +9,17 @@ required_capability: term_function FROM books | WHERE TERM(author, "gabriel") | KEEP book_no, title -| LIMIT 3; +| LIMIT 3 // end::term-with-field[] +; ignoreOrder:true +// tag::term-with-field-result[] book_no:keyword | title:text 4814 | El Coronel No Tiene Quien Le Escriba / No One Writes to the Colonel (Spanish Edition) 4917 | Autumn of the Patriarch 6380 | La hojarasca (Spanish Edition) +// end::term-with-field-result[] ; termWithKeywordField diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Avg.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Avg.java index 41feee0e63661..9f32a4a740a72 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Avg.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Avg.java @@ -46,7 +46,14 @@ public class Avg extends AggregateFunction implements SurrogateExpression { tag = "docsStatsAvgNestedExpression" ) } ) - public Avg(Source source, @Param(name = "number", type = { "double", "integer", "long" }) Expression field) { + public Avg( + Source source, + @Param( + name = "number", + type = { "double", "integer", "long" }, + description = "Expression that outputs values to average." + ) Expression field + ) { this(source, field, Literal.TRUE); } diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Count.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Count.java index 1d6a88ddcec3c..af2b975b9e417 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Count.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Count.java @@ -55,7 +55,7 @@ public class Count extends AggregateFunction implements ToAggregator, SurrogateE ), @Example( description = "To count the number of times an expression returns `TRUE` use " - + "a <> command to remove rows that shouldn't be included", + + "a <> command to remove rows that shouldn’t be included", file = "stats", tag = "count-where" ), diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/CountDistinct.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/CountDistinct.java index f97ead54c7be9..3957a926d9ad2 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/CountDistinct.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/CountDistinct.java @@ -79,28 +79,27 @@ public class CountDistinct extends AggregateFunction implements OptionalArgument returnType = "long", description = "Returns the approximate number of distinct values.", appendix = """ - [discrete] - [[esql-agg-count-distinct-approximate]] - ==== Counts are approximate + ### Counts are approximate [esql-agg-count-distinct-approximate] Computing exact counts requires loading values into a set and returning its - size. This doesn't scale when working on high-cardinality sets and/or large + size. This doesn’t scale when working on high-cardinality sets and/or large values as the required memory usage and the need to communicate those per-shard sets between nodes would utilize too many resources of the cluster. This `COUNT_DISTINCT` function is based on the - https://static.googleusercontent.com/media/research.google.com/fr//pubs/archive/40671.pdf[HyperLogLog++] + [HyperLogLog++](https://static.googleusercontent.com/media/research.google.com/fr//pubs/archive/40671.pdf) algorithm, which counts based on the hashes of the values with some interesting properties: - include::../../../aggregations/metrics/cardinality-aggregation.asciidoc[tag=explanation] + :::{include} /reference/data-analysis/aggregations/_snippets/search-aggregations-metrics-cardinality-aggregation-explanation.md + ::: The `COUNT_DISTINCT` function takes an optional second parameter to configure - the precision threshold. The precision_threshold options allows to trade memory + 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`. + maximum supported value is `40000`, thresholds above this number will have the + same effect as a threshold of `40000`. The default value is `3000`. """, type = FunctionType.AGGREGATE, examples = { diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Median.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Median.java index 41f3ea0efea06..6ed4019cfeb97 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Median.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Median.java @@ -40,11 +40,10 @@ public class Median extends AggregateFunction implements SurrogateExpression { + "also known as the 50% <>.", note = "Like <>, `MEDIAN` is <>.", appendix = """ - [WARNING] - ==== + ::::{warning} `MEDIAN` is also {wikipedia}/Nondeterministic_algorithm[non-deterministic]. This means you can get slightly different results using the same data. - ====""", + ::::""", type = FunctionType.AGGREGATE, examples = { @Example(file = "stats_percentile", tag = "median"), @@ -56,7 +55,14 @@ public class Median extends AggregateFunction implements SurrogateExpression { tag = "docsStatsMedianNestedExpression" ), } ) - public Median(Source source, @Param(name = "number", type = { "double", "integer", "long" }) Expression field) { + public Median( + Source source, + @Param( + name = "number", + type = { "double", "integer", "long" }, + description = "Expression that outputs values to calculate the median of." + ) Expression field + ) { this(source, field, Literal.TRUE); } diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MedianAbsoluteDeviation.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MedianAbsoluteDeviation.java index 5c7db4e31502a..f25d95a7df8c8 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MedianAbsoluteDeviation.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MedianAbsoluteDeviation.java @@ -45,16 +45,15 @@ public class MedianAbsoluteDeviation extends NumericAggregate implements Surroga + "or may not be normally distributed. For such data it can be more descriptive " + "than standard deviation." + "\n\n" - + "It is calculated as the median of each data point's deviation from the median of " + + "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 <>.", appendix = """ - [WARNING] - ==== + ::::{warning} `MEDIAN_ABSOLUTE_DEVIATION` is also {wikipedia}/Nondeterministic_algorithm[non-deterministic]. This means you can get slightly different results using the same data. - ====""", + ::::""", type = FunctionType.AGGREGATE, examples = { @Example(file = "median_absolute_deviation", tag = "median-absolute-deviation"), diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Percentile.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Percentile.java index fb61db603486b..b8758d3e3885d 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Percentile.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Percentile.java @@ -54,18 +54,15 @@ public class Percentile extends NumericAggregate implements SurrogateExpression + "For example, the 95th percentile is the value which is greater than 95% of the " + "observed values and the 50th percentile is the `MEDIAN`.", appendix = """ - [discrete] - [[esql-percentile-approximate]] - ==== `PERCENTILE` is (usually) approximate + ### `PERCENTILE` is (usually) approximate [esql-percentile-approximate] - include::../../../aggregations/metrics/percentile-aggregation.asciidoc[tag=approximate] + :::{include} /reference/data-analysis/aggregations/_snippets/search-aggregations-metrics-percentile-aggregation-approximate.md + ::: - [WARNING] - ==== + ::::{warning} `PERCENTILE` is also {wikipedia}/Nondeterministic_algorithm[non-deterministic]. This means you can get slightly different results using the same data. - ==== - """, + ::::""", type = FunctionType.AGGREGATE, examples = { @Example(file = "stats_percentile", tag = "percentile"), diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/StdDev.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/StdDev.java index 19365c3166d13..10e604de89b3c 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/StdDev.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/StdDev.java @@ -43,7 +43,7 @@ public class StdDev extends AggregateFunction implements ToAggregator { @Example(file = "stats", tag = "stdev"), @Example( description = "The expression can use inline functions. For example, to calculate the standard " - + "deviation of each employee's maximum salary changes, first use `MV_MAX` on each row, " + + "deviation of each employee’s maximum salary changes, first use `MV_MAX` on each row, " + "and then use `STD_DEV` on the result", file = "stats", tag = "docsStatsStdDevNestedExpression" diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Sum.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Sum.java index f8fe28d85a929..69795d06ea214 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Sum.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Sum.java @@ -54,7 +54,7 @@ public class Sum extends NumericAggregate implements SurrogateExpression { @Example(file = "stats", tag = "sum"), @Example( description = "The expression can use inline functions. For example, to calculate " - + "the sum of each employee's maximum salary changes, apply the " + + "the sum of each employee’s maximum salary changes, apply the " + "`MV_MAX` function to each row and then sum the results", file = "stats", tag = "docsStatsSumNestedExpression" diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java index 6ffee21411acb..5e05c3a448295 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java @@ -73,17 +73,16 @@ public class Values extends AggregateFunction implements ToAggregator { "long", "version" }, preview = true, - description = "Returns all values in a group as a multivalued field. The order of the returned values isn't guaranteed. " + description = "Returns all values in a group as a multivalued field. The order of the returned values isn’t guaranteed. " + "If you need the values returned in order use <>.", appendix = """ - [WARNING] - ==== - This can use a significant amount of memory and ES|QL doesn't yet + ::::{warning} + This can use a significant amount of memory and ES|QL doesn’t yet grow aggregations beyond memory. So this aggregation will work until it is used to collect more values than can fit into memory. Once it collects too many values it will fail the query with - a <>. - ====""", + a [Circuit Breaker Error](docs-content://troubleshoot/elasticsearch/circuit-breaker-errors.md). + ::::""", type = FunctionType.AGGREGATE, examples = @Example(file = "string", tag = "values-grouped") ) diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/package-info.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/package-info.java index 9f08401a42dd1..bf12542d9331d 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/package-info.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/package-info.java @@ -12,7 +12,7 @@ *

Guide to adding new aggregate function

*
    *
  1. - * Aggregation functions are more complex than scalar functions, so it's a good idea to discuss + * Aggregation functions are more complex than scalar functions, so it’s a good idea to discuss * the new function with the ESQL team before starting to implement it. *

    * You may also discuss its implementation, as aggregations may require special performance considerations. @@ -27,7 +27,7 @@ *

  2. * Pick one of the csv-spec files in {@code x-pack/plugin/esql/qa/testFixtures/src/main/resources/} * and add a test for the function you want to write. These files are roughly themed but there - * isn't a strong guiding principle in the organization. + * isn’t a strong guiding principle in the organization. *
    3. *
  3. * Rerun the {@code CsvTests} and watch your new test fail. @@ -72,7 +72,7 @@ * Implement {@link org.elasticsearch.xpack.esql.expression.SurrogateExpression}, and its required * {@link org.elasticsearch.xpack.esql.expression.SurrogateExpression#surrogate()} method. *

    - * It's used to be able to fold the aggregation when it receives only literals, + * It’s used to be able to fold the aggregation when it receives only literals, * or when the aggregation can be simplified. *

    *
    4. @@ -192,7 +192,7 @@ *
  4. * After completing your template, run the generation with {@code ./gradlew :x-pack:plugin:esql:compute:compileJava}. *

    - * You may need to tweak some import orders per type so they don't raise warnings. + * You may need to tweak some import orders per type so they don’t raise warnings. *

    *
    5. *
diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/FullTextFunction.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/FullTextFunction.java index 7d329d4baf5c9..b3aed1e3af0a2 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/FullTextFunction.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/FullTextFunction.java @@ -53,7 +53,7 @@ /** * Base class for full-text functions that use ES queries to match documents. - * These functions needs to be pushed down to Lucene queries to be executed - there's no Evaluator for them, but depend on + * These functions needs to be pushed down to Lucene queries to be executed - there’s no Evaluator for them, but depend on * {@link org.elasticsearch.xpack.esql.optimizer.LocalPhysicalPlanOptimizer} to rewrite them into Lucene queries. */ public abstract class FullTextFunction extends Function diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Match.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Match.java index e5fb46209c5e8..9c9be72f52bdf 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Match.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Match.java @@ -120,7 +120,7 @@ public class Match extends FullTextFunction implements OptionalArgument, PostOpt protected final Expression field; - // Options for match function. They don't need to be serialized as the data nodes will retrieve them from the query builder + // Options for match function. They don’t need to be serialized as the data nodes will retrieve them from the query builder private final transient Expression options; public static final Map ALLOWED_OPTIONS = Map.ofEntries( diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchOperator.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchOperator.java index 38b5022b34351..5a613407d273f 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchOperator.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchOperator.java @@ -19,7 +19,7 @@ /** * This class performs a {@link org.elasticsearch.xpack.esql.querydsl.query.MatchQuery} using an operator. - * This is used as a convenience for generating documentation and for error message purposes - it's a way to represent + * This is used as a convenience for generating documentation and for error message purposes - it’s a way to represent * the match operator in the function syntax. * Serialization is provided as a way to pass the corresponding tests - serialization must be done to a Match class. */ diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Bucket.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Bucket.java index ac54e3d6484d5..fb6a17819c5ac 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Bucket.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Bucket.java @@ -109,16 +109,18 @@ another in which the bucket size is provided directly (two parameters). file = "bucket", tag = "docsBucketMonth", explanation = """ - 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.""" + 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.""" ), @Example( description = "Combine `BUCKET` with an <> to create a histogram:", file = "bucket", tag = "docsBucketMonthlyHistogram", explanation = """ - NOTE: `BUCKET` does not create buckets that don't match any documents. - That's why this example is missing `1985-03-01` and other dates.""" + ::::{note} + `BUCKET` does not create buckets that don’t match any documents. + That’s why this example is missing `1985-03-01` and other dates. + ::::""" ), @Example( description = """ @@ -127,22 +129,26 @@ another in which the bucket size is provided directly (two parameters). file = "bucket", tag = "docsBucketWeeklyHistogram", explanation = """ - NOTE: `BUCKET` does not filter any rows. It only uses the provided range to pick a good bucket size. + ::::{note} + `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`BUCKET` with <> to filter rows.""" + Combine `BUCKET` with <> to filter rows. + ::::""" ), @Example(description = """ If the desired bucket size is known in advance, simply provide it as the second argument, leaving the range out:""", file = "bucket", tag = "docsBucketWeeklyHistogramWithSpan", explanation = """ - NOTE: When providing the bucket size as the second parameter, it must be a time - duration or date period."""), + ::::{note} + When providing the bucket size as the second parameter, it must be a time + duration or date period. + ::::"""), @Example( description = "`BUCKET` can also operate on numeric fields. For example, to create a salary histogram:", file = "bucket", tag = "docsBucketNumeric", explanation = """ 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.""" + You have to find the `min` and `max` separately. {{esql}} doesn’t yet have an easy way to do that automatically.""" ), @Example(description = """ The range can be omitted if the desired bucket size is known in advance. Simply @@ -169,7 +175,7 @@ another in which the bucket size is provided directly (two parameters). @Example( description = """ Sometimes you need to change the start value of each bucket by a given duration (similar to date histogram - aggregation's <> parameter). To do so, you will need to + aggregation’s <> parameter). To do so, you will need to take into account how the language handles expressions within the `STATS` command: if these contain functions or arithmetic operators, a virtual `EVAL` is inserted before and/or after the `STATS` command. Consequently, a double compensation is needed to adjust the bucketed date value before the aggregation and then again after. For instance, diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java index 6cad20b4e28ba..4d80e7dd04359 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java @@ -52,9 +52,9 @@ public class Categorize extends GroupingFunction { detailedDescription = """ `CATEGORIZE` has the following limitations: - * can't be used within other expressions - * can't be used with multiple groupings - * can't be used or referenced within aggregate functions""", + * can’t be used within other expressions + * can’t be used with multiple groupings + * can’t be used or referenced within aggregate functions""", examples = { @Example( file = "docs", @@ -96,7 +96,7 @@ public boolean foldable() { @Override public Nullability nullable() { - // Null strings and strings that don't produce tokens after analysis lead to null values. + // Null strings and strings that don’t produce tokens after analysis lead to null values. // This includes empty strings, only whitespace, (hexa)decimal numbers and stopwords. return Nullability.TRUE; } diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/conditional/Case.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/conditional/Case.java index 04da04e1b3927..fff1189207cc7 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/conditional/Case.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/conditional/Case.java @@ -117,7 +117,7 @@ public Case( "text", "unsigned_long", "version" }, - description = "The value that's returned when the corresponding condition is the first to evaluate to `true`. " + description = "The value that’s returned when the corresponding condition is the first to evaluate to `true`. " + "The default value is returned when no condition matches." ) List rest ) { @@ -266,7 +266,7 @@ public boolean foldable() { * {@code EVAL c=CASE(b, bar, bort)}. */ public Expression partiallyFold(FoldContext ctx) { - // TODO don't throw away the results of any `fold`. That might mean looking for literal TRUE on the conditions. + // TODO don’t throw away the results of any `fold`. That might mean looking for literal TRUE on the conditions. List newChildren = new ArrayList<>(children().size()); boolean modified = false; for (Condition condition : conditions) { @@ -288,7 +288,7 @@ public Expression partiallyFold(FoldContext ctx) { * The multivalued field will make a warning, but eventually * become null. And null will become false. So cases 2-4 are * the same. In those cases we fold the entire condition - * away, returning just what ever's remaining in the CASE. + * away, returning just what ever’s remaining in the CASE. */ newChildren.add(condition.value); return finishPartialFold(newChildren); @@ -333,7 +333,7 @@ public ConditionEvaluator apply(DriverContext driverContext) { return new ConditionEvaluator( /* * We treat failures as null just like any other failure. - * It's just that we then *immediately* convert it to + * It’s just that we then *immediately* convert it to * true or false using the tri-valued boolean logic stuff. * And that makes it into false. This is, *exactly* what * happens in PostgreSQL and MySQL and SQLite: @@ -422,8 +422,8 @@ public Block eval(Page page) { * on the right hand side is slow we skip it. * * And it'd be good if that lazy evaluation were fast. But this - * implementation isn't. It's fairly simple - running position at - * a time - but it's not at all fast. + * implementation isn’t . It’s fairly simple - running position at + * a time - but it’s not at all fast. */ int positionCount = page.getPositionCount(); try (Block.Builder result = resultType.newBlockBuilder(positionCount, blockFactory)) { @@ -525,7 +525,7 @@ public Block eval(Page page) { for (int p = 0; p < lhs.getPositionCount(); p++) { if (lhsOrRhs.mask().getBoolean(p)) { // TODO Copy the per-type specialization that COALESCE has. - // There's also a slowdown because copying from a block checks to see if there are any nulls and that's slow. + // There’s also a slowdown because copying from a block checks to see if there are any nulls and that’s slow. // Vectors do not, so this still shows as fairly fast. But not as fast as the per-type unrolling. builder.copyFrom(lhs, p, p + 1); } else { diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToBoolean.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToBoolean.java index ad73de7829692..8f4abeb38628d 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToBoolean.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToBoolean.java @@ -56,9 +56,9 @@ public class ToBoolean extends AbstractConvertFunction { returnType = "boolean", 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*. - The numerical value of *0* will be converted to *false*, anything else will be converted to *true*.""", + 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`. + The numerical value of `0` will be converted to `false`, anything else will be converted to `true`.""", examples = @Example(file = "boolean", tag = "to_boolean") ) public ToBoolean( diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDatetime.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDatetime.java index f8fe663b9086c..b25d9b2b99095 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDatetime.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDatetime.java @@ -58,14 +58,14 @@ public class ToDatetime extends AbstractConvertFunction { returnType = "date", 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'`. + 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 <>.""", note = "Note that when converting from nanosecond resolution to millisecond resolution with this function, the nanosecond date is " + "truncated, not rounded.", examples = { @Example(file = "date", tag = "to_datetime-str", explanation = """ Note that in this example, the last value in the source multi-valued field has not been converted. - The reason being that if the date format is not respected, the conversion will result in a *null* value. + The reason being that if the date format is not respected, the conversion will result in a `null` value. When this happens a _Warning_ header is added to the response. The header will provide information on the source of the failure: diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDouble.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDouble.java index 67b7af73576eb..76320920359b3 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDouble.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDouble.java @@ -59,10 +59,10 @@ public class ToDouble extends AbstractConvertFunction { description = """ Converts an input value to a double value. 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. Boolean *true* will be converted to double *1.0*, *false* to *0.0*.""", + converted to double. Boolean `true` will be converted to double `1.0`, `false` to `0.0`.""", examples = @Example(file = "floats", tag = "to_double-str", explanation = """ - 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. + 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."` diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToIP.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToIP.java index cd161744bfc86..2b8597f56ee16 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToIP.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToIP.java @@ -43,8 +43,8 @@ public class ToIP extends AbstractConvertFunction { returnType = "ip", description = "Converts an input string to an IP value.", examples = @Example(file = "ip", tag = "to_ip", explanation = """ - 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. + 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/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToInteger.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToInteger.java index d316b6eb46c38..910d471506436 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToInteger.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToInteger.java @@ -64,10 +64,10 @@ public class ToInteger extends AbstractConvertFunction { Converts an input value to an integer value. 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. - Boolean *true* will be converted to integer *1*, *false* to *0*.""", + Boolean `true` will be converted to integer `1`, `false` to `0`.""", examples = @Example(file = "ints", tag = "to_int-long", explanation = """ Note that in this example, the last value of the multi-valued field cannot be converted as an integer. - When this happens, the result is a *null* value. In this case a _Warning_ header is added to the response. + 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:61: evaluation of [TO_INTEGER(long)] failed, treating result as null. Only first 20 failures recorded."` diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToLong.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToLong.java index dbfb52b408b44..b52e74609327e 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToLong.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToLong.java @@ -61,10 +61,10 @@ public class ToLong extends AbstractConvertFunction { description = """ Converts an input value to a long value. 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*.""", + Boolean `true` will be converted to long `1`, `false` to `0`.""", examples = @Example(file = "ints", tag = "to_long-str", explanation = """ - 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. + 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:113: evaluation of [TO_LONG(str3)] failed, treating result as null. Only first 20 failures recorded."` diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToUnsignedLong.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToUnsignedLong.java index ea06793f7adb6..93df809d34c1e 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToUnsignedLong.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToUnsignedLong.java @@ -63,10 +63,10 @@ public class ToUnsignedLong extends AbstractConvertFunction { description = """ Converts an input value to an unsigned long value. 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*.""", + Boolean `true` will be converted to unsigned long `1`, `false` to `0`.""", examples = @Example(file = "ints", tag = "to_unsigned_long-str", explanation = """ - 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. + 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:133: evaluation of [TO_UL(str3)] failed, treating result as null. Only first 20 failures recorded."` diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/DateDiff.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/DateDiff.java index 4d843ea7180a9..35785d46fba0a 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/DateDiff.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/DateDiff.java @@ -134,33 +134,29 @@ public static Part resolve(String dateTimeUnit) { 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.""", detailedDescription = """ - [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 - |=== - - Note that while there is an overlap between the function's supported units and - {esql}'s supported time span literals, these sets are distinct and not + **Datetime difference units** + + | unit | 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 | + + Note that while there is an overlap between the function’s supported units and + {{esql}}’s supported time span literals, these sets are distinct and not interchangeable. Similarly, the supported abbreviations are conveniently shared with implementations of this function in other established products and not - necessarily common with the date-time nomenclature used by {es}.""", + necessarily common with the date-time nomenclature used by {{es}}.""", examples = { @Example(file = "date", tag = "docsDateDiff"), @Example(description = """ When subtracting in calendar units - like year, month a.s.o. - only the fully elapsed units are counted. To avoid this and obtain also remainders, simply switch to the next smaller unit and do the date math accordingly. diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/DateExtract.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/DateExtract.java index 7d8648a672ff8..d617546258f5f 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/DateExtract.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/DateExtract.java @@ -60,7 +60,7 @@ public class DateExtract extends EsqlConfigurationFunction { ) public DateExtract( Source source, - // Need to replace the commas in the description here with semi-colon as there's a bug in the CSV parser + // Need to replace the commas in the description here with semi-colon as there’s a bug in the CSV parser // used in the CSVTests and fixing it is not trivial @Param(name = "datePart", type = { "keyword", "text" }, description = """ Part of the date to extract.\n @@ -69,7 +69,7 @@ public DateExtract( `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] + Refer to {javadoc8}/java/time/temporal/ChronoField.html[java.time.temporal.ChronoField] for a description of these values.\n If `null`, the function returns `null`.""") Expression chronoFieldExp, @Param( @@ -120,7 +120,7 @@ public ExpressionEvaluator.Factory toEvaluator(ToEvaluator toEvaluator) { "Unsupported field type [" + field().dataType().name() + "]. " - + "If you're seeing this, there's a bug in DateExtract.resolveType" + + "If you're seeing this, there’s a bug in DateExtract.resolveType" ); }; @@ -152,7 +152,7 @@ public ExpressionEvaluator.Factory toEvaluator(ToEvaluator toEvaluator) { } private ChronoField chronoField(FoldContext ctx) { - // chronoField's never checked (the return is). The foldability test is done twice and type is checked in resolveType() already. + // chronoField’s never checked (the return is). The foldability test is done twice and type is checked in resolveType() already. // TODO: move the slimmed down code here to toEvaluator? if (chronoField == null) { Expression field = children().get(0); diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/DateParse.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/DateParse.java index 7c38b54ed232b..ef1acbc395308 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/DateParse.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/DateParse.java @@ -57,8 +57,8 @@ public DateParse( Source source, @Param(name = "datePattern", type = { "keyword", "text" }, description = """ The date format. Refer to the - https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html[`DateTimeFormatter` - documentation] for the syntax. If `null`, the function returns `null`.""", optional = true) Expression first, + {javadoc14}/java.base/java/time/format/DateTimeFormatter.html[`DateTimeFormatter` documentation] for the syntax. + If `null`, the function returns `null`.""", optional = true) Expression first, @Param( name = "dateString", type = { "keyword", "text" }, diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/DateTrunc.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/DateTrunc.java index 7983c38cc4288..9153bb075f70b 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/DateTrunc.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/DateTrunc.java @@ -76,7 +76,7 @@ public interface DateTruncFactoryProvider { ) public DateTrunc( Source source, - // Need to replace the commas in the description here with semi-colon as there's a bug in the CSV parser + // Need to replace the commas in the description here with semi-colon as there’s a bug in the CSV parser // used in the CSVTests and fixing it is not trivial @Param( name = "interval", @@ -138,7 +138,7 @@ static long processDatetime(long fieldVal, @Fixed Rounding.Prepared rounding) { @Evaluator(extraName = "DateNanos") static long processDateNanos(long fieldVal, @Fixed Rounding.Prepared rounding) { - // Currently, ES|QL doesn't support rounding to sub-millisecond values, so it's safe to cast before rounding. + // Currently, ES|QL doesn’t support rounding to sub-millisecond values, so it’s safe to cast before rounding. return DateUtils.toNanoSeconds(rounding.round(DateUtils.toMilliSeconds(fieldVal))); } diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/AbstractTrigonometricFunction.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/AbstractTrigonometricFunction.java index f44e7b029643c..20b978afcaeca 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/AbstractTrigonometricFunction.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/AbstractTrigonometricFunction.java @@ -33,7 +33,7 @@ protected AbstractTrigonometricFunction(StreamInput in) throws IOException { } /** - * Build an evaluator for this function given the evaluator for it's input. + * Build an evaluator for this function given the evaluator for it’s input. */ protected abstract EvalOperator.ExpressionEvaluator.Factory doubleEvaluator(EvalOperator.ExpressionEvaluator.Factory field); diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Cast.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Cast.java index f4936f8ee37c6..44a2986358319 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Cast.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Cast.java @@ -59,7 +59,7 @@ public static ExpressionEvaluator.Factory cast(Source source, DataType current, } private static EsqlIllegalArgumentException cantCast(DataType current, DataType required) { - return new EsqlIllegalArgumentException("can't process [" + current.typeName() + " -> " + required.typeName() + "]"); + return new EsqlIllegalArgumentException("can’t process [" + current.typeName() + " -> " + required.typeName() + "]"); } @Evaluator(extraName = "IntToLong") diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/DoubleConstantFunction.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/DoubleConstantFunction.java index 8c42fb22db0ba..1962622f525cd 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/DoubleConstantFunction.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/DoubleConstantFunction.java @@ -14,7 +14,7 @@ import org.elasticsearch.xpack.esql.core.type.DataType; /** - * Function that emits constants, like Euler's number. + * Function that emits constants, like Euler’s number. */ public abstract class DoubleConstantFunction extends ScalarFunction { protected DoubleConstantFunction(Source source) { diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/E.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/E.java index e1eceef7ed1f5..96884e32d9166 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/E.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/E.java @@ -21,14 +21,14 @@ import java.util.List; /** - * Function that emits Euler's number. + * Function that emits Euler’s number. */ public class E extends DoubleConstantFunction { public static final NamedWriteableRegistry.Entry ENTRY = new NamedWriteableRegistry.Entry(Expression.class, "E", E::new); @FunctionInfo( returnType = "double", - description = "Returns {wikipedia}/E_(mathematical_constant)[Euler's number].", + description = "Returns {wikipedia}/E_(mathematical_constant)[Euler’s number].", examples = @Example(file = "math", tag = "e") ) public E(Source source) { diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Pi.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Pi.java index 32b7a0ab88b4e..1d2723d89af58 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Pi.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Pi.java @@ -28,7 +28,7 @@ public class Pi extends DoubleConstantFunction { @FunctionInfo( returnType = "double", - description = "Returns {wikipedia}/Pi[Pi], the ratio of a circle's circumference to its diameter.", + description = "Returns {wikipedia}/Pi[Pi], the ratio of a circle’s circumference to its diameter.", examples = @Example(file = "math", tag = "pi") ) public Pi(Source source) { diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Tau.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Tau.java index 1a7669b7391e1..c64f508bf2331 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Tau.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Tau.java @@ -30,7 +30,7 @@ public class Tau extends DoubleConstantFunction { @FunctionInfo( returnType = "double", - description = "Returns the https://tauday.com/tau-manifesto[ratio] of a circle's circumference to its radius.", + description = "Returns the [ratio](https://tauday.com/tau-manifesto) of a circle’s circumference to its radius.", examples = @Example(file = "math", tag = "tau") ) public Tau(Source source) { diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/AbstractMultivalueFunction.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/AbstractMultivalueFunction.java index a32761cfd9948..09532e348d886 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/AbstractMultivalueFunction.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/AbstractMultivalueFunction.java @@ -75,8 +75,8 @@ protected AbstractEvaluator(DriverContext driverContext, EvalOperator.Expression /** * Called when evaluating a {@link Block} that does not contain null values. - * It's useful to specialize this from {@link #evalNullable} because it knows - * that it's producing an "array vector" because it only ever emits single + * It’s useful to specialize this from {@link #evalNullable} because it knows + * that it’s producing an "array vector" because it only ever emits single * valued fields and no null values. Building an array vector directly is * generally faster than building it via a {@link Block.Builder}. * diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvConcat.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvConcat.java index 26211258e6ca6..cae366ed7d08d 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvConcat.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvConcat.java @@ -121,8 +121,8 @@ public String toString() { } /** - * Evaluator for {@link MvConcat}. Not generated and doesn't extend from - * {@link AbstractMultivalueFunction.AbstractEvaluator} because it's just + * Evaluator for {@link MvConcat}. Not generated and doesn’t extend from + * {@link AbstractMultivalueFunction.AbstractEvaluator} because it’s just * too different from all the other mv operators: *
    *
  • It takes an extra parameter - the delimiter
    • @@ -146,7 +146,7 @@ public final Block eval(Page page) { try (BytesRefBlock fieldVal = (BytesRefBlock) field.eval(page); BytesRefBlock delimVal = (BytesRefBlock) delim.eval(page)) { int positionCount = page.getPositionCount(); try (BytesRefBlock.Builder builder = context.blockFactory().newBytesRefBlockBuilder(positionCount)) { - BytesRefBuilder work = new BytesRefBuilder(); // TODO BreakingBytesRefBuilder so we don't blow past circuit breakers + BytesRefBuilder work = new BytesRefBuilder(); // TODO BreakingBytesRefBuilder so we don’t blow past circuit breakers BytesRef fieldScratch = new BytesRef(); BytesRef delimScratch = new BytesRef(); for (int p = 0; p < positionCount; p++) { diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvDedupe.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvDedupe.java index 4d85d3a6a8d2e..2826335403075 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvDedupe.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvDedupe.java @@ -49,7 +49,7 @@ public class MvDedupe extends AbstractMultivalueFunction { "unsigned_long", "version" }, description = "Remove duplicate values from a multivalued field.", - note = "`MV_DEDUPE` may, but won't always, sort the values in the column.", + note = "`MV_DEDUPE` may, but won’t always, sort the values in the column.", examples = @Example(file = "string", tag = "mv_dedupe") ) public MvDedupe( diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvFirst.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvFirst.java index 957c74883ffdf..a741fbd1175b3 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvFirst.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvFirst.java @@ -61,9 +61,9 @@ public class MvFirst extends AbstractMultivalueFunction { multivalued columns in a known order like <>.""", detailedDescription = """ The order that <> are read from - underlying storage is not guaranteed. It is *frequently* ascending, but don't + 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 + `MV_FIRST`. `MV_MIN` has optimizations for sorted values so there isn’t a performance benefit to `MV_FIRST`.""", examples = @Example(file = "string", tag = "mv_first") ) diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvLast.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvLast.java index fedbc1934d1be..e65d7fca2221b 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvLast.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvLast.java @@ -61,9 +61,9 @@ public class MvLast extends AbstractMultivalueFunction { columns in a known order like <>.""", detailedDescription = """ The order that <> are read from - underlying storage is not guaranteed. It is *frequently* ascending, but don't + 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 + `MV_LAST`. `MV_MAX` has optimizations for sorted values so there isn’t a performance benefit to `MV_LAST`.""", examples = @Example(file = "string", tag = "mv_last") ) diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvMedian.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvMedian.java index 42510a5685de3..519cb3025927e 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvMedian.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvMedian.java @@ -49,7 +49,7 @@ public class MvMedian extends AbstractMultivalueFunction { @Example( description = "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*:", + + "the average rounds **down**:", file = "math", tag = "mv_median_round_down" ) } diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvMedianAbsoluteDeviation.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvMedianAbsoluteDeviation.java index 9bdfd1a2ccafc..46552742ca9a5 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvMedianAbsoluteDeviation.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvMedianAbsoluteDeviation.java @@ -48,7 +48,7 @@ public class MvMedianAbsoluteDeviation extends AbstractMultivalueFunction { returnType = { "double", "integer", "long", "unsigned_long" }, description = "Converts a multivalued field into a single valued field containing the median absolute deviation." + "\n\n" - + "It is calculated as the median of each data point's deviation from the median of " + + "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 = "If the field has an even number of values, " @@ -138,7 +138,7 @@ static int finishInts(Longs longs) { /** * Similar to the code in `finish`, for when the values are in ascending order. The major differences are: - * - As values are sorted, we don't need to sort them for the first median calculation. + * - As values are sorted, we don’t need to sort them for the first median calculation. * - We take the values directly from the block instead of from the helper object. */ static int ascending(Longs longs, IntBlock values, int firstValue, int count) { @@ -187,7 +187,7 @@ static long finish(Longs longs) { /** * Similar to the code in `finish`, for when the values are in ascending order. The major differences are: - * - As values are sorted, we don't need to sort them for the first median calculation. + * - As values are sorted, we don’t need to sort them for the first median calculation. * - We take the values directly from the block instead of from the helper object. */ static long ascending(Longs longs, LongBlock values, int firstValue, int count) { @@ -250,7 +250,7 @@ static double finish(Doubles doubles) { /** * Similar to the code in `finish`, for when the values are in ascending order. The major differences are: - * - As values are sorted, we don't need to sort them for the first median calculation. + * - As values are sorted, we don’t need to sort them for the first median calculation. * - We take the values directly from the block instead of from the helper object. */ static double ascending(Doubles doubles, DoubleBlock values, int firstValue, int count) { @@ -310,7 +310,7 @@ static long finishUnsignedLong(Longs longs) { /** * Similar to the code in `finish`, for when the values are in ascending order. The major differences are: - * - As values are sorted, we don't need to sort them for the first median calculation. + * - As values are sorted, we don’t need to sort them for the first median calculation. * - We take the values directly from the block instead of from the helper object. */ static long ascendingUnsignedLong(Longs longs, LongBlock values, int firstValue, int count) { diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvPSeriesWeightedSum.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvPSeriesWeightedSum.java index d5093964145b7..a7cbb4daae16f 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvPSeriesWeightedSum.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvPSeriesWeightedSum.java @@ -65,8 +65,8 @@ public MvPSeriesWeightedSum( @Param( name = "p", type = { "double" }, - description = "It is a constant number that represents the 'p' parameter in the P-Series. " - + "It impacts every element's contribution to the weighted sum." + description = "It is a constant number that represents the *p* parameter in the P-Series. " + + "It impacts every element’s contribution to the weighted sum." ) Expression p ) { super(source, Arrays.asList(field, p)); @@ -95,7 +95,7 @@ protected TypeResolution resolveType() { } if (p.dataType() == NULL) { - // If the type is `null` this parameter doesn't have to be foldable. It's effectively foldable anyway. + // If the type is `null` this parameter doesn’t have to be foldable. It’s effectively foldable anyway. // TODO figure out if the tests are wrong here, or if null is really different from foldable null return resolution; } diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvPercentile.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvPercentile.java index 4e4aee307f1c7..6798f45665aee 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvPercentile.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvPercentile.java @@ -439,7 +439,7 @@ private static long calculateLongPercentile(double fraction, long lowerValue, lo * Calculates a percentile for a double avoiding overflows. *

    * If the values are too separated (negative + positive), it uses a slightly different approach. - * This approach would fail if the values are big but not separated, so it's only used in this case. + * This approach would fail if the values are big but not separated, so it’s only used in this case. *

    */ private static double calculateDoublePercentile(double fraction, double lowerValue, double upperValue) { diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvSlice.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvSlice.java index 3bffb7853d3b4..e71914e3fa236 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvSlice.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvSlice.java @@ -75,7 +75,7 @@ public class MvSlice extends EsqlScalarFunction implements OptionalArgument, Eva in a known order like <> or <>.""", detailedDescription = """ The order that <> are read from - underlying storage is not guaranteed. It is *frequently* ascending, but don't + underlying storage is not guaranteed. It is **frequently** ascending, but don’t rely on that.""", examples = { @Example(file = "ints", tag = "mv_slice_positive"), @Example(file = "ints", tag = "mv_slice_negative") } ) diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/nulls/Coalesce.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/nulls/Coalesce.java index a426a14b0a319..171fb25bf69e9 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/nulls/Coalesce.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/nulls/Coalesce.java @@ -170,16 +170,16 @@ protected TypeResolution resolveType() { @Override public Nullability nullable() { - // If any of the children aren't nullable then this isn't. + // If any of the children aren’t nullable then this isn’t . for (Expression c : children()) { if (c.nullable() == Nullability.FALSE) { return Nullability.FALSE; } } /* - * Otherwise let's call this one "unknown". If we returned TRUE here + * Otherwise let’s call this one "unknown". If we returned TRUE here * an optimizer rule would replace this with null if any of our children - * fold to null. We don't want that at all. + * fold to null. We don’t want that at all. */ return Nullability.UNKNOWN; } @@ -211,7 +211,7 @@ public ExpressionEvaluator.Factory toEvaluator(ToEvaluator toEvaluator) { case NULL -> EvalOperator.CONSTANT_NULL_FACTORY; case UNSUPPORTED, SHORT, BYTE, DATE_PERIOD, OBJECT, DOC_DATA_TYPE, SOURCE, TIME_DURATION, FLOAT, HALF_FLOAT, TSID_DATA_TYPE, SCALED_FLOAT, PARTIAL_AGG, AGGREGATE_METRIC_DOUBLE -> throw new UnsupportedOperationException( - dataType() + " can't be coalesced" + dataType() + " can’t be coalesced" ); }; } diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/package-info.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/package-info.java index d0b646a622b60..c119ed71dfcdb 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/package-info.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/package-info.java @@ -19,7 +19,7 @@ *
      *
    1. Fork the Elasticsearch repo.
      2. *
    2. Clone your fork locally.
      3. - *
    3. Add Elastic's remote, it should look a little like: + *
    4. Add Elastic’s remote, it should look a little like: * 
      {@code
  * [remote "elastic"]
  * url = git@github.com:elastic/elasticsearch.git
@@ -42,20 +42,20 @@
  *         from within Intellij or, alternatively, via Gradle:
  *         {@code ./gradlew :x-pack:plugin:esql:test --tests "org.elasticsearch.xpack.esql.CsvTests"}
  *         IntelliJ will take a few minutes to compile everything but the test itself should take only a few seconds.
- *         This is a fast path to running ESQL's integration tests.
+ *         This is a fast path to running ESQL’s integration tests.
  *
      5. *
    5. * Pick one of the csv-spec files in {@code x-pack/plugin/esql/qa/testFixtures/src/main/resources/} * and add a test for the function you want to write. These files are roughly themed but there - * isn't a strong guiding principle in the organization. + * isn’t a strong guiding principle in the organization. *
      6. *
    6. - * Rerun the {@code CsvTests} and watch your new test fail. Yay, TDD doing it's job. + * Rerun the {@code CsvTests} and watch your new test fail. Yay, TDD doing it’s job. *
      7. *
    7. * Find a function in this package similar to the one you are working on and copy it to build - * yours. There's some ceremony required in each function class to make it constant foldable, - * and return the right types. Take a stab at these, but don't worry too much about getting + * yours. There’s some ceremony required in each function class to make it constant foldable, + * and return the right types. Take a stab at these, but don’t worry too much about getting * it right. Your function might extend from one of several abstract base classes, all of * those are fine for this guide, but might have special instructions called out later. * Known good base classes: @@ -92,7 +92,7 @@ *
    8. * Once your evaluator is generated you can have your function return it, * generally by implementing {@link org.elasticsearch.xpack.esql.evaluator.mapper.EvaluatorMapper#toEvaluator}. - * It's possible that your abstract base class implements that function and + * It’s possible that your abstract base class implements that function and * will need you to implement something else: *
        *
      • {@link org.elasticsearch.xpack.esql.expression.function.scalar.convert.AbstractConvertFunction}: {@code factories}
        • @@ -113,22 +113,22 @@ * and a deserializing constructor. Then add an {@link org.elasticsearch.common.io.stream.NamedWriteableRegistry.Entry} * constant and register it. To register it, look for a method like * {@link org.elasticsearch.xpack.esql.expression.function.scalar.ScalarFunctionWritables#getNamedWriteables()} - * in your function's class hierarchy. Keep going up until you hit a function with that name. + * in your function’s class hierarchy. Keep going up until you hit a function with that name. * Then add your new "ENTRY" constant to the list it returns. * *
      • * Rerun the {@code CsvTests}. They should find your function and maybe even pass. Add a - * few more tests in the csv-spec tests. They run quickly so it isn't a big deal having - * half a dozen of them per function. In fact, it's useful to add more complex combinations + * few more tests in the csv-spec tests. They run quickly so it isn’t a big deal having + * half a dozen of them per function. In fact, it’s useful to add more complex combinations * of things here, just to catch any accidental strange interactions. For example, have * your function take its input from an index like {@code FROM employees | EVAL foo=MY_FUNCTION(emp_no)}. - * It's probably a good idea to have your function passed as a parameter to another function + * It’s probably a good idea to have your function passed as a parameter to another function * like {@code EVAL foo=MOST(0, MY_FUNCTION(emp_no))}. And likely useful to try the reverse * like {@code EVAL foo=MY_FUNCTION(MOST(languages + 10000, emp_no)}. *
        • *
      • - * Now it's time to make a unit test! The infrastructure for these is under some flux at - * the moment, but it's good to extend {@code AbstractScalarFunctionTestCase}. All of + * Now it’s time to make a unit test! The infrastructure for these is under some flux at + * the moment, but it’s good to extend {@code AbstractScalarFunctionTestCase}. All of * these tests are parameterized and expect to spend some time finding good parameters. * Also add serialization tests that extend {@code AbstractExpressionSerializationTests<>}. * And also add type error tests that extends {@code ErrorsForCasesWithoutExamplesTestCase}. @@ -142,7 +142,7 @@ * {@code ./gradlew -p x-pack/plugin/esql/ test} *
        • *
      • - * Now it's time to generate some docs! + * Now it’s time to generate some docs! * Actually, running the tests in the example above should have done it for you. * The generated files are *
          @@ -163,7 +163,7 @@ * list it in {@code docs/reference/esql/functions/math-functions.asciidoc}. *

          * You can generate the docs for just your function by running - * {@code ./gradlew :x-pack:plugin:esql:test -Dtests.class='*SinTests'}. It's just + * {@code ./gradlew :x-pack:plugin:esql:test -Dtests.class='*SinTests'}. It’s just * running your new unit test. You should see something like: *

          * 
          {@code
@@ -179,17 +179,17 @@
  *          }
          * from the elasticsearch directory. The first time you run the docs build it does a bunch * of things with docker to get itself ready. Hopefully you can sit back and watch the show. - * It won't need to do it a second time unless some poor soul updates the Dockerfile in the + * It won’t need to do it a second time unless some poor soul updates the Dockerfile in the * docs repo. * *
        • * When it finishes building it'll open a browser window. Go to the * functions page to see your - * function in the list and follow it's link to get to the page you built. Make sure it + * function in the list and follow it’s link to get to the page you built. Make sure it * looks ok. *
          • *
        • - * Let's finish up the code by making the tests backwards compatible. Since this is a new + * Let’s finish up the code by making the tests backwards compatible. Since this is a new * feature we just have to convince the tests not to run in a cluster that includes older * versions of Elasticsearch. We do that with a {@link org.elasticsearch.rest.RestHandler#supportedCapabilities capability} * on the REST handler. ESQL has a ton of capabilities so we list them @@ -204,7 +204,7 @@ *
        • * Open the PR. The subject and description of the PR are important because those'll turn * into the commit message we see in the commit history. Good PR descriptions make me very - * happy. But functions don't need an essay. + * happy. But functions don’t need an essay. *
          • *
        • * Add the {@code >enhancement} and {@code :Analytics/ES|QL} tags if you are able. @@ -212,11 +212,11 @@ *
          • *
        • * CI might fail for random looking reasons. The first thing you should do is merge {@code main} - * into your PR branch. That's usually just: + * into your PR branch. That’s usually just: * 
          {@code
  * git checkout main && git pull elastic main && git checkout mybranch && git merge main
  *         }
          - * Don't worry about the commit message. It'll get squashed away in the merge. + * Don’t worry about the commit message. It'll get squashed away in the merge. *
          • *
    */ diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/BinarySpatialFunction.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/BinarySpatialFunction.java index 25c0607155afd..df012f9b169d3 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/BinarySpatialFunction.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/BinarySpatialFunction.java @@ -131,7 +131,7 @@ public String sourceText() { protected TypeResolution resolveType() { if (left().foldable() && right().foldable() == false || isNull(left().dataType())) { - // Left is literal, but right is not, check the left field's type against the right field + // Left is literal, but right is not, check the left field’s type against the right field return resolveType(right(), left(), SECOND, FIRST); } else { // All other cases check the right against the left diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/AutomataMatch.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/AutomataMatch.java index 0af22a357aeca..4469f86dc7469 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/AutomataMatch.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/AutomataMatch.java @@ -34,7 +34,7 @@ public static EvalOperator.ExpressionEvaluator.Factory toEvaluator( ) { /* * ByteRunAutomaton has a way to convert utf32 to utf8, but if we used it - * we couldn't get a nice toDot - so we call UTF32ToUTF8 ourselves. + * we couldn’t get a nice toDot - so we call UTF32ToUTF8 ourselves. */ Automaton automaton = Operations.determinize(new UTF32ToUTF8().convert(utf32Automaton), Operations.DEFAULT_DETERMINIZE_WORK_LIMIT); ByteRunAutomaton run = new ByteRunAutomaton(automaton, true); diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Left.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Left.java index 0d885e3f3c341..a82427f866a91 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Left.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Left.java @@ -47,7 +47,7 @@ public class Left extends EsqlScalarFunction { @FunctionInfo( returnType = "keyword", - description = "Returns the substring that extracts 'length' chars from 'string' starting from the left.", + description = "Returns the substring that extracts *length* chars from *string* starting from the left.", examples = { @Example(file = "string", tag = "left") } ) public Left( diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/RLike.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/RLike.java index 76facd2631001..0138f2350a36a 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/RLike.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/RLike.java @@ -47,17 +47,11 @@ Matching special characters (eg. `.`, `*`, `(`...) will require escaping. The escape character is backslash `\\`. Since also backslash is a special character in string literals, it will require further escaping. - [source.merge.styled,esql] - ---- - include::{esql-specs}/string.csv-spec[tag=rlikeEscapingSingleQuotes] - ---- + <> To reduce the overhead of escaping, we suggest using triple quotes strings `\"\"\"` - [source.merge.styled,esql] - ---- - include::{esql-specs}/string.csv-spec[tag=rlikeEscapingTripleQuotes] - ---- + <> """, operator = "RLIKE", examples = @Example(file = "docs", tag = "rlike")) public RLike( Source source, diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Right.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Right.java index e0ebed29cca72..5878cf6a7b1ca 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Right.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Right.java @@ -47,7 +47,7 @@ public class Right extends EsqlScalarFunction { @FunctionInfo( returnType = "keyword", - description = "Return the substring that extracts 'length' chars from 'str' starting from the right.", + description = "Return the substring that extracts *length* chars from *str* starting from the right.", examples = @Example(file = "string", tag = "right") ) public Right( diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Substring.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Substring.java index 73ea409676fbd..84056de98facd 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Substring.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Substring.java @@ -52,7 +52,7 @@ public class Substring extends EsqlScalarFunction implements OptionalArgument { @Example(file = "docs", tag = "substring", description = "This example returns the first three characters of every last name:"), @Example(file = "docs", tag = "substringEnd", description = """ A negative start position is interpreted as being relative to the end of the string. - This example returns the last three characters of of every last name:"""), + This example returns the last three characters of every last name:"""), @Example(file = "docs", tag = "substringRemainder", description = """ If length is omitted, substring returns the remainder of the string. This example returns all characters except for the first:""") } diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/WildcardLike.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/WildcardLike.java index da0c0e47fbc52..22cb0895e4392 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/WildcardLike.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/WildcardLike.java @@ -58,17 +58,11 @@ also act on a constant (literal) expression. The right-hand side of the operator The escape character is backslash `\\`. Since also backslash is a special character in string literals, it will require further escaping. - [source.merge.styled,esql] - ---- - include::{esql-specs}/string.csv-spec[tag=likeEscapingSingleQuotes] - ---- + <> To reduce the overhead of escaping, we suggest using triple quotes strings `\"\"\"` - [source.merge.styled,esql] - ---- - include::{esql-specs}/string.csv-spec[tag=likeEscapingTripleQuotes] - ---- + <> """, operator = "LIKE", examples = @Example(file = "docs", tag = "like")) public WildcardLike( Source source, diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/analysis/ParsingTests.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/analysis/ParsingTests.java index 859e1d788ff06..e458fb009d5c3 100644 --- a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/analysis/ParsingTests.java +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/analysis/ParsingTests.java @@ -79,7 +79,11 @@ public void testLeastFunctionInvalidInputs() { */ public void testInlineCast() throws IOException { EsqlFunctionRegistry registry = new EsqlFunctionRegistry(); - Path dir = PathUtils.get(System.getProperty("java.io.tmpdir")).resolve("esql").resolve("functions").resolve("kibana"); + Path dir = PathUtils.get(System.getProperty("java.io.tmpdir")) + .resolve("query-languages") + .resolve("esql") + .resolve("kibana") + .resolve("definition"); Files.createDirectories(dir); Path file = dir.resolve("inline_cast.json"); try (XContentBuilder report = new XContentBuilder(JsonXContent.jsonXContent, Files.newOutputStream(file))) { diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java index a6d8e3c2e057f..a5717e26724f7 100644 --- a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java @@ -11,7 +11,6 @@ import com.carrotsearch.randomizedtesting.annotations.ParametersFactory; import org.apache.lucene.util.BytesRef; -import org.elasticsearch.common.Strings; import org.elasticsearch.common.breaker.CircuitBreaker; import org.elasticsearch.common.unit.ByteSizeValue; import org.elasticsearch.common.util.BigArrays; @@ -24,13 +23,10 @@ import org.elasticsearch.compute.operator.DriverContext; import org.elasticsearch.compute.operator.EvalOperator.ExpressionEvaluator; import org.elasticsearch.compute.test.TestBlockFactory; -import org.elasticsearch.core.PathUtils; import org.elasticsearch.indices.CrankyCircuitBreakerService; import org.elasticsearch.logging.LogManager; import org.elasticsearch.logging.Logger; import org.elasticsearch.test.ESTestCase; -import org.elasticsearch.xcontent.XContentBuilder; -import org.elasticsearch.xcontent.json.JsonXContent; import org.elasticsearch.xpack.esql.core.expression.Attribute; import org.elasticsearch.xpack.esql.core.expression.Expression; import org.elasticsearch.xpack.esql.core.expression.FieldAttribute; @@ -44,32 +40,12 @@ import org.elasticsearch.xpack.esql.core.util.StringUtils; import org.elasticsearch.xpack.esql.evaluator.EvalMapper; import org.elasticsearch.xpack.esql.evaluator.mapper.EvaluatorMapper; -import org.elasticsearch.xpack.esql.expression.function.fulltext.MatchOperator; import org.elasticsearch.xpack.esql.expression.function.scalar.conditional.Greatest; import org.elasticsearch.xpack.esql.expression.function.scalar.nulls.Coalesce; -import org.elasticsearch.xpack.esql.expression.function.scalar.string.RLike; -import org.elasticsearch.xpack.esql.expression.function.scalar.string.WildcardLike; -import org.elasticsearch.xpack.esql.expression.predicate.nulls.IsNotNull; -import org.elasticsearch.xpack.esql.expression.predicate.nulls.IsNull; -import org.elasticsearch.xpack.esql.expression.predicate.operator.arithmetic.Add; -import org.elasticsearch.xpack.esql.expression.predicate.operator.arithmetic.Div; -import org.elasticsearch.xpack.esql.expression.predicate.operator.arithmetic.Mod; -import org.elasticsearch.xpack.esql.expression.predicate.operator.arithmetic.Mul; -import org.elasticsearch.xpack.esql.expression.predicate.operator.arithmetic.Neg; -import org.elasticsearch.xpack.esql.expression.predicate.operator.arithmetic.Sub; -import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.Equals; -import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.GreaterThan; -import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.GreaterThanOrEqual; -import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.In; -import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.LessThan; -import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.LessThanOrEqual; -import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.NotEquals; import org.elasticsearch.xpack.esql.io.stream.PlanStreamOutput; import org.elasticsearch.xpack.esql.optimizer.rules.logical.FoldNull; -import org.elasticsearch.xpack.esql.parser.ExpressionBuilder; import org.elasticsearch.xpack.esql.planner.Layout; import org.elasticsearch.xpack.esql.planner.PlannerUtils; -import org.elasticsearch.xpack.esql.session.Configuration; import org.hamcrest.Matcher; import org.hamcrest.Matchers; import org.junit.After; @@ -80,33 +56,25 @@ import java.lang.reflect.InvocationTargetException; import java.lang.reflect.Method; import java.math.BigInteger; -import java.nio.file.Files; -import java.nio.file.Path; import java.util.ArrayList; import java.util.Arrays; import java.util.Collections; -import java.util.Comparator; import java.util.HashMap; import java.util.HashSet; import java.util.List; import java.util.Locale; import java.util.Map; -import java.util.Optional; import java.util.Set; import java.util.TreeSet; import java.util.stream.Collectors; import java.util.stream.IntStream; import java.util.stream.Stream; -import static java.util.Map.entry; import static org.elasticsearch.compute.data.BlockUtils.toJavaObject; import static org.elasticsearch.xpack.esql.EsqlTestUtils.randomLiteral; import static org.elasticsearch.xpack.esql.EsqlTestUtils.unboundLogicalOptimizerContext; import static org.elasticsearch.xpack.esql.SerializationTestUtils.assertSerialization; import static org.elasticsearch.xpack.esql.SerializationTestUtils.serializeDeserialize; -import static org.elasticsearch.xpack.esql.expression.function.EsqlFunctionRegistry.mapParam; -import static org.elasticsearch.xpack.esql.expression.function.EsqlFunctionRegistry.param; -import static org.elasticsearch.xpack.esql.expression.function.EsqlFunctionRegistry.paramWithoutAnnotation; import static org.hamcrest.Matchers.either; import static org.hamcrest.Matchers.endsWith; import static org.hamcrest.Matchers.equalTo; @@ -120,30 +88,6 @@ * Base class for function tests. */ public abstract class AbstractFunctionTestCase extends ESTestCase { - /** - * Operators are unregistered functions. - */ - private static final Map> OPERATORS = Map.ofEntries( - entry("in", In.class), - entry("like", WildcardLike.class), - entry("rlike", RLike.class), - entry("equals", Equals.class), - entry("not_equals", NotEquals.class), - entry("greater_than", GreaterThan.class), - entry("greater_than_or_equal", GreaterThanOrEqual.class), - entry("less_than", LessThan.class), - entry("less_than_or_equal", LessThanOrEqual.class), - entry("add", Add.class), - entry("sub", Sub.class), - entry("mul", Mul.class), - entry("div", Div.class), - entry("mod", Mod.class), - entry("neg", Neg.class), - entry("is_null", IsNull.class), - entry("is_not_null", IsNotNull.class), - // Match operator is both a function and an operator - entry("match_operator", MatchOperator.class) - ); private static EsqlFunctionRegistry functionRegistry = new EsqlFunctionRegistry().snapshotRegistry(); @@ -172,7 +116,7 @@ protected static Iterable parameterSuppliersFromTypedData(List * * @param entirelyNullPreservesType should a test case that only contains parameters - * with the {@code null} type keep it's expected type? + * with the {@code null} type keep it’s expected type? * This is mostly going to be {@code true} * except for functions that base their type entirely * on input types like {@link Greatest} or {@link Coalesce}. @@ -210,7 +154,7 @@ protected static List anyNullIsNull( * * Also, if this was the first time we saw the signature we copy it * *again*, replacing the argument with null, but annotating the - * argument's type as `null` explicitly. + * argument’s type as `null` explicitly. */ Set> uniqueSignatures = new HashSet<>(); for (TestCaseSupplier original : testCaseSuppliers) { @@ -470,7 +414,7 @@ public static Stream validFunctionParameters() { if (DataType.UNDER_CONSTRUCTION.containsKey(t)) { /* * Types under construction aren't checked because we're actively - * adding support for them to functions. That's *why* they are + * adding support for them to functions. That’s *why* they are * under construction. */ return false; @@ -478,7 +422,7 @@ public static Stream validFunctionParameters() { if (t.isCounter()) { /* * For now, we're assuming no functions take counters - * as parameters. That's not true - some do. But we'll + * as parameters. That’s not true - some do. But we'll * need to update the tests to handle that. */ return false; @@ -780,7 +724,7 @@ public static void testFunctionInfo() { for (int i = 0; i < args.size(); i++) { typesFromSignature.add(new HashSet<>()); } - for (Map.Entry, DataType> entry : signatures().entrySet()) { + for (Map.Entry, DataType> entry : signatures(getTestClass()).entrySet()) { List types = entry.getKey(); for (int i = 0; i < args.size() && i < types.size(); i++) { typesFromSignature.get(i).add(types.get(i).esNameIfPossible()); @@ -856,51 +800,13 @@ protected final void assertTypeResolutionFailure(Expression expression) { assertThat(expression.typeResolved().message(), equalTo(testCase.getExpectedTypeError())); } - @AfterClass - public static void renderSignature() throws IOException { - // Temporarily turn off docs generation during docs freeze - // TODO: Only turn this back on once this generates the correct MD files - if (System.getProperty("generateDocs") == null || true) { - return; - } - String name = functionName(); - String rendered = buildSignatureSvg(name); - if (rendered == null) { - LogManager.getLogger(getTestClass()).info("Skipping rendering signature because the function isn't registered"); - } else { - LogManager.getLogger(getTestClass()).info("Writing function signature"); - writeToTempDir("signature", name, "svg", rendered); - } - } - - private static String buildSignatureSvg(String name) throws IOException { - String binaryOperator = binaryOperator(name); - if (binaryOperator != null) { - return RailRoadDiagram.binaryOperator(binaryOperator); - } - String unaryOperator = unaryOperator(name); - if (unaryOperator != null) { - return RailRoadDiagram.unaryOperator(unaryOperator); - } - String searchOperator = searchOperator(name); - if (searchOperator != null) { - return RailRoadDiagram.searchOperator(searchOperator); - } - FunctionDefinition definition = definition(name); - if (definition != null) { - return RailRoadDiagram.functionSignature(definition); - } - return null; - } - private static Class classGeneratingSignatures = null; /** - * Unique signatures in this test's parameters. + * Unique signatures in this test’s parameters. */ private static Map, DataType> signatures; - private static Map, DataType> signatures() { - Class testClass = getTestClass(); + static Map, DataType> signatures(Class testClass) { if (signatures != null && classGeneratingSignatures == testClass) { return signatures; } @@ -931,249 +837,10 @@ private static Map, DataType> signatures() { @AfterClass public static void renderDocs() throws IOException { - renderDocs(functionName()); - } - - protected static void renderDocs(String name) throws IOException { - // Temporarily turn off docs generation during docs freeze - // TODO: Only turn this back on once this generates the correct MD files - if (System.getProperty("generateDocs") == null || true) { + if (System.getProperty("generateDocs") == null) { return; } - if (binaryOperator(name) != null || unaryOperator(name) != null || searchOperator(name) != null || likeOrInOperator(name)) { - renderDocsForOperators(name); - return; - } - FunctionDefinition definition = definition(name); - if (definition != null) { - EsqlFunctionRegistry.FunctionDescription description = EsqlFunctionRegistry.description(definition); - if (name.equals("case")) { - /* - * Hack the description, so we render a proper one for case. - */ - // TODO build the description properly *somehow* - EsqlFunctionRegistry.ArgSignature trueValue = description.args().get(1); - EsqlFunctionRegistry.ArgSignature falseValue = new EsqlFunctionRegistry.ArgSignature( - "elseValue", - trueValue.type(), - "The value that's returned when no condition evaluates to `true`.", - true - ); - description = new EsqlFunctionRegistry.FunctionDescription( - description.name(), - List.of(description.args().get(0), trueValue, falseValue), - description.returnType(), - description.description(), - description.variadic(), - description.type() - ); - } - renderTypes(name, description.args()); - renderParametersList(name, description.argNames(), description.argDescriptions()); - FunctionInfo info = EsqlFunctionRegistry.functionInfo(definition); - renderDescription(name, description.description(), info.detailedDescription(), info.note()); - Optional mapArgSignature = description.args() - .stream() - .filter(EsqlFunctionRegistry.ArgSignature::mapArg) - .findFirst(); - boolean hasFunctionOptions = mapArgSignature.isPresent(); - if (hasFunctionOptions) { - renderFunctionNamedParams(name, (EsqlFunctionRegistry.MapArgSignature) mapArgSignature.get()); - } - boolean hasExamples = renderExamples(name, info); - boolean hasAppendix = renderAppendix(name, info.appendix()); - renderFullLayout(name, info.preview(), hasExamples, hasAppendix, hasFunctionOptions); - renderKibanaInlineDocs(name, info); - renderKibanaFunctionDefinition(name, info, description.args(), description.variadic()); - return; - } - LogManager.getLogger(getTestClass()).info("Skipping rendering types because the function '" + name + "' isn't registered"); - } - - private static final String DOCS_WARNING = - "// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.\n\n"; - - private static final String PREVIEW_CALLOUT = - "\npreview::[\"Do not use 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.\"]\n"; - - private static void renderTypes(String name, List args) throws IOException { - StringBuilder header = new StringBuilder(); - List argNames = args.stream().map(EsqlFunctionRegistry.ArgSignature::name).toList(); - for (String arg : argNames) { - header.append(arg).append(" | "); - } - header.append("result"); - - List table = new ArrayList<>(); - for (Map.Entry, DataType> sig : signatures().entrySet()) { // TODO flip to using sortedSignatures - if (shouldHideSignature(sig.getKey(), sig.getValue())) { - continue; - } - if (sig.getKey().size() > argNames.size()) { // skip variadic [test] cases (but not those with optional parameters) - continue; - } - StringBuilder b = new StringBuilder(); - for (int i = 0; i < sig.getKey().size(); i++) { - DataType argType = sig.getKey().get(i); - EsqlFunctionRegistry.ArgSignature argSignature = args.get(i); - if (argSignature.mapArg()) { - b.append("named parameters"); - } else { - b.append(argType.esNameIfPossible()); - } - b.append(" | "); - } - b.append("| ".repeat(argNames.size() - sig.getKey().size())); - b.append(sig.getValue().esNameIfPossible()); - table.add(b.toString()); - } - Collections.sort(table); - if (table.isEmpty()) { - table.add(signatures.values().iterator().next().esNameIfPossible()); - } - - String rendered = DOCS_WARNING + """ - *Supported types* - - [%header.monospaced.styled,format=dsv,separator=|] - |=== - """ + header + "\n" + table.stream().collect(Collectors.joining("\n")) + "\n|===\n"; - LogManager.getLogger(getTestClass()).info("Writing function types for [{}]:\n{}", name, rendered); - writeToTempDir("types", name, "asciidoc", rendered); - } - - private static void renderParametersList(String name, List argNames, List argDescriptions) throws IOException { - StringBuilder builder = new StringBuilder(); - builder.append(DOCS_WARNING); - builder.append("*Parameters*\n"); - for (int a = 0; a < argNames.size(); a++) { - builder.append("\n`").append(argNames.get(a)).append("`::\n").append(argDescriptions.get(a)).append('\n'); - } - String rendered = builder.toString(); - LogManager.getLogger(getTestClass()).info("Writing parameters for [{}]:\n{}", name, rendered); - writeToTempDir("parameters", name, "asciidoc", rendered); - } - - private static void renderDescription(String name, String description, String detailedDescription, String note) throws IOException { - String rendered = DOCS_WARNING + """ - *Description* - - """ + description + "\n"; - - if (Strings.isNullOrEmpty(detailedDescription) == false) { - rendered += "\n" + detailedDescription + "\n"; - } - - if (Strings.isNullOrEmpty(note) == false) { - rendered += "\nNOTE: " + note + "\n"; - } - LogManager.getLogger(getTestClass()).info("Writing description for [{}]:\n{}", name, rendered); - writeToTempDir("description", name, "asciidoc", rendered); - } - - private static boolean renderExamples(String name, FunctionInfo info) throws IOException { - if (info == null || info.examples().length == 0) { - return false; - } - StringBuilder builder = new StringBuilder(); - builder.append(DOCS_WARNING); - if (info.examples().length == 1) { - builder.append("*Example*\n\n"); - } else { - builder.append("*Examples*\n\n"); - } - for (Example example : info.examples()) { - if (example.description().length() > 0) { - builder.append(example.description()); - builder.append("\n"); - } - builder.append(""" - [source.merge.styled,esql] - ---- - include::{esql-specs}/$FILE$.csv-spec[tag=$TAG$] - ---- - [%header.monospaced.styled,format=dsv,separator=|] - |=== - include::{esql-specs}/$FILE$.csv-spec[tag=$TAG$-result] - |=== - """.replace("$FILE$", example.file()).replace("$TAG$", example.tag())); - if (example.explanation().length() > 0) { - builder.append("\n"); - builder.append(example.explanation()); - builder.append("\n\n"); - } - } - builder.append('\n'); - String rendered = builder.toString(); - LogManager.getLogger(getTestClass()).info("Writing examples for [{}]:\n{}", name, rendered); - writeToTempDir("examples", name, "asciidoc", rendered); - return true; - } - - private static boolean renderAppendix(String name, String appendix) throws IOException { - if (appendix.isEmpty()) { - return false; - } - - String rendered = DOCS_WARNING + appendix + "\n"; - - LogManager.getLogger(getTestClass()).info("Writing appendix for [{}]:\n{}", name, rendered); - writeToTempDir("appendix", name, "asciidoc", rendered); - return true; - } - - private static void renderFunctionNamedParams(String name, EsqlFunctionRegistry.MapArgSignature mapArgSignature) throws IOException { - String header = "name | types | description"; - - List table = new ArrayList<>(); - for (Map.Entry argSignatureEntry : mapArgSignature.mapParams().entrySet()) { - StringBuilder builder = new StringBuilder(); - EsqlFunctionRegistry.MapEntryArgSignature arg = argSignatureEntry.getValue(); - builder.append(arg.name()).append(" | ").append(arg.type()).append(" | ").append(arg.description()); - table.add(builder.toString()); - } - - String rendered = DOCS_WARNING + """ - *Supported function named parameters* - - [%header.monospaced.styled,format=dsv,separator=|] - |=== - """ + header + "\n" + table.stream().collect(Collectors.joining("\n")) + "\n|===\n"; - LogManager.getLogger(getTestClass()).info("Writing function named parameters for [{}]:\n{}", functionName(), rendered); - writeToTempDir("functionNamedParams", name, "asciidoc", rendered); - } - - private static void renderFullLayout(String name, boolean preview, boolean hasExamples, boolean hasAppendix, boolean hasFunctionOptions) - throws IOException { - String rendered = DOCS_WARNING + """ - [discrete] - [[esql-$NAME$]] - === `$UPPER_NAME$` - $PREVIEW_CALLOUT$ - *Syntax* - - [.text-center] - image::esql/functions/signature/$NAME$.svg[Embedded,opts=inline] - - include::../parameters/$NAME$.asciidoc[] - include::../description/$NAME$.asciidoc[] - include::../types/$NAME$.asciidoc[] - """.replace("$NAME$", name) - .replace("$UPPER_NAME$", name.toUpperCase(Locale.ROOT)) - .replace("$PREVIEW_CALLOUT$", preview ? PREVIEW_CALLOUT : ""); - if (hasFunctionOptions) { - rendered += "include::../functionNamedParams/" + name + ".asciidoc[]\n"; - } - if (hasExamples) { - rendered += "include::../examples/" + name + ".asciidoc[]\n"; - } - if (hasAppendix) { - rendered += "include::../appendix/" + name + ".asciidoc[]\n"; - } - LogManager.getLogger(getTestClass()).info("Writing layout for [{}]:\n{}", name, rendered); - writeToTempDir("layout", name, "asciidoc", rendered); + DocsV3Support.renderDocs(functionName(), getTestClass()); } protected static Constructor constructorWithFunctionInfo(Class clazz) { @@ -1186,185 +853,6 @@ protected static Constructor constructorWithFunctionInfo(Class clazz) { return null; } - private static void renderDocsForOperators(String name) throws IOException { - Constructor ctor = constructorWithFunctionInfo(OPERATORS.get(name)); - assert ctor != null; - FunctionInfo functionInfo = ctor.getAnnotation(FunctionInfo.class); - assert functionInfo != null; - renderDocsForOperators(name, ctor, functionInfo); - } - - protected static void renderDocsForOperators(String name, Constructor ctor, FunctionInfo functionInfo) throws IOException { - renderKibanaInlineDocs(name, functionInfo); - - var params = ctor.getParameters(); - - List args = new ArrayList<>(params.length); - for (int i = 1; i < params.length; i++) { // skipping 1st argument, the source - if (Configuration.class.isAssignableFrom(params[i].getType()) == false) { - MapParam mapParamInfo = params[i].getAnnotation(MapParam.class); - if (mapParamInfo != null) { - args.add(mapParam(mapParamInfo)); - } else { - Param paramInfo = params[i].getAnnotation(Param.class); - args.add(paramInfo != null ? param(paramInfo) : paramWithoutAnnotation(params[i].getName())); - } - } - } - renderKibanaFunctionDefinition(name, functionInfo, args, likeOrInOperator(name)); - renderTypes(name, args); - } - - private static void renderKibanaInlineDocs(String name, FunctionInfo info) throws IOException { - StringBuilder builder = new StringBuilder(); - builder.append(""" - - - """); - builder.append("### ").append(name.toUpperCase(Locale.ROOT)).append("\n"); - builder.append(removeAsciidocLinks(info.description())).append("\n\n"); - - if (info.examples().length > 0) { - Example example = info.examples()[0]; - builder.append("```\n"); - builder.append("read-example::").append(example.file()).append(".csv-spec[tag=").append(example.tag()).append("]\n"); - builder.append("```\n"); - } - if (Strings.isNullOrEmpty(info.note()) == false) { - builder.append("Note: ").append(removeAsciidocLinks(info.note())).append("\n"); - } - String rendered = builder.toString(); - LogManager.getLogger(getTestClass()).info("Writing kibana inline docs for [{}]:\n{}", name, rendered); - writeToTempDir("kibana/docs", name, "md", rendered); - } - - private static void renderKibanaFunctionDefinition( - String name, - FunctionInfo info, - List args, - boolean variadic - ) throws IOException { - - XContentBuilder builder = JsonXContent.contentBuilder().prettyPrint().lfAtEnd().startObject(); - builder.field( - "comment", - "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it." - ); - if (false == info.operator().isEmpty()) { - builder.field("type", "operator"); - builder.field("operator", info.operator()); - assertThat(isAggregation(), equalTo(false)); - } else { - builder.field("type", switch (info.type()) { - case SCALAR -> "scalar"; - case AGGREGATE -> "agg"; - case GROUPING -> "grouping"; - }); - } - builder.field("name", name); - builder.field("description", removeAsciidocLinks(info.description())); - if (Strings.isNullOrEmpty(info.note()) == false) { - builder.field("note", removeAsciidocLinks(info.note())); - } - // TODO aliases - - builder.startArray("signatures"); - if (args.isEmpty()) { - builder.startObject(); - builder.startArray("params"); - builder.endArray(); - // There should only be one return type so just use that as the example - builder.field("returnType", signatures().values().iterator().next().esNameIfPossible()); - builder.endObject(); - } else { - int minArgCount = (int) args.stream().filter(a -> false == a.optional()).count(); - for (Map.Entry, DataType> sig : sortedSignatures()) { - if (variadic && sig.getKey().size() > args.size()) { - // For variadic functions we test much longer signatures, let's just stop at the last one - continue; - } - if (sig.getKey().size() < minArgCount) { - throw new IllegalArgumentException("signature " + sig.getKey() + " is missing non-optional arg for " + args); - } - if (shouldHideSignature(sig.getKey(), sig.getValue())) { - continue; - } - builder.startObject(); - builder.startArray("params"); - for (int i = 0; i < sig.getKey().size(); i++) { - EsqlFunctionRegistry.ArgSignature arg = args.get(i); - builder.startObject(); - builder.field("name", arg.name()); - if (arg.mapArg()) { - builder.field("type", "function_named_parameters"); - builder.field( - "mapParams", - arg.mapParams() - .values() - .stream() - .map(mapArgSignature -> "{" + mapArgSignature + "}") - .collect(Collectors.joining(", ")) - ); - } else { - builder.field("type", sig.getKey().get(i).esNameIfPossible()); - } - builder.field("optional", arg.optional()); - builder.field("description", arg.description()); - builder.endObject(); - } - builder.endArray(); - builder.field("variadic", variadic); - builder.field("returnType", sig.getValue().esNameIfPossible()); - builder.endObject(); - } - } - builder.endArray(); - - if (info.examples().length > 0) { - builder.startArray("examples"); - for (Example example : info.examples()) { - builder.value("read-example::" + example.file() + ".csv-spec[tag=" + example.tag() + ", json]"); - } - builder.endArray(); - } - builder.field("preview", info.preview()); - builder.field("snapshot_only", EsqlFunctionRegistry.isSnapshotOnly(name)); - - String rendered = Strings.toString(builder.endObject()); - LogManager.getLogger(getTestClass()).info("Writing kibana function definition for [{}]:\n{}", name, rendered); - writeToTempDir("kibana/definition", name, "json", rendered); - } - - private static String removeAsciidocLinks(String asciidoc) { - return asciidoc.replaceAll("[^ ]+\\[([^\\]]+)\\]", "$1"); - } - - private static List, DataType>> sortedSignatures() { - List, DataType>> sortedSignatures = new ArrayList<>(signatures().entrySet()); - Collections.sort(sortedSignatures, new Comparator<>() { - @Override - public int compare(Map.Entry, DataType> lhs, Map.Entry, DataType> rhs) { - int maxlen = Math.max(lhs.getKey().size(), rhs.getKey().size()); - for (int i = 0; i < maxlen; i++) { - if (lhs.getKey().size() <= i) { - return -1; - } - if (rhs.getKey().size() <= i) { - return 1; - } - int c = lhs.getKey().get(i).esNameIfPossible().compareTo(rhs.getKey().get(i).esNameIfPossible()); - if (c != 0) { - return c; - } - } - return lhs.getValue().esNameIfPossible().compareTo(rhs.getValue().esNameIfPossible()); - } - }); - return sortedSignatures; - } - protected static String functionName() { Class testClass = getTestClass(); if (testClass.isAnnotationPresent(FunctionName.class)) { @@ -1375,82 +863,17 @@ protected static String functionName() { } } - private static FunctionDefinition definition(String name) { + static boolean functionRegistered(String name) { + return functionRegistry.functionExists(name); + } + + static FunctionDefinition definition(String name) { if (functionRegistry.functionExists(name)) { return functionRegistry.resolveFunction(name); } return null; } - /** - * If this test is a for a binary operator return its symbol, otherwise return {@code null}. - * This is functionally the reverse of the combination of - * {@link ExpressionBuilder#visitArithmeticBinary} and {@link ExpressionBuilder#visitComparison}. - */ - private static String binaryOperator(String name) { - return switch (name) { - case "add" -> "+"; - case "div" -> "/"; - case "equals" -> "=="; - case "greater_than" -> ">"; - case "greater_than_or_equal" -> ">="; - case "less_than" -> "<"; - case "less_than_or_equal" -> "<="; - case "mod" -> "%"; - case "mul" -> "*"; - case "not_equals" -> "!="; - case "sub" -> "-"; - default -> null; - }; - } - - /** - * If this test is a for a search operator return its symbol, otherwise return {@code null}. - */ - private static String searchOperator(String name) { - return switch (name) { - case "match_operator" -> ":"; - default -> null; - }; - } - - /** - * If this tests is for a unary operator return its symbol, otherwise return {@code null}. - * This is functionally the reverse of {@link ExpressionBuilder#visitArithmeticUnary}. - */ - private static String unaryOperator(String name) { - return switch (name) { - case "neg" -> "-"; - default -> null; - }; - } - - /** - * If this tests is for a like or rlike operator return true, otherwise return {@code null}. - */ - private static boolean likeOrInOperator(String name) { - return switch (name.toLowerCase(Locale.ENGLISH)) { - case "rlike", "like", "in", "not_rlike", "not_like", "not_in" -> true; - default -> false; - }; - } - - /** - * Write some text to a tempdir so we can copy it to the docs later. - *

    - * We need to write to a tempdir instead of the docs because the tests - * don't have write permission to the docs. - *

    - */ - private static void writeToTempDir(String subdir, String name, String extension, String str) throws IOException { - // We have to write to a tempdir because it's all test are allowed to write to. Gradle can move them. - Path dir = PathUtils.get(System.getProperty("java.io.tmpdir")).resolve("esql").resolve("functions").resolve(subdir); - Files.createDirectories(dir); - Path file = dir.resolve(name + "." + extension); - Files.writeString(file, str); - LogManager.getLogger(getTestClass()).info("Wrote to file: {}", file); - } - private final List breakers = Collections.synchronizedList(new ArrayList<>()); protected final DriverContext driverContext() { @@ -1478,7 +901,7 @@ public void allMemoryReleased() { /** * Returns true if the current test case is for an aggregation function. *

    - * This method requires reflection, as it's called from a static context (@AfterClass documentation rendering). + * This method requires reflection, as it’s called from a static context (@AfterClass documentation rendering). *

    */ private static boolean isAggregation() { @@ -1488,7 +911,7 @@ private static boolean isAggregation() { /** * Should this particular signature be hidden from the docs even though we test it? */ - private static boolean shouldHideSignature(List argTypes, DataType returnType) { + static boolean shouldHideSignature(List argTypes, DataType returnType) { for (DataType dt : DataType.UNDER_CONSTRUCTION.keySet()) { if (returnType == dt || argTypes.contains(dt)) { return true; diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java new file mode 100644 index 0000000000000..032b4394f993a --- /dev/null +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java @@ -0,0 +1,1024 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0; you may not use this file except in compliance with the Elastic License + * 2.0. + */ + +package org.elasticsearch.xpack.esql.expression.function; + +import com.unboundid.util.NotNull; + +import org.elasticsearch.common.Strings; +import org.elasticsearch.core.PathUtils; +import org.elasticsearch.logging.LogManager; +import org.elasticsearch.logging.Logger; +import org.elasticsearch.xcontent.XContentBuilder; +import org.elasticsearch.xcontent.json.JsonXContent; +import org.elasticsearch.xpack.esql.CsvTestsDataLoader; +import org.elasticsearch.xpack.esql.core.type.DataType; +import org.elasticsearch.xpack.esql.expression.function.fulltext.MatchOperator; +import org.elasticsearch.xpack.esql.expression.function.scalar.string.RLike; +import org.elasticsearch.xpack.esql.expression.function.scalar.string.WildcardLike; +import org.elasticsearch.xpack.esql.expression.predicate.logical.And; +import org.elasticsearch.xpack.esql.expression.predicate.logical.Not; +import org.elasticsearch.xpack.esql.expression.predicate.logical.Or; +import org.elasticsearch.xpack.esql.expression.predicate.nulls.IsNotNull; +import org.elasticsearch.xpack.esql.expression.predicate.nulls.IsNull; +import org.elasticsearch.xpack.esql.expression.predicate.operator.arithmetic.Add; +import org.elasticsearch.xpack.esql.expression.predicate.operator.arithmetic.Div; +import org.elasticsearch.xpack.esql.expression.predicate.operator.arithmetic.Mod; +import org.elasticsearch.xpack.esql.expression.predicate.operator.arithmetic.Mul; +import org.elasticsearch.xpack.esql.expression.predicate.operator.arithmetic.Neg; +import org.elasticsearch.xpack.esql.expression.predicate.operator.arithmetic.Sub; +import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.Equals; +import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.GreaterThan; +import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.GreaterThanOrEqual; +import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.In; +import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.LessThan; +import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.LessThanOrEqual; +import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.NotEquals; +import org.elasticsearch.xpack.esql.session.Configuration; + +import java.io.BufferedReader; +import java.io.IOException; +import java.io.InputStream; +import java.io.InputStreamReader; +import java.lang.annotation.Annotation; +import java.lang.reflect.Constructor; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collections; +import java.util.HashMap; +import java.util.List; +import java.util.Locale; +import java.util.Map; +import java.util.Optional; +import java.util.function.Function; +import java.util.regex.Matcher; +import java.util.regex.Pattern; +import java.util.stream.Collectors; + +import static java.util.Map.entry; +import static org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase.constructorWithFunctionInfo; +import static org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase.definition; +import static org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase.functionRegistered; +import static org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase.shouldHideSignature; +import static org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase.signatures; +import static org.elasticsearch.xpack.esql.expression.function.EsqlFunctionRegistry.mapParam; +import static org.elasticsearch.xpack.esql.expression.function.EsqlFunctionRegistry.param; +import static org.elasticsearch.xpack.esql.expression.function.EsqlFunctionRegistry.paramWithoutAnnotation; + +public abstract class DocsV3Support { + + static final String DOCS_WARNING = + "% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.\n\n"; + + static final String PREVIEW_CALLOUT = """ + ::::{warning} + Do not use 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. + :::: + """; + + static FunctionDocsSupport forFunctions(String name, Class testClass) { + return new FunctionDocsSupport(name, testClass); + } + + static OperatorsDocsSupport forOperators(String name, Class testClass) { + return new OperatorsDocsSupport(name, testClass); + } + + static void renderDocs(String name, Class testClass) throws IOException { + if (OPERATORS.containsKey(name)) { + var docs = DocsV3Support.forOperators(name, testClass); + docs.renderSignature(); + docs.renderDocs(); + } else if (functionRegistered(name)) { + var docs = DocsV3Support.forFunctions(name, testClass); + docs.renderSignature(); + docs.renderDocs(); + } else { + LogManager.getLogger(testClass).info("Skipping rendering docs because the function '" + name + "' isn't registered"); + } + } + + public static void renderNegatedOperator( + @NotNull Constructor ctor, + String name, + Function description, + Class testClass + ) throws IOException { + var docs = forOperators("not " + name.toLowerCase(Locale.ROOT), testClass); + docs.renderDocsForNegatedOperators(ctor, description); + } + + private static final Map MACROS = new HashMap<>(); + private static final Map knownFiles; + private static final Map knownCommands; + private static final Map knownOperators; + private static final Map knownMapping; + + static { + MACROS.put("wikipedia", "https://en.wikipedia.org/wiki"); + MACROS.put("javadoc8", "https://docs.oracle.com/javase/8/docs/api"); + MACROS.put("javadoc14", "https://docs.oracle.com/en/java/javase/14/docs/api"); + MACROS.put("javadoc", "https://docs.oracle.com/en/java/javase/11/docs/api"); + // This static list of known root query-languages/-*.md files is used to simulate old simple ascii-doc links + knownFiles = Map.ofEntries( + entry("esql-commands", "esql/esql-commands.md"), + entry("esql-enrich-data", "esql/esql-enrich-data.md"), + entry("esql-examples", "esql/esql-examples.md"), + entry("esql-functions-operators", "esql/esql-functions-operators.md"), + entry("esql-implicit-casting", "esql/esql-implicit-casting.md"), + entry("esql-metadata-fields", "esql/esql-metadata-fields.md"), + entry("esql-multivalued-fields", "esql/esql-multivalued-fields.md"), + entry("esql-process-data-with-dissect-grok", "esql/esql-process-data-with-dissect-grok.md"), + entry("esql-syntax", "esql/esql-syntax.md"), + entry("esql-time-spans", "esql/esql-time-spans.md"), + entry("esql-limitations", "esql/limitations.md"), + entry("esql-function-named-params", "esql/esql-syntax.md"), + entry("query-dsl-query-string-query", "query-dsl-query-string-query.md") + ); + // Static links to the commands file + knownCommands = Map.ofEntries(entry("where", "where"), entry("stats-by", "stats")); + // Static links to handwritten operators files + knownOperators = Map.ofEntries(entry("cast-operator", "Cast (::)")); + // Static links to mapping-reference + knownMapping = Map.ofEntries( + entry("text", "/reference/elasticsearch/mapping-reference/text.md"), + entry("semantic-text", "/reference/elasticsearch/mapping-reference/semantic-text.md"), + entry("mapping-index", "/reference/elasticsearch/mapping-reference/mapping-index.md"), + entry("doc-values", "/reference/elasticsearch/mapping-reference/doc-values.md") + ); + } + /** + * Operators are unregistered functions. + */ + static final Map OPERATORS = Map.ofEntries( + // Binary + operatorEntry("equals", "==", Equals.class, OperatorCategory.BINARY), + operatorEntry("not_equals", "!=", NotEquals.class, OperatorCategory.BINARY), + operatorEntry("greater_than", ">", GreaterThan.class, OperatorCategory.BINARY), + operatorEntry("greater_than_or_equal", ">=", GreaterThanOrEqual.class, OperatorCategory.BINARY), + operatorEntry("less_than", "<", LessThan.class, OperatorCategory.BINARY), + operatorEntry("less_than_or_equal", "<=", LessThanOrEqual.class, OperatorCategory.BINARY), + operatorEntry("add", "+", Add.class, OperatorCategory.BINARY), + operatorEntry("sub", "-", Sub.class, OperatorCategory.BINARY), + operatorEntry("mul", "*", Mul.class, OperatorCategory.BINARY), + operatorEntry("div", "/", Div.class, OperatorCategory.BINARY), + operatorEntry("mod", "%", Mod.class, OperatorCategory.BINARY), + // Unary + operatorEntry("neg", "-", Neg.class, OperatorCategory.UNARY), + // Logical + operatorEntry("and", "AND", And.class, OperatorCategory.LOGICAL), + operatorEntry("or", "OR", Or.class, OperatorCategory.LOGICAL), + operatorEntry("not", "NOT", Not.class, OperatorCategory.LOGICAL), + // NULL and IS NOT NULL + operatorEntry("is_null", "IS NULL", IsNull.class, OperatorCategory.NULL_PREDICATES), + operatorEntry("is_not_null", "IS NOT NULL", IsNotNull.class, OperatorCategory.NULL_PREDICATES), + // LIKE AND RLIKE + // case "rlike", "like", "in", "not_rlike", "not_like", "not_in" -> true; + operatorEntry("like", "LIKE", WildcardLike.class, OperatorCategory.LIKE_AND_RLIKE, true), + operatorEntry("rlike", "RLIKE", RLike.class, OperatorCategory.LIKE_AND_RLIKE, true), + // IN + operatorEntry("in", "IN", In.class, OperatorCategory.IN, true), + // Search + operatorEntry("match_operator", ":", MatchOperator.class, OperatorCategory.SEARCH) + ); + + enum OperatorCategory { + BINARY, + UNARY, + LOGICAL, + NULL_PREDICATES, + IN, + LIKE_AND_RLIKE, + SEARCH + } + + record OperatorConfig(String name, String symbol, Class clazz, OperatorCategory category, boolean variadic) {} + + private static Map.Entry operatorEntry( + String name, + String symbol, + Class clazz, + OperatorCategory category, + boolean variadic + ) { + return entry(name, new OperatorConfig(name, symbol, clazz, category, variadic)); + } + + private static Map.Entry operatorEntry(String name, String symbol, Class clazz, OperatorCategory category) { + return entry(name, new OperatorConfig(name, symbol, clazz, category, false)); + } + + protected final String category; + protected final String name; + protected final Logger logger; + protected final Class testClass; + + private DocsV3Support(String category, String name, Class testClass) { + this.category = category; + this.name = name; + this.logger = LogManager.getLogger(testClass); + this.testClass = testClass; + } + + String replaceLinks(String text) { + return replaceAsciidocLinks(replaceMacros(text)); + } + + private String replaceAsciidocLinks(String text) { + Pattern pattern = Pattern.compile("<<([^>]*)>>"); + Matcher matcher = pattern.matcher(text); + StringBuffer result = new StringBuffer(); + while (matcher.find()) { + String match = matcher.group(1); + matcher.appendReplacement(result, getLink(match)); + } + matcher.appendTail(result); + return result.toString(); + } + + private String replaceMacros(String text) { + Pattern pattern = Pattern.compile("\\{([^}]+)}(/[^\\[]+)\\[([^]]+)\\]"); + + Matcher matcher = pattern.matcher(text); + StringBuffer result = new StringBuffer(); + while (matcher.find()) { + String macro = matcher.group(1); + String path = matcher.group(2); + String display = matcher.group(3); + matcher.appendReplacement(result, getMacroLink(macro, path, display)); + } + matcher.appendTail(result); + return result.toString(); + } + + private String getMacroLink(String macro, String path, String display) { + if (MACROS.containsKey(macro) == false) { + throw new IllegalArgumentException("Unknown macro [" + macro + "]"); + } + return String.format(Locale.ROOT, "[%s](%s%s)", display, MACROS.get(macro), path); + } + + /** + * The new link syntax is extremely verbose. + * Rather than make a large number of messy changes to the java files, we simply re-write the existing links to the new syntax. + */ + private String getLink(String key) { + String[] parts = key.split(",\\s*"); + // Inject esql examples + if (parts[0].equals("load-esql-example")) { + try { + Map example = Arrays.stream(parts[1].trim().split("\\s+")) + .map(s -> s.split("\\s*=\\s*", 2)) + .map(p -> entry(p[0], p[1])) + .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue)); + return "```esql\n" + loadExample(example.get("file"), example.get("tag")) + "\n```\n"; + } catch (IOException e) { + return e.getMessage(); + } + } + // Known root query-languages markdown files + if (knownFiles.containsKey(parts[0])) { + return makeLink(key, "", "/reference/query-languages/" + knownFiles.get(parts[0])); + } + // Old-style links within ES|QL reference + if (key.startsWith("esql-")) { + String cmd = parts[0].replace("esql-", ""); + String parentFile = knownCommands.containsKey(cmd) + ? "/reference/query-languages/esql/esql-commands.md" + : "/reference/query-languages/esql/esql-functions-operators.md"; + return makeLink(key, "esql-", parentFile); + } + // Old-style links to Query DSL pages + if (key.startsWith("query-dsl-")) { + // <> + // [`match`](/reference/query-languages/query-dsl-match-query.md) + return makeLink(key, "query-dsl-", "/reference/query-languages/query-dsl-match-query.md"); + } + // Known links to mapping-reference + if (knownMapping.containsKey(parts[0])) { + return makeLink(key, "", knownMapping.get(parts[0])); + } + // Various other remaining old asciidoc links + // <> + return switch (parts[0]) { + case "match-field-params" -> makeLink(key, "", "/reference/query-languages/query-dsl-match-query.md"); + case "search-aggregations-bucket-histogram-aggregation" -> makeLink( + key, + "", + "/reference/data-analysis/aggregations/search-aggregations-bucket-histogram-aggregation.md" + ); + default -> throw new IllegalArgumentException("Invalid link key <<" + key + ">>"); + }; + } + + private String makeLink(String key, String prefix, String parentFile) { + String displayText = key.substring(prefix.length()); + if (knownCommands.containsKey(displayText)) { + displayText = "`" + knownCommands.get(displayText).toUpperCase(Locale.ROOT) + "`"; + } else if (knownOperators.containsKey(displayText)) { + displayText = "`" + knownOperators.get(displayText) + "`"; + } else { + int comma = displayText.indexOf(','); + if (comma > 0) { + key = prefix + displayText.substring(0, comma); + displayText = displayText.substring(comma + 1).trim(); + } else if (parentFile.contains("esql/esql-")) { + // For ES|QL commands and functions we normally make uppercase code + displayText = "`" + displayText.toUpperCase(Locale.ROOT) + "`"; + } + } + if (parentFile.contains("/" + key + ".md")) { + // The current docs-builder trips off all link targets that match the filename, so we need to do the same + return String.format(Locale.ROOT, "[%s](%s)", displayText, parentFile); + } else { + return String.format(Locale.ROOT, "[%s](%s#%s)", displayText, parentFile, key); + } + } + + void writeToTempImageDir(String str) throws IOException { + // We have to write to a tempdir because it’s all test are allowed to write to. Gradle can move them. + Path dir = PathUtils.get(System.getProperty("java.io.tmpdir")).resolve("esql").resolve("images").resolve(category); + writeToTempDir(dir, "svg", str); + } + + void writeToTempSnippetsDir(String subdir, String str) throws IOException { + // We have to write to a tempdir because it’s all test are allowed to write to. Gradle can move them. + Path dir = PathUtils.get(System.getProperty("java.io.tmpdir")) + .resolve("esql") + .resolve("_snippets") + .resolve(category) + .resolve(subdir); + writeToTempDir(dir, "md", str); + } + + void writeToTempKibanaDir(String subdir, String extension, String str) throws IOException { + // We have to write to a tempdir because it’s all test are allowed to write to. Gradle can move them. + Path dir = PathUtils.get(System.getProperty("java.io.tmpdir")).resolve("esql").resolve("kibana").resolve(subdir).resolve(category); + writeToTempDir(dir, extension, str); + } + + private void writeToTempDir(Path dir, String extension, String str) throws IOException { + Files.createDirectories(dir); + Path file = dir.resolve(name + "." + extension); + Files.writeString(file, str); + logger.info("Wrote to file: {}", file); + } + + protected abstract void renderSignature() throws IOException; + + protected abstract void renderDocs() throws IOException; + + static class FunctionDocsSupport extends DocsV3Support { + private FunctionDocsSupport(String name, Class testClass) { + super("functions", name, testClass); + } + + @Override + protected void renderSignature() throws IOException { + String rendered = buildFunctionSignatureSvg(); + if (rendered == null) { + logger.info("Skipping rendering signature because the function isn't registered"); + } else { + logger.info("Writing function signature"); + writeToTempImageDir(rendered); + } + } + + @Override + protected void renderDocs() throws IOException { + FunctionDefinition definition = definition(name); + renderSignature(); + EsqlFunctionRegistry.FunctionDescription description = EsqlFunctionRegistry.description(definition); + if (name.equals("case")) { + /* + * Hack the description, so we render a proper one for case. + */ + // TODO build the description properly *somehow* + EsqlFunctionRegistry.ArgSignature trueValue = description.args().get(1); + EsqlFunctionRegistry.ArgSignature falseValue = new EsqlFunctionRegistry.ArgSignature( + "elseValue", + trueValue.type(), + "The value that’s returned when no condition evaluates to `true`.", + true + ); + description = new EsqlFunctionRegistry.FunctionDescription( + description.name(), + List.of(description.args().get(0), trueValue, falseValue), + description.returnType(), + description.description(), + description.variadic(), + description.type() + ); + } + renderTypes(name, description.args()); + renderParametersList(description.argNames(), description.argDescriptions()); + FunctionInfo info = EsqlFunctionRegistry.functionInfo(definition); + assert info != null; + renderDescription(description.description(), info.detailedDescription(), info.note()); + Optional mapArgSignature = description.args() + .stream() + .filter(EsqlFunctionRegistry.ArgSignature::mapArg) + .findFirst(); + boolean hasFunctionOptions = mapArgSignature.isPresent(); + if (hasFunctionOptions) { + renderFunctionNamedParams((EsqlFunctionRegistry.MapArgSignature) mapArgSignature.get()); + } + boolean hasExamples = renderExamples(info); + boolean hasAppendix = renderAppendix(info.appendix()); + renderFullLayout(info.preview(), hasExamples, hasAppendix, hasFunctionOptions); + renderKibanaInlineDocs(name, info); + renderKibanaFunctionDefinition(name, info, description.args(), description.variadic()); + } + + private void renderFunctionNamedParams(EsqlFunctionRegistry.MapArgSignature mapArgSignature) throws IOException { + String header = "| name | types | description |\n| --- | --- | --- |"; + + List table = new ArrayList<>(); + for (Map.Entry argSignatureEntry : mapArgSignature.mapParams().entrySet()) { + StringBuilder builder = new StringBuilder("| "); + EsqlFunctionRegistry.MapEntryArgSignature arg = argSignatureEntry.getValue(); + builder.append(arg.name()).append(" | ").append(arg.type()).append(" | ").append(arg.description()); + table.add(builder.append(" |").toString()); + } + + String rendered = DOCS_WARNING + """ + **Supported function named parameters** + + """ + header + "\n" + table.stream().collect(Collectors.joining("\n")) + "\n"; + logger.info("Writing function named parameters for [{}]:\n{}", name, rendered); + writeToTempSnippetsDir("functionNamedParams", rendered); + } + + private void renderFullLayout(boolean preview, boolean hasExamples, boolean hasAppendix, boolean hasFunctionOptions) + throws IOException { + StringBuilder rendered = new StringBuilder( + DOCS_WARNING + """ + ## `$UPPER_NAME$` [esql-$NAME$] + $PREVIEW_CALLOUT$ + **Syntax** + + :::{image} ../../../images/$CATEGORY$/$NAME$.svg + :alt: Embedded + :class: text-center + ::: + + """.replace("$NAME$", name) + .replace("$CATEGORY$", category) + .replace("$UPPER_NAME$", name.toUpperCase(Locale.ROOT)) + .replace("$PREVIEW_CALLOUT$", preview ? PREVIEW_CALLOUT : "") + ); + for (String section : new String[] { "parameters", "description", "types" }) { + rendered.append(addInclude(section)); + } + if (hasFunctionOptions) { + rendered.append(addInclude("functionNamedParams")); + } + if (hasExamples) { + rendered.append(addInclude("examples")); + } + if (hasAppendix) { + rendered.append(addInclude("appendix")); + } + logger.info("Writing layout for [{}]:\n{}", name, rendered.toString()); + writeToTempSnippetsDir("layout", rendered.toString()); + } + + private String addInclude(String section) { + return """ + + :::{include} ../$SECTION$/$NAME$.md + ::: + """.replace("$NAME$", name).replace("$SECTION$", section); + } + } + + static class OperatorsDocsSupport extends DocsV3Support { + + private OperatorsDocsSupport(String name, Class testClass) { + super("operators", name, testClass); + } + + @Override + protected void renderSignature() throws IOException { + OperatorConfig op = OPERATORS.get(name); + String rendered = (switch (op.category()) { + case BINARY -> RailRoadDiagram.binaryOperator(op.symbol()); + case UNARY -> RailRoadDiagram.unaryOperator(op.symbol()); + case SEARCH -> RailRoadDiagram.searchOperator(op.symbol()); + default -> buildFunctionSignatureSvg(); + }); + if (rendered == null) { + logger.info("Skipping rendering signature because the operator isn't registered"); + } else { + logger.info("Writing operator signature"); + writeToTempImageDir(rendered); + } + } + + @Override + protected void renderDocs() throws IOException { + DocsV3Support.OperatorConfig op = OPERATORS.get(name); + Constructor ctor = constructorWithFunctionInfo(op.clazz()); + if (ctor != null) { + FunctionInfo functionInfo = ctor.getAnnotation(FunctionInfo.class); + assert functionInfo != null; + renderDocsForOperators(op.name(), ctor, functionInfo, op.variadic()); + } else { + logger.info("Skipping rendering docs for operator '" + op.name() + "' with no @FunctionInfo"); + } + } + + void renderDocsForNegatedOperators(Constructor ctor, Function description) throws IOException { + String baseName = name.toLowerCase(Locale.ROOT).replace("not ", ""); + OperatorConfig op = OPERATORS.get(baseName); + assert op != null; + FunctionInfo orig = ctor.getAnnotation(FunctionInfo.class); + assert orig != null; + FunctionInfo functionInfo = new FunctionInfo() { + @Override + public Class annotationType() { + return orig.annotationType(); + } + + @Override + public String operator() { + return name; + } + + @Override + public String[] returnType() { + return orig.returnType(); + } + + @Override + public boolean preview() { + return orig.preview(); + } + + @Override + public String description() { + return description.apply(orig.description().replace(baseName, name)); + } + + @Override + public String detailedDescription() { + return ""; + } + + @Override + public String note() { + return orig.note().replace(baseName, name); + } + + @Override + public String appendix() { + return orig.appendix().replace(baseName, name); + } + + @Override + public FunctionType type() { + return orig.type(); + } + + @Override + public Example[] examples() { + // throw away examples + return new Example[] {}; + } + }; + renderDocsForOperators("not_" + baseName, ctor, functionInfo, op.variadic()); + } + + void renderDocsForOperators(String name, Constructor ctor, FunctionInfo info, boolean variadic) throws IOException { + renderKibanaInlineDocs(name, info); + + var params = ctor.getParameters(); + + List args = new ArrayList<>(params.length); + for (int i = 1; i < params.length; i++) { // skipping 1st argument, the source + if (Configuration.class.isAssignableFrom(params[i].getType()) == false) { + MapParam mapParamInfo = params[i].getAnnotation(MapParam.class); + if (mapParamInfo != null) { + args.add(mapParam(mapParamInfo)); + } else { + Param paramInfo = params[i].getAnnotation(Param.class); + args.add(paramInfo != null ? param(paramInfo) : paramWithoutAnnotation(params[i].getName())); + } + } + } + renderKibanaFunctionDefinition(name, info, args, variadic); + renderDetailedDescription(info.detailedDescription(), info.note()); + renderTypes(name, args); + renderExamples(info); + // TODO: Consider rendering more for operators, like layout, which is currently static + } + + void renderDetailedDescription(String detailedDescription, String note) throws IOException { + StringBuilder rendered = new StringBuilder(); + if (Strings.isNullOrEmpty(detailedDescription) == false) { + detailedDescription = replaceLinks(detailedDescription.trim()); + rendered.append("\n").append(detailedDescription).append("\n"); + } + + if (Strings.isNullOrEmpty(note) == false) { + rendered.append("\n::::{note}\n").append(replaceLinks(note)).append("\n::::\n\n"); + } + if (rendered.isEmpty() == false) { + rendered.append("\n"); + logger.info("Writing detailed description for [{}]:\n{}", name, rendered); + writeToTempSnippetsDir("detailedDescription", rendered.toString()); + } + } + } + + protected String buildFunctionSignatureSvg() throws IOException { + FunctionDefinition definition = definition(name); + return (definition != null) ? RailRoadDiagram.functionSignature(definition) : null; + } + + void renderParametersList(List argNames, List argDescriptions) throws IOException { + StringBuilder builder = new StringBuilder(); + builder.append(DOCS_WARNING); + builder.append("**Parameters**\n"); + for (int a = 0; a < argNames.size(); a++) { + String description = replaceLinks(argDescriptions.get(a)); + builder.append("\n`").append(argNames.get(a)).append("`\n: ").append(description).append('\n'); + } + builder.append('\n'); + String rendered = builder.toString(); + logger.info("Writing parameters for [{}]:\n{}", name, rendered); + writeToTempSnippetsDir("parameters", rendered); + } + + void renderTypes(String name, List args) throws IOException { + StringBuilder header = new StringBuilder("| "); + StringBuilder separator = new StringBuilder("| "); + List argNames = args.stream().map(EsqlFunctionRegistry.ArgSignature::name).toList(); + for (String arg : argNames) { + header.append(arg).append(" | "); + separator.append("---").append(" | "); + } + header.append("result |"); + separator.append("--- |"); + + List table = new ArrayList<>(); + var signatures = signatures(testClass); + for (Map.Entry, DataType> sig : signatures(testClass).entrySet()) { // TODO flip to using sortedSignatures + if (shouldHideSignature(sig.getKey(), sig.getValue())) { + continue; + } + if (sig.getKey().size() > argNames.size()) { // skip variadic [test] cases (but not those with optional parameters) + continue; + } + StringBuilder b = new StringBuilder("| "); + for (int i = 0; i < sig.getKey().size(); i++) { + DataType argType = sig.getKey().get(i); + EsqlFunctionRegistry.ArgSignature argSignature = args.get(i); + if (argSignature.mapArg()) { + b.append("named parameters"); + } else { + b.append(argType.esNameIfPossible()); + } + b.append(" | "); + } + b.append("| ".repeat(argNames.size() - sig.getKey().size())); + b.append(sig.getValue().esNameIfPossible()); + b.append(" |"); + table.add(b.toString()); + } + Collections.sort(table); + if (table.isEmpty()) { + table.add(signatures.values().iterator().next().esNameIfPossible()); + } + + String rendered = DOCS_WARNING + """ + **Supported types** + + """ + header + "\n" + separator + "\n" + table.stream().collect(Collectors.joining("\n")) + "\n\n"; + logger.info("Writing function types for [{}]:\n{}", name, rendered); + writeToTempSnippetsDir("types", rendered); + } + + void renderDescription(String description, String detailedDescription, String note) throws IOException { + description = replaceLinks(description.trim()); + note = replaceLinks(note); + String rendered = DOCS_WARNING + """ + **Description** + + """ + description + "\n"; + + detailedDescription = replaceLinks(detailedDescription.trim()); + if (Strings.isNullOrEmpty(detailedDescription) == false) { + rendered += "\n" + detailedDescription + "\n"; + } + + if (Strings.isNullOrEmpty(note) == false) { + rendered += "\n::::{note}\n" + note + "\n::::\n\n"; + } + rendered += "\n"; + logger.info("Writing description for [{}]:\n{}", name, rendered); + writeToTempSnippetsDir("description", rendered); + } + + protected boolean renderExamples(FunctionInfo info) throws IOException { + if (info == null || info.examples().length == 0) { + return false; + } + StringBuilder builder = new StringBuilder(); + builder.append(DOCS_WARNING); + if (info.examples().length == 1) { + builder.append("**Example**\n\n"); + } else { + builder.append("**Examples**\n\n"); + } + for (Example example : info.examples()) { + if (example.description().length() > 0) { + builder.append(replaceLinks(example.description().trim())); + builder.append("\n\n"); + } + String exampleQuery = loadExampleQuery(example); + String exampleResult = loadExampleResult(example); + builder.append(exampleQuery).append("\n").append(exampleResult).append("\n"); + if (example.explanation().length() > 0) { + builder.append("\n"); + builder.append(replaceLinks(example.explanation().trim())); + builder.append("\n\n"); + } + } + builder.append('\n'); + String rendered = builder.toString(); + logger.info("Writing examples for [{}]:\n{}", name, rendered); + writeToTempSnippetsDir("examples", rendered); + return true; + } + + void renderKibanaInlineDocs(String name, FunctionInfo info) throws IOException { + StringBuilder builder = new StringBuilder(); + builder.append(""" + + + """); + builder.append("### ").append(name.toUpperCase(Locale.ROOT)).append("\n"); + builder.append(removeAsciidocLinks(info.description())).append("\n\n"); + + if (info.examples().length > 0) { + Example example = info.examples()[0]; + builder.append("```\n"); + builder.append(loadExample(example.file(), example.tag())); + builder.append("\n```\n"); + } + if (Strings.isNullOrEmpty(info.note()) == false) { + builder.append("Note: ").append(removeAsciidocLinks(info.note())).append("\n"); + } + String rendered = builder.toString(); + logger.info("Writing kibana inline docs for [{}]:\n{}", name, rendered); + writeToTempKibanaDir("docs", "md", rendered); + } + + void renderKibanaFunctionDefinition(String name, FunctionInfo info, List args, boolean variadic) + throws IOException { + + try (XContentBuilder builder = JsonXContent.contentBuilder().prettyPrint().lfAtEnd().startObject()) { + builder.field( + "comment", + "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it." + ); + if (false == info.operator().isEmpty()) { + builder.field("type", "operator"); + builder.field("operator", info.operator()); + // TODO: Bring back this assertion + // assertThat(isAggregation(), equalTo(false)); + } else { + builder.field("type", switch (info.type()) { + case SCALAR -> "scalar"; + case AGGREGATE -> "agg"; + case GROUPING -> "grouping"; + }); + } + builder.field("name", name); + builder.field("description", removeAsciidocLinks(info.description())); + if (Strings.isNullOrEmpty(info.note()) == false) { + builder.field("note", removeAsciidocLinks(info.note())); + } + // TODO aliases + + builder.startArray("signatures"); + if (args.isEmpty()) { + builder.startObject(); + builder.startArray("params"); + builder.endArray(); + // There should only be one return type so just use that as the example + builder.field("returnType", signatures(testClass).values().iterator().next().esNameIfPossible()); + builder.endObject(); + } else { + int minArgCount = (int) args.stream().filter(a -> false == a.optional()).count(); + for (Map.Entry, DataType> sig : sortedSignatures()) { + if (variadic && sig.getKey().size() > args.size()) { + // For variadic functions we test much longer signatures, let’s just stop at the last one + continue; + } + if (sig.getKey().size() < minArgCount) { + throw new IllegalArgumentException("signature " + sig.getKey() + " is missing non-optional arg for " + args); + } + if (shouldHideSignature(sig.getKey(), sig.getValue())) { + continue; + } + builder.startObject(); + builder.startArray("params"); + for (int i = 0; i < sig.getKey().size(); i++) { + EsqlFunctionRegistry.ArgSignature arg = args.get(i); + builder.startObject(); + builder.field("name", arg.name()); + if (arg.mapArg()) { + builder.field("type", "function_named_parameters"); + builder.field( + "mapParams", + arg.mapParams() + .values() + .stream() + .map(mapArgSignature -> "{" + mapArgSignature + "}") + .collect(Collectors.joining(", ")) + ); + } else { + builder.field("type", sig.getKey().get(i).esNameIfPossible()); + } + builder.field("optional", arg.optional()); + builder.field("description", arg.description()); + builder.endObject(); + } + builder.endArray(); + builder.field("variadic", variadic); + builder.field("returnType", sig.getValue().esNameIfPossible()); + builder.endObject(); + } + } + builder.endArray(); + + if (info.examples().length > 0) { + builder.startArray("examples"); + for (Example example : info.examples()) { + builder.value(loadExample(example.file(), example.tag())); + } + builder.endArray(); + } + builder.field("preview", info.preview()); + builder.field("snapshot_only", EsqlFunctionRegistry.isSnapshotOnly(name)); + + String rendered = Strings.toString(builder.endObject()); + logger.info("Writing kibana function definition for [{}]:\n{}", name, rendered); + writeToTempKibanaDir("definition", "json", rendered); + } + } + + private String removeAsciidocLinks(String asciidoc) { + return asciidoc.replaceAll("[^ ]+\\[([^\\]]+)\\]", "$1"); + } + + private List, DataType>> sortedSignatures() { + List, DataType>> sortedSignatures = new ArrayList<>(signatures(testClass).entrySet()); + Collections.sort(sortedSignatures, (lhs, rhs) -> { + int maxlen = Math.max(lhs.getKey().size(), rhs.getKey().size()); + for (int i = 0; i < maxlen; i++) { + if (lhs.getKey().size() <= i) { + return -1; + } + if (rhs.getKey().size() <= i) { + return 1; + } + int c = lhs.getKey().get(i).esNameIfPossible().compareTo(rhs.getKey().get(i).esNameIfPossible()); + if (c != 0) { + return c; + } + } + return lhs.getValue().esNameIfPossible().compareTo(rhs.getValue().esNameIfPossible()); + }); + return sortedSignatures; + } + + protected boolean renderAppendix(String appendix) throws IOException { + if (appendix.isEmpty()) { + return false; + } + + String rendered = DOCS_WARNING + replaceLinks(appendix) + "\n"; + + logger.info("Writing appendix for [{}]:\n{}", name, rendered); + writeToTempSnippetsDir("appendix", rendered); + return true; + } + + private HashMap> examples = new HashMap<>(); + + protected String loadExampleQuery(Example example) throws IOException { + return "```esql\n" + loadExample(example.file(), example.tag()) + "\n```\n"; + } + + protected String loadExampleResult(Example example) throws IOException { + return loadExample(example.file(), example.tag() + "-result"); + } + + protected String loadExample(String csvSpec, String tag) throws IOException { + if (examples.containsKey(csvSpec) == false) { + var taggedExamples = loadExampleFile(csvSpec); + examples.put(csvSpec, taggedExamples); + return taggedExamples.get(tag); + } else { + return examples.get(csvSpec).get(tag); + } + } + + protected Map loadExampleFile(String csvSpec) throws IOException { + Map taggedExamples = new HashMap<>(); + String csvFile = csvSpec.endsWith(".csv-spec") ? csvSpec : csvSpec + ".csv-spec"; + InputStream specInputStream = CsvTestsDataLoader.class.getResourceAsStream("/" + csvFile); + if (specInputStream == null) { + throw new IllegalArgumentException("Failed to find examples file [" + csvFile + "]"); + } + try (BufferedReader spec = new BufferedReader(new InputStreamReader(specInputStream, StandardCharsets.UTF_8))) { + + String line; + Pattern tagPattern = Pattern.compile("//\\s*(tag|end)::([\\w\\-_]+)\\[]"); + + String currentTag = null; + List currentLines = null; + + while ((line = spec.readLine()) != null) { + Matcher tagMatcher = tagPattern.matcher(line); + if (tagMatcher.find()) { + String tagType = tagMatcher.group(1); + currentTag = tagMatcher.group(2); + if (tagType.equals("tag")) { + currentLines = new ArrayList<>(); + } else if (tagType.equals("end")) { + if (currentLines == null) { + throw new IllegalArgumentException("End tag found, but no starting tag was found: " + line); + } + taggedExamples.put(currentTag, reformatExample(currentTag, currentLines)); + currentLines = null; + currentTag = null; + } + } else if (currentTag != null) { + currentLines.add(line); // Collect lines within the block + } + } + } + return taggedExamples; + } + + protected String reformatExample(String tag, List lines) { + if (tag.endsWith("-result")) { + StringBuffer sb = new StringBuffer(); + for (String line : lines) { + sb.append(renderTableLine(line, sb.isEmpty())); + } + return sb.toString(); + } else { + return lines.stream().map(l -> l.stripTrailing().replaceAll("\\\\", "\\\\\\\\")).collect(Collectors.joining("\n")); + } + } + + private String renderTableLine(String line, boolean header) { + String[] columns = line.split("\\|"); + if (header) { + return renderTableLine(columns) + renderTableSpacerLine(columns.length); + } else { + return renderTableLine(columns); + } + } + + private String renderTableLine(String[] columns) { + StringBuffer sb = new StringBuffer(); + sb.append("| "); + for (int i = 0; i < columns.length; i++) { + if (i > 0) { + sb.append(" | "); + } + // Some cells have regex content (see CATEGORIZE), so we need to escape this + sb.append(columns[i].trim().replaceAll("\\.\\*", ".\\\\*")); + } + return sb.append(" |\n").toString(); + } + + private String renderTableSpacerLine(int columns) { + StringBuffer sb = new StringBuffer(); + sb.append("| "); + for (int i = 0; i < columns; i++) { + if (i > 0) { + sb.append(" | "); + } + sb.append("---"); + } + return sb.append(" |\n").toString(); + } +} diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3SupportTests.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3SupportTests.java new file mode 100644 index 0000000000000..e17127b98b0bc --- /dev/null +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3SupportTests.java @@ -0,0 +1,332 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0; you may not use this file except in compliance with the Elastic License + * 2.0. + */ + +package org.elasticsearch.xpack.esql.expression.function; + +import org.elasticsearch.test.ESTestCase; + +import java.io.IOException; +import java.lang.reflect.Constructor; + +import static org.hamcrest.Matchers.equalTo; + +public class DocsV3SupportTests extends ESTestCase { + private static DocsV3Support docs = DocsV3Support.forFunctions("test", DocsV3SupportTests.class); + + public void testFunctionLink() { + String text = "The value that is greater than half of all values and less than half of all values, " + + "also known as the 50% <>."; + String expected = "The value that is greater than half of all values and less than half of all values, " + + "also known as the 50% [`PERCENTILE`](/reference/query-languages/esql/esql-functions-operators.md#esql-percentile)."; + assertThat(docs.replaceLinks(text), equalTo(expected)); + } + + public void testOperatorLink() { + String text = "If you need floating point division, <> one of the arguments to a `DOUBLE`."; + String expected = """ + If you need floating point division, + [`Cast (::)`](/reference/query-languages/esql/esql-functions-operators.md#esql-cast-operator) + one of the arguments to a `DOUBLE`.""".replaceAll("\n", " "); + assertThat(docs.replaceLinks(text), equalTo(expected)); + } + + public void testCommandLink() { + String text = "use a <> command to remove rows"; + String expected = "use a [`WHERE`](/reference/query-languages/esql/esql-commands.md#esql-where) command to remove rows"; + assertThat(docs.replaceLinks(text), equalTo(expected)); + } + + public void testStatsCommandLink() { + String text = "Combine `DATE_TRUNC` with <>"; + String expected = "Combine `DATE_TRUNC` with [`STATS`](/reference/query-languages/esql/esql-commands.md#esql-stats-by)"; + assertThat(docs.replaceLinks(text), equalTo(expected)); + } + + public void testFunctionAndHeaderLinks() { + String text = "Like <>, `MEDIAN` is <>."; + String expected = "Like [`PERCENTILE`](/reference/query-languages/esql/esql-functions-operators.md#esql-percentile), " + + "`MEDIAN` is [usually approximate](/reference/query-languages/esql/esql-functions-operators.md#esql-percentile-approximate)."; + assertThat(docs.replaceLinks(text), equalTo(expected)); + } + + public void testWikipediaMacro() { + String text = "Returns the {wikipedia}/Inverse_trigonometric_functions[arccosine] of `n` as an angle, expressed in radians."; + String expected = "Returns the [arccosine](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions) " + + "of `n` as an angle, expressed in radians."; + assertThat(docs.replaceLinks(text), equalTo(expected)); + } + + public void testWikipediaMacro2() { + String text = "This builds on the three-valued logic ({wikipedia}/Three-valued_logic[3VL]) of the language."; + String expected = + "This builds on the three-valued logic ([3VL](https://en.wikipedia.org/wiki/Three-valued_logic)) of the language."; + assertThat(docs.replaceLinks(text), equalTo(expected)); + } + + public void testJavadocMacro() { + String text = "This is a noop for `long` (including unsigned) and `integer`.\n" + + "For `double` this picks the closest `double` value to the integer similar to\n" + + "{javadoc}/java.base/java/lang/Math.html#ceil(double)[Math.ceil]."; + String expected = "This is a noop for `long` (including unsigned) and `integer`.\n" + + "For `double` this picks the closest `double` value to the integer similar to\n" + + "[Math.ceil](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Math.html#ceil(double))."; + assertThat(docs.replaceLinks(text), equalTo(expected)); + } + + public void testJavadoc8Macro() { + String text = "Refer to {javadoc8}/java/time/temporal/ChronoField.html[java.time.temporal.ChronoField]"; + String expected = + "Refer to [java.time.temporal.ChronoField](https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoField.html)"; + assertThat(docs.replaceLinks(text), equalTo(expected)); + } + + public void testJavadoc8MacroLongText() { + String text = """ + Part of the date to extract.\n + 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 {javadoc8}/java/time/temporal/ChronoField.html[java.time.temporal.ChronoField] + for a description of these values.\n + If `null`, the function returns `null`."""; + String expected = """ + Part of the date to extract.\n + 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 [java.time.temporal.ChronoField](https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoField.html) + for a description of these values.\n + If `null`, the function returns `null`."""; + assertThat(docs.replaceLinks(text), equalTo(expected)); + } + + public void testExampleLoadMacro() { + String text = "<>"; + String expected = """ + ```esql + ROW message = "foo ( bar" + | WHERE message RLIKE "foo \\\\( bar" + ``` + """; + assertThat(docs.replaceLinks(text), equalTo(expected)); + } + + public void testKnownRootEsqlFiles() { + String text = """ + The order that <> + are read from underlying storage is not guaranteed"""; + String expected = """ + The order that [multivalued fields](/reference/query-languages/esql/esql-multivalued-fields.md) + are read from underlying storage is not guaranteed"""; + assertThat(docs.replaceLinks(text), equalTo(expected)); + } + + public void testKnownRootWithTag() { + String text = """ + Match can use <> + to specify additional options for the match query."""; + String expected = """ + Match can use [function named parameters](/reference/query-languages/esql/esql-syntax.md#esql-function-named-params) + to specify additional options for the match query."""; + assertThat(docs.replaceLinks(text), equalTo(expected)); + } + + public void testRenderingExampleRaw() throws IOException { + String expectedExample = """ + ROW wkt = "POINT(42.97109630194 14.7552534413725)" + | EVAL pt = TO_GEOPOINT(wkt)"""; + String example = docs.loadExample("spatial.csv-spec", "to_geopoint-str"); + assertThat(example, equalTo(expectedExample)); + } + + public void testRenderingExampleResultRaw() throws IOException { + String expectedResults = """ + | wkt:keyword | pt:geo_point | + | --- | --- | + | "POINT(42.97109630194 14.7552534413725)" | POINT(42.97109630194 14.7552534413725) | + """; + String results = docs.loadExample("spatial.csv-spec", "to_geopoint-str-result"); + assertThat(results, equalTo(expectedResults)); + } + + public void testRenderingExampleRaw2() throws IOException { + String expectedExample = """ + ROW n=1 + | STATS COUNT(n > 0 OR NULL), COUNT(n < 0 OR NULL)"""; + String example = docs.loadExample("stats", "count-or-null"); + assertThat(example, equalTo(expectedExample)); + } + + public void testRenderingExampleResultRaw2() throws IOException { + String expectedResults = """ + | COUNT(n > 0 OR NULL):long | COUNT(n < 0 OR NULL):long | + | --- | --- | + | 1 | 0 | + """; + String results = docs.loadExample("stats", "count-or-null-result"); + assertThat(results, equalTo(expectedResults)); + } + + public void testRenderingExampleEmojis() throws IOException { + String expectedResults = "ROW bending_arts = \"💧🪨🔥💨\" | EVAL bending_arts_reversed = REVERSE(bending_arts);"; + String results = docs.loadExample("string", "reverseEmoji"); + assertThat(results, equalTo(expectedResults)); + } + + public void testRenderingExampleResultEmojis() throws IOException { + String expectedResults = """ + | bending_arts:keyword | bending_arts_reversed:keyword | + | --- | --- | + | 💧🪨🔥💨 | 💨🔥🪨💧 | + """; + String results = docs.loadExample("string", "reverseEmoji-result"); + assertThat(results, equalTo(expectedResults)); + } + + public void testRenderingExampleFromClass() throws IOException { + String expected = """ + + ```esql + FROM employees + | STATS COUNT(height) + ``` + + | COUNT(height):long | + | --- | + | 100 | + + To count the number of rows, use `COUNT()` or `COUNT(*)` + + ```esql + FROM employees + | STATS count = COUNT(*) BY languages + | SORT languages DESC + ``` + + | count:long | languages:integer | + | --- | --- | + | 10 | null | + | 21 | 5 | + | 18 | 4 | + | 17 | 3 | + | 19 | 2 | + | 15 | 1 | + + The expression can use inline functions. This example splits a string into multiple values + using the `SPLIT` function and counts the values + + ```esql + ROW words="foo;bar;baz;qux;quux;foo" + | STATS word_count = COUNT(SPLIT(words, ";")) + ``` + + | word_count:long | + | --- | + | 6 | + + To count the number of times an expression returns `TRUE` use a + [`WHERE`](/reference/query-languages/esql/esql-commands.md#esql-where) command + to remove rows that shouldn’t be included + + ```esql + ROW n=1 + | WHERE n < 0 + | STATS COUNT(n) + ``` + + | COUNT(n):long | + | --- | + | 0 | + + To count the same stream of data based on two different expressions use the pattern + `COUNT( OR NULL)`. This builds on the three-valued logic + ([3VL](https://en.wikipedia.org/wiki/Three-valued_logic)) of the language: + `TRUE OR NULL` is `TRUE`, but `FALSE OR NULL` is `NULL`, plus the way COUNT handles + `NULL`s: `COUNT(TRUE)` and `COUNT(FALSE)` are both 1, but `COUNT(NULL)` is 0. + + ```esql + ROW n=1 + | STATS COUNT(n > 0 OR NULL), COUNT(n < 0 OR NULL) + ``` + + | COUNT(n > 0 OR NULL):long | COUNT(n < 0 OR NULL):long | + | --- | --- | + | 1 | 0 | + """; + FunctionInfo info = functionInfo(TestClass.class); + assert info != null; + DocsV3Support docs = DocsV3Support.forFunctions("count", TestClass.class); + StringBuilder results = new StringBuilder(); + for (Example example : info.examples()) { + if (example.description().isEmpty() == false) { + results.append("\n"); + results.append(docs.replaceLinks(example.description().trim())); + results.append("\n"); + } + String query = docs.loadExampleQuery(example); + String result = docs.loadExampleResult(example); + results.append("\n").append(query).append("\n").append(result); + } + assertThat(results.toString(), equalTo(expected)); + } + + private static FunctionInfo functionInfo(Class clazz) { + Constructor constructor = constructorFor(clazz); + if (constructor == null) { + return null; + } + return constructor.getAnnotation(FunctionInfo.class); + } + + private static Constructor constructorFor(Class clazz) { + Constructor[] constructors = clazz.getConstructors(); + if (constructors.length == 0) { + return null; + } + if (constructors.length > 1) { + for (Constructor constructor : constructors) { + if (constructor.getAnnotation(FunctionInfo.class) != null) { + return constructor; + } + } + } + return constructors[0]; + } + + public static class TestClass { + @FunctionInfo( + returnType = "long", + description = "Returns the total number (count) of input values.", + type = FunctionType.AGGREGATE, + examples = { + @Example(file = "stats", tag = "count"), + @Example(description = "To count the number of rows, use `COUNT()` or `COUNT(*)`", file = "docs", tag = "countAll"), + @Example(description = """ + The expression can use inline functions. This example splits a string into multiple values + using the `SPLIT` function and counts the values""", file = "stats", tag = "docsCountWithExpression"), + @Example(description = """ + To count the number of times an expression returns `TRUE` use a + <> command + to remove rows that shouldn’t be included""", file = "stats", tag = "count-where"), + @Example( + description = """ + To count the same stream of data based on two different expressions use the pattern + `COUNT( OR NULL)`. This builds on the three-valued logic + ({wikipedia}/Three-valued_logic[3VL]) of the language: + `TRUE OR NULL` is `TRUE`, but `FALSE OR NULL` is `NULL`, plus the way COUNT handles + `NULL`s: `COUNT(TRUE)` and `COUNT(FALSE)` are both 1, but `COUNT(NULL)` is 0.""", + file = "stats", + tag = "count-or-null" + ) } + ) + public TestClass() {} + } +} diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/RailRoadDiagram.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/RailRoadDiagram.java index 43e2ededeff0e..dfec2a563b429 100644 --- a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/RailRoadDiagram.java +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/RailRoadDiagram.java @@ -123,21 +123,7 @@ private static String toSvg(Expression exp) throws IOException { toSvg.setLiteralFont(FONT.getOrCompute()); toSvg.setRuleFont(FONT.getOrCompute()); - return tightenStyles(toSvg.convert(rrDiagram)); - } - - /** - * "Tighten" the styles in the SVG so they beat the styles sitting in the - * main page. We need this because we're embedding the SVG into the page. - * We need to embed the SVG into the page so it can get fonts loaded in the - * primary stylesheet. We need to load a font so they images are consistent - * on all clients. - */ - private static String tightenStyles(String svg) { - for (String c : new String[] { "c", "k", "s", "j", "l" }) { - svg = svg.replace("." + c, "#guide ." + c); - } - return svg; + return toSvg.convert(rrDiagram); } /** diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/RLikeTests.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/RLikeTests.java index 26340be224082..5578b2bfb1919 100644 --- a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/RLikeTests.java +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/RLikeTests.java @@ -28,6 +28,7 @@ import java.util.function.Function; import java.util.function.Supplier; +import static org.elasticsearch.xpack.esql.expression.function.DocsV3Support.renderNegatedOperator; import static org.hamcrest.Matchers.equalTo; import static org.hamcrest.Matchers.nullValue; import static org.hamcrest.Matchers.startsWith; @@ -155,6 +156,6 @@ static Expression buildRLike(Logger logger, Source source, List args @AfterClass public static void renderNotRLike() throws IOException { - WildcardLikeTests.renderNot(constructorWithFunctionInfo(RLike.class), "RLIKE", d -> d); + renderNegatedOperator(constructorWithFunctionInfo(RLike.class), "RLIKE", d -> d, getTestClass()); } } diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/WildcardLikeTests.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/WildcardLikeTests.java index 53e666738e182..f53ece7bca73d 100644 --- a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/WildcardLikeTests.java +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/WildcardLikeTests.java @@ -9,7 +9,6 @@ import com.carrotsearch.randomizedtesting.annotations.Name; import com.carrotsearch.randomizedtesting.annotations.ParametersFactory; -import com.unboundid.util.NotNull; import org.apache.lucene.util.BytesRef; import org.elasticsearch.xpack.esql.core.expression.Expression; @@ -19,22 +18,16 @@ import org.elasticsearch.xpack.esql.core.tree.Source; import org.elasticsearch.xpack.esql.core.type.DataType; import org.elasticsearch.xpack.esql.expression.function.AbstractScalarFunctionTestCase; -import org.elasticsearch.xpack.esql.expression.function.Example; -import org.elasticsearch.xpack.esql.expression.function.FunctionInfo; import org.elasticsearch.xpack.esql.expression.function.FunctionName; -import org.elasticsearch.xpack.esql.expression.function.FunctionType; import org.elasticsearch.xpack.esql.expression.function.TestCaseSupplier; import org.junit.AfterClass; import java.io.IOException; -import java.lang.annotation.Annotation; -import java.lang.reflect.Constructor; import java.util.ArrayList; import java.util.List; -import java.util.Locale; -import java.util.function.Function; import java.util.function.Supplier; +import static org.elasticsearch.xpack.esql.expression.function.DocsV3Support.renderNegatedOperator; import static org.hamcrest.Matchers.equalTo; import static org.hamcrest.Matchers.startsWith; @@ -100,64 +93,6 @@ static Expression buildWildcardLike(Source source, List args) { @AfterClass public static void renderNotLike() throws IOException { - renderNot(constructorWithFunctionInfo(WildcardLike.class), "LIKE", d -> d); - } - - public static void renderNot(@NotNull Constructor ctor, String name, Function description) throws IOException { - FunctionInfo orig = ctor.getAnnotation(FunctionInfo.class); - assert orig != null; - FunctionInfo functionInfo = new FunctionInfo() { - @Override - public Class annotationType() { - return orig.annotationType(); - } - - @Override - public String operator() { - return "NOT " + name; - } - - @Override - public String[] returnType() { - return orig.returnType(); - } - - @Override - public boolean preview() { - return orig.preview(); - } - - @Override - public String description() { - return description.apply(orig.description().replace(name, "NOT " + name)); - } - - @Override - public String detailedDescription() { - return ""; - } - - @Override - public String note() { - return orig.note().replace(name, "NOT " + name); - } - - @Override - public String appendix() { - return orig.appendix().replace(name, "NOT " + name); - } - - @Override - public FunctionType type() { - return orig.type(); - } - - @Override - public Example[] examples() { - // throw away examples - return new Example[] {}; - } - }; - renderDocsForOperators("not_" + name.toLowerCase(Locale.ENGLISH), ctor, functionInfo); + renderNegatedOperator(constructorWithFunctionInfo(WildcardLike.class), "LIKE", d -> d, getTestClass()); } } diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/predicate/operator/comparison/InTests.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/predicate/operator/comparison/InTests.java index 03a4b063d6294..8177ac22abaad 100644 --- a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/predicate/operator/comparison/InTests.java +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/predicate/operator/comparison/InTests.java @@ -19,7 +19,6 @@ import org.elasticsearch.xpack.esql.core.type.DataType; import org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase; import org.elasticsearch.xpack.esql.expression.function.TestCaseSupplier; -import org.elasticsearch.xpack.esql.expression.function.scalar.string.WildcardLikeTests; import org.junit.AfterClass; import java.io.IOException; @@ -38,6 +37,7 @@ import static org.elasticsearch.xpack.esql.core.type.DataType.GEO_SHAPE; import static org.elasticsearch.xpack.esql.core.util.SpatialCoordinateTypes.CARTESIAN; import static org.elasticsearch.xpack.esql.core.util.SpatialCoordinateTypes.GEO; +import static org.elasticsearch.xpack.esql.expression.function.DocsV3Support.renderNegatedOperator; import static org.hamcrest.Matchers.equalTo; import static org.hamcrest.Matchers.matchesPattern; @@ -339,11 +339,12 @@ protected Expression build(Source source, List args) { @AfterClass public static void renderNotIn() throws IOException { - WildcardLikeTests.renderNot( + renderNegatedOperator( constructorWithFunctionInfo(In.class), "IN", d -> "The `NOT IN` operator allows testing whether a field or expression does *not* equal any element " - + "in a list of literals, fields or expressions." + + "in a list of literals, fields or expressions.", + getTestClass() ); } }