diff --git a/explore-analyze/query-filter/languages/sql-cli.md b/explore-analyze/query-filter/languages/sql-cli.md index 93a376cfff..b511233551 100644 --- a/explore-analyze/query-filter/languages/sql-cli.md +++ b/explore-analyze/query-filter/languages/sql-cli.md @@ -28,7 +28,7 @@ If security is enabled on your cluster, you can pass the username and password i $ ./bin/elasticsearch-sql-cli https://sql_user:strongpassword@some.server:9200 ``` -Once the CLI is running you can use any [query](sql-spec.md) that Elasticsearch supports: +Once the CLI is running you can use any [query](elasticsearch://reference/query-languages/sql/sql-spec.md) that Elasticsearch supports: ```sql sql> SELECT * FROM library WHERE page_count > 500 ORDER BY page_count DESC; diff --git a/explore-analyze/query-filter/languages/sql-commands.md b/explore-analyze/query-filter/languages/sql-commands.md deleted file mode 100644 index 231754d745..0000000000 --- a/explore-analyze/query-filter/languages/sql-commands.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-commands.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# SQL Commands [sql-commands] - -This section contains the list of SQL commands supported by Elasticsearch SQL along with their syntax: - -[DESCRIBE TABLE](sql-syntax-describe-table.md) -: Describe a table. - -[SELECT](sql-syntax-select.md) -: Retrieve rows from zero or more tables. - -[SHOW CATALOGS](sql-syntax-show-catalogs.md) -: List available catalogs. - -[SHOW COLUMNS](sql-syntax-show-columns.md) -: List columns in table. - -[SHOW FUNCTIONS](sql-syntax-show-functions.md) -: List supported functions. - -[SHOW TABLES](sql-syntax-show-tables.md) -: List tables available. - diff --git a/explore-analyze/query-filter/languages/sql-concepts.md b/explore-analyze/query-filter/languages/sql-concepts.md index 0f569971e6..b63a913e46 100644 --- a/explore-analyze/query-filter/languages/sql-concepts.md +++ b/explore-analyze/query-filter/languages/sql-concepts.md @@ -29,7 +29,7 @@ So let’s start from the bottom; these roughly are: | SQL | {{es}} | Description | | --- | --- | --- | -| `column` | `field` | In both cases, at the lowest level, data is stored in *named* entries, of a variety of [data types](sql-data-types.md), containing *one* value. SQL calls such an entry a *column* while {{es}} a *field*.Notice that in {{es}} a field can contain *multiple* values of the same type (essentially a list) while in SQL, a *column* can contain *exactly* one value of said type.Elasticsearch SQL will do its best to preserve the SQL semantic and, depending on the query, reject those that return fields with more than one value. | +| `column` | `field` | In both cases, at the lowest level, data is stored in *named* entries, of a variety of [data types](elasticsearch://reference/query-languages/sql/sql-data-types.md), containing *one* value. SQL calls such an entry a *column* while {{es}} a *field*. Notice that in {{es}} a field can contain *multiple* values of the same type (essentially a list) while in SQL, a *column* can contain *exactly* one value of said type. Elasticsearch SQL will do its best to preserve the SQL semantic and, depending on the query, reject those that return fields with more than one value. | | `row` | `document` | `Column`s and `field`s do *not* exist by themselves; they are part of a `row` or a `document`. The two have slightly different semantics: a `row` tends to be *strict* (and have more enforcements) while a `document` tends to be a bit more flexible or loose (while still having a structure). | | `table` | `index` | The target against which queries, whether in SQL or {{es}} get executed against. | | `schema` | *implicit* | In RDBMS, `schema` is mainly a namespace of tables and typically used as a security boundary. {{es}} does not provide an equivalent concept for it. However when security is enabled, {{es}} automatically applies the security enforcement so that a role sees only the data it is allowed to (in SQL jargon, its *schema*). | diff --git a/explore-analyze/query-filter/languages/sql-data-types.md b/explore-analyze/query-filter/languages/sql-data-types.md deleted file mode 100644 index 0ced0e25bc..0000000000 --- a/explore-analyze/query-filter/languages/sql-data-types.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-data-types.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Data Types [sql-data-types] - -| {{es}} type | Elasticsearch SQL type | SQL type | SQL precision | -| --- | --- | --- | --- | -| Core types | -| [`null`](elasticsearch://reference/elasticsearch/mapping-reference/null-value.md) | `null` | NULL | 0 | -| [`boolean`](elasticsearch://reference/elasticsearch/mapping-reference/boolean.md) | `boolean` | BOOLEAN | 1 | -| [`byte`](elasticsearch://reference/elasticsearch/mapping-reference/number.md) | `byte` | TINYINT | 3 | -| [`short`](elasticsearch://reference/elasticsearch/mapping-reference/number.md) | `short` | SMALLINT | 5 | -| [`integer`](elasticsearch://reference/elasticsearch/mapping-reference/number.md) | `integer` | INTEGER | 10 | -| [`long`](elasticsearch://reference/elasticsearch/mapping-reference/number.md) | `long` | BIGINT | 19 | -| [`unsigned_long`](elasticsearch://reference/elasticsearch/mapping-reference/number.md) | `[preview] unsigned_long` | BIGINT | 20 | -| [`double`](elasticsearch://reference/elasticsearch/mapping-reference/number.md) | `double` | DOUBLE | 15 | -| [`float`](elasticsearch://reference/elasticsearch/mapping-reference/number.md) | `float` | REAL | 7 | -| [`half_float`](elasticsearch://reference/elasticsearch/mapping-reference/number.md) | `half_float` | FLOAT | 3 | -| [`scaled_float`](elasticsearch://reference/elasticsearch/mapping-reference/number.md) | `scaled_float` | DOUBLE | 15 | -| [keyword type family](elasticsearch://reference/elasticsearch/mapping-reference/keyword.md) | `keyword` | VARCHAR | 32,766 | -| [`text`](elasticsearch://reference/elasticsearch/mapping-reference/text.md) | `text` | VARCHAR | 2,147,483,647 | -| [`binary`](elasticsearch://reference/elasticsearch/mapping-reference/binary.md) | `binary` | VARBINARY | 2,147,483,647 | -| [`date`](elasticsearch://reference/elasticsearch/mapping-reference/date.md) | `datetime` | TIMESTAMP | 29 | -| [`ip`](elasticsearch://reference/elasticsearch/mapping-reference/ip.md) | `ip` | VARCHAR | 39 | -| [`version`](elasticsearch://reference/elasticsearch/mapping-reference/version.md) | `version` | VARCHAR | 32,766 | -| Complex types | -| [`object`](elasticsearch://reference/elasticsearch/mapping-reference/object.md) | `object` | STRUCT | 0 | -| [`nested`](elasticsearch://reference/elasticsearch/mapping-reference/nested.md) | `nested` | STRUCT | 0 | -| Unsupported types | -| *types not mentioned above* | `unsupported` | OTHER | 0 | - -::::{note} -Most of {{es}} [data types](elasticsearch://reference/elasticsearch/mapping-reference/field-data-types.md) are available in Elasticsearch SQL, as indicated above. As one can see, all of {{es}} [data types](elasticsearch://reference/elasticsearch/mapping-reference/field-data-types.md) are mapped to the data type with the same name in Elasticsearch SQL, with the exception of **date** data type which is mapped to **datetime** in Elasticsearch SQL. This is to avoid confusion with the ANSI SQL types **DATE** (date only) and **TIME** (time only), which are also supported by Elasticsearch SQL in queries (with the use of [`CAST`](sql-functions-type-conversion.md#sql-functions-type-conversion-cast)/[`CONVERT`](sql-functions-type-conversion.md#sql-functions-type-conversion-convert)), but don’t correspond to an actual mapping in {{es}} (see the [`table`](#es-sql-only-types) below). -:::: - - -Obviously, not all types in {{es}} have an equivalent in SQL and vice-versa hence why, Elasticsearch SQL uses the data type *particularities* of the former over the latter as ultimately {{es}} is the backing store. - -In addition to the types above, Elasticsearch SQL also supports at *runtime* SQL-specific types that do not have an equivalent in {{es}}. Such types cannot be loaded from {{es}} (as it does not know about them) however can be used inside Elasticsearch SQL in queries or their results. - -$$$es-sql-only-types$$$ -The table below indicates these types: - -| SQL type | SQL precision | -| --- | --- | -| `date` | 29 | -| `time` | 18 | -| `interval_year` | 7 | -| `interval_month` | 7 | -| `interval_day` | 23 | -| `interval_hour` | 23 | -| `interval_minute` | 23 | -| `interval_second` | 23 | -| `interval_year_to_month` | 7 | -| `interval_day_to_hour` | 23 | -| `interval_day_to_minute` | 23 | -| `interval_day_to_second` | 23 | -| `interval_hour_to_minute` | 23 | -| `interval_hour_to_second` | 23 | -| `interval_minute_to_second` | 23 | -| `geo_point` | 52 | -| `geo_shape` | 2,147,483,647 | -| `shape` | 2,147,483,647 | - - -## SQL and multi-fields [sql-multi-field] - -A core concept in {{es}} is that of an `analyzed` field, that is a full-text value that is interpreted in order to be effectively indexed. These fields are of type [`text`](elasticsearch://reference/elasticsearch/mapping-reference/text.md) and are not used for sorting or aggregations as their actual value depends on the [`analyzer`](elasticsearch://reference/elasticsearch/mapping-reference/analyzer.md) used hence why {{es}} also offers the [`keyword`](elasticsearch://reference/elasticsearch/mapping-reference/keyword.md) type for storing the *exact* value. - -In most case, and the default actually, is to use both types for strings which {{es}} supports through [multi-fields](elasticsearch://reference/elasticsearch/mapping-reference/multi-fields.md), that is the ability to index the same string in multiple ways; for example index it both as `text` for search but also as `keyword` for sorting and aggregations. - -As SQL requires exact values, when encountering a `text` field Elasticsearch SQL will search for an exact multi-field that it can use for comparisons, sorting and aggregations. To do that, it will search for the first `keyword` that it can find that is *not* normalized and use that as the original field *exact* value. - -Consider the following `string` mapping: - -```js -{ - "first_name": { - "type": "text", - "fields": { - "raw": { - "type": "keyword" - } - } - } -} -``` - -The following SQL query: - -```sql -SELECT first_name FROM index WHERE first_name = 'John' -``` - -is identical to: - -```sql -SELECT first_name FROM index WHERE first_name.raw = 'John' -``` - -as Elasticsearch SQL automatically *picks* up the `raw` multi-field from `raw` for exact matching. diff --git a/explore-analyze/query-filter/languages/sql-functions-aggs.md b/explore-analyze/query-filter/languages/sql-functions-aggs.md deleted file mode 100644 index 789a5b3e89..0000000000 --- a/explore-analyze/query-filter/languages/sql-functions-aggs.md +++ /dev/null @@ -1,893 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-functions-aggs.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Aggregate Functions [sql-functions-aggs] - -Functions for computing a *single* result from a set of input values. Elasticsearch SQL supports aggregate functions only alongside [grouping](sql-syntax-select.md#sql-syntax-group-by) (implicit or explicit). - - -## General Purpose [sql-functions-aggs-general] - -## `AVG` [sql-functions-aggs-avg] - -```sql -AVG(numeric_field) <1> -``` - -**Input**: - -1. numeric field. If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. - - -**Output**: `double` numeric value - -**Description**: Returns the [Average](https://en.wikipedia.org/wiki/Arithmetic_mean) (arithmetic mean) of input values. - -```sql -SELECT AVG(salary) AS avg FROM emp; - - avg ---------------- -48248.55 -``` - -```sql -SELECT AVG(salary / 12.0) AS avg FROM emp; - - avg ---------------- -4020.7125 -``` - - -## `COUNT` [sql-functions-aggs-count] - -```sql -COUNT(expression) <1> -``` - -**Input**: - -1. a field name, wildcard (`*`) or any numeric value. For `COUNT(*)` or `COUNT()`, all values are considered, including `null` or missing ones. For `COUNT()`, `null` values are not considered. - - -**Output**: numeric value - -**Description**: Returns the total number (count) of input values. - -```sql -SELECT COUNT(*) AS count FROM emp; - - count ---------------- -100 -``` - - -## `COUNT(ALL)` [sql-functions-aggs-count-all] - -```sql -COUNT(ALL field_name) <1> -``` - -**Input**: - -1. a field name. If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. - - -**Output**: numeric value - -**Description**: Returns the total number (count) of all *non-null* input values. `COUNT()` and `COUNT(ALL )` are equivalent. - -```sql -SELECT COUNT(ALL last_name) AS count_all, COUNT(DISTINCT last_name) count_distinct FROM emp; - - count_all | count_distinct ----------------+------------------ -100 |96 -``` - -```sql -SELECT COUNT(ALL CASE WHEN languages IS NULL THEN -1 ELSE languages END) AS count_all, COUNT(DISTINCT CASE WHEN languages IS NULL THEN -1 ELSE languages END) count_distinct FROM emp; - - count_all | count_distinct ----------------+--------------- -100 |6 -``` - - -## `COUNT(DISTINCT)` [sql-functions-aggs-count-distinct] - -```sql -COUNT(DISTINCT field_name) <1> -``` - -**Input**: - -1. a field name - - -**Output**: numeric value. If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. - -**Description**: Returns the total number of *distinct non-null* values in input values. - -```sql -SELECT COUNT(DISTINCT hire_date) unique_hires, COUNT(hire_date) AS hires FROM emp; - - unique_hires | hires -----------------+--------------- -99 |100 -``` - -```sql -SELECT COUNT(DISTINCT DATE_TRUNC('YEAR', hire_date)) unique_hires, COUNT(DATE_TRUNC('YEAR', hire_date)) AS hires FROM emp; - - unique_hires | hires ----------------+--------------- -14 |100 -``` - - -## `FIRST/FIRST_VALUE` [sql-functions-aggs-first] - -```sql -FIRST( - field_name <1> - [, ordering_field_name]) <2> -``` - -**Input**: - -1. target field for the aggregation -2. optional field used for ordering - - -**Output**: same type as the input - -**Description**: Returns the first non-`null` value (if such exists) of the `field_name` input column sorted by the `ordering_field_name` column. If `ordering_field_name` is not provided, only the `field_name` column is used for the sorting. E.g.: - -| a | b | -| --- | --- | -| 100 | 1 | -| 200 | 1 | -| 1 | 2 | -| 2 | 2 | -| 10 | null | -| 20 | null | -| null | null | - -```sql -SELECT FIRST(a) FROM t -``` - -will result in: - -| FIRST(a) | -| --- | -| 1 | - -and - -```sql -SELECT FIRST(a, b) FROM t -``` - -will result in: - -| FIRST(a, b) | -| --- | -| 100 | - -```sql -SELECT FIRST(first_name) FROM emp; - - FIRST(first_name) --------------------- -Alejandro -``` - -```sql -SELECT gender, FIRST(first_name) FROM emp GROUP BY gender ORDER BY gender; - - gender | FIRST(first_name) -------------+-------------------- -null | Berni -F | Alejandro -M | Amabile -``` - -```sql -SELECT FIRST(first_name, birth_date) FROM emp; - - FIRST(first_name, birth_date) --------------------------------- -Remzi -``` - -```sql -SELECT gender, FIRST(first_name, birth_date) FROM emp GROUP BY gender ORDER BY gender; - - gender | FIRST(first_name, birth_date) ---------------+-------------------------------- -null | Lillian -F | Sumant -M | Remzi -``` - -`FIRST_VALUE` is a name alias and can be used instead of `FIRST`, e.g.: - -```sql -SELECT gender, FIRST_VALUE(first_name, birth_date) FROM emp GROUP BY gender ORDER BY gender; - - gender | FIRST_VALUE(first_name, birth_date) ---------------+-------------------------------------- -null | Lillian -F | Sumant -M | Remzi -``` - -```sql -SELECT gender, FIRST_VALUE(SUBSTRING(first_name, 2, 6), birth_date) AS "first" FROM emp GROUP BY gender ORDER BY gender; - - gender | first ----------------+--------------- -null |illian -F |umant -M |emzi -``` - -::::{note} -`FIRST` cannot be used in a HAVING clause. -:::: - - -::::{note} -`FIRST` cannot be used with columns of type [`text`](elasticsearch://reference/elasticsearch/mapping-reference/text.md) unless the field is also [saved as a keyword](elasticsearch://reference/elasticsearch/mapping-reference/text.md#before-enabling-fielddata). -:::: - - - -## `LAST/LAST_VALUE` [sql-functions-aggs-last] - -```sql -LAST( - field_name <1> - [, ordering_field_name]) <2> -``` - -**Input**: - -1. target field for the aggregation -2. optional field used for ordering - - -**Output**: same type as the input - -**Description**: It’s the inverse of [`FIRST/FIRST_VALUE`](#sql-functions-aggs-first). Returns the last non-`null` value (if such exists) of the `field_name` input column sorted descending by the `ordering_field_name` column. If `ordering_field_name` is not provided, only the `field_name` column is used for the sorting. E.g.: - -| a | b | -| --- | --- | -| 10 | 1 | -| 20 | 1 | -| 1 | 2 | -| 2 | 2 | -| 100 | null | -| 200 | null | -| null | null | - -```sql -SELECT LAST(a) FROM t -``` - -will result in: - -| LAST(a) | -| --- | -| 200 | - -and - -```sql -SELECT LAST(a, b) FROM t -``` - -will result in: - -| LAST(a, b) | -| --- | -| 2 | - -```sql -SELECT LAST(first_name) FROM emp; - - LAST(first_name) -------------------- -Zvonko -``` - -```sql -SELECT gender, LAST(first_name) FROM emp GROUP BY gender ORDER BY gender; - - gender | LAST(first_name) -------------+------------------- -null | Patricio -F | Xinglin -M | Zvonko -``` - -```sql -SELECT LAST(first_name, birth_date) FROM emp; - - LAST(first_name, birth_date) -------------------------------- -Hilari -``` - -```sql -SELECT gender, LAST(first_name, birth_date) FROM emp GROUP BY gender ORDER BY gender; - - gender | LAST(first_name, birth_date) ------------+------------------------------- -null | Eberhardt -F | Valdiodio -M | Hilari -``` - -`LAST_VALUE` is a name alias and can be used instead of `LAST`, e.g.: - -```sql -SELECT gender, LAST_VALUE(first_name, birth_date) FROM emp GROUP BY gender ORDER BY gender; - - gender | LAST_VALUE(first_name, birth_date) ------------+------------------------------------- -null | Eberhardt -F | Valdiodio -M | Hilari -``` - -```sql -SELECT gender, LAST_VALUE(SUBSTRING(first_name, 3, 8), birth_date) AS "last" FROM emp GROUP BY gender ORDER BY gender; - - gender | last ----------------+--------------- -null |erhardt -F |ldiodio -M |lari -``` - -::::{note} -`LAST` cannot be used in `HAVING` clause. -:::: - - -::::{note} -`LAST` cannot be used with columns of type [`text`](elasticsearch://reference/elasticsearch/mapping-reference/text.md) unless the field is also [`saved as a keyword`](elasticsearch://reference/elasticsearch/mapping-reference/text.md#before-enabling-fielddata). -:::: - - - -## `MAX` [sql-functions-aggs-max] - -```sql -MAX(field_name) <1> -``` - -**Input**: - -1. a numeric field. If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. - - -**Output**: same type as the input - -**Description**: Returns the maximum value across input values in the field `field_name`. - -```sql -SELECT MAX(salary) AS max FROM emp; - - max ---------------- -74999 -``` - -```sql -SELECT MAX(ABS(salary / -12.0)) AS max FROM emp; - - max ------------------ -6249.916666666667 -``` - -::::{note} -`MAX` on a field of type [`text`](elasticsearch://reference/elasticsearch/mapping-reference/text.md) or [`keyword`](elasticsearch://reference/elasticsearch/mapping-reference/keyword.md) is translated into [`LAST/LAST_VALUE`](#sql-functions-aggs-last) and therefore, it cannot be used in `HAVING` clause. -:::: - - - -## `MIN` [sql-functions-aggs-min] - -```sql -MIN(field_name) <1> -``` - -**Input**: - -1. a numeric field. If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. - - -**Output**: same type as the input - -**Description**: Returns the minimum value across input values in the field `field_name`. - -```sql -SELECT MIN(salary) AS min FROM emp; - - min ---------------- -25324 -``` - -::::{note} -`MIN` on a field of type [`text`](elasticsearch://reference/elasticsearch/mapping-reference/text.md) or [`keyword`](elasticsearch://reference/elasticsearch/mapping-reference/keyword.md) is translated into [`FIRST/FIRST_VALUE`](#sql-functions-aggs-first) and therefore, it cannot be used in `HAVING` clause. -:::: - - - -## `SUM` [sql-functions-aggs-sum] - -```sql -SUM(field_name) <1> -``` - -**Input**: - -1. a numeric field. If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. - - -**Output**: `bigint` for integer input, `double` for floating points - -**Description**: Returns the sum of input values in the field `field_name`. - -```sql -SELECT SUM(salary) AS sum FROM emp; - - sum ---------------- -4824855 -``` - -```sql -SELECT ROUND(SUM(salary / 12.0), 1) AS sum FROM emp; - - sum ---------------- -402071.3 -``` - - -## Statistics [sql-functions-aggs-statistics] - - -## `KURTOSIS` [sql-functions-aggs-kurtosis] - -```sql -KURTOSIS(field_name) <1> -``` - -**Input**: - -1. a numeric field. If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. - - -**Output**: `double` numeric value - -**Description**: - -[Quantify](https://en.wikipedia.org/wiki/Kurtosis) the shape of the distribution of input values in the field `field_name`. - -```sql -SELECT MIN(salary) AS min, MAX(salary) AS max, KURTOSIS(salary) AS k FROM emp; - - min | max | k ----------------+---------------+------------------ -25324 |74999 |2.0444718929142986 -``` - -::::{note} -`KURTOSIS` cannot be used on top of scalar functions or operators but only directly on a field. So, for example, the following is not allowed and an error is returned: - -```sql - SELECT KURTOSIS(salary / 12.0), gender FROM emp GROUP BY gender -``` - -:::: - - - -## `MAD` [sql-functions-aggs-mad] - -```sql -MAD(field_name) <1> -``` - -**Input**: - -1. a numeric field. If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. - - -**Output**: `double` numeric value - -**Description**: - -[Measure](https://en.wikipedia.org/wiki/Median_absolute_deviation) the variability of the input values in the field `field_name`. - -```sql -SELECT MIN(salary) AS min, MAX(salary) AS max, AVG(salary) AS avg, MAD(salary) AS mad FROM emp; - - min | max | avg | mad ----------------+---------------+---------------+--------------- -25324 |74999 |48248.55 |10096.5 -``` - -```sql -SELECT MIN(salary / 12.0) AS min, MAX(salary / 12.0) AS max, AVG(salary/ 12.0) AS avg, MAD(salary / 12.0) AS mad FROM emp; - - min | max | avg | mad -------------------+-----------------+---------------+----------------- -2110.3333333333335|6249.916666666667|4020.7125 |841.3750000000002 -``` - - -## `PERCENTILE` [sql-functions-aggs-percentile] - -```sql -PERCENTILE( - field_name, <1> - percentile[, <2> - method[, <3> - method_parameter]]) <4> -``` - -**Input**: - -1. a numeric field. If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. -2. a numeric expression (must be a constant and not based on a field). If `null`, the function returns `null`. -3. optional string literal for the [percentile algorithm](elasticsearch://reference/aggregations/search-aggregations-metrics-percentile-aggregation.md#search-aggregations-metrics-percentile-aggregation-approximation). Possible values: `tdigest` or `hdr`. Defaults to `tdigest`. -4. optional numeric literal that configures the [percentile algorithm](elasticsearch://reference/aggregations/search-aggregations-metrics-percentile-aggregation.md#search-aggregations-metrics-percentile-aggregation-approximation). Configures `compression` for `tdigest` or `number_of_significant_value_digits` for `hdr`. The default is the same as that of the backing algorithm. - - -**Output**: `double` numeric value - -**Description**: - -Returns the nth [percentile](https://en.wikipedia.org/wiki/Percentile) (represented by `numeric_exp` parameter) of input values in the field `field_name`. - -```sql -SELECT languages, PERCENTILE(salary, 95) AS "95th" FROM emp - GROUP BY languages; - - languages | 95th ----------------+----------------- -null |74482.4 -1 |71122.8 -2 |70271.4 -3 |71926.0 -4 |69352.15 -5 |56371.0 -``` - -```sql -SELECT languages, PERCENTILE(salary / 12.0, 95) AS "95th" FROM emp - GROUP BY languages; - - languages | 95th ----------------+------------------ -null |6206.866666666667 -1 |5926.9 -2 |5855.949999999999 -3 |5993.833333333333 -4 |5779.345833333333 -5 |4697.583333333333 -``` - -```sql -SELECT - languages, - PERCENTILE(salary, 97.3, 'tdigest', 100.0) AS "97.3_TDigest", - PERCENTILE(salary, 97.3, 'hdr', 3) AS "97.3_HDR" -FROM emp -GROUP BY languages; - - languages | 97.3_TDigest | 97.3_HDR ----------------+-----------------+--------------- -null |74720.036 |74992.0 -1 |72316.132 |73712.0 -2 |71792.436 |69936.0 -3 |73326.23999999999|74992.0 -4 |71753.281 |74608.0 -5 |61176.16000000001|56368.0 -``` - - -## `PERCENTILE_RANK` [sql-functions-aggs-percentile-rank] - -```sql -PERCENTILE_RANK( - field_name, <1> - value[, <2> - method[, <3> - method_parameter]]) <4> -``` - -**Input**: - -1. a numeric field. If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. -2. a numeric expression (must be a constant and not based on a field). If `null`, the function returns `null`. -3. optional string literal for the [percentile algorithm](elasticsearch://reference/aggregations/search-aggregations-metrics-percentile-aggregation.md#search-aggregations-metrics-percentile-aggregation-approximation). Possible values: `tdigest` or `hdr`. Defaults to `tdigest`. -4. optional numeric literal that configures the [percentile algorithm](elasticsearch://reference/aggregations/search-aggregations-metrics-percentile-aggregation.md#search-aggregations-metrics-percentile-aggregation-approximation). Configures `compression` for `tdigest` or `number_of_significant_value_digits` for `hdr`. The default is the same as that of the backing algorithm. - - -**Output**: `double` numeric value - -**Description**: - -Returns the nth [percentile rank](https://en.wikipedia.org/wiki/Percentile_rank) (represented by `numeric_exp` parameter) of input values in the field `field_name`. - -```sql -SELECT languages, PERCENTILE_RANK(salary, 65000) AS rank FROM emp GROUP BY languages; - - languages | rank ----------------+----------------- -null |73.65766569962062 -1 |73.7291625157734 -2 |88.88005607010643 -3 |79.43662623295829 -4 |85.70446389643493 -5 |96.79075152940749 -``` - -```sql -SELECT languages, PERCENTILE_RANK(salary/12, 5000) AS rank FROM emp GROUP BY languages; - - languages | rank ----------------+------------------ -null |66.91240875912409 -1 |66.70766707667076 -2 |84.13266895048271 -3 |61.052992625621684 -4 |76.55646443990001 -5 |94.00696864111498 -``` - -```sql -SELECT - languages, - ROUND(PERCENTILE_RANK(salary, 65000, 'tdigest', 100.0), 2) AS "rank_TDigest", - ROUND(PERCENTILE_RANK(salary, 65000, 'hdr', 3), 2) AS "rank_HDR" -FROM emp -GROUP BY languages; - - languages | rank_TDigest | rank_HDR ----------------+---------------+--------------- -null |73.66 |80.0 -1 |73.73 |73.33 -2 |88.88 |89.47 -3 |79.44 |76.47 -4 |85.7 |83.33 -5 |96.79 |95.24 -``` - - -## `SKEWNESS` [sql-functions-aggs-skewness] - -```sql -SKEWNESS(field_name) <1> -``` - -**Input**: - -1. a numeric field. If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. - - -**Output**: `double` numeric value - -**Description**: - -[Quantify](https://en.wikipedia.org/wiki/Skewness) the asymmetric distribution of input values in the field `field_name`. - -```sql -SELECT MIN(salary) AS min, MAX(salary) AS max, SKEWNESS(salary) AS s FROM emp; - - min | max | s ----------------+---------------+------------------ -25324 |74999 |0.2707722118423227 -``` - -::::{note} -`SKEWNESS` cannot be used on top of scalar functions but only directly on a field. So, for example, the following is not allowed and an error is returned: - -```sql - SELECT SKEWNESS(ROUND(salary / 12.0, 2), gender FROM emp GROUP BY gender -``` - -:::: - - - -## `STDDEV_POP` [sql-functions-aggs-stddev-pop] - -```sql -STDDEV_POP(field_name) <1> -``` - -**Input**: - -1. a numeric field. If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. - - -**Output**: `double` numeric value - -**Description**: - -Returns the [population standard deviation](https://en.wikipedia.org/wiki/Standard_deviations) of input values in the field `field_name`. - -```sql -SELECT MIN(salary) AS min, MAX(salary) AS max, STDDEV_POP(salary) AS stddev FROM emp; - - min | max | stddev ----------------+---------------+------------------ -25324 |74999 |13765.125502787832 -``` - -```sql -SELECT MIN(salary / 12.0) AS min, MAX(salary / 12.0) AS max, STDDEV_POP(salary / 12.0) AS stddev FROM emp; - - min | max | stddev -------------------+-----------------+----------------- -2110.3333333333335|6249.916666666667|1147.093791898986 -``` - - -## `STDDEV_SAMP` [sql-functions-aggs-stddev-samp] - -```sql -STDDEV_SAMP(field_name) <1> -``` - -**Input**: - -1. a numeric field. If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. - - -**Output**: `double` numeric value - -**Description**: - -Returns the [sample standard deviation](https://en.wikipedia.org/wiki/Standard_deviations) of input values in the field `field_name`. - -```sql -SELECT MIN(salary) AS min, MAX(salary) AS max, STDDEV_SAMP(salary) AS stddev FROM emp; - - min | max | stddev ----------------+---------------+------------------ -25324 |74999 |13834.471662090747 -``` - -```sql -SELECT MIN(salary / 12.0) AS min, MAX(salary / 12.0) AS max, STDDEV_SAMP(salary / 12.0) AS stddev FROM emp; - - min | max | stddev -------------------+-----------------+----------------- -2110.3333333333335|6249.916666666667|1152.872638507562 -``` - - -## `SUM_OF_SQUARES` [sql-functions-aggs-sum-squares] - -```sql -SUM_OF_SQUARES(field_name) <1> -``` - -**Input**: - -1. a numeric field. If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. - - -**Output**: `double` numeric value - -**Description**: - -Returns the sum of squares of input values in the field `field_name`. - -```sql -SELECT MIN(salary) AS min, MAX(salary) AS max, SUM_OF_SQUARES(salary) AS sumsq - FROM emp; - - min | max | sumsq ----------------+---------------+---------------- -25324 |74999 |2.51740125721E11 -``` - -```sql -SELECT MIN(salary / 24.0) AS min, MAX(salary / 24.0) AS max, SUM_OF_SQUARES(salary / 24.0) AS sumsq FROM emp; - - min | max | sumsq -------------------+------------------+------------------- -1055.1666666666667|3124.9583333333335|4.370488293767361E8 -``` - - -## `VAR_POP` [sql-functions-aggs-var-pop] - -```sql -VAR_POP(field_name) <1> -``` - -**Input**: - -1. a numeric field. If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. - - -**Output**: `double` numeric value - -**Description**: - -Returns the [population variance](https://en.wikipedia.org/wiki/Variance) of input values in the field `field_name`. - -```sql -SELECT MIN(salary) AS min, MAX(salary) AS max, VAR_POP(salary) AS varpop FROM emp; - - min | max | varpop ----------------+---------------+---------------- -25324 |74999 |1.894786801075E8 -``` - -```sql -SELECT MIN(salary / 24.0) AS min, MAX(salary / 24.0) AS max, VAR_POP(salary / 24.0) AS varpop FROM emp; - - min | max | varpop -------------------+------------------+------------------ -1055.1666666666667|3124.9583333333335|328956.04185329855 -``` - - -## `VAR_SAMP` [sql-functions-aggs-var-samp] - -```sql -VAR_SAMP(field_name) <1> -``` - -**Input**: - -1. a numeric field. If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. - - -**Output**: `double` numeric value - -**Description**: - -Returns the [sample variance](https://en.wikipedia.org/wiki/Variance) of input values in the field `field_name`. - -```sql -SELECT MIN(salary) AS min, MAX(salary) AS max, VAR_SAMP(salary) AS varsamp FROM emp; - - min | max | varsamp ----------------+---------------+---------------- -25324 |74999 |1.913926061691E8 -``` - -```sql -SELECT MIN(salary / 24.0) AS min, MAX(salary / 24.0) AS max, VAR_SAMP(salary / 24.0) AS varsamp FROM emp; - - min | max | varsamp -------------------+------------------+---------------- -1055.1666666666667|3124.9583333333335|332278.830154847 -``` - - diff --git a/explore-analyze/query-filter/languages/sql-functions-conditional.md b/explore-analyze/query-filter/languages/sql-functions-conditional.md deleted file mode 100644 index 7f73f52c50..0000000000 --- a/explore-analyze/query-filter/languages/sql-functions-conditional.md +++ /dev/null @@ -1,456 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-functions-conditional.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Conditional Functions And Expressions [sql-functions-conditional] - -Functions that return one of their arguments by evaluating in an if-else manner. - -## `CASE` [sql-functions-conditional-case] - -```sql -CASE WHEN condition THEN result - [WHEN ...] - [ELSE default_result] -END -``` - -**Input**: - -One or multiple *WHEN **condition** THEN **result** clauses are used and the expression can optionally have an *ELSE **default_result** clause. Every **condition** should be a boolean expression. - -**Output**: one of the **result** expressions if the corresponding *WHEN **condition** evaluates to `true` or the **default_result** if all *WHEN **condition** clauses evaluate to `false`. If the optional *ELSE **default_result** clause is missing and all *WHEN **condition** clauses evaluate to `false` then `null` is returned. - -**Description**: The CASE expression is a generic conditional expression which simulates if/else statements of other programming languages If the condition’s result is true, the value of the result expression that follows the condition will be the returned the subsequent when clauses will be skipped and not processed. - -```sql -SELECT CASE WHEN 1 > 2 THEN 'elastic' - WHEN 2 <= 3 THEN 'search' - END AS "case"; - - case ---------------- -search -``` - -```sql -SELECT CASE WHEN 1 > 2 THEN 'elastic' - WHEN 2 > 10 THEN 'search' - END AS "case"; - - case ---------------- -null -``` - -```sql -SELECT CASE WHEN 1 > 2 THEN 'elastic' - WHEN 2 > 10 THEN 'search' - ELSE 'default' - END AS "case"; - - case ---------------- -default -``` - -As a variant, a case expression can be expressed with a syntax similar to **switch-case** of other programming languages: - -```sql -CASE expression - WHEN value1 THEN result1 - [WHEN value2 THEN result2] - [WHEN ...] - [ELSE default_result] -END -``` - -In this case it’s transformed internally to: - -```sql -CASE WHEN expression = value1 THEN result1 - [WHEN expression = value2 THEN result2] - [WHEN ...] - [ELSE default_result] -END -``` - -```sql -SELECT CASE 5 - WHEN 1 THEN 'elastic' - WHEN 2 THEN 'search' - WHEN 5 THEN 'elasticsearch' - END AS "case"; - - case ---------------- -elasticsearch -``` - -```sql -SELECT CASE 5 - WHEN 1 THEN 'elastic' - WHEN 2 THEN 'search' - WHEN 3 THEN 'elasticsearch' - ELSE 'default' - END AS "case"; - - case ---------------- -default -``` - -::::{note} -All result expressions must be of compatible data types. More specifically all result expressions should have a compatible data type with the 1st *non-null* result expression. E.g.: - -for the following query: - -```sql -CASE WHEN a = 1 THEN null - WHEN a > 2 THEN 10 - WHEN a > 5 THEN 'foo' -END -``` - -an error message would be returned, mentioning that **foo** is of data type **keyword**, which does not match the expected data type **integer** (based on result **10**). - -:::: - - -### Conditional bucketing [sql-functions-conditional-case-groupby-custom-buckets] - -CASE can be used as a GROUP BY key in a query to facilitate custom bucketing and assign descriptive names to those buckets. If, for example, the values for a key are too many or, simply, ranges of those values are more interesting than every single value, CASE can create custom buckets as in the following example: - -```sql -SELECT count(*) AS count, - CASE WHEN NVL(languages, 0) = 0 THEN 'zero' - WHEN languages = 1 THEN 'one' - WHEN languages = 2 THEN 'bilingual' - WHEN languages = 3 THEN 'trilingual' - ELSE 'multilingual' - END as lang_skills -FROM employees -GROUP BY lang_skills -ORDER BY lang_skills; -``` - -With this query, one can create normal grouping buckets for values *0, 1, 2, 3* with descriptive names, and every value *>= 4* falls into the *multilingual* bucket. - - - -## `COALESCE` [sql-functions-conditional-coalesce] - -```sql -COALESCE( - expression, <1> - expression, <2> - ...) -``` - -**Input**: - -1. 1st expression -2. 2nd expression - - -… - -**N**th expression - -COALESCE can take an arbitrary number of arguments. - -**Output**: one of the expressions or `null` - -**Description**: Returns the first of its arguments that is not null. If all arguments are null, then it returns `null`. - -```sql -SELECT COALESCE(null, 'elastic', 'search') AS "coalesce"; - - coalesce ---------------- -elastic -``` - -```sql -SELECT COALESCE(null, null, null, null) AS "coalesce"; - - coalesce ---------------- -null -``` - - -## `GREATEST` [sql-functions-conditional-greatest] - -```sql -GREATEST( - expression, <1> - expression, <2> - ...) -``` - -**Input**: - -1. 1st expression -2. 2nd expression - - -… - -**N**th expression - -GREATEST can take an arbitrary number of arguments and all of them must be of the same data type. - -**Output**: one of the expressions or `null` - -**Description**: Returns the argument that has the largest value which is not null. If all arguments are null, then it returns `null`. - -```sql -SELECT GREATEST(null, 1, 2) AS "greatest"; - - greatest ---------------- -2 -``` - -```sql -SELECT GREATEST(null, null, null, null) AS "greatest"; - - greatest ---------------- -null -``` - - -## `IFNULL` [sql-functions-conditional-ifnull] - -```sql -IFNULL( - expression, <1> - expression) <2> -``` - -**Input**: - -1. 1st expression -2. 2nd expression - - -**Output**: 2nd expression if 1st expression is null, otherwise 1st expression. - -**Description**: Variant of [`COALESCE`](#sql-functions-conditional-coalesce) with only two arguments. Returns the first of its arguments that is not null. If all arguments are null, then it returns `null`. - -```sql -SELECT IFNULL('elastic', null) AS "ifnull"; - - ifnull ---------------- -elastic -``` - -```sql -SELECT IFNULL(null, 'search') AS "ifnull"; - - ifnull ---------------- -search -``` - - -## `IIF` [sql-functions-conditional-iif] - -```sql -IIF( - expression, <1> - expression, <2> - [expression]) <3> -``` - -**Input**: - -1. boolean condition to check -2. return value if the boolean condition evaluates to `true` -3. return value if the boolean condition evaluates `false`; optional - - -**Output**: 2nd expression if 1st expression (condition) evaluates to `true`. If it evaluates to `false` return 3rd expression. If 3rd expression is not provided return `null`. - -**Description**: Conditional function that implements the standard *IF THEN ELSE * logic of programming languages. If the 3rd expression is not provided and the condition evaluates to `false`, `null` is returned. - -```sql -SELECT IIF(1 < 2, 'TRUE', 'FALSE') AS result1, IIF(1 > 2, 'TRUE', 'FALSE') AS result2; - - result1 | result2 ----------------+--------------- -TRUE |FALSE -``` - -```sql -SELECT IIF(1 < 2, 'TRUE') AS result1, IIF(1 > 2 , 'TRUE') AS result2; - - result1 | result2 ----------------+--------------- -TRUE |null -``` - -::::{tip} -**IIF** functions can be combined to implement more complex logic simulating the [`CASE`](#sql-functions-conditional-case) expression. E.g.: - -```sql -IIF(a = 1, 'one', IIF(a = 2, 'two', IIF(a = 3, 'three', 'many'))) -``` - -:::: - - - -## `ISNULL` [sql-functions-conditional-isnull] - -```sql -ISNULL( - expression, <1> - expression) <2> -``` - -**Input**: - -1. 1st expression -2. 2nd expression - - -**Output**: 2nd expression if 1st expression is null, otherwise 1st expression. - -**Description**: Variant of [`COALESCE`](#sql-functions-conditional-coalesce) with only two arguments. Returns the first of its arguments that is not null. If all arguments are null, then it returns `null`. - -```sql -SELECT ISNULL('elastic', null) AS "isnull"; - - isnull ---------------- -elastic -``` - -```sql -SELECT ISNULL(null, 'search') AS "isnull"; - - isnull ---------------- -search -``` - - -## `LEAST` [sql-functions-conditional-least] - -```sql -LEAST( - expression, <1> - expression, <2> - ...) -``` - -**Input**: - -1. 1st expression -2. 2nd expression - - -… - -**N**th expression - -LEAST can take an arbitrary number of arguments and all of them must be of the same data type. - -**Output**: one of the expressions or `null` - -**Description**: Returns the argument that has the smallest value which is not null. If all arguments are null, then it returns `null`. - -```sql -SELECT LEAST(null, 2, 1) AS "least"; - - least ---------------- -1 -``` - -```sql -SELECT LEAST(null, null, null, null) AS "least"; - - least ---------------- -null -``` - - -## `NULLIF` [sql-functions-conditional-nullif] - -```sql -NULLIF( - expression, <1> - expression) <2> -``` - -**Input**: - -1. 1st expression -2. 2nd expression - - -**Output**: `null` if the 2 expressions are equal, otherwise the 1st expression. - -**Description**: Returns `null` when the two input expressions are equal and if not, it returns the 1st expression. - -```sql -SELECT NULLIF('elastic', 'search') AS "nullif"; - nullif ---------------- -elastic -``` - -```sql -SELECT NULLIF('elastic', 'elastic') AS "nullif"; - - nullif:s ---------------- -null -``` - - -## `NVL` [sql-functions-conditional-nvl] - -```sql -NVL( - expression, <1> - expression) <2> -``` - -**Input**: - -1. 1st expression -2. 2nd expression - - -**Output**: 2nd expression if 1st expression is null, otherwise 1st expression. - -**Description**: Variant of [`COALESCE`](#sql-functions-conditional-coalesce) with only two arguments. Returns the first of its arguments that is not null. If all arguments are null, then it returns `null`. - -```sql -SELECT NVL('elastic', null) AS "nvl"; - - nvl ---------------- -elastic -``` - -```sql -SELECT NVL(null, 'search') AS "nvl"; - - nvl ---------------- -search -``` diff --git a/explore-analyze/query-filter/languages/sql-functions-datetime.md b/explore-analyze/query-filter/languages/sql-functions-datetime.md deleted file mode 100644 index ee522d02a9..0000000000 --- a/explore-analyze/query-filter/languages/sql-functions-datetime.md +++ /dev/null @@ -1,1542 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-functions-datetime.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Date/Time and Interval Functions and Operators [sql-functions-datetime] - -Elasticsearch SQL offers a wide range of facilities for performing date/time manipulations. - -## Intervals [sql-functions-datetime-interval] - -A common requirement when dealing with date/time in general revolves around the notion of `interval`, a topic that is worth exploring in the context of {{es}} and Elasticsearch SQL. - -{{es}} has comprehensive support for [date math](elasticsearch://reference/elasticsearch/rest-apis/common-options.md#date-math) both inside [index names](elasticsearch://reference/elasticsearch/rest-apis/api-conventions.md#api-date-math-index-names) and [queries](elasticsearch://reference/elasticsearch/mapping-reference/mapping-date-format.md). Inside Elasticsearch SQL the former is supported as is by passing the expression in the table name, while the latter is supported through the standard SQL `INTERVAL`. - -The table below shows the mapping between {{es}} and Elasticsearch SQL: - -| {{es}} | Elasticsearch SQL | -| --- | --- | -| Index/Table datetime math | -| `` | -| Query date/time math | -| `1y` | `INTERVAL 1 YEAR` | -| `2M` | `INTERVAL 2 MONTH` | -| `3w` | `INTERVAL 21 DAY` | -| `4d` | `INTERVAL 4 DAY` | -| `5h` | `INTERVAL 5 HOUR` | -| `6m` | `INTERVAL 6 MINUTE` | -| `7s` | `INTERVAL 7 SECOND` | - -`INTERVAL` allows either `YEAR` and `MONTH` to be mixed together *or* `DAY`, `HOUR`, `MINUTE` and `SECOND`. - -::::{tip} -Elasticsearch SQL accepts also the plural for each time unit (e.g. both `YEAR` and `YEARS` are valid). -:::: - - -Example of the possible combinations below: - -| Interval | Description | -| --- | --- | -| `INTERVAL '1-2' YEAR TO MONTH` | 1 year and 2 months | -| `INTERVAL '3 4' DAYS TO HOURS` | 3 days and 4 hours | -| `INTERVAL '5 6:12' DAYS TO MINUTES` | 5 days, 6 hours and 12 minutes | -| `INTERVAL '3 4:56:01' DAY TO SECOND` | 3 days, 4 hours, 56 minutes and 1 second | -| `INTERVAL '2 3:45:01.23456789' DAY TO SECOND` | 2 days, 3 hours, 45 minutes, 1 second and 234567890 nanoseconds | -| `INTERVAL '123:45' HOUR TO MINUTES` | 123 hours and 45 minutes | -| `INTERVAL '65:43:21.0123' HOUR TO SECONDS` | 65 hours, 43 minutes, 21 seconds and 12300000 nanoseconds | -| `INTERVAL '45:01.23' MINUTES TO SECONDS` | 45 minutes, 1 second and 230000000 nanoseconds | - - -## Comparison [_comparison] - -Date/time fields can be compared to [date math](elasticsearch://reference/elasticsearch/rest-apis/common-options.md#date-math) expressions with the equality (`=`) and `IN` operators: - -```sql -SELECT hire_date FROM emp WHERE hire_date = '1987-03-01||+4y/y'; - - hire_date ------------------------- -1991-01-26T00:00:00.000Z -1991-10-22T00:00:00.000Z -1991-09-01T00:00:00.000Z -1991-06-26T00:00:00.000Z -1991-08-30T00:00:00.000Z -1991-12-01T00:00:00.000Z -``` - -```sql -SELECT hire_date FROM emp WHERE hire_date IN ('1987-03-01||+2y/M', '1987-03-01||+3y/M'); - - hire_date ------------------------- -1989-03-31T00:00:00.000Z -1990-03-02T00:00:00.000Z -``` - - -## Operators [_operators] - -Basic arithmetic operators (`+`, `-`, `*`) support date/time parameters as indicated below: - -```sql -SELECT INTERVAL 1 DAY + INTERVAL 53 MINUTES AS result; - - result ---------------- -+1 00:53:00 -``` - -```sql -SELECT CAST('1969-05-13T12:34:56' AS DATETIME) + INTERVAL 49 YEARS AS result; - - result --------------------- -2018-05-13T12:34:56Z -``` - -```sql -SELECT - INTERVAL '49-1' YEAR TO MONTH result; - - result ---------------- --49-1 -``` - -```sql -SELECT INTERVAL '1' DAY - INTERVAL '2' HOURS AS result; - - result ---------------- -+0 22:00:00 -``` - -```sql -SELECT CAST('2018-05-13T12:34:56' AS DATETIME) - INTERVAL '2-8' YEAR TO MONTH AS result; - - result --------------------- -2015-09-13T12:34:56Z -``` - -```sql -SELECT -2 * INTERVAL '3' YEARS AS result; - - result ---------------- --6-0 -``` - - -## Functions [_functions] - -Functions that target date/time. - - -## `CURRENT_DATE/CURDATE` [sql-functions-current-date] - -```sql -CURRENT_DATE -CURRENT_DATE() -CURDATE() -``` - -**Input**: *none* - -**Output**: date - -**Description**: Returns the date (no time part) when the current query reached the server. It can be used both as a keyword: `CURRENT_DATE` or as a function with no arguments: `CURRENT_DATE()`. - -::::{note} -Unlike CURRENT_DATE, `CURDATE()` can only be used as a function with no arguments and not as a keyword. -:::: - - -This method always returns the same value for its every occurrence within the same query. - -```sql -SELECT CURRENT_DATE AS result; - - result ------------------------- -2018-12-12 -``` - -```sql -SELECT CURRENT_DATE() AS result; - - result ------------------------- -2018-12-12 -``` - -```sql -SELECT CURDATE() AS result; - - result ------------------------- -2018-12-12 -``` - -Typically, this function (as well as its twin [TODAY())](#sql-functions-today) function is used for relative date filtering: - -```sql -SELECT first_name FROM emp WHERE hire_date > TODAY() - INTERVAL 35 YEARS ORDER BY first_name ASC LIMIT 5; - - first_name ------------- -Alejandro -Amabile -Anoosh -Basil -Brendon -``` - - -## `CURRENT_TIME/CURTIME` [sql-functions-current-time] - -```sql -CURRENT_TIME -CURRENT_TIME([precision]) <1> -CURTIME -``` - -**Input**: - -1. fractional digits; optional - - -**Output**: time - -**Description**: Returns the time when the current query reached the server. As a function, `CURRENT_TIME()` accepts *precision* as an optional parameter for rounding the second fractional digits (nanoseconds). The default *precision* is 3, meaning a milliseconds precision current time will be returned. - -This method always returns the same value for its every occurrence within the same query. - -```sql -SELECT CURRENT_TIME AS result; - - result ------------------------- -12:31:27.237Z -``` - -```sql -SELECT CURRENT_TIME() AS result; - - result ------------------------- -12:31:27.237Z -``` - -```sql -SELECT CURTIME() AS result; - - result ------------------------- -12:31:27.237Z -``` - -```sql -SELECT CURRENT_TIME(1) AS result; - - result ------------------------- -12:31:27.2Z -``` - -Typically, this function is used for relative date/time filtering: - -```sql -SELECT first_name FROM emp WHERE CAST(hire_date AS TIME) > CURRENT_TIME() - INTERVAL 20 MINUTES ORDER BY first_name ASC LIMIT 5; - - first_name ---------------- -Alejandro -Amabile -Anneke -Anoosh -Arumugam -``` - -::::{important} -Currently, using a *precision* greater than 6 doesn’t make any difference to the output of the function as the maximum number of second fractional digits returned is 6. -:::: - - - -## `CURRENT_TIMESTAMP` [sql-functions-current-timestamp] - -```sql -CURRENT_TIMESTAMP -CURRENT_TIMESTAMP([precision]) <1> -``` - -**Input**: - -1. fractional digits; optional - - -**Output**: date/time - -**Description**: Returns the date/time when the current query reached the server. As a function, `CURRENT_TIMESTAMP()` accepts *precision* as an optional parameter for rounding the second fractional digits (nanoseconds). The default *precision* is 3, meaning a milliseconds precision current date/time will be returned. - -This method always returns the same value for its every occurrence within the same query. - -```sql -SELECT CURRENT_TIMESTAMP AS result; - - result ------------------------- -2018-12-12T14:48:52.448Z -``` - -```sql -SELECT CURRENT_TIMESTAMP() AS result; - - result ------------------------- -2018-12-12T14:48:52.448Z -``` - -```sql -SELECT CURRENT_TIMESTAMP(1) AS result; - - result ------------------------- -2018-12-12T14:48:52.4Z -``` - -Typically, this function (as well as its twin [NOW())](#sql-functions-now) function is used for relative date/time filtering: - -```sql -SELECT first_name FROM emp WHERE hire_date > NOW() - INTERVAL 100 YEARS ORDER BY first_name ASC LIMIT 5; - - first_name ---------------- -Alejandro -Amabile -Anneke -Anoosh -Arumugam -``` - -::::{important} -Currently, using a *precision* greater than 6 doesn’t make any difference to the output of the function as the maximum number of second fractional digits returned is 6. -:::: - - - -## `DATE_ADD/DATEADD/TIMESTAMP_ADD/TIMESTAMPADD` [sql-functions-datetime-add] - -```sql -DATE_ADD( - string_exp, <1> - integer_exp, <2> - datetime_exp) <3> -``` - -**Input**: - -1. string expression denoting the date/time unit to add to the date/datetime. If `null`, the function returns `null`. -2. integer expression denoting how many times the above unit should be added to/from the date/datetime, if a negative value is used it results to a subtraction from the date/datetime. If `null`, the function returns `null`. -3. date/datetime expression. If `null`, the function returns `null`. - - -**Output**: datetime - -**Description**: Add the given number of date/time units to a date/datetime. If the number of units is negative then it’s subtracted from the date/datetime. - -::::{warning} -If the second argument is a long there is possibility of truncation since an integer value will be extracted and used from that long. -:::: - - -| Datetime units to add/subtract | -| --- | -| **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 | - -```sql -SELECT DATE_ADD('years', 10, '2019-09-04T11:22:33.000Z'::datetime) AS "+10 years"; - - +10 years ------------------------- -2029-09-04T11:22:33.000Z -``` - -```sql -SELECT DATE_ADD('week', 10, '2019-09-04T11:22:33.000Z'::datetime) AS "+10 weeks"; - - +10 weeks ------------------------- -2019-11-13T11:22:33.000Z -``` - -```sql -SELECT DATE_ADD('seconds', -1234, '2019-09-04T11:22:33.000Z'::datetime) AS "-1234 seconds"; - - -1234 seconds ------------------------- -2019-09-04T11:01:59.000Z -``` - -```sql -SELECT DATE_ADD('qq', -417, '2019-09-04'::date) AS "-417 quarters"; - - -417 quarters ------------------------- -1915-06-04T00:00:00.000Z -``` - -```sql -SELECT DATE_ADD('minutes', 9235, '2019-09-04'::date) AS "+9235 minutes"; - - +9235 minutes ------------------------- -2019-09-10T09:55:00.000Z -``` - - -## `DATE_DIFF/DATEDIFF/TIMESTAMP_DIFF/TIMESTAMPDIFF` [sql-functions-datetime-diff] - -```sql -DATE_DIFF( - string_exp, <1> - datetime_exp, <2> - datetime_exp) <3> -``` - -**Input**: - -1. string expression denoting the date/time unit difference between the following two date/datetime expressions. If `null`, the function returns `null`. -2. start date/datetime expression. If `null`, the function returns `null`. -3. end date/datetime expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Subtract the second argument from the third argument and return their difference in multiples of the unit specified in the first argument. If the second argument (start) is greater than the third argument (end), then 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 | - -```sql -SELECT DATE_DIFF('years', '2019-09-04T11:22:33.000Z'::datetime, '2032-09-04T22:33:11.000Z'::datetime) AS "diffInYears"; - - diffInYears ------------------------- -13 -``` - -```sql -SELECT DATE_DIFF('week', '2019-09-04T11:22:33.000Z'::datetime, '2016-12-08T22:33:11.000Z'::datetime) AS "diffInWeeks"; - - diffInWeeks ------------------------- --143 -``` - -```sql -SELECT DATE_DIFF('seconds', '2019-09-04T11:22:33.123Z'::datetime, '2019-07-12T22:33:11.321Z'::datetime) AS "diffInSeconds"; - - diffInSeconds ------------------------- --4625362 -``` - -```sql -SELECT DATE_DIFF('qq', '2019-09-04'::date, '2025-04-25'::date) AS "diffInQuarters"; - - diffInQuarters ------------------------- -23 -``` - -::::{note} -For `hour` and `minute`, `DATEDIFF` doesn’t do any rounding, but instead first truncates the more detailed time fields on the 2 dates to zero and then calculates the subtraction. -:::: - - -```sql -SELECT DATEDIFF('hours', '2019-11-10T12:10:00.000Z'::datetime, '2019-11-10T23:59:59.999Z'::datetime) AS "diffInHours"; - - diffInHours ------------------------- -11 -``` - -```sql -SELECT DATEDIFF('minute', '2019-11-10T12:10:00.000Z'::datetime, '2019-11-10T12:15:59.999Z'::datetime) AS "diffInMinutes"; - - diffInMinutes ------------------------- -5 -``` - -```sql -SELECT DATE_DIFF('minutes', '2019-09-04'::date, '2015-08-17T22:33:11.567Z'::datetime) AS "diffInMinutes"; - - diffInMinutes ------------------------- --2128407 -``` - - -## `DATE_FORMAT` [sql-functions-datetime-dateformat] - -```sql -DATE_FORMAT( - date_exp/datetime_exp/time_exp, <1> - string_exp) <2> -``` - -**Input**: - -1. date/datetime/time expression. If `null`, the function returns `null`. -2. format pattern. If `null` or an empty string, the function returns `null`. - - -**Output**: string - -**Description**: Returns the date/datetime/time as a string using the format specified in the 2nd argument. The formatting pattern is one of the specifiers used in the [MySQL DATE_FORMAT() function](https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html#function_date-format). - -::::{note} -If the 1st argument is of type `time`, then pattern specified by the 2nd argument cannot contain date related units (e.g. *dd*, *MM*, *yyyy*, etc.). If it contains such units an error is returned. Ranges for month and day specifiers (%c, %D, %d, %e, %m) start at one, unlike MySQL, where they start at zero, due to the fact that MySQL permits the storing of incomplete dates such as *2014-00-00*. Elasticsearch in this case returns an error. -:::: - - -```sql -SELECT DATE_FORMAT(CAST('2020-04-05' AS DATE), '%d/%m/%Y') AS "date"; - - date ------------------- -05/04/2020 -``` - -```sql -SELECT DATE_FORMAT(CAST('2020-04-05T11:22:33.987654' AS DATETIME), '%d/%m/%Y %H:%i:%s.%f') AS "datetime"; - - datetime ------------------- -05/04/2020 11:22:33.987654 -``` - -```sql -SELECT DATE_FORMAT(CAST('23:22:33.987' AS TIME), '%H %i %s.%f') AS "time"; - - time ------------------- -23 22 33.987000 -``` - - -## `DATE_PARSE` [sql-functions-datetime-dateparse] - -```sql -DATE_PARSE( - string_exp, <1> - string_exp) <2> -``` - -**Input**: - -1. date expression as a string. If `null` or an empty string, the function returns `null`. -2. parsing pattern. If `null` or an empty string, the function returns `null`. - - -**Output**: date - -**Description**: Returns a date by parsing the 1st argument using the format specified in the 2nd argument. The parsing format pattern used is the one from [`java.time.format.DateTimeFormatter`](https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html). - -::::{note} -If the parsing pattern does not contain all valid date units (e.g. *HH:mm:ss*, *dd-MM HH:mm:ss*, etc.) an error is returned as the function needs to return a value of `date` type which will contain date part. -:::: - - -```sql -SELECT DATE_PARSE('07/04/2020', 'dd/MM/yyyy') AS "date"; - - date ------------ -2020-04-07 -``` - -::::{note} -The resulting `date` will have the time zone specified by the user through the [`time_zone`](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-sql-query)/[`timezone`](sql-jdbc.md#jdbc-cfg-timezone) REST/driver parameters with no conversion applied. - -```sql -{ - "query" : "SELECT DATE_PARSE('07/04/2020', 'dd/MM/yyyy') AS \"date\"", - "time_zone" : "Europe/Athens" -} - - date ------------- -2020-04-07T00:00:00.000+03:00 -``` - -:::: - - - -## `DATETIME_FORMAT` [sql-functions-datetime-datetimeformat] - -```sql -DATETIME_FORMAT( - date_exp/datetime_exp/time_exp, <1> - string_exp) <2> -``` - -**Input**: - -1. date/datetime/time expression. If `null`, the function returns `null`. -2. format pattern. If `null` or an empty string, the function returns `null`. - - -**Output**: string - -**Description**: Returns the date/datetime/time as a string using the format specified in the 2nd argument. The formatting pattern used is the one from [`java.time.format.DateTimeFormatter`](https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html). - -::::{note} -If the 1st argument is of type `time`, then pattern specified by the 2nd argument cannot contain date related units (e.g. *dd*, *MM*, *yyyy*, etc.). If it contains such units an error is returned. -:::: - - -```sql -SELECT DATETIME_FORMAT(CAST('2020-04-05' AS DATE), 'dd/MM/yyyy') AS "date"; - - date ------------------- -05/04/2020 -``` - -```sql -SELECT DATETIME_FORMAT(CAST('2020-04-05T11:22:33.987654' AS DATETIME), 'dd/MM/yyyy HH:mm:ss.SS') AS "datetime"; - - datetime ------------------- -05/04/2020 11:22:33.98 -``` - -```sql -SELECT DATETIME_FORMAT(CAST('11:22:33.987' AS TIME), 'HH mm ss.S') AS "time"; - - time ------------------- -11 22 33.9 -``` - - -## `DATETIME_PARSE` [sql-functions-datetime-datetimeparse] - -```sql -DATETIME_PARSE( - string_exp, <1> - string_exp) <2> -``` - -**Input**: - -1. datetime expression as a string. If `null` or an empty string, the function returns `null`. -2. parsing pattern. If `null` or an empty string, the function returns `null`. - - -**Output**: datetime - -**Description**: Returns a datetime by parsing the 1st argument using the format specified in the 2nd argument. The parsing format pattern used is the one from [`java.time.format.DateTimeFormatter`](https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html). - -::::{note} -If the parsing pattern contains only date or only time units (e.g. *dd/MM/yyyy*, *HH:mm:ss*, etc.) an error is returned as the function needs to return a value of `datetime` type which must contain both. -:::: - - -```sql -SELECT DATETIME_PARSE('07/04/2020 10:20:30.123', 'dd/MM/yyyy HH:mm:ss.SSS') AS "datetime"; - - datetime ------------------------- -2020-04-07T10:20:30.123Z -``` - -```sql -SELECT DATETIME_PARSE('10:20:30 07/04/2020 Europe/Berlin', 'HH:mm:ss dd/MM/yyyy VV') AS "datetime"; - - datetime ------------------------- -2020-04-07T08:20:30.000Z -``` - -::::{note} -If timezone is not specified in the datetime string expression and the parsing pattern, the resulting `datetime` will have the time zone specified by the user through the [`time_zone`](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-sql-query)/[`timezone`](sql-jdbc.md#jdbc-cfg-timezone) REST/driver parameters with no conversion applied. - -```sql -{ - "query" : "SELECT DATETIME_PARSE('10:20:30 07/04/2020', 'HH:mm:ss dd/MM/yyyy') AS \"datetime\"", - "time_zone" : "Europe/Athens" -} - - datetime ------------------------------ -2020-04-07T10:20:30.000+03:00 -``` - -:::: - - - -## `TIME_PARSE` [sql-functions-datetime-timeparse] - -```sql -TIME_PARSE( - string_exp, <1> - string_exp) <2> -``` - -**Input**: - -1. time expression as a string. If `null` or an empty string, the function returns `null`. -2. parsing pattern. If `null` or an empty string, the function returns `null`. - - -**Output**: time - -**Description**: Returns a time by parsing the 1st argument using the format specified in the 2nd argument. The parsing format pattern used is the one from [`java.time.format.DateTimeFormatter`](https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html). - -::::{note} -If the parsing pattern contains only date units (e.g. *dd/MM/yyyy*) an error is returned as the function needs to return a value of `time` type which will contain only time. -:::: - - -```sql -SELECT TIME_PARSE('10:20:30.123', 'HH:mm:ss.SSS') AS "time"; - - time ---------------- -10:20:30.123Z -``` - -```sql -SELECT TIME_PARSE('10:20:30-01:00', 'HH:mm:ssXXX') AS "time"; - - time ---------------- -11:20:30.000Z -``` - -::::{note} -If timezone is not specified in the time string expression and the parsing pattern, the resulting `time` will have the offset of the time zone specified by the user through the [`time_zone`](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-sql-query)/[`timezone`](sql-jdbc.md#jdbc-cfg-timezone) REST/driver parameters at the Unix epoch date (`1970-01-01`) with no conversion applied. - -```sql -{ - "query" : "SELECT DATETIME_PARSE('10:20:30', 'HH:mm:ss') AS \"time\"", - "time_zone" : "Europe/Athens" -} - - time ------------------------------------- -10:20:30.000+02:00 -``` - -:::: - - - -## `DATE_PART/DATEPART` [sql-functions-datetime-part] - -```sql -DATE_PART( - string_exp, <1> - datetime_exp) <2> -``` - -**Input**: - -1. string expression denoting the unit to extract from the date/datetime. If `null`, the function returns `null`. -2. date/datetime expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Extract the specified unit from a date/datetime. It’s similar to [`EXTRACT`](#sql-functions-datetime-extract) but with different names and aliases for the units and provides more options (e.g.: `TZOFFSET`). - -| Datetime units to extract | -| --- | -| **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 | -| tzoffset | tz | - -```sql -SELECT DATE_PART('year', '2019-09-22T11:22:33.123Z'::datetime) AS "years"; - - years ----------- -2019 -``` - -```sql -SELECT DATE_PART('mi', '2019-09-04T11:22:33.123Z'::datetime) AS mins; - - mins ------------ -22 -``` - -```sql -SELECT DATE_PART('quarters', CAST('2019-09-24' AS DATE)) AS quarter; - - quarter -------------- -3 -``` - -```sql -SELECT DATE_PART('month', CAST('2019-09-24' AS DATE)) AS month; - - month -------------- -9 -``` - -::::{note} -For `week` and `weekday` the unit is extracted using the non-ISO calculation, which means that a given week is considered to start from Sunday, not Monday. -:::: - - -```sql -SELECT DATE_PART('week', '2019-09-22T11:22:33.123Z'::datetime) AS week; - - week ----------- -39 -``` - -::::{note} -The `tzoffset` returns the total number of minutes (signed) that represent the time zone’s offset. -:::: - - -```sql -SELECT DATE_PART('tzoffset', '2019-09-04T11:22:33.123+05:15'::datetime) AS tz_mins; - - tz_mins --------------- -315 -``` - -```sql -SELECT DATE_PART('tzoffset', '2019-09-04T11:22:33.123-03:49'::datetime) AS tz_mins; - - tz_mins --------------- --229 -``` - - -## `DATE_TRUNC/DATETRUNC` [sql-functions-datetime-trunc] - -```sql -DATE_TRUNC( - string_exp, <1> - datetime_exp/interval_exp) <2> -``` - -**Input**: - -1. string expression denoting the unit to which the date/datetime/interval should be truncated to. If `null`, the function returns `null`. -2. date/datetime/interval expression. If `null`, the function returns `null`. - - -**Output**: datetime/interval - -**Description**: Truncate the date/datetime/interval to the specified unit by setting all fields that are less significant than the specified one to zero (or one, for day, day of week and month). If the first argument is `week` and the second argument is of `interval` type, an error is thrown since the `interval` data type doesn’t support a `week` time unit. - -| Datetime truncation units | -| --- | -| **unit** | **abbreviations** | -| millennium | millennia | -| century | centuries | -| decade | decades | -| year | years, yy, yyyy | -| quarter | quarters, qq, q | -| month | months, mm, m | -| week | weeks, wk, ww | -| day | days, dd, d | -| hour | hours, hh | -| minute | minutes, mi, n | -| second | seconds, ss, s | -| millisecond | milliseconds, ms | -| microsecond | microseconds, mcs | -| nanosecond | nanoseconds, ns | - -```sql -SELECT DATE_TRUNC('millennium', '2019-09-04T11:22:33.123Z'::datetime) AS millennium; - - millennium ------------------------- -2000-01-01T00:00:00.000Z -``` - -```sql -SELECT DATETRUNC('week', '2019-08-24T11:22:33.123Z'::datetime) AS week; - - week ------------------------- -2019-08-19T00:00:00.000Z -``` - -```sql -SELECT DATE_TRUNC('mi', '2019-09-04T11:22:33.123Z'::datetime) AS mins; - - mins ------------------------- -2019-09-04T11:22:00.000Z -``` - -```sql -SELECT DATE_TRUNC('decade', CAST('2019-09-04' AS DATE)) AS decades; - - decades ------------------------- -2010-01-01T00:00:00.000Z -``` - -```sql -SELECT DATETRUNC('quarters', CAST('2019-09-04' AS DATE)) AS quarter; - - quarter ------------------------- -2019-07-01T00:00:00.000Z -``` - -```sql -SELECT DATE_TRUNC('centuries', INTERVAL '199-5' YEAR TO MONTH) AS centuries; - - centuries ------------------- - +100-0 -``` - -```sql -SELECT DATE_TRUNC('hours', INTERVAL '17 22:13:12' DAY TO SECONDS) AS hour; - - hour ------------------- -+17 22:00:00 -``` - -```sql -SELECT DATE_TRUNC('days', INTERVAL '19 15:24:19' DAY TO SECONDS) AS day; - - day ------------------- -+19 00:00:00 -``` - - -## `FORMAT` [sql-functions-datetime-format] - -```sql -FORMAT( - date_exp/datetime_exp/time_exp, <1> - string_exp) <2> -``` - -**Input**: - -1. date/datetime/time expression. If `null`, the function returns `null`. -2. format pattern. If `null` or an empty string, the function returns `null`. - - -**Output**: string - -**Description**: Returns the date/datetime/time as a string using the [format](https://docs.microsoft.com/en-us/sql/t-sql/functions/format-transact-sql#arguments) specified in the 2nd argument. The formatting pattern used is the one from [Microsoft SQL Server Format Specification](https://docs.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings). - -::::{note} -If the 1st argument is of type `time`, then pattern specified by the 2nd argument cannot contain date related units (e.g. *dd*, *MM*, *yyyy*, etc.). If it contains such units an error is returned.
Format specifier `F` will be working similar to format specifier `f`. It will return the fractional part of seconds, and the number of digits will be same as of the number of `Fs` provided as input (up to 9 digits). Result will contain `0` appended in the end to match with number of `F` provided. e.g.: for a time part `10:20:30.1234` and pattern `HH:mm:ss.FFFFFF`, the output string of the function would be: `10:20:30.123400`.
Format specifier `y` will return year-of-era instead of one/two low-order digits. eg.: For year `2009`, `y` will be returning `2009` instead of `9`. For year `43`, `y` format specifier will return `43`. - Special characters like `"` , `\` and `%` will be returned as it is without any change. eg.: formatting date `17-sep-2020` with `%M` will return `%9` -:::: - - -```sql -SELECT FORMAT(CAST('2020-04-05' AS DATE), 'dd/MM/yyyy') AS "date"; - - date ------------------- -05/04/2020 -``` - -```sql -SELECT FORMAT(CAST('2020-04-05T11:22:33.987654' AS DATETIME), 'dd/MM/yyyy HH:mm:ss.ff') AS "datetime"; - - datetime ------------------- -05/04/2020 11:22:33.98 -``` - -```sql -SELECT FORMAT(CAST('11:22:33.987' AS TIME), 'HH mm ss.f') AS "time"; - - time ------------------- -11 22 33.9 -``` - - -## `TO_CHAR` [sql-functions-datetime-to_char] - -```sql -TO_CHAR( - date_exp/datetime_exp/time_exp, <1> - string_exp) <2> -``` - -**Input**: - -1. date/datetime/time expression. If `null`, the function returns `null`. -2. format pattern. If `null` or an empty string, the function returns `null`. - - -**Output**: string - -**Description**: Returns the date/datetime/time as a string using the format specified in the 2nd argument. The formatting pattern conforms to [PostgreSQL Template Patterns for Date/Time Formatting](https://www.postgresql.org/docs/13/functions-formatting.html). - -::::{note} -If the 1st argument is of type `time`, then the pattern specified by the 2nd argument cannot contain date related units (e.g. *dd*, *MM*, *YYYY*, etc.). If it contains such units an error is returned.
The result of the patterns `TZ` and `tz` (time zone abbreviations) in some cases differ from the results returned by the `TO_CHAR` in PostgreSQL. The reason is that the time zone abbreviations specified by the JDK are different from the ones specified by PostgreSQL. This function might show an actual time zone abbreviation instead of the generic `LMT` or empty string or offset returned by the PostgreSQL implementation. The summer/daylight markers might also differ between the two implementations (e.g. will show `HT` instead of `HST` for Hawaii).
The `FX`, `TM`, `SP` pattern modifiers are not supported and will show up as `FX`, `TM`, `SP` literals in the output. -:::: - - -```sql -SELECT TO_CHAR(CAST('2020-04-05' AS DATE), 'DD/MM/YYYY') AS "date"; - - date ------------------- -05/04/2020 -``` - -```sql -SELECT TO_CHAR(CAST('2020-04-05T11:22:33.987654' AS DATETIME), 'DD/MM/YYYY HH24:MI:SS.FF2') AS "datetime"; - - datetime ------------------- -05/04/2020 11:22:33.98 -``` - -```sql -SELECT TO_CHAR(CAST('23:22:33.987' AS TIME), 'HH12 MI SS.FF1') AS "time"; - - time ------------------- -11 22 33.9 -``` - - -## `DAY_OF_MONTH/DOM/DAY` [sql-functions-datetime-day] - -```sql -DAY_OF_MONTH(datetime_exp) <1> -``` - -**Input**: - -1. date/datetime expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Extract the day of the month from a date/datetime. - -```sql -SELECT DAY_OF_MONTH(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS day; - - day ---------------- -19 -``` - - -## `DAY_OF_WEEK/DAYOFWEEK/DOW` [sql-functions-datetime-dow] - -```sql -DAY_OF_WEEK(datetime_exp) <1> -``` - -**Input**: - -1. date/datetime expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Extract the day of the week from a date/datetime. Sunday is `1`, Monday is `2`, etc. - -```sql -SELECT DAY_OF_WEEK(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS day; - - day ---------------- -2 -``` - - -## `DAY_OF_YEAR/DOY` [sql-functions-datetime-doy] - -```sql -DAY_OF_YEAR(datetime_exp) <1> -``` - -**Input**: - -1. date/datetime expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Extract the day of the year from a date/datetime. - -```sql -SELECT DAY_OF_YEAR(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS day; - - day ---------------- -50 -``` - - -## `DAY_NAME/DAYNAME` [sql-functions-datetime-dayname] - -```sql -DAY_NAME(datetime_exp) <1> -``` - -**Input**: - -1. date/datetime expression. If `null`, the function returns `null`. - - -**Output**: string - -**Description**: Extract the day of the week from a date/datetime in text format (`Monday`, `Tuesday`…). - -```sql -SELECT DAY_NAME(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS day; - - day ---------------- -Monday -``` - - -## `HOUR_OF_DAY/HOUR` [sql-functions-datetime-hour] - -```sql -HOUR_OF_DAY(datetime_exp) <1> -``` - -**Input**: - -1. date/datetime expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Extract the hour of the day from a date/datetime. - -```sql -SELECT HOUR_OF_DAY(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS hour; - - hour ---------------- -10 -``` - - -## `ISO_DAY_OF_WEEK/ISODAYOFWEEK/ISODOW/IDOW` [sql-functions-datetime-isodow] - -```sql -ISO_DAY_OF_WEEK(datetime_exp) <1> -``` - -**Input**: - -1. date/datetime expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Extract the day of the week from a date/datetime, following the [ISO 8601 standard](https://en.wikipedia.org/wiki/ISO_week_date). Monday is `1`, Tuesday is `2`, etc. - -```sql -SELECT ISO_DAY_OF_WEEK(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS day; - - day ---------------- -1 -``` - - -## `ISO_WEEK_OF_YEAR/ISOWEEKOFYEAR/ISOWEEK/IWOY/IW` [sql-functions-datetime-isoweek] - -```sql -ISO_WEEK_OF_YEAR(datetime_exp) <1> -``` - -**Input**: - -1. date/datetime expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Extract the week of the year from a date/datetime, following [ISO 8601 standard](https://en.wikipedia.org/wiki/ISO_week_date). The first week of a year is the first week with a majority (4 or more) of its days in January. - -```sql -SELECT ISO_WEEK_OF_YEAR(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS week; - - week ---------------- -8 -``` - - -## `MINUTE_OF_DAY` [sql-functions-datetime-minuteofday] - -```sql -MINUTE_OF_DAY(datetime_exp) <1> -``` - -**Input**: - -1. date/datetime expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Extract the minute of the day from a date/datetime. - -```sql -SELECT MINUTE_OF_DAY(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS minute; - - minute ---------------- -623 -``` - - -## `MINUTE_OF_HOUR/MINUTE` [sql-functions-datetime-minute] - -```sql -MINUTE_OF_HOUR(datetime_exp) <1> -``` - -**Input**: - -1. date/datetime expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Extract the minute of the hour from a date/datetime. - -```sql -SELECT MINUTE_OF_HOUR(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS minute; - - minute ---------------- -23 -``` - - -## `MONTH_OF_YEAR/MONTH` [sql-functions-datetime-month] - -```sql -MONTH(datetime_exp) <1> -``` - -**Input**: - -1. date/datetime expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Extract the month of the year from a date/datetime. - -```sql -SELECT MONTH_OF_YEAR(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS month; - - month ---------------- -2 -``` - - -## `MONTH_NAME/MONTHNAME` [sql-functions-datetime-monthname] - -```sql -MONTH_NAME(datetime_exp) <1> -``` - -**Input**: - -1. date/datetime expression. If `null`, the function returns `null`. - - -**Output**: string - -**Description**: Extract the month from a date/datetime in text format (`January`, `February`…). - -```sql -SELECT MONTH_NAME(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS month; - - month ---------------- -February -``` - - -## `NOW` [sql-functions-now] - -```sql -NOW() -``` - -**Input**: *none* - -**Output**: datetime - -**Description**: This function offers the same functionality as [CURRENT_TIMESTAMP()](#sql-functions-current-timestamp) function: returns the datetime when the current query reached the server. This method always returns the same value for its every occurrence within the same query. - -```sql -SELECT NOW() AS result; - - result ------------------------- -2018-12-12T14:48:52.448Z -``` - -Typically, this function (as well as its twin [CURRENT_TIMESTAMP())](#sql-functions-current-timestamp) function is used for relative date/time filtering: - -```sql -SELECT first_name FROM emp WHERE hire_date > NOW() - INTERVAL 100 YEARS ORDER BY first_name ASC LIMIT 5; - - first_name ---------------- -Alejandro -Amabile -Anneke -Anoosh -Arumugam -``` - - -## `SECOND_OF_MINUTE/SECOND` [sql-functions-datetime-second] - -```sql -SECOND_OF_MINUTE(datetime_exp) <1> -``` - -**Input**: - -1. date/datetime expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Extract the second of the minute from a date/datetime. - -```sql -SELECT SECOND_OF_MINUTE(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS second; - - second ---------------- -27 -``` - - -## `QUARTER` [sql-functions-datetime-quarter] - -```sql -QUARTER(datetime_exp) <1> -``` - -**Input**: - -1. date/datetime expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Extract the year quarter the date/datetime falls in. - -```sql -SELECT QUARTER(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS quarter; - - quarter ---------------- -1 -``` - - -## `TODAY` [sql-functions-today] - -```sql -TODAY() -``` - -**Input**: *none* - -**Output**: date - -**Description**: This function offers the same functionality as [CURRENT_DATE()](#sql-functions-current-date) function: returns the date when the current query reached the server. This method always returns the same value for its every occurrence within the same query. - -```sql -SELECT TODAY() AS result; - - result ------------------------- -2018-12-12 -``` - -Typically, this function (as well as its twin [CURRENT_TIMESTAMP())](#sql-functions-current-timestamp) function is used for relative date filtering: - -```sql -SELECT first_name FROM emp WHERE hire_date > TODAY() - INTERVAL 35 YEARS ORDER BY first_name ASC LIMIT 5; - - first_name ------------- -Alejandro -Amabile -Anoosh -Basil -Brendon -``` - - -## `WEEK_OF_YEAR/WEEK` [sql-functions-datetime-week] - -```sql -WEEK_OF_YEAR(datetime_exp) <1> -``` - -**Input**: - -1. date/datetime expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Extract the week of the year from a date/datetime. - -```sql -SELECT WEEK(CAST('1988-01-05T09:22:10Z' AS TIMESTAMP)) AS week, ISOWEEK(CAST('1988-01-05T09:22:10Z' AS TIMESTAMP)) AS isoweek; - - week | isoweek ----------------+--------------- -2 |1 -``` - - -## `YEAR` [sql-functions-datetime-year] - -```sql -YEAR(datetime_exp) <1> -``` - -**Input**: - -1. date/datetime expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Extract the year from a date/datetime. - -```sql -SELECT YEAR(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS year; - - year ---------------- -2018 -``` - - -## `EXTRACT` [sql-functions-datetime-extract] - -```sql -EXTRACT( - datetime_function <1> - FROM datetime_exp) <2> -``` - -**Input**: - -1. date/time function name -2. date/datetime expression - - -**Output**: integer - -**Description**: Extract fields from a date/datetime by specifying the name of a datetime function. The following - -```sql -SELECT EXTRACT(DAY_OF_YEAR FROM CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS day; - - day ---------------- -50 -``` - -is the equivalent to - -```sql -SELECT DAY_OF_YEAR(CAST('2018-02-19T10:23:27Z' AS TIMESTAMP)) AS day; - - day ---------------- -50 -``` - - diff --git a/explore-analyze/query-filter/languages/sql-functions-geo.md b/explore-analyze/query-filter/languages/sql-functions-geo.md deleted file mode 100644 index c43ff754ce..0000000000 --- a/explore-analyze/query-filter/languages/sql-functions-geo.md +++ /dev/null @@ -1,210 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-functions-geo.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Geo Functions [sql-functions-geo] - -::::{warning} -This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features. -:::: - - -The geo functions work with geometries stored in `geo_point`, `geo_shape` and `shape` fields, or returned by other geo functions. - -## Limitations [_limitations_4] - -[`geo_point`](elasticsearch://reference/elasticsearch/mapping-reference/geo-point.md), [`geo_shape`](elasticsearch://reference/elasticsearch/mapping-reference/geo-shape.md) and [`shape`](elasticsearch://reference/elasticsearch/mapping-reference/shape.md) and types are represented in SQL as geometry and can be used interchangeably with the following exceptions: - -* `geo_shape` and `shape` fields don’t have doc values, therefore these fields cannot be used for filtering, grouping or sorting. -* `geo_points` fields are indexed and have doc values by default, however only latitude and longitude are stored and indexed with some loss of precision from the original values (4.190951585769653E-8 for the latitude and 8.381903171539307E-8 for longitude). The altitude component is accepted but not stored in doc values nor indexed. Therefore calling `ST_Z` function in the filtering, grouping or sorting will return `null`. - - -## Geometry Conversion [_geometry_conversion] - -### `ST_AsWKT` [sql-functions-geo-st-as-wkt] - -```sql -ST_AsWKT( - geometry <1> -) -``` - -**Input**: - -1. geometry. If `null`, the function returns `null`. - - -**Output**: string - -**Description**: Returns the WKT representation of the `geometry`. - -```sql -SELECT city, ST_AsWKT(location) location FROM "geo" WHERE city = 'Amsterdam'; - - city:s | location:s -Amsterdam |POINT (4.850312 52.347557) -``` - - -### `ST_WKTToSQL` [sql-functions-geo-st-wkt-to-sql] - -```sql -ST_WKTToSQL( - string <1> -) -``` - -**Input**: - -1. string WKT representation of geometry. If `null`, the function returns `null`. - - -**Output**: geometry - -**Description**: Returns the geometry from WKT representation. - -```sql -SELECT CAST(ST_WKTToSQL('POINT (10 20)') AS STRING) location; - - location:s -POINT (10.0 20.0) -``` - - - -## Geometry Properties [_geometry_properties] - -### `ST_GeometryType` [sql-functions-geo-st-geometrytype] - -```sql -ST_GeometryType( - geometry <1> -) -``` - -**Input**: - -1. geometry. If `null`, the function returns `null`. - - -**Output**: string - -**Description**: Returns the type of the `geometry` such as POINT, MULTIPOINT, LINESTRING, MULTILINESTRING, POLYGON, MULTIPOLYGON, GEOMETRYCOLLECTION, ENVELOPE or CIRCLE. - -```sql -SELECT ST_GeometryType(ST_WKTToSQL('POINT (10 20)')) type; - - type:s -POINT -``` - - -### `ST_X` [sql-functions-geo-st-x] - -```sql -ST_X( - geometry <1> -) -``` - -**Input**: - -1. geometry. If `null`, the function returns `null`. - - -**Output**: double - -**Description**: Returns the longitude of the first point in the geometry. - -```sql -SELECT ST_X(ST_WKTToSQL('POINT (10 20)')) x; - - x:d -10.0 -``` - - -### `ST_Y` [sql-functions-geo-st-y] - -```sql -ST_Y( - geometry <1> -) -``` - -**Input**: - -1. geometry. If `null`, the function returns `null`. - - -**Output**: double - -**Description**: Returns the latitude of the first point in the geometry. - -```sql -SELECT ST_Y(ST_WKTToSQL('POINT (10 20)')) y; - - y:d -20.0 -``` - - -### `ST_Z` [sql-functions-geo-st-z] - -```sql -ST_Z( - geometry <1> -) -``` - -**Input**: - -1. geometry. If `null`, the function returns `null`. - - -**Output**: double - -**Description**: Returns the altitude of the first point in the geometry. - -```sql -SELECT ST_Z(ST_WKTToSQL('POINT (10 20 30)')) z; - - z:d -30.0 -``` - - -### `ST_Distance` [sql-functions-geo-st-distance] - -```sql -ST_Distance( - geometry, <1> - geometry <2> -) -``` - -**Input**: - -1. source geometry. If `null`, the function returns `null`. -2. target geometry. If `null`, the function returns `null`. - - -**Output**: Double - -**Description**: Returns the distance between geometries in meters. Both geometries have to be points. - -```sql -SELECT ST_Distance(ST_WKTToSQL('POINT (10 20)'), ST_WKTToSQL('POINT (20 30)')) distance; - - distance:d -1499101.2889383635 -``` - - - diff --git a/explore-analyze/query-filter/languages/sql-functions-grouping.md b/explore-analyze/query-filter/languages/sql-functions-grouping.md deleted file mode 100644 index 8d83b4ba4b..0000000000 --- a/explore-analyze/query-filter/languages/sql-functions-grouping.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-functions-grouping.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Grouping Functions [sql-functions-grouping] - -Functions for creating special *grouping*s (also known as *bucketing*); as such these need to be used as part of the [grouping](sql-syntax-select.md#sql-syntax-group-by). - -## `HISTOGRAM` [sql-functions-grouping-histogram] - -```sql -HISTOGRAM( - numeric_exp, <1> - numeric_interval) <2> - -HISTOGRAM( - date_exp, <3> - date_time_interval) <4> -``` - -**Input**: - -1. numeric expression (typically a field). If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. -2. numeric interval. If `null`, the function returns `null`. -3. date/time expression (typically a field). If this field contains only `null` values, the function returns `null`. Otherwise, the function ignores `null` values in this field. -4. date/time [interval](sql-functions-datetime.md#sql-functions-datetime-interval). If `null`, the function returns `null`. - - -**Output**: non-empty buckets or groups of the given expression divided according to the given interval - -**Description**: The histogram function takes all matching values and divides them into buckets with fixed size matching the given interval, using (roughly) the following formula: - -```sql -bucket_key = Math.floor(value / interval) * interval -``` - -::::{note} -The histogram in SQL does **NOT** return empty buckets for missing intervals as the traditional [histogram](elasticsearch://reference/aggregations/search-aggregations-bucket-histogram-aggregation.md) and [date histogram](elasticsearch://reference/aggregations/search-aggregations-bucket-datehistogram-aggregation.md). Such behavior does not fit conceptually in SQL which treats all missing values as `null`; as such the histogram places all missing values in the `null` group. -:::: - - -`Histogram` can be applied on either numeric fields: - -```sql -SELECT HISTOGRAM(salary, 5000) AS h FROM emp GROUP BY h; - - h ---------------- -25000 -30000 -35000 -40000 -45000 -50000 -55000 -60000 -65000 -70000 -``` - -or date/time fields: - -```sql -SELECT HISTOGRAM(birth_date, INTERVAL 1 YEAR) AS h, COUNT(*) AS c FROM emp GROUP BY h; - - - h | c -------------------------+--------------- -null |10 -1952-01-01T00:00:00.000Z|8 -1953-01-01T00:00:00.000Z|11 -1954-01-01T00:00:00.000Z|8 -1955-01-01T00:00:00.000Z|4 -1956-01-01T00:00:00.000Z|5 -1957-01-01T00:00:00.000Z|4 -1958-01-01T00:00:00.000Z|7 -1959-01-01T00:00:00.000Z|9 -1960-01-01T00:00:00.000Z|8 -1961-01-01T00:00:00.000Z|8 -1962-01-01T00:00:00.000Z|6 -1963-01-01T00:00:00.000Z|7 -1964-01-01T00:00:00.000Z|4 -1965-01-01T00:00:00.000Z|1 -``` - -Expressions inside the histogram are also supported as long as the return type is numeric: - -```sql -SELECT HISTOGRAM(salary % 100, 10) AS h, COUNT(*) AS c FROM emp GROUP BY h; - - h | c ----------------+--------------- -0 |10 -10 |15 -20 |10 -30 |14 -40 |9 -50 |9 -60 |8 -70 |13 -80 |3 -90 |9 -``` - -Do note that histograms (and grouping functions in general) allow custom expressions but cannot have any functions applied to them in the `GROUP BY`. In other words, the following statement is **NOT** allowed: - -```sql -SELECT MONTH(HISTOGRAM(birth_date), 2)) AS h, COUNT(*) as c FROM emp GROUP BY h ORDER BY h DESC; -``` - -as it requires two groupings (one for histogram followed by a second for applying the function on top of the histogram groups). - -Instead one can rewrite the query to move the expression on the histogram *inside* of it: - -```sql -SELECT HISTOGRAM(MONTH(birth_date), 2) AS h, COUNT(*) as c FROM emp GROUP BY h ORDER BY h DESC; - - h | c ----------------+--------------- -12 |7 -10 |17 -8 |16 -6 |16 -4 |18 -2 |10 -0 |6 -null |10 -``` - -::::{important} -When the histogram in SQL is applied on **DATE** type instead of **DATETIME**, the interval specified is truncated to the multiple of a day. E.g.: for `HISTOGRAM(CAST(birth_date AS DATE), INTERVAL '2 3:04' DAY TO MINUTE)` the interval actually used will be `INTERVAL '2' DAY`. If the interval specified is less than 1 day, e.g.: `HISTOGRAM(CAST(birth_date AS DATE), INTERVAL '20' HOUR)` then the interval used will be `INTERVAL '1' DAY`. -:::: - - -::::{important} -All intervals specified for a date/time HISTOGRAM will use a [fixed interval](elasticsearch://reference/aggregations/search-aggregations-bucket-datehistogram-aggregation.md) in their `date_histogram` aggregation definition, with the notable exceptions of `INTERVAL '1' YEAR`, `INTERVAL '1' MONTH` and `INTERVAL '1' DAY` where a calendar interval is used. The choice for a calendar interval was made for having a more intuitive result for YEAR, MONTH and DAY groupings. In the case of YEAR, for example, the calendar intervals consider a one year bucket as the one starting on January 1st that specific year, whereas a fixed interval one-year-bucket considers one year as a number of milliseconds (for example, `31536000000ms` corresponding to 365 days, 24 hours per day, 60 minutes per hour etc.). With fixed intervals, the day of February 5th, 2019 for example, belongs to a bucket that starts on December 20th, 2018 and {{es}} (and implicitly Elasticsearch SQL) would have returned the year 2018 for a date that’s actually in 2019. With calendar interval this behavior is more intuitive, having the day of February 5th, 2019 actually belonging to the 2019 year bucket. -:::: - - -::::{important} -Histogram in SQL cannot be applied on **TIME** type. E.g.: `HISTOGRAM(CAST(birth_date AS TIME), INTERVAL '10' MINUTES)` is currently not supported. -:::: diff --git a/explore-analyze/query-filter/languages/sql-functions-math.md b/explore-analyze/query-filter/languages/sql-functions-math.md deleted file mode 100644 index c7da803983..0000000000 --- a/explore-analyze/query-filter/languages/sql-functions-math.md +++ /dev/null @@ -1,722 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-functions-math.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Mathematical Functions [sql-functions-math] - -All math and trigonometric functions require their input (where applicable) to be numeric. - - -## Generic [sql-functions-math-generic] - -## `ABS` [sql-functions-math-abs] - -```sql -ABS(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: numeric - -**Description**: Returns the [absolute value](https://en.wikipedia.org/wiki/Absolute_value) of `numeric_exp`. The return type is the same as the input type. - -```sql -SELECT ABS(-123.5), ABS(55); - - ABS(-123.5) | ABS(55) ----------------+--------------- -123.5 |55 -``` - - -## `CBRT` [sql-functions-math-cbrt] - -```sql -CBRT(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns the [cube root](https://en.wikipedia.org/wiki/Cube_root) of `numeric_exp`. - -```sql -SELECT CBRT(-125.5); - - CBRT(-125.5) -------------------- --5.0066577974783435 -``` - - -## `CEIL/CEILING` [sql-functions-math-ceil] - -```sql -CEIL(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: integer or long numeric value - -**Description**: Returns the smallest integer greater than or equal to `numeric_exp`. - -```sql -SELECT CEIL(125.01), CEILING(-125.99); - - CEIL(125.01) |CEILING(-125.99) ----------------+---------------- -126 |-125 -``` - - -## `E` [sql-functions-math-e] - -```sql -E() -``` - -**Input**: *none* - -**Output**: `2.718281828459045` - -**Description**: Returns [Euler’s number](https://en.wikipedia.org/wiki/E_%28mathematical_constant%29). - -```sql -SELECT E(), CEIL(E()); - - E() | CEIL(E()) ------------------+--------------- -2.718281828459045|3 -``` - - -## `EXP` [sql-functions-math-exp] - -```sql -EXP(numeric_exp) <1> -``` - -**Input**: - -1. float numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns [Euler’s number at the power](https://en.wikipedia.org/wiki/Exponential_function) of `numeric_exp` enumeric_exp. - -```sql -SELECT EXP(1), E(), EXP(2), E() * E(); - - EXP(1) | E() | EXP(2) | E() * E() ------------------+-----------------+----------------+------------------ -2.718281828459045|2.718281828459045|7.38905609893065|7.3890560989306495 -``` - - -## `EXPM1` [sql-functions-math-expm1] - -```sql -EXPM1(numeric_exp) <1> -``` - -**Input**: - -1. float numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns [Euler’s number at the power](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.md#expm1-double-) of `numeric_exp` minus 1 (enumeric_exp - 1). - -```sql -SELECT E(), EXP(2), EXPM1(2); - - E() | EXP(2) | EXPM1(2) ------------------+----------------+---------------- -2.718281828459045|7.38905609893065|6.38905609893065 -``` - - -## `FLOOR` [sql-functions-math-floor] - -```sql -FLOOR(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: integer or long numeric value - -**Description**: Returns the largest integer less than or equal to `numeric_exp`. - -```sql -SELECT FLOOR(125.01), FLOOR(-125.99); - - FLOOR(125.01) |FLOOR(-125.99) ----------------+--------------- -125 |-126 -``` - - -## `LOG` [sql-functions-math-log] - -```sql -LOG(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns the [natural logarithm](https://en.wikipedia.org/wiki/Natural_logarithm) of `numeric_exp`. - -```sql -SELECT EXP(3), LOG(20.085536923187668); - - EXP(3) |LOG(20.085536923187668) -------------------+----------------------- -20.085536923187668|3.0 -``` - - -## `LOG10` [sql-functions-math-log10] - -```sql -LOG10(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns the [base 10 logarithm](https://en.wikipedia.org/wiki/Common_logarithm) of `numeric_exp`. - -```sql -SELECT LOG10(5), LOG(5)/LOG(10); - - LOG10(5) | LOG(5)/LOG(10) -------------------+----------------------- -0.6989700043360189|0.6989700043360187 -``` - - -## `PI` [sql-functions-math-pi] - -```sql -PI() -``` - -**Input**: *none* - -**Output**: `3.141592653589793` - -**Description**: Returns [PI number](https://en.wikipedia.org/wiki/Pi). - -```sql -SELECT PI(); - - PI() ------------------ -3.141592653589793 -``` - - -## `POWER` [sql-functions-math-power] - -```sql -POWER( - numeric_exp, <1> - integer_exp) <2> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. -2. integer expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns the value of `numeric_exp` to the power of `integer_exp`. - -```sql -SELECT POWER(3, 2), POWER(3, 3); - - POWER(3, 2) | POWER(3, 3) ----------------+--------------- -9.0 |27.0 -``` - -```sql -SELECT POWER(5, -1), POWER(5, -2); - - POWER(5, -1) | POWER(5, -2) ----------------+--------------- -0.2 |0.04 -``` - - -## `RANDOM/RAND` [sql-functions-math-random] - -```sql -RANDOM(seed) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns a random double using the given seed. - -```sql -SELECT RANDOM(123); - - RANDOM(123) ------------------- -0.7231742029971469 -``` - - -## `ROUND` [sql-functions-math-round] - -```sql -ROUND( - numeric_exp <1> - [, integer_exp]) <2> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. -2. integer expression; optional. If `null`, the function returns `null`. - - -**Output**: numeric - -**Description**: Returns `numeric_exp` rounded to `integer_exp` places right of the decimal point. If `integer_exp` is negative, `numeric_exp` is rounded to |`integer_exp`| places to the left of the decimal point. If `integer_exp` is omitted, the function will perform as if `integer_exp` would be 0. The returned numeric data type is the same as the data type of `numeric_exp`. - -```sql -SELECT ROUND(-345.153, 1) AS rounded; - - rounded ---------------- --345.2 -``` - -```sql -SELECT ROUND(-345.153, -1) AS rounded; - - rounded ---------------- --350.0 -``` - - -## `SIGN/SIGNUM` [sql-functions-math-sign] - -```sql -SIGN(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: [-1, 0, 1] - -**Description**: Returns an indicator of the sign of `numeric_exp`. If `numeric_exp` is less than zero, –1 is returned. If `numeric_exp` equals zero, 0 is returned. If `numeric_exp` is greater than zero, 1 is returned. - -```sql -SELECT SIGN(-123), SIGN(0), SIGN(415); - - SIGN(-123) | SIGN(0) | SIGN(415) ----------------+---------------+--------------- --1 |0 |1 -``` - - -## `SQRT` [sql-functions-math-sqrt] - -```sql -SQRT(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns [square root](https://en.wikipedia.org/wiki/Square_root) of `numeric_exp`. - -```sql -SELECT SQRT(EXP(2)), E(), SQRT(25); - - SQRT(EXP(2)) | E() | SQRT(25) ------------------+-----------------+--------------- -2.718281828459045|2.718281828459045|5.0 -``` - - -## `TRUNCATE/TRUNC` [sql-functions-math-truncate] - -```sql -TRUNCATE( - numeric_exp <1> - [, integer_exp]) <2> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. -2. integer expression; optional. If `null`, the function returns `null`. - - -**Output**: numeric - -**Description**: Returns `numeric_exp` truncated to `integer_exp` places right of the decimal point. If `integer_exp` is negative, `numeric_exp` is truncated to |`integer_exp`| places to the left of the decimal point. If `integer_exp` is omitted, the function will perform as if `integer_exp` would be 0. The returned numeric data type is the same as the data type of `numeric_exp`. - -```sql -SELECT TRUNC(-345.153, 1) AS trimmed; - - trimmed ---------------- --345.1 -``` - -```sql -SELECT TRUNCATE(-345.153, -1) AS trimmed; - - trimmed ---------------- --340.0 -``` - - -## Trigonometric [sql-functions-math-trigonometric] - - -## `ACOS` [sql-functions-math-acos] - -```sql -ACOS(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns the [arccosine](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions) of `numeric_exp` as an angle, expressed in radians. - -```sql -SELECT ACOS(COS(PI())), PI(); - - ACOS(COS(PI())) | PI() ------------------+----------------- -3.141592653589793|3.141592653589793 -``` - - -## `ASIN` [sql-functions-math-asin] - -```sql -ASIN(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns the [arcsine](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions) of `numeric_exp` as an angle, expressed in radians. - -```sql -SELECT ROUND(DEGREES(ASIN(0.7071067811865475))) AS "ASIN(0.707)", ROUND(SIN(RADIANS(45)), 3) AS "SIN(45)"; - - ASIN(0.707) | SIN(45) ----------------+--------------- -45.0 |0.707 -``` - - -## `ATAN` [sql-functions-math-atan] - -```sql -ATAN(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns the [arctangent](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions) of `numeric_exp` as an angle, expressed in radians. - -```sql -SELECT DEGREES(ATAN(TAN(RADIANS(90)))); - -DEGREES(ATAN(TAN(RADIANS(90)))) -------------------------------- -90.0 -``` - - -## `ATAN2` [sql-functions-math-atan2] - -```sql -ATAN2( - ordinate, <1> - abscisa) <2> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. -2. numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns the [arctangent of the `ordinate` and `abscisa` coordinates](https://en.wikipedia.org/wiki/Atan2) specified as an angle, expressed in radians. - -```sql -SELECT ATAN2(5 * SIN(RADIANS(45)), 5 * COS(RADIANS(45))) AS "ATAN2(5*SIN(45), 5*COS(45))", RADIANS(45); - -ATAN2(5*SIN(45), 5*COS(45))| RADIANS(45) ----------------------------+------------------ -0.7853981633974483 |0.7853981633974483 -``` - - -## `COS` [sql-functions-math-cos] - -```sql -COS(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns the [cosine](https://en.wikipedia.org/wiki/Trigonometric_functions#cosine) of `numeric_exp`, where `numeric_exp` is an angle expressed in radians. - -```sql -SELECT COS(RADIANS(180)), POWER(SIN(RADIANS(54)), 2) + POWER(COS(RADIANS(54)), 2) AS pythagorean_identity; - -COS(RADIANS(180))|pythagorean_identity ------------------+-------------------- --1.0 |1.0 -``` - - -## `COSH` [sql-functions-math-cosh] - -```sql -COSH(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns the [hyperbolic cosine](https://en.wikipedia.org/wiki/Hyperbolic_function) of `numeric_exp`. - -```sql -SELECT COSH(5), (POWER(E(), 5) + POWER(E(), -5)) / 2 AS "(e^5 + e^-5)/2"; - - COSH(5) | (e^5 + e^-5)/2 ------------------+----------------- -74.20994852478785|74.20994852478783 -``` - - -## `COT` [sql-functions-math-cot] - -```sql -COT(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns the [cotangent](https://en.wikipedia.org/wiki/Trigonometric_functions#Cosecant,_secant,_and_cotangent) of `numeric_exp`, where `numeric_exp` is an angle expressed in radians. - -```sql -SELECT COT(RADIANS(30)) AS "COT(30)", COS(RADIANS(30)) / SIN(RADIANS(30)) AS "COS(30)/SIN(30)"; - - COT(30) | COS(30)/SIN(30) -------------------+------------------ -1.7320508075688774|1.7320508075688776 -``` - - -## `DEGREES` [sql-functions-math-degrees] - -```sql -DEGREES(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Convert from [radians](https://en.wikipedia.org/wiki/Radian) to [degrees](https://en.wikipedia.org/wiki/Degree_(angle)). - -```sql -SELECT DEGREES(PI() * 2), DEGREES(PI()); - -DEGREES(PI() * 2)| DEGREES(PI()) ------------------+--------------- -360.0 |180.0 -``` - - -## `RADIANS` [sql-functions-math-radians] - -```sql -RADIANS(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Convert from [degrees](https://en.wikipedia.org/wiki/Degree_(angle)) to [radians](https://en.wikipedia.org/wiki/Radian). - -```sql -SELECT RADIANS(90), PI()/2; - - RADIANS(90) | PI()/2 -------------------+------------------ -1.5707963267948966|1.5707963267948966 -``` - - -## `SIN` [sql-functions-math-sin] - -```sql -SIN(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns the [sine](https://en.wikipedia.org/wiki/Trigonometric_functions#sine) of `numeric_exp`, where `numeric_exp` is an angle expressed in radians. - -```sql -SELECT SIN(RADIANS(90)), POWER(SIN(RADIANS(67)), 2) + POWER(COS(RADIANS(67)), 2) AS pythagorean_identity; - -SIN(RADIANS(90))|pythagorean_identity -----------------+-------------------- -1.0 |1.0 -``` - - -## `SINH` [sql-functions-math-sinh] - -```sql -SINH(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns the [hyperbolic sine](https://en.wikipedia.org/wiki/Hyperbolic_function) of `numeric_exp`. - -```sql -SELECT SINH(5), (POWER(E(), 5) - POWER(E(), -5)) / 2 AS "(e^5 - e^-5)/2"; - - SINH(5) | (e^5 - e^-5)/2 ------------------+----------------- -74.20321057778875|74.20321057778874 -``` - - -## `TAN` [sql-functions-math-tan] - -```sql -TAN(numeric_exp) <1> -``` - -**Input**: - -1. numeric expression. If `null`, the function returns `null`. - - -**Output**: double numeric value - -**Description**: Returns the [tangent](https://en.wikipedia.org/wiki/Trigonometric_functions#tangent) of `numeric_exp`, where `numeric_exp` is an angle expressed in radians. - -```sql -SELECT TAN(RADIANS(66)) AS "TAN(66)", SIN(RADIANS(66))/COS(RADIANS(66)) AS "SIN(66)/COS(66)=TAN(66)"; - - TAN(66) |SIN(66)/COS(66)=TAN(66) -------------------+----------------------- -2.2460367739042164|2.246036773904216 -``` - - diff --git a/explore-analyze/query-filter/languages/sql-functions-search.md b/explore-analyze/query-filter/languages/sql-functions-search.md deleted file mode 100644 index 64e7105b8d..0000000000 --- a/explore-analyze/query-filter/languages/sql-functions-search.md +++ /dev/null @@ -1,194 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-functions-search.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Full-Text Search Functions [sql-functions-search] - -Search functions should be used when performing full-text search, namely when the `MATCH` or `QUERY` predicates are being used. Outside a, so-called, search context, these functions will return default values such as `0` or `NULL`. - -Elasticsearch SQL optimizes all queries executed against {{es}} depending on the scoring needs. Using [`track_scores`](elasticsearch://reference/elasticsearch/rest-apis/sort-search-results.md#_track_scores) on the search request or [`_doc` sorting](elasticsearch://reference/elasticsearch/rest-apis/sort-search-results.md) that disables scores calculation, Elasticsearch SQL instructs {{es}} not to compute scores when these are not needed. For example, every time a `SCORE()` function is encountered in the SQL query, the scores are computed. - -## `MATCH` [sql-functions-search-match] - -```sql -MATCH( - field_exp, <1> - constant_exp <2> - [, options]) <3> -``` - -**Input**: - -1. field(s) to match -2. matching text -3. additional parameters; optional - - -**Description**: A full-text search option, in the form of a predicate, available in Elasticsearch SQL that gives the user control over powerful [match](elasticsearch://reference/query-languages/query-dsl/query-dsl-match-query.md) and [multi_match](elasticsearch://reference/query-languages/query-dsl/query-dsl-multi-match-query.md) {{es}} queries. - -The first parameter is the field or fields to match against. In case it receives one value only, Elasticsearch SQL will use a `match` query to perform the search: - -```sql -SELECT author, name FROM library WHERE MATCH(author, 'frank'); - - author | name ----------------+------------------- -Frank Herbert |Dune -Frank Herbert |Dune Messiah -Frank Herbert |Children of Dune -Frank Herbert |God Emperor of Dune -``` - -However, it can also receive a list of fields and their corresponding optional `boost` value. In this case, Elasticsearch SQL will use a `multi_match` query to match the documents: - -```sql -SELECT author, name, SCORE() FROM library WHERE MATCH('author^2,name^5', 'frank dune'); - - author | name | SCORE() ----------------+-------------------+--------------- -Frank Herbert |Dune |11.443176 -Frank Herbert |Dune Messiah |9.446629 -Frank Herbert |Children of Dune |8.043278 -Frank Herbert |God Emperor of Dune|7.0029488 -``` - -::::{note} -The `multi_match` query in {{es}} has the option of [per-field boosting](elasticsearch://reference/query-languages/query-dsl/query-dsl-multi-match-query.md) that gives preferential weight (in terms of scoring) to fields being searched in, using the `^` character. In the example above, the `name` field has a greater weight in the final score than the `author` field when searching for `frank dune` text in both of them. -:::: - - -Both options above can be used in combination with the optional third parameter of the `MATCH()` predicate, where one can specify additional configuration parameters (separated by semicolon `;`) for either `match` or `multi_match` queries. For example: - -```sql -SELECT author, name, SCORE() FROM library WHERE MATCH(name, 'to the star', 'operator=OR;fuzziness=AUTO:1,5;minimum_should_match=1') -ORDER BY SCORE() DESC LIMIT 2; - - author | name | SCORE() ------------------+------------------------------------+--------------- -Douglas Adams |The Hitchhiker's Guide to the Galaxy|3.1756816 -Peter F. Hamilton|Pandora's Star |3.0997515 -``` - -::::{note} -The allowed optional parameters for a single-field `MATCH()` variant (for the `match` {{es}} query) are: `analyzer`, `auto_generate_synonyms_phrase_query`, `lenient`, `fuzziness`, `fuzzy_transpositions`, `fuzzy_rewrite`, `minimum_should_match`, `operator`, `max_expansions`, `prefix_length`. -:::: - - -::::{note} -The allowed optional parameters for a multi-field `MATCH()` variant (for the `multi_match` {{es}} query) are: `analyzer`, `auto_generate_synonyms_phrase_query`, `lenient`, `fuzziness`, `fuzzy_transpositions`, `fuzzy_rewrite`, `minimum_should_match`, `operator`, `max_expansions`, `prefix_length`, `slop`, `tie_breaker`, `type`. -:::: - - - -## `QUERY` [sql-functions-search-query] - -```sql -QUERY( - constant_exp <1> - [, options]) <2> -``` - -**Input**: - -1. query text -2. additional parameters; optional - - -**Description**: Just like `MATCH`, `QUERY` is a full-text search predicate that gives the user control over the [query_string](elasticsearch://reference/query-languages/query-dsl/query-dsl-query-string-query.md) query in {{es}}. - -The first parameter is basically the input that will be passed as is to the `query_string` query, which means that anything that `query_string` accepts in its `query` field can be used here as well: - -```sql -SELECT author, name, SCORE() FROM library WHERE QUERY('name:dune'); - - author | name | SCORE() ----------------+-------------------+--------------- -Frank Herbert |Dune |2.2886353 -Frank Herbert |Dune Messiah |1.8893257 -Frank Herbert |Children of Dune |1.6086556 -Frank Herbert |God Emperor of Dune|1.4005898 -``` - -A more advanced example, showing more of the features that `query_string` supports, of course possible with Elasticsearch SQL: - -```sql -SELECT author, name, page_count, SCORE() FROM library WHERE QUERY('_exists_:"author" AND page_count:>200 AND (name:/star.*/ OR name:duna~)'); - - author | name | page_count | SCORE() -------------------+-------------------+---------------+--------------- -Frank Herbert |Dune |604 |3.7164764 -Frank Herbert |Dune Messiah |331 |3.4169943 -Frank Herbert |Children of Dune |408 |3.2064917 -Frank Herbert |God Emperor of Dune|454 |3.0504425 -Peter F. Hamilton |Pandora's Star |768 |3.0 -Robert A. Heinlein|Starship Troopers |335 |3.0 -``` - -The query above uses the `_exists_` query to select documents that have values in the `author` field, a range query for `page_count` and regex and fuzziness queries for the `name` field. - -If one needs to customize various configuration options that `query_string` exposes, this can be done using the second *optional* parameter. Multiple settings can be specified separated by a semicolon `;`: - -```sql -SELECT author, name, SCORE() FROM library WHERE QUERY('dune god', 'default_operator=and;default_field=name'); - - author | name | SCORE() ----------------+-------------------+--------------- -Frank Herbert |God Emperor of Dune|3.6984892 -``` - -::::{note} -The allowed optional parameters for `QUERY()` are: `allow_leading_wildcard`, `analyze_wildcard`, `analyzer`, `auto_generate_synonyms_phrase_query`, `default_field`, `default_operator`, `enable_position_increments`, `escape`, `fuzziness`, `fuzzy_max_expansions`, `fuzzy_prefix_length`, `fuzzy_rewrite`, `fuzzy_transpositions`, `lenient`, `max_determinized_states`, `minimum_should_match`, `phrase_slop`, `rewrite`, `quote_analyzer`, `quote_field_suffix`, `tie_breaker`, `time_zone`, `type`. -:::: - - - -## `SCORE` [sql-functions-search-score] - -```sql -SCORE() -``` - -**Input**: *none* - -**Output**: `double` numeric value - -**Description**: Returns the [relevance](https://www.elastic.co/guide/en/elasticsearch/guide/2.x/relevance-intro.html) of a given input to the executed query. The higher score, the more relevant the data. - -::::{note} -When doing multiple text queries in the `WHERE` clause then, their scores will be combined using the same rules as {{es}}'s [bool query](elasticsearch://reference/query-languages/query-dsl/query-dsl-bool-query.md). -:::: - - -Typically `SCORE` is used for ordering the results of a query based on their relevance: - -```sql -SELECT SCORE(), * FROM library WHERE MATCH(name, 'dune') ORDER BY SCORE() DESC; - - SCORE() | author | name | page_count | release_date ----------------+---------------+-------------------+---------------+-------------------- -2.2886353 |Frank Herbert |Dune |604 |1965-06-01T00:00:00Z -1.8893257 |Frank Herbert |Dune Messiah |331 |1969-10-15T00:00:00Z -1.6086556 |Frank Herbert |Children of Dune |408 |1976-04-21T00:00:00Z -1.4005898 |Frank Herbert |God Emperor of Dune|454 |1981-05-28T00:00:00Z -``` - -However, it is perfectly fine to return the score without sorting by it: - -```sql -SELECT SCORE() AS score, name, release_date FROM library WHERE QUERY('dune') ORDER BY YEAR(release_date) DESC; - - score | name | release_date ----------------+-------------------+-------------------- -1.4005898 |God Emperor of Dune|1981-05-28T00:00:00Z -1.6086556 |Children of Dune |1976-04-21T00:00:00Z -1.8893257 |Dune Messiah |1969-10-15T00:00:00Z -2.2886353 |Dune |1965-06-01T00:00:00Z -``` - - diff --git a/explore-analyze/query-filter/languages/sql-functions-string.md b/explore-analyze/query-filter/languages/sql-functions-string.md deleted file mode 100644 index 41202913b0..0000000000 --- a/explore-analyze/query-filter/languages/sql-functions-string.md +++ /dev/null @@ -1,608 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-functions-string.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# String Functions [sql-functions-string] - -Functions for performing string manipulation. - -## `ASCII` [sql-functions-string-ascii] - -```sql -ASCII(string_exp) <1> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Returns the ASCII code value of the leftmost character of `string_exp` as an integer. - -```sql -SELECT ASCII('Elastic'); - -ASCII('Elastic') ----------------- -69 -``` - - -## `BIT_LENGTH` [sql-functions-string-bit-length] - -```sql -BIT_LENGTH(string_exp) <1> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Returns the length in bits of the `string_exp` input expression. - -```sql -SELECT BIT_LENGTH('Elastic'); - -BIT_LENGTH('Elastic') ---------------------- -56 -``` - - -## `CHAR` [sql-functions-string-char] - -```sql -CHAR(code) <1> -``` - -**Input**: - -1. integer expression between `0` and `255`. If `null`, negative, or greater than `255`, the function returns `null`. - - -**Output**: string - -**Description**: Returns the character that has the ASCII code value specified by the numeric input. - -```sql -SELECT CHAR(69); - - CHAR(69) ---------------- -E -``` - - -## `CHAR_LENGTH` [sql-functions-string-char-length] - -```sql -CHAR_LENGTH(string_exp) <1> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Returns the length in characters of the input, if the string expression is of a character data type; otherwise, returns the length in bytes of the string expression (the smallest integer not less than the number of bits divided by 8). - -```sql -SELECT CHAR_LENGTH('Elastic'); - -CHAR_LENGTH('Elastic') ----------------------- -7 -``` - - -## `CONCAT` [sql-functions-string-concat] - -```sql -CONCAT( - string_exp1, <1> - string_exp2) <2> -``` - -**Input**: - -1. string expression. Treats `null` as an empty string. -2. string expression. Treats `null` as an empty string. - - -**Output**: string - -**Description**: Returns a character string that is the result of concatenating `string_exp1` to `string_exp2`. - -The resulting string cannot exceed a byte length of 1 MB. - -```sql -SELECT CONCAT('Elasticsearch', ' SQL'); - -CONCAT('Elasticsearch', ' SQL') -------------------------------- -Elasticsearch SQL -``` - - -## `INSERT` [sql-functions-string-insert] - -```sql -INSERT( - source, <1> - start, <2> - length, <3> - replacement) <4> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. -2. integer expression. If `null`, the function returns `null`. -3. integer expression. If `null`, the function returns `null`. -4. string expression. If `null`, the function returns `null`. - - -**Output**: string - -**Description**: Returns a string where `length` characters have been deleted from `source`, beginning at `start`, and where `replacement` has been inserted into `source`, beginning at `start`. - -The resulting string cannot exceed a byte length of 1 MB. - -```sql -SELECT INSERT('Elastic ', 8, 1, 'search'); - -INSERT('Elastic ', 8, 1, 'search') ----------------------------------- -Elasticsearch -``` - - -## `LCASE` [sql-functions-string-lcase] - -```sql -LCASE(string_exp) <1> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. - - -**Output**: string - -**Description**: Returns a string equal to that in `string_exp`, with all uppercase characters converted to lowercase. - -```sql -SELECT LCASE('Elastic'); - -LCASE('Elastic') ----------------- -elastic -``` - - -## `LEFT` [sql-functions-string-left] - -```sql -LEFT( - string_exp, <1> - count) <2> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. -2. integer expression. If `null`, the function returns `null`. If `0` or negative, the function returns an empty string. - - -**Output**: string - -**Description**: Returns the leftmost count characters of `string_exp`. - -```sql -SELECT LEFT('Elastic',3); - -LEFT('Elastic',3) ------------------ -Ela -``` - - -## `LENGTH` [sql-functions-string-length] - -```sql -LENGTH(string_exp) <1> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Returns the number of characters in `string_exp`, excluding trailing blanks. - -```sql -SELECT LENGTH('Elastic '); - -LENGTH('Elastic ') --------------------- -7 -``` - - -## `LOCATE` [sql-functions-string-locate] - -```sql -LOCATE( - pattern, <1> - source <2> - [, start]<3> -) -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. -2. string expression. If `null`, the function returns `null`. -3. integer expression; optional. If `null`, `0`, `1`, negative, or not specified, the search starts at the first character position. - - -**Output**: integer - -**Description**: Returns the starting position of the first occurrence of `pattern` within `source`. The optional `start` specifies the character position to start the search with. If the `pattern` is not found within `source`, the function returns `0`. - -```sql -SELECT LOCATE('a', 'Elasticsearch'); - -LOCATE('a', 'Elasticsearch') ----------------------------- -3 -``` - -```sql -SELECT LOCATE('a', 'Elasticsearch', 5); - -LOCATE('a', 'Elasticsearch', 5) -------------------------------- -10 -``` - - -## `LTRIM` [sql-functions-string-ltrim] - -```sql -LTRIM(string_exp) <1> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. - - -**Output**: string - -**Description**: Returns the characters of `string_exp`, with leading blanks removed. - -```sql -SELECT LTRIM(' Elastic'); - -LTRIM(' Elastic') -------------------- -Elastic -``` - - -## `OCTET_LENGTH` [sql-functions-string-octet-length] - -```sql -OCTET_LENGTH(string_exp) <1> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Returns the length in bytes of the `string_exp` input expression. - -```sql -SELECT OCTET_LENGTH('Elastic'); - -OCTET_LENGTH('Elastic') ------------------------ -7 -``` - - -## `POSITION` [sql-functions-string-position] - -```sql -POSITION( - string_exp1, <1> - string_exp2) <2> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. -2. string expression. If `null`, the function returns `null`. - - -**Output**: integer - -**Description**: Returns the position of the `string_exp1` in `string_exp2`. The result is an exact numeric. - -```sql -SELECT POSITION('Elastic', 'Elasticsearch'); - -POSITION('Elastic', 'Elasticsearch') ------------------------------------- -1 -``` - - -## `REPEAT` [sql-functions-string-repeat] - -```sql -REPEAT( - string_exp, <1> - count) <2> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. -2. integer expression. If `0`, negative, or `null`, the function returns `null`. - - -**Output**: string - -**Description**: Returns a character string composed of `string_exp` repeated `count` times. - -The resulting string cannot exceed a byte length of 1 MB. - -```sql -SELECT REPEAT('La', 3); - - REPEAT('La', 3) ----------------- -LaLaLa -``` - - -## `REPLACE` [sql-functions-string-replace] - -```sql -REPLACE( - source, <1> - pattern, <2> - replacement) <3> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. -2. string expression. If `null`, the function returns `null`. -3. string expression. If `null`, the function returns `null`. - - -**Output**: string - -**Description**: Search `source` for occurrences of `pattern`, and replace with `replacement`. - -The resulting string cannot exceed a byte length of 1 MB. - -```sql -SELECT REPLACE('Elastic','El','Fant'); - -REPLACE('Elastic','El','Fant') ------------------------------- -Fantastic -``` - - -## `RIGHT` [sql-functions-string-right] - -```sql -RIGHT( - string_exp, <1> - count) <2> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. -2. integer expression. If `null`, the function returns `null`. If `0` or negative, the function returns an empty string. - - -**Output**: string - -**Description**: Returns the rightmost count characters of `string_exp`. - -```sql -SELECT RIGHT('Elastic',3); - -RIGHT('Elastic',3) ------------------- -tic -``` - - -## `RTRIM` [sql-functions-string-rtrim] - -```sql -RTRIM(string_exp) <1> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. - - -**Output**: string - -**Description**: Returns the characters of `string_exp` with trailing blanks removed. - -```sql -SELECT RTRIM('Elastic '); - -RTRIM('Elastic ') -------------------- -Elastic -``` - - -## `SPACE` [sql-functions-string-space] - -```sql -SPACE(count) <1> -``` - -**Input**: - -1. integer expression. If `null` or negative, the function returns `null`. - - -**Output**: string - -**Description**: Returns a character string consisting of `count` spaces. - -The resulting string cannot exceed a byte length of 1 MB. - -```sql -SELECT SPACE(3); - - SPACE(3) ---------------- -``` - - -## `STARTS_WITH` [sql-functions-string-startswith] - -```sql -STARTS_WITH( - source, <1> - pattern) <2> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. -2. string expression. If `null`, the function returns `null`. - - -**Output**: boolean value - -**Description**: Returns `true` if the source expression starts with the specified pattern, `false` otherwise. The matching is case sensitive. - -```sql -SELECT STARTS_WITH('Elasticsearch', 'Elastic'); - -STARTS_WITH('Elasticsearch', 'Elastic') --------------------------------- -true -``` - -```sql -SELECT STARTS_WITH('Elasticsearch', 'ELASTIC'); - -STARTS_WITH('Elasticsearch', 'ELASTIC') --------------------------------- -false -``` - - -## `SUBSTRING` [sql-functions-string-substring] - -```sql -SUBSTRING( - source, <1> - start, <2> - length) <3> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. -2. integer expression. If `null`, the function returns `null`. -3. integer expression. If `null`, the function returns `null`. - - -**Output**: string - -**Description**: Returns a character string that is derived from `source`, beginning at the character position specified by `start` for `length` characters. - -```sql -SELECT SUBSTRING('Elasticsearch', 0, 7); - -SUBSTRING('Elasticsearch', 0, 7) --------------------------------- -Elastic -``` - - -## `TRIM` [sql-functions-string-trim] - -```sql -TRIM(string_exp) <1> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. - - -**Output**: string - -**Description**: Returns the characters of `string_exp`, with leading and trailing blanks removed. - -```sql -SELECT TRIM(' Elastic ') AS trimmed; - -trimmed --------------- -Elastic -``` - - -## `UCASE` [sql-functions-string-ucase] - -```sql -UCASE(string_exp) <1> -``` - -**Input**: - -1. string expression. If `null`, the function returns `null`. - - -**Output**: string - -**Description**: Returns a string equal to that of the input, with all lowercase characters converted to uppercase. - -```sql -SELECT UCASE('Elastic'); - -UCASE('Elastic') ----------------- -ELASTIC -``` - - diff --git a/explore-analyze/query-filter/languages/sql-functions-system.md b/explore-analyze/query-filter/languages/sql-functions-system.md deleted file mode 100644 index d97d61da03..0000000000 --- a/explore-analyze/query-filter/languages/sql-functions-system.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-functions-system.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# System Functions [sql-functions-system] - -These functions return metadata type of information about the system being queried. - -## `DATABASE` [sql-functions-system-database] - -```sql -DATABASE() -``` - -**Input**: *none* - -**Output**: string - -**Description**: Returns the name of the database being queried. In the case of Elasticsearch SQL, this is the name of the Elasticsearch cluster. This function should always return a non-null value. - -```sql -SELECT DATABASE(); - - DATABASE ---------------- -elasticsearch -``` - - -## `USER` [sql-functions-system-user] - -```sql -USER() -``` - -**Input**: *none* - -**Output**: string - -**Description**: Returns the username of the authenticated user executing the query. This function can return `null` in case [security](../../../deploy-manage/deploy/self-managed/installing-elasticsearch.md) is disabled. - -```sql -SELECT USER(); - - USER ---------------- -elastic -``` - - diff --git a/explore-analyze/query-filter/languages/sql-functions-type-conversion.md b/explore-analyze/query-filter/languages/sql-functions-type-conversion.md deleted file mode 100644 index be0f399ced..0000000000 --- a/explore-analyze/query-filter/languages/sql-functions-type-conversion.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-functions-type-conversion.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Type Conversion Functions [sql-functions-type-conversion] - -Functions for converting an expression of one data type to another. - -## `CAST` [sql-functions-type-conversion-cast] - -```sql -CAST( - expression <1> - AS data_type) <2> -``` - -1. Expression to cast. If `null`, the function returns `null`. -2. Target data type to cast to - - -**Description**: Casts the result of the given expression to the target [data type](sql-data-types.md). If the cast is not possible (for example because of target type is too narrow or because the value itself cannot be converted), the query fails. - -```sql -SELECT CAST('123' AS INT) AS int; - - int ---------------- -123 -``` - -```sql -SELECT CAST(123 AS VARCHAR) AS string; - - string ---------------- -123 -``` - -```sql -SELECT YEAR(CAST('2018-05-19T11:23:45Z' AS TIMESTAMP)) AS year; - - year ---------------- -2018 -``` - -::::{important} -Both ANSI SQL and Elasticsearch SQL types are supported with the former taking precedence. This only affects `FLOAT` which due naming conflict, is interpreted as ANSI SQL and thus maps to `double` in {{es}} as oppose to `float`. To obtain an {{es}} `float`, perform casting to its SQL equivalent, `real` type. -:::: - - - -## `CONVERT` [sql-functions-type-conversion-convert] - -```sql -CONVERT( - expression, <1> - data_type) <2> -``` - -1. Expression to convert. If `null`, the function returns `null`. -2. Target data type to convert to - - -**Description**: Works exactly like [`CAST`](#sql-functions-type-conversion-cast) with slightly different syntax. Moreover, apart from the standard [data types](sql-data-types.md) it supports the corresponding [ODBC data types](https://docs.microsoft.com/en-us/sql/odbc/reference/appendixes/explicit-data-type-conversion-function?view=sql-server-2017). - -```sql -SELECT CONVERT('123', SQL_INTEGER) AS int; - - int ---------------- -123 -``` - -```sql -SELECT CONVERT('123', INTEGER) AS int; - - int ---------------- -123 -``` - - diff --git a/explore-analyze/query-filter/languages/sql-functions.md b/explore-analyze/query-filter/languages/sql-functions.md deleted file mode 100644 index c83c79e36a..0000000000 --- a/explore-analyze/query-filter/languages/sql-functions.md +++ /dev/null @@ -1,210 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-functions.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Functions and Operators [sql-functions] - -Elasticsearch SQL provides a comprehensive set of built-in operators and functions: - -* [Operators](sql-operators.md) - - * [`Equality (=)`](sql-operators.md#sql-operators-equality) - * [`Null safe Equality (<=>)`](sql-operators.md#sql-operators-null-safe-equality) - * [`Inequality (<> or !=)`](sql-operators.md#sql-operators-inequality) - * [`Comparison (<, <=, >, >=)`](sql-operators.md#sql-operators-comparison) - * [`BETWEEN`](sql-operators.md#sql-operators-between) - * [`IS NULL/IS NOT NULL`](sql-operators.md#sql-operators-is-null) - * [`IN (, , ...)`](sql-operators.md#sql-operators-in) - * [`AND`](sql-operators-logical.md#sql-operators-and) - * [`OR`](sql-operators-logical.md#sql-operators-or) - * [`NOT`](sql-operators-logical.md#sql-operators-not) - * [`Add (+)`](sql-operators-math.md#sql-operators-plus) - * [`Subtract (infix -)`](sql-operators-math.md#sql-operators-subtract) - * [`Negate (unary -)`](sql-operators-math.md#sql-operators-negate) - * [`Multiply (*)`](sql-operators-math.md#sql-operators-multiply) - * [`Divide (/)`](sql-operators-math.md#sql-operators-divide) - * [`Modulo or Remainder(%)`](sql-operators-math.md#sql-operators-remainder) - * [`Cast (::)`](sql-operators-cast.md#sql-operators-cast-cast) - -* [LIKE and RLIKE Operators](sql-like-rlike-operators.md) - - * [`LIKE`](sql-like-rlike-operators.md#sql-like-operator) - * [`RLIKE`](sql-like-rlike-operators.md#sql-rlike-operator) - -* [Aggregate Functions](sql-functions-aggs.md) - - * [`AVG`](sql-functions-aggs.md#sql-functions-aggs-avg) - * [`COUNT`](sql-functions-aggs.md#sql-functions-aggs-count) - * [`COUNT(ALL)`](sql-functions-aggs.md#sql-functions-aggs-count-all) - * [`COUNT(DISTINCT)`](sql-functions-aggs.md#sql-functions-aggs-count-distinct) - * [`FIRST/FIRST_VALUE`](sql-functions-aggs.md#sql-functions-aggs-first) - * [`LAST/LAST_VALUE`](sql-functions-aggs.md#sql-functions-aggs-last) - * [`MAX`](sql-functions-aggs.md#sql-functions-aggs-max) - * [`MIN`](sql-functions-aggs.md#sql-functions-aggs-min) - * [`SUM`](sql-functions-aggs.md#sql-functions-aggs-sum) - * [`KURTOSIS`](sql-functions-aggs.md#sql-functions-aggs-kurtosis) - * [`MAD`](sql-functions-aggs.md#sql-functions-aggs-mad) - * [`PERCENTILE`](sql-functions-aggs.md#sql-functions-aggs-percentile) - * [`PERCENTILE_RANK`](sql-functions-aggs.md#sql-functions-aggs-percentile-rank) - * [`SKEWNESS`](sql-functions-aggs.md#sql-functions-aggs-skewness) - * [`STDDEV_POP`](sql-functions-aggs.md#sql-functions-aggs-stddev-pop) - * [`STDDEV_SAMP`](sql-functions-aggs.md#sql-functions-aggs-stddev-samp) - * [`SUM_OF_SQUARES`](sql-functions-aggs.md#sql-functions-aggs-sum-squares) - * [`VAR_POP`](sql-functions-aggs.md#sql-functions-aggs-var-pop) - * [`VAR_SAMP`](sql-functions-aggs.md#sql-functions-aggs-var-samp) - -* [Grouping Functions](sql-functions-grouping.md) - - * [`HISTOGRAM`](sql-functions-grouping.md#sql-functions-grouping-histogram) - -* [Date-Time Operators](sql-functions-datetime.md#sql-functions-datetime-interval) -* [Date-Time Functions](sql-functions-datetime.md#sql-functions-current-date) - - * [`CURRENT_DATE/CURDATE`](sql-functions-datetime.md#sql-functions-current-date) - * [`CURRENT_TIME/CURTIME`](sql-functions-datetime.md#sql-functions-current-time) - * [`CURRENT_TIMESTAMP`](sql-functions-datetime.md#sql-functions-current-timestamp) - * [`DATE_ADD/DATEADD/TIMESTAMP_ADD/TIMESTAMPADD`](sql-functions-datetime.md#sql-functions-datetime-add) - * [`DATE_DIFF/DATEDIFF/TIMESTAMP_DIFF/TIMESTAMPDIFF`](sql-functions-datetime.md#sql-functions-datetime-diff) - * [`DATE_FORMAT`](sql-functions-datetime.md#sql-functions-datetime-dateformat) - * [`DATE_PARSE`](sql-functions-datetime.md#sql-functions-datetime-dateparse) - * [`DATETIME_FORMAT`](sql-functions-datetime.md#sql-functions-datetime-datetimeformat) - * [`DATETIME_PARSE`](sql-functions-datetime.md#sql-functions-datetime-datetimeparse) - * [`FORMAT`](sql-functions-datetime.md#sql-functions-datetime-format) - * [`DATE_PART/DATEPART`](sql-functions-datetime.md#sql-functions-datetime-part) - * [`DATE_TRUNC/DATETRUNC`](sql-functions-datetime.md#sql-functions-datetime-trunc) - * [`DAY_OF_MONTH/DOM/DAY`](sql-functions-datetime.md#sql-functions-datetime-day) - * [`DAY_OF_WEEK/DAYOFWEEK/DOW`](sql-functions-datetime.md#sql-functions-datetime-dow) - * [`DAY_OF_YEAR/DOY`](sql-functions-datetime.md#sql-functions-datetime-doy) - * [`DAY_NAME/DAYNAME`](sql-functions-datetime.md#sql-functions-datetime-dayname) - * [`EXTRACT`](sql-functions-datetime.md#sql-functions-datetime-extract) - * [`HOUR_OF_DAY/HOUR`](sql-functions-datetime.md#sql-functions-datetime-hour) - * [`ISO_DAY_OF_WEEK/ISODAYOFWEEK/ISODOW/IDOW`](sql-functions-datetime.md#sql-functions-datetime-isodow) - * [`ISO_WEEK_OF_YEAR/ISOWEEKOFYEAR/ISOWEEK/IWOY/IW`](sql-functions-datetime.md#sql-functions-datetime-isoweek) - * [`MINUTE_OF_DAY`](sql-functions-datetime.md#sql-functions-datetime-minuteofday) - * [`MINUTE_OF_HOUR/MINUTE`](sql-functions-datetime.md#sql-functions-datetime-minute) - * [`MONTH_OF_YEAR/MONTH`](sql-functions-datetime.md#sql-functions-datetime-month) - * [`MONTH_NAME/MONTHNAME`](sql-functions-datetime.md#sql-functions-datetime-monthname) - * [`NOW`](sql-functions-datetime.md#sql-functions-now) - * [`SECOND_OF_MINUTE/SECOND`](sql-functions-datetime.md#sql-functions-datetime-second) - * [`QUARTER`](sql-functions-datetime.md#sql-functions-datetime-quarter) - * [`TIME_PARSE`](sql-functions-datetime.md#sql-functions-datetime-timeparse) - * [`TO_CHAR`](sql-functions-datetime.md#sql-functions-datetime-to_char) - * [`TODAY`](sql-functions-datetime.md#sql-functions-today) - * [`WEEK_OF_YEAR/WEEK`](sql-functions-datetime.md#sql-functions-datetime-week) - * [`YEAR`](sql-functions-datetime.md#sql-functions-datetime-year) - -* [Full-Text Search Functions](sql-functions-search.md) - - * [`MATCH`](sql-functions-search.md#sql-functions-search-match) - * [`QUERY`](sql-functions-search.md#sql-functions-search-query) - * [`SCORE`](sql-functions-search.md#sql-functions-search-score) - -* [Mathematical Functions](sql-functions-math.md) - - * [`ABS`](sql-functions-math.md#sql-functions-math-abs) - * [`CBRT`](sql-functions-math.md#sql-functions-math-cbrt) - * [`CEIL/CEILING`](sql-functions-math.md#sql-functions-math-ceil) - * [`E`](sql-functions-math.md#sql-functions-math-e) - * [`EXP`](sql-functions-math.md#sql-functions-math-exp) - * [`EXPM1`](sql-functions-math.md#sql-functions-math-expm1) - * [`FLOOR`](sql-functions-math.md#sql-functions-math-floor) - * [`LOG`](sql-functions-math.md#sql-functions-math-log) - * [`LOG10`](sql-functions-math.md#sql-functions-math-log10) - * [`PI`](sql-functions-math.md#sql-functions-math-pi) - * [`POWER`](sql-functions-math.md#sql-functions-math-power) - * [`RANDOM/RAND`](sql-functions-math.md#sql-functions-math-random) - * [`ROUND`](sql-functions-math.md#sql-functions-math-round) - * [`SIGN/SIGNUM`](sql-functions-math.md#sql-functions-math-sign) - * [`SQRT`](sql-functions-math.md#sql-functions-math-sqrt) - * [`TRUNCATE/TRUNC`](sql-functions-math.md#sql-functions-math-truncate) - * [`ACOS`](sql-functions-math.md#sql-functions-math-acos) - * [`ASIN`](sql-functions-math.md#sql-functions-math-asin) - * [`ATAN`](sql-functions-math.md#sql-functions-math-atan) - * [`ATAN2`](sql-functions-math.md#sql-functions-math-atan2) - * [`COS`](sql-functions-math.md#sql-functions-math-cos) - * [`COSH`](sql-functions-math.md#sql-functions-math-cosh) - * [`COT`](sql-functions-math.md#sql-functions-math-cot) - * [`DEGREES`](sql-functions-math.md#sql-functions-math-degrees) - * [`RADIANS`](sql-functions-math.md#sql-functions-math-radians) - * [`SIN`](sql-functions-math.md#sql-functions-math-sin) - * [`SINH`](sql-functions-math.md#sql-functions-math-sinh) - * [`TAN`](sql-functions-math.md#sql-functions-math-tan) - -* [String Functions](sql-functions-string.md) - - * [`ASCII`](sql-functions-string.md#sql-functions-string-ascii) - * [`BIT_LENGTH`](sql-functions-string.md#sql-functions-string-bit-length) - * [`CHAR`](sql-functions-string.md#sql-functions-string-char) - * [`CHAR_LENGTH`](sql-functions-string.md#sql-functions-string-char-length) - * [`CONCAT`](sql-functions-string.md#sql-functions-string-concat) - * [`INSERT`](sql-functions-string.md#sql-functions-string-insert) - * [`LCASE`](sql-functions-string.md#sql-functions-string-lcase) - * [`LEFT`](sql-functions-string.md#sql-functions-string-left) - * [`LENGTH`](sql-functions-string.md#sql-functions-string-length) - * [`LOCATE`](sql-functions-string.md#sql-functions-string-locate) - * [`LTRIM`](sql-functions-string.md#sql-functions-string-ltrim) - * [`OCTET_LENGTH`](sql-functions-string.md#sql-functions-string-octet-length) - * [`POSITION`](sql-functions-string.md#sql-functions-string-position) - * [`REPEAT`](sql-functions-string.md#sql-functions-string-repeat) - * [`REPLACE`](sql-functions-string.md#sql-functions-string-replace) - * [`RIGHT`](sql-functions-string.md#sql-functions-string-right) - * [`RTRIM`](sql-functions-string.md#sql-functions-string-rtrim) - * [`SPACE`](sql-functions-string.md#sql-functions-string-space) - * [`SUBSTRING`](sql-functions-string.md#sql-functions-string-substring) - * [`TRIM`](sql-functions-string.md#sql-functions-string-trim) - * [`UCASE`](sql-functions-string.md#sql-functions-string-ucase) - -* [Type Conversion Functions](sql-functions-type-conversion.md) - - * [`CAST`](sql-functions-type-conversion.md#sql-functions-type-conversion-cast) - * [`CONVERT`](sql-functions-type-conversion.md#sql-functions-type-conversion-convert) - -* [Conditional Functions And Expressions](sql-functions-conditional.md) - - * [`CASE`](sql-functions-conditional.md#sql-functions-conditional-case) - * [`COALESCE`](sql-functions-conditional.md#sql-functions-conditional-coalesce) - * [`GREATEST`](sql-functions-conditional.md#sql-functions-conditional-greatest) - * [`IFNULL`](sql-functions-conditional.md#sql-functions-conditional-ifnull) - * [`IIF`](sql-functions-conditional.md#sql-functions-conditional-iif) - * [`ISNULL`](sql-functions-conditional.md#sql-functions-conditional-isnull) - * [`LEAST`](sql-functions-conditional.md#sql-functions-conditional-least) - * [`NULLIF`](sql-functions-conditional.md#sql-functions-conditional-nullif) - * [`NVL`](sql-functions-conditional.md#sql-functions-conditional-nvl) - -* [Geo Functions](sql-functions-geo.md) - - * [`ST_AsWKT`](sql-functions-geo.md#sql-functions-geo-st-as-wkt) - * [`ST_Distance`](sql-functions-geo.md#sql-functions-geo-st-distance) - * [`ST_GeometryType`](sql-functions-geo.md#sql-functions-geo-st-geometrytype) - * [`ST_WKTToSQL`](sql-functions-geo.md#sql-functions-geo-st-wkt-to-sql) - * [`ST_X`](sql-functions-geo.md#sql-functions-geo-st-x) - * [`ST_Y`](sql-functions-geo.md#sql-functions-geo-st-y) - * [`ST_Z`](sql-functions-geo.md#sql-functions-geo-st-z) - -* [System Functions](sql-functions-system.md) - - * [`DATABASE`](sql-functions-system.md#sql-functions-system-database) - * [`USER`](sql-functions-system.md#sql-functions-system-user) - - - - - - - - - - - - - - - - - diff --git a/explore-analyze/query-filter/languages/sql-index-frozen.md b/explore-analyze/query-filter/languages/sql-index-frozen.md deleted file mode 100644 index 88b45a7e30..0000000000 --- a/explore-analyze/query-filter/languages/sql-index-frozen.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-index-frozen.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Frozen Indices [sql-index-frozen] - -By default, Elasticsearch SQL doesn’t search [frozen indices](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-unfreeze). To search frozen indices, use one of the following features: - -dedicated configuration parameter -: Set to `true` properties `index_include_frozen` in the [SQL search API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-sql-query) or `index.include.frozen` in the drivers to include frozen indices. - -dedicated keyword -: Explicitly perform the inclusion through the dedicated `FROZEN` keyword in the `FROM` clause or `INCLUDE FROZEN` in the `SHOW` commands: - -```sql -SHOW TABLES INCLUDE FROZEN; - - catalog | name | type | kind ----------------+---------------+----------+--------------- -javaRestTest |archive |TABLE |FROZEN INDEX -javaRestTest |emp |TABLE |INDEX -javaRestTest |employees |VIEW |ALIAS -javaRestTest |library |TABLE |INDEX -``` - -```sql -SELECT * FROM FROZEN archive LIMIT 1; - - author | name | page_count | release_date ------------------+--------------------+---------------+-------------------- -James S.A. Corey |Leviathan Wakes |561 |2011-06-02T00:00:00Z -``` - -Unless enabled, frozen indices are completely ignored; it is as if they do not exist and as such, queries ran against them are likely to fail. - diff --git a/explore-analyze/query-filter/languages/sql-index-patterns.md b/explore-analyze/query-filter/languages/sql-index-patterns.md deleted file mode 100644 index 8a89a795c1..0000000000 --- a/explore-analyze/query-filter/languages/sql-index-patterns.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-index-patterns.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Index patterns [sql-index-patterns] - -Elasticsearch SQL supports two types of patterns for matching multiple indices or tables: - - -## {{es}} multi-target syntax [sql-index-patterns-multi] - -The {{es}} notation for enumerating, including or excluding [multi-target syntax](elasticsearch://reference/elasticsearch/rest-apis/api-conventions.md#api-multi-index) is supported *as long* as it is quoted or escaped as a table identifier. - -For example: - -```sql -SHOW TABLES "*,-l*"; - - catalog | name | type | kind ----------------+---------------+----------+--------------- -javaRestTest |emp |TABLE |INDEX -javaRestTest |employees |VIEW |ALIAS -``` - -Notice the pattern is surrounded by double quotes `"`. It enumerated `*` meaning all indices however it excludes (due to `-`) all indices that start with `l`. This notation is very convenient and powerful as it allows both inclusion and exclusion, depending on the target naming convention. - -The same kind of patterns can also be used to query multiple indices or tables. - -For example: - -```sql -SELECT emp_no FROM "e*p" LIMIT 1; - - emp_no ---------------- -10001 -``` - -::::{note} -There is the restriction that all resolved concrete tables have the exact same mapping. -:::: - - -[preview] To run a [{{ccs}}](../../../solutions/search/cross-cluster-search.md), specify a cluster name using the `:` syntax, where `` maps to a SQL catalog (cluster) and `` to a table (index or data stream). The `` supports wildcards (`*`) and `` can be an index pattern. - -For example: - -```sql -SELECT emp_no FROM "my*cluster:*emp" LIMIT 1; - - emp_no ---------------- -10001 -``` - - -## SQL `LIKE` notation [sql-index-patterns-like] - -The common `LIKE` statement (including escaping if needed) to match a wildcard pattern, based on one `_` or multiple `%` characters. - -Using `SHOW TABLES` command again: - -```sql -SHOW TABLES LIKE 'emp%'; - - catalog | name | type | kind ----------------+---------------+----------+--------------- -javaRestTest |emp |TABLE |INDEX -javaRestTest |employees |VIEW |ALIAS -``` - -The pattern matches all tables that start with `emp`. - -This command supports *escaping* as well, for example: - -```sql -SHOW TABLES LIKE 'emp!%' ESCAPE '!'; - - catalog | name | type | kind ----------------+---------------+---------------+--------------- -``` - -Notice how now `emp%` does not match any tables because `%`, which means match zero or more characters, has been escaped by `!` and thus becomes an regular char. And since there is no table named `emp%`, an empty table is returned. - -In a nutshell, the differences between the two type of patterns are: - -| Feature | Multi index | SQL `LIKE` | -| --- | --- | --- | -| Type of quoting | `"` | `'` | -| Inclusion | Yes | Yes | -| Exclusion | Yes | No | -| Enumeration | Yes | No | -| One char pattern | No | `_` | -| Multi char pattern | `*` | `%` | -| Escaping | No | `ESCAPE` | - -Which one to use, is up to you however try to stick to the same one across your queries for consistency. - -::::{note} -As the query type of quoting between the two patterns is fairly similar (`"` vs `'`), Elasticsearch SQL *always* requires the keyword `LIKE` for SQL `LIKE` pattern. -:::: - - diff --git a/explore-analyze/query-filter/languages/sql-lexical-structure.md b/explore-analyze/query-filter/languages/sql-lexical-structure.md deleted file mode 100644 index a117dd0c41..0000000000 --- a/explore-analyze/query-filter/languages/sql-lexical-structure.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-lexical-structure.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Lexical Structure [sql-lexical-structure] - -This section covers the major lexical structure of SQL, which for the most part, is going to resemble that of ANSI SQL itself hence why low-levels details are not discussed in depth. - -Elasticsearch SQL currently accepts only one *command* at a time. A command is a sequence of *tokens* terminated by the end of input stream. - -A token can be a *key word*, an *identifier* (*quoted* or *unquoted*), a *literal* (or constant) or a special character symbol (typically a delimiter). Tokens are typically separated by whitespace (be it space, tab) though in some cases, where there is no ambiguity (typically due to a character symbol) this is not needed - however for readability purposes this should be avoided. - -## Key Words [sql-syntax-keywords] - -Take the following example: - -```sql -SELECT * FROM table -``` - -This query has four tokens: `SELECT`, `*`, `FROM` and `table`. The first three, namely `SELECT`, `*` and `FROM` are *key words* meaning words that have a fixed meaning in SQL. The token `table` is an *identifier* meaning it identifies (by name) an entity inside SQL such as a table (in this case), a column, etc… - -As one can see, both key words and identifiers have the *same* lexical structure and thus one cannot know whether a token is one or the other without knowing the SQL language; the complete list of key words is available in the [reserved appendix](sql-syntax-reserved.md). Do note that key words are case-insensitive meaning the previous example can be written as: - -```sql -select * fRoM table; -``` - -Identifiers however are not - as {{es}} is case sensitive, Elasticsearch SQL uses the received value verbatim. - -To help differentiate between the two, through-out the documentation the SQL key words are upper-cased a convention we find increases readability and thus recommend to others. - - -## Identifiers [sql-syntax-identifiers] - -Identifiers can be of two types: *quoted* and *unquoted*: - -```sql -SELECT ip_address FROM "hosts-*" -``` - -This query has two identifiers, `ip_address` and `hosts-*` (an [index pattern](elasticsearch://reference/elasticsearch/rest-apis/api-conventions.md#api-multi-index)). As `ip_address` does not clash with any key words it can be used verbatim, `hosts-*` on the other hand cannot as it clashes with `-` (minus operation) and `*` hence the double quotes. - -Another example: - -```sql -SELECT "from" FROM "" -``` - -The first identifier from needs to quoted as otherwise it clashes with the `FROM` key word (which is case insensitive as thus can be written as `from`) while the second identifier using {{es}} [Date math support in index and index alias names](elasticsearch://reference/elasticsearch/rest-apis/api-conventions.md#api-date-math-index-names) would have otherwise confuse the parser. - -Hence why in general, **especially** when dealing with user input it is **highly** recommended to use quotes for identifiers. It adds minimal increase to your queries and in return offers clarity and disambiguation. - - -## Literals (Constants) [sql-syntax-literals] - -Elasticsearch SQL supports two kind of *implicitly-typed* literals: strings and numbers. - - -#### String Literals [sql-syntax-string-literals] - -A string literal is an arbitrary number of characters bounded by single quotes `'`: `'Giant Robot'`. To include a single quote in the string, escape it using another single quote: `'Captain EO''s Voyage'`. - -::::{note} -An escaped single quote is **not** a double quote (`"`), but a single quote `'` *repeated* (`''`). -:::: - - - -#### Numeric Literals [_numeric_literals] - -Numeric literals are accepted both in decimal and scientific notation with exponent marker (`e` or `E`), starting either with a digit or decimal point `.`: - -```sql -1969 -- integer notation -3.14 -- decimal notation -.1234 -- decimal notation starting with decimal point -4E5 -- scientific notation (with exponent marker) -1.2e-3 -- scientific notation with decimal point -``` - -Numeric literals that contain a decimal point are always interpreted as being of type `double`. Those without are considered `integer` if they fit otherwise their type is `long` (or `BIGINT` in ANSI SQL types). - - -#### Generic Literals [sql-syntax-generic-literals] - -When dealing with arbitrary type literal, one creates the object by casting, typically, the string representation to the desired type. This can be achieved through the dedicated [cast operator](sql-operators-cast.md) and [functions](sql-functions-type-conversion.md): - -```sql -123::LONG -- cast 123 to a LONG -CAST('1969-05-13T12:34:56' AS TIMESTAMP) -- cast the given string to datetime -CONVERT('10.0.0.1', IP) -- cast '10.0.0.1' to an IP -``` - -Do note that Elasticsearch SQL provides functions that out of the box return popular literals (like `E()`) or provide dedicated parsing for certain strings. - - -## Single vs Double Quotes [sql-syntax-single-vs-double-quotes] - -It is worth pointing out that in SQL, single quotes `'` and double quotes `"` have different meaning and **cannot** be used interchangeably. Single quotes are used to declare a [string literal](#sql-syntax-string-literals) while double quotes for [identifiers](#sql-syntax-identifiers). - -To wit: - -```sql -SELECT "first_name" <1> - FROM "musicians" <1> - WHERE "last_name" <1> - = 'Carroll' <2> -``` - -1. Double quotes `"` used for column and table identifiers -2. Single quotes `'` used for a string literal - - -::::{note} -To escape single or double quotes, one needs to use that specific quote one more time. For example, the literal `John's` can be escaped like `SELECT 'John''s' AS name`. The same goes for double quotes escaping - `SELECT 123 AS "test""number"` will display as a result a column with the name `test"number`. -:::: - - - -## Special characters [sql-syntax-special-chars] - -A few characters that are not alphanumeric have a dedicated meaning different from that of an operator. For completeness these are specified below: - -| Char | Description | -| --- | --- | -| `*` | The asterisk (or wildcard) is used in some contexts to denote all fields for a table. Can be also used as an argument to some aggregate functions. | -| `,` | Commas are used to enumerate the elements of a list. | -| `.` | Used in numeric constants or to separate identifiers qualifiers (catalog, table, column names, etc…). | -| `()` | Parentheses are used for specific SQL commands, function declarations or to enforce precedence. | - - -## Operators [sql-syntax-operators] - -Most operators in Elasticsearch SQL have the same precedence and are left-associative. As this is done at parsing time, parenthesis need to be used to enforce a different precedence. - -The following table indicates the supported operators and their precedence (highest to lowest); - -| Operator/Element | Associativity | Description | -| --- | --- | --- | -| `.` | left | qualifier separator | -| `::` | left | PostgreSQL-style type cast | -| `+ -` | right | unary plus and minus (numeric literal sign) | -| `* / %` | left | multiplication, division, modulo | -| `+ -` | left | addition, subtraction | -| `BETWEEN IN LIKE` | | range containment, string matching | -| `< > <= >= = <=> <> !=` | | comparison | -| `NOT` | right | logical negation | -| `AND` | left | logical conjunction | -| `OR` | left | logical disjunction | - - -## Comments [sql-syntax-comments] - -Elasticsearch SQL allows comments which are sequence of characters ignored by the parsers. - -Two styles are supported: - -Single Line -: Comments start with a double dash `--` and continue until the end of the line. - -Multi line -: Comments that start with `/*` and end with `*/` (also known as C-style). - -```sql --- single line comment -/* multi - line - comment - that supports /* nested comments */ - */ -``` - - diff --git a/explore-analyze/query-filter/languages/sql-like-rlike-operators.md b/explore-analyze/query-filter/languages/sql-like-rlike-operators.md deleted file mode 100644 index fd427a58d7..0000000000 --- a/explore-analyze/query-filter/languages/sql-like-rlike-operators.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-like-rlike-operators.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# LIKE and RLIKE Operators [sql-like-rlike-operators] - -`LIKE` and `RLIKE` operators are commonly used to filter data based on string patterns. They usually act on a field placed on the left-hand side of the operator, but can also act on a constant (literal) expression. The right-hand side of the operator represents the pattern. Both can be used in the `WHERE` clause of the `SELECT` statement, but `LIKE` can also be used in other places, such as defining an [index pattern](sql-index-patterns.md) or across various [SHOW commands](sql-commands.md). This section covers only the `SELECT ... WHERE ...` usage. - -::::{note} -One significant difference between `LIKE`/`RLIKE` and the [full-text search predicates](sql-functions-search.md) is that the former act on [exact fields](sql-data-types.md#sql-multi-field) while the latter also work on [analyzed](elasticsearch://reference/elasticsearch/mapping-reference/text.md) fields. If the field used with `LIKE`/`RLIKE` doesn’t have an exact not-normalized sub-field (of [keyword](elasticsearch://reference/elasticsearch/mapping-reference/keyword.md) type) Elasticsearch SQL will not be able to run the query. If the field is either exact or has an exact sub-field, it will use it as is, or it will automatically use the exact sub-field even if it wasn’t explicitly specified in the statement. -:::: - - -## `LIKE` [sql-like-operator] - -```sql -expression <1> -LIKE constant_exp <2> -``` - -1. typically a field, or a constant expression -2. pattern - - -**Description**: The SQL `LIKE` operator is used to compare a value to similar values using wildcard operators. There are two wildcards used in conjunction with the `LIKE` operator: - -* The percent sign (%) -* The underscore (_) - -The percent sign represents zero, one or multiple characters. The underscore represents a single number or character. These symbols can be used in combinations. - -::::{note} -No other characters have special meaning or act as wildcard. Characters often used as wildcards in other languages (`*` or `?`) are treated as normal characters. -:::: - - -```sql -SELECT author, name FROM library WHERE name LIKE 'Dune%'; - - author | name ----------------+--------------- -Frank Herbert |Dune -Frank Herbert |Dune Messiah -``` - -There is, also, the possibility of using an escape character if one needs to match the wildcard characters themselves. This can be done by using the `ESCAPE [escape_character]` statement after the `LIKE ...` operator: - -``` -SELECT name, author FROM library WHERE name LIKE 'Dune/%' ESCAPE '/'; -``` -In the example above `/` is defined as an escape character which needs to be placed before the `%` or `_` characters if one needs to match those characters in the pattern specifically. By default, there is no escape character defined. - -::::{important} -Even though `LIKE` is a valid option when searching or filtering in Elasticsearch SQL, full-text search predicates `MATCH` and `QUERY` are [faster and much more powerful and are the preferred alternative](#sql-like-prefer-full-text). -:::: - - - -## `RLIKE` [sql-rlike-operator] - -```sql -expression <1> -RLIKE constant_exp <2> -``` - -1. typically a field, or a constant expression -2. pattern - - -**Description**: This operator is similar to `LIKE`, but the user is not limited to search for a string based on a fixed pattern with the percent sign (`%`) and underscore (`_`); the pattern in this case is a regular expression which allows the construction of more flexible patterns. - -For supported syntax, see [*Regular expression syntax*](elasticsearch://reference/query-languages/query-dsl/regexp-syntax.md). - -```sql -SELECT author, name FROM library WHERE name RLIKE 'Child.* Dune'; - - author | name ----------------+---------------- -Frank Herbert |Children of Dune -``` - -::::{important} -Even though `RLIKE` is a valid option when searching or filtering in Elasticsearch SQL, full-text search predicates `MATCH` and `QUERY` are [faster and much more powerful and are the preferred alternative](#sql-like-prefer-full-text). -:::: - - - -## Prefer full-text search predicates [sql-like-prefer-full-text] - -When using `LIKE`/`RLIKE`, do consider using [full-text search predicates](sql-functions-search.md) which are faster, much more powerful and offer the option of sorting by relevancy (results can be returned based on how well they matched). - -For example: - -| LIKE/RLIKE | QUERY/MATCH | -| --- | --- | -| ``foo LIKE 'bar'`` | ``MATCH(foo, 'bar')`` | -| ``foo LIKE 'bar' AND tar LIKE 'goo'`` | ``MATCH('foo^2, tar^5', 'bar goo', 'operator=and')`` | -| ``foo LIKE 'barr'`` | ``QUERY('foo: bar~')`` | -| ``foo LIKE 'bar' AND tar LIKE 'goo'`` | ``QUERY('foo: bar AND tar: goo')`` | -| ``foo RLIKE 'ba.*'`` | ``MATCH(foo, 'ba', 'fuzziness=AUTO:1,5')`` | -| ``foo RLIKE 'b.{{1}}r'`` | ``MATCH(foo, 'br', 'fuzziness=1')`` | - - diff --git a/explore-analyze/query-filter/languages/sql-limitations.md b/explore-analyze/query-filter/languages/sql-limitations.md deleted file mode 100644 index ba566857b8..0000000000 --- a/explore-analyze/query-filter/languages/sql-limitations.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-limitations.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# SQL Limitations [sql-limitations] - - -## Large queries may throw `ParsingException` [large-parsing-trees] - -Extremely large queries can consume too much memory during the parsing phase, in which case the Elasticsearch 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 Elasticsearch 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: - -```sql -[nested_field_name].[sub_field_name] -``` - -For example: - -```sql -SELECT dep.dep_name.keyword FROM test_emp GROUP BY languages; -``` - - -## Scalar functions on nested fields are not allowed in `WHERE` and `ORDER BY` clauses [_scalar_functions_on_nested_fields_are_not_allowed_in_where_and_order_by_clauses] - -Elasticsearch SQL doesn’t support the usage of scalar functions on top of nested fields in `WHERE` and `ORDER BY` clauses with the exception of comparison and logical operators. - -For example: - -```sql -SELECT * FROM test_emp WHERE LENGTH(dep.dep_name.keyword) > 5; -``` - -and - -```sql -SELECT * FROM test_emp ORDER BY YEAR(dep.start_date); -``` - -are not supported but: - -```sql -SELECT * FROM test_emp WHERE dep.start_date >= CAST('2020-01-01' AS DATE) OR dep.dep_end_date IS NULL; -``` - -is supported. - - -## Multi-nested fields [_multi_nested_fields] - -Elasticsearch 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 - column | type | mapping -----------------------+---------------+------------- -nested_A |STRUCT |NESTED -nested_A.nested_X |STRUCT |NESTED -nested_A.nested_X.text|VARCHAR |KEYWORD -nested_A.text |VARCHAR |KEYWORD -nested_B |STRUCT |NESTED -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, Elasticsearch SQL will display an error message. - - -## Paginating nested inner hits [_paginating_nested_inner_hits] - -When SELECTing a nested field, pagination will not work as expected, Elasticsearch 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 Elasticsearch SQL. - - -## Array type of fields [_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, Elasticsearch SQL cannot know whether a field is a single or multi value. When multiple values are returned for a field, by default, Elasticsearch 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 [_sorting_by_aggregation] - -When doing aggregations (`GROUP BY`) Elasticsearch 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. Elasticsearch 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: - -```sql -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 Elasticsearch 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 functions can be used for ordering. Here are some examples of queries that are **not allowed**: - -```sql -SELECT age, ROUND(AVG(salary)) AS avg FROM test GROUP BY age ORDER BY avg; - -SELECT age, MAX(salary) - MIN(salary) AS diff FROM test GROUP BY age ORDER BY diff; -``` - - -## Using a sub-select [_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 Elasticsearch SQL. For example: - -```sql -SELECT * FROM (SELECT first_name, last_name FROM emp WHERE last_name NOT LIKE '%a%') WHERE first_name LIKE 'A%' ORDER BY 1; - - first_name | last_name ----------------+--------------- - Alejandro |McAlpine - Anneke |Preusig - Anoosh |Peyn - Arumugam |Ossenbruggen -``` - -The query above is possible because it is equivalent with: - -```sql -SELECT first_name, last_name FROM emp WHERE last_name NOT LIKE '%a%' AND first_name LIKE 'A%' ORDER BY 1; -``` - -But, if the sub-select would include a `GROUP BY` or `HAVING` or the enclosing `SELECT` would be more complex than `SELECT X FROM (SELECT ...) WHERE [simple_condition]`, this is currently **un-supported**. - - -## Using [`FIRST`](sql-functions-aggs.md#sql-functions-aggs-first)/[`LAST`](sql-functions-aggs.md#sql-functions-aggs-last) aggregation functions in `HAVING` clause [first-last-agg-functions-having-clause] - -Using `FIRST` and `LAST` in the `HAVING` clause is not supported. The same applies to [`MIN`](sql-functions-aggs.md#sql-functions-aggs-min) and [`MAX`](sql-functions-aggs.md#sql-functions-aggs-max) when their target column is of type [`keyword`](elasticsearch://reference/elasticsearch/mapping-reference/keyword.md) or [`unsigned_long`](elasticsearch://reference/elasticsearch/mapping-reference/number.md) as they are internally translated to `FIRST` and `LAST`. - - -## Using TIME data type in GROUP BY or [`HISTOGRAM`](sql-functions-grouping.md#sql-functions-grouping-histogram) [group-by-time] - -Using `TIME` data type as a grouping key is currently not supported. For example: - -```sql -SELECT count(*) FROM test GROUP BY CAST(date_created AS TIME); -``` - -On the other hand, it can still be used if it’s wrapped with a scalar function that returns another data type, for example: - -```sql -SELECT count(*) FROM test GROUP BY MINUTE((CAST(date_created AS TIME)); -``` - -`TIME` data type is also currently not supported in histogram grouping function. For example: - -```sql -SELECT HISTOGRAM(CAST(birth_date AS TIME), INTERVAL '10' MINUTES) as h, COUNT(*) FROM t GROUP BY h -``` - - -## Geo-related functions [geo-sql-limitations] - -Since `geo_shape` fields don’t have doc values these fields cannot be used for filtering, grouping or sorting. - -By default,`geo_points` fields are indexed and have doc values. However only latitude and longitude are stored and indexed with some loss of precision from the original values (4.190951585769653E-8 for the latitude and 8.381903171539307E-8 for longitude). The altitude component is accepted but not stored in doc values nor indexed. Therefore calling `ST_Z` function in the filtering, grouping or sorting will return `null`. - - -## Retrieving using the `fields` search parameter [using-fields-api] - -Elasticsearch SQL retrieves column values using the [search API’s `fields` parameter](elasticsearch://reference/elasticsearch/rest-apis/retrieve-selected-fields.md#search-fields-param). Any limitations on the `fields` parameter also apply to Elasticsearch 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`](sql-syntax-select.md#sql-syntax-pivot) clause [aggs-in-pivot] - -The aggregation expression in [`PIVOT`](sql-syntax-select.md#sql-syntax-pivot) will currently accept only one aggregation. It is thus not possible to obtain multiple aggregations for any one pivoted column. - - -## Using a subquery in [`PIVOT`](sql-syntax-select.md#sql-syntax-pivot)'s `IN`-subclause [subquery-in-pivot] - -The values that the [`PIVOT`](sql-syntax-select.md#sql-syntax-pivot) query could pivot must be provided in the query as a list of literals; providing a subquery instead to build this list is not currently supported. For example, in this query: - -```sql -SELECT * FROM test_emp PIVOT (SUM(salary) FOR languages IN (1, 2)) -``` - -the `languages` of interest must be listed explicitly: `IN (1, 2)`. On the other hand, this example would **not work**: - -```sql -SELECT * FROM test_emp PIVOT (SUM(salary) FOR languages IN (SELECT languages FROM test_emp WHERE languages <=2 GROUP BY languages)) -``` diff --git a/explore-analyze/query-filter/languages/sql-operators-cast.md b/explore-analyze/query-filter/languages/sql-operators-cast.md deleted file mode 100644 index eb1bd1c683..0000000000 --- a/explore-analyze/query-filter/languages/sql-operators-cast.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-operators-cast.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Cast Operators [sql-operators-cast] - -## `Cast (::)` [sql-operators-cast-cast] - -`::` provides an alternative syntax to the [`CAST`](sql-functions-type-conversion.md#sql-functions-type-conversion-cast) function. - -```sql -SELECT '123'::long AS long; - - long ---------------- -123 -``` - - diff --git a/explore-analyze/query-filter/languages/sql-operators-logical.md b/explore-analyze/query-filter/languages/sql-operators-logical.md deleted file mode 100644 index d9a2930cb0..0000000000 --- a/explore-analyze/query-filter/languages/sql-operators-logical.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-operators-logical.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Logical Operators [sql-operators-logical] - -Boolean operator for evaluating one or two expressions. - -## `AND` [sql-operators-and] - -```sql -SELECT last_name l FROM "test_emp" WHERE emp_no > 10000 AND emp_no < 10005 ORDER BY emp_no LIMIT 5; -``` - - -## `OR` [sql-operators-or] - -```sql -SELECT last_name l FROM "test_emp" WHERE emp_no < 10003 OR emp_no = 10005 ORDER BY emp_no LIMIT 5; -``` - - -## `NOT` [sql-operators-not] - -```sql -SELECT last_name l FROM "test_emp" WHERE NOT emp_no = 10000 LIMIT 5; -``` - - diff --git a/explore-analyze/query-filter/languages/sql-operators-math.md b/explore-analyze/query-filter/languages/sql-operators-math.md deleted file mode 100644 index 15a1dc7aa7..0000000000 --- a/explore-analyze/query-filter/languages/sql-operators-math.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-operators-math.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Math Operators [sql-operators-math] - -Perform mathematical operations affecting one or two values. The result is a value of numeric type. - -## `Add (+)` [sql-operators-plus] - -```sql -SELECT 1 + 1 AS x; -``` - - -## `Subtract (infix -)` [sql-operators-subtract] - -```sql -SELECT 1 - 1 AS x; -``` - - -## `Negate (unary -)` [sql-operators-negate] - -```sql -SELECT - 1 AS x; -``` - - -## `Multiply (*)` [sql-operators-multiply] - -```sql -SELECT 2 * 3 AS x; -``` - - -## `Divide (/)` [sql-operators-divide] - -```sql -SELECT 6 / 3 AS x; -``` - - -## `Modulo or Remainder(%)` [sql-operators-remainder] - -```sql -SELECT 5 % 2 AS x; -``` - - diff --git a/explore-analyze/query-filter/languages/sql-operators.md b/explore-analyze/query-filter/languages/sql-operators.md deleted file mode 100644 index 78006ea233..0000000000 --- a/explore-analyze/query-filter/languages/sql-operators.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-operators.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Comparison Operators [sql-operators] - -Boolean operator for comparing against one or multiple expressions. - -## `Equality (=)` [sql-operators-equality] - -```sql -SELECT last_name l FROM "test_emp" WHERE emp_no = 10000 LIMIT 5; -``` - - -## `Null safe Equality (<=>)` [sql-operators-null-safe-equality] - -```sql -SELECT 'elastic' <=> null AS "equals"; - - equals ---------------- -false -``` - -```sql -SELECT null <=> null AS "equals"; - - equals ---------------- -true -``` - - -## `Inequality (<> or !=)` [sql-operators-inequality] - -```sql -SELECT last_name l FROM "test_emp" WHERE emp_no <> 10000 ORDER BY emp_no LIMIT 5; -``` - - -## `Comparison (<, <=, >, >=)` [sql-operators-comparison] - -```sql -SELECT last_name l FROM "test_emp" WHERE emp_no < 10003 ORDER BY emp_no LIMIT 5; -``` - - -## `BETWEEN` [sql-operators-between] - -```sql -SELECT last_name l FROM "test_emp" WHERE emp_no BETWEEN 9990 AND 10003 ORDER BY emp_no; -``` - - -## `IS NULL/IS NOT NULL` [sql-operators-is-null] - -```sql -SELECT last_name l FROM "test_emp" WHERE emp_no IS NOT NULL AND gender IS NULL; -``` - - -## `IN (, , ...)` [sql-operators-in] - -```sql -SELECT last_name l FROM "test_emp" WHERE emp_no IN (10000, 10001, 10002, 999) ORDER BY emp_no LIMIT 5; -``` - - diff --git a/explore-analyze/query-filter/languages/sql-spec.md b/explore-analyze/query-filter/languages/sql-spec.md deleted file mode 100644 index 03374ae74c..0000000000 --- a/explore-analyze/query-filter/languages/sql-spec.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-spec.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# SQL Language [sql-spec] - -This chapter describes the SQL syntax and semantics supported namely: - -[Lexical Structure](sql-lexical-structure.md) -: Lexical structure - -[SQL Commands](sql-commands.md) -: Commands - -[Data Types](sql-data-types.md) -: Data types - -[Index patterns](sql-index-patterns.md) -: Index patterns - - - - - - - - - - - - diff --git a/explore-analyze/query-filter/languages/sql-syntax-describe-table.md b/explore-analyze/query-filter/languages/sql-syntax-describe-table.md deleted file mode 100644 index 167b9e4501..0000000000 --- a/explore-analyze/query-filter/languages/sql-syntax-describe-table.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-syntax-describe-table.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# DESCRIBE TABLE [sql-syntax-describe-table] - -```sql -DESCRIBE | DESC - [CATALOG identifier]? <1> - [INCLUDE FROZEN]? <2> - [table_identifier | <3> - LIKE pattern] <4> -``` - -1. Catalog (cluster) identifier. Supports wildcards (`*`). -2. Whether or not to include frozen indices. -3. Single table (index or data stream) identifier or double-quoted multi-target pattern. -4. SQL LIKE pattern matching table names. - - -**Description**: `DESC` and `DESCRIBE` are aliases to [SHOW COLUMNS](sql-syntax-show-columns.md). - -```sql -DESCRIBE emp; - - column | type | mapping ---------------------+---------------+--------------- -birth_date |TIMESTAMP |datetime -dep |STRUCT |nested -dep.dep_id |VARCHAR |keyword -dep.dep_name |VARCHAR |text -dep.dep_name.keyword|VARCHAR |keyword -dep.from_date |TIMESTAMP |datetime -dep.to_date |TIMESTAMP |datetime -emp_no |INTEGER |integer -first_name |VARCHAR |text -first_name.keyword |VARCHAR |keyword -gender |VARCHAR |keyword -hire_date |TIMESTAMP |datetime -languages |TINYINT |byte -last_name |VARCHAR |text -last_name.keyword |VARCHAR |keyword -name |VARCHAR |keyword -salary |INTEGER |integer -``` - diff --git a/explore-analyze/query-filter/languages/sql-syntax-reserved.md b/explore-analyze/query-filter/languages/sql-syntax-reserved.md deleted file mode 100644 index 43ac61ac84..0000000000 --- a/explore-analyze/query-filter/languages/sql-syntax-reserved.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-syntax-reserved.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# Reserved keywords [sql-syntax-reserved] - -Table with reserved keywords that need to be quoted. Also provide an example to make it more obvious. - -The following table lists all of the keywords that are reserved in Elasticsearch SQL, along with their status in the SQL standard. These reserved keywords must be quoted (using double quotes) in order to be used as an identifier, for example: - -```sql -SELECT "AS" FROM index -``` - -| Keyword | SQL:2016 | SQL-92 | -| --- | --- | --- | -| `ALL` | reserved | reserved | -| `AND` | reserved | reserved | -| `ANY` | reserved | reserved | -| `AS` | reserved | reserved | -| `ASC` | reserved | reserved | -| `BETWEEN` | reserved | reserved | -| `BY` | reserved | reserved | -| `CAST` | reserved | reserved | -| `CATALOG` | reserved | reserved | -| `CONVERT` | reserved | reserved | -| `CURRENT_DATE` | reserved | reserved | -| `CURRENT_TIMESTAMP` | reserved | reserved | -| `CURRENT_TIME` | reserved | reserved | -| `DAY` | reserved | reserved | -| `DAYS` | | | -| `DESC` | reserved | reserved | -| `DESCRIBE` | reserved | reserved | -| `DISTINCT` | reserved | reserved | -| `ESCAPE` | reserved | reserved | -| `EXISTS` | reserved | reserved | -| `EXPLAIN` | reserved | reserved | -| `EXTRACT` | reserved | reserved | -| `FALSE` | reserved | reserved | -| `FIRST` | reserved | reserved | -| `FROM` | reserved | reserved | -| `FULL` | reserved | reserved | -| `GROUP` | reserved | reserved | -| `HAVING` | reserved | reserved | -| `HOUR` | reserved | reserved | -| `HOURS` | | | -| `IN` | reserved | reserved | -| `INNER` | reserved | reserved | -| `INTERVAL` | reserved | reserved | -| `IS` | reserved | reserved | -| `JOIN` | reserved | reserved | -| `LEFT` | reserved | reserved | -| `LIKE` | reserved | reserved | -| `LIMIT` | reserved | reserved | -| `MATCH` | reserved | reserved | -| `MINUTE` | reserved | reserved | -| `MINUTES` | | | -| `MONTH` | reserved | reserved | -| `NATURAL` | reserved | reserved | -| `NOT` | reserved | reserved | -| `NULL` | reserved | reserved | -| `NULLS` | | | -| `ON` | reserved | reserved | -| `OR` | reserved | reserved | -| `ORDER` | reserved | reserved | -| `OUTER` | reserved | reserved | -| `RIGHT` | reserved | reserved | -| `RLIKE` | | | -| `QUERY` | | | -| `SECOND` | reserved | reserved | -| `SECONDS` | | | -| `SELECT` | reserved | reserved | -| `SESSION` | | reserved | -| `TABLE` | reserved | reserved | -| `TABLES` | | | -| `THEN` | reserved | reserved | -| `TO` | reserved | reserved | -| `TOP` | reserved | reserved | -| `TRUE` | reserved | reserved | -| `TYPE` | | | -| `USING` | reserved | reserved | -| `WHEN` | reserved | reserved | -| `WHERE` | reserved | reserved | -| `WITH` | reserved | reserved | -| `YEAR` | reserved | reserved | -| `YEARS` | | | - diff --git a/explore-analyze/query-filter/languages/sql-syntax-select.md b/explore-analyze/query-filter/languages/sql-syntax-select.md deleted file mode 100644 index 61fa96095d..0000000000 --- a/explore-analyze/query-filter/languages/sql-syntax-select.md +++ /dev/null @@ -1,650 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-syntax-select.html -applies_to: - stack: ga - serverless: ga -products: - - id: elasticsearch ---- - -# SELECT [sql-syntax-select] - -```sql -SELECT [TOP [ count ] ] select_expr [, ...] -[ FROM table_name ] -[ WHERE condition ] -[ GROUP BY grouping_element [, ...] ] -[ HAVING condition] -[ ORDER BY expression [ ASC | DESC ] [, ...] ] -[ LIMIT [ count ] ] -[ PIVOT ( aggregation_expr FOR column IN ( value [ [ AS ] alias ] [, ...] ) ) ] -``` - -**Description**: Retrieves rows from zero or more tables. - -The general execution of `SELECT` is as follows: - -1. All elements in the `FROM` list are computed (each element can be base or alias table). Currently `FROM` supports exactly one table. Do note however that the table name can be a pattern (see [FROM Clause](#sql-syntax-from) below). -2. If the `WHERE` clause is specified, all rows that do not satisfy the condition are eliminated from the output. (See [WHERE Clause](#sql-syntax-where) below.) -3. If the `GROUP BY` clause is specified, or if there are aggregate function calls, the output is combined into groups of rows that match on one or more values, and the results of aggregate functions are computed. If the `HAVING` clause is present, it eliminates groups that do not satisfy the given condition. (See [GROUP BY Clause](#sql-syntax-group-by) and [HAVING Clause](#sql-syntax-having) below.) -4. The actual output rows are computed using the `SELECT` output expressions for each selected row or row group. -5. If the `ORDER BY` clause is specified, the returned rows are sorted in the specified order. If `ORDER BY` is not given, the rows are returned in whatever order the system finds fastest to produce. (See [ORDER BY Clause](#sql-syntax-order-by) below.) -6. If the `LIMIT` or `TOP` is specified (cannot use both in the same query), the `SELECT` statement only returns a subset of the result rows. (See [LIMIT Clause](#sql-syntax-limit) and [TOP clause](#sql-syntax-top) below.) - -## `SELECT` List [sql-syntax-select-list] - -`SELECT` list, namely the expressions between `SELECT` and `FROM`, represent the output rows of the `SELECT` statement. - -As with a table, every output column of a `SELECT` has a name which can be either specified per column through the `AS` keyword : - -```sql -SELECT 1 + 1 AS result; - - result ---------------- -2 -``` - -Note: `AS` is an optional keyword however it helps with the readability and in some case ambiguity of the query which is why it is recommended to specify it. - -assigned by Elasticsearch SQL if no name is given: - -```sql -SELECT 1 + 1; - - 1 + 1 --------------- -2 -``` - -or if it’s a simple column reference, use its name as the column name: - -```sql -SELECT emp_no FROM emp LIMIT 1; - - emp_no ---------------- -10001 -``` - - -## Wildcard [sql-syntax-select-wildcard] - -To select all the columns in the source, one can use `*`: - -```sql -SELECT * FROM emp LIMIT 1; - - birth_date | emp_no | first_name | gender | hire_date | languages | last_name | name | salary ---------------------+---------------+---------------+---------------+------------------------+---------------+---------------+---------------+--------------- -1953-09-02T00:00:00Z|10001 |Georgi |M |1986-06-26T00:00:00.000Z|2 |Facello |Georgi Facello |57305 -``` - -which essentially returns all(top-level fields, sub-fields, such as multi-fields are ignored] columns found. - - -## TOP [sql-syntax-top] - -The `TOP` clause can be used before the [`SELECT` list](#sql-syntax-select-list) or the < to restrict (limit) the number of rows returned using the format: - -```sql -SELECT TOP