honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
OpenSearch/docs/reference/sql/functions/index.asciidoc

171 lines
5.4 KiB
Plaintext
Raw Normal View History

[DOCS] Move sql to docs (#31474)
2018-06-22 18:40:25 -04:00
[role="xpack"]
[testenv="basic"]
Revert "Revert "Merge branch 'feature/sql'"" This reverts commit elastic/x-pack-elasticsearch@cc79e199112db85b08a6e0682b123bb2a82445e8. We'll merge this when we're good and ready. Original commit: elastic/x-pack-elasticsearch@b3ef4f2836eda281bce7c3c2c1730933d868efa9
2017-12-13 10:19:31 -05:00
[[sql-functions]]
== Functions and Operators
DOC: Enhance SQL Functions documentation Split function section into multiple chapters Add String functions Add (small) section on Conversion/Cast functions Add missing aggregation functions Enable documentation testing (was disabled by accident). While at it, fix failing tests Improve spec tests to allow multi-line queries (useful for docs) Add ability to ignore a spec test (name should end with -Ignore)
2018-09-05 18:19:49 -04:00
{es-sql} provides a comprehensive set of built-in operators and functions:
* <<sql-operators, Operators>>
SQL: Documentation for LIKE and RLIKE operators (#40623) (cherry picked from commit 9536c5f7b7fecda4592f6b169adef180eadbba54)
2019-04-01 11:01:03 -04:00
** <<sql-operators-equality>>
** <<sql-operators-null-safe-equality>>
** <<sql-operators-inequality>>
** <<sql-operators-comparison>>
** <<sql-operators-between>>
** <<sql-operators-is-null>>
** <<sql-operators-in>>
** <<sql-operators-and>>
** <<sql-operators-or>>
** <<sql-operators-not>>
** <<sql-operators-plus>>
** <<sql-operators-subtract>>
** <<sql-operators-negate>>
** <<sql-operators-multiply>>
** <<sql-operators-divide>>
** <<sql-operators-remainder>>
** <<sql-operators-cast-cast>>
* <<sql-like-rlike-operators>>
** <<sql-like-operator>>
** <<sql-rlike-operator>>
* <<sql-functions-aggs>>
Include functions' aliases in the list of functions (#40584) (cherry picked from commit 4034f8f31616353d2f5d09a90753d75e2870ee18)
2019-03-28 08:28:07 -04:00
** <<sql-functions-aggs-avg>>
** <<sql-functions-aggs-count>>
** <<sql-functions-aggs-count-all>>
** <<sql-functions-aggs-count-distinct>>
** <<sql-functions-aggs-first>>
** <<sql-functions-aggs-last>>
** <<sql-functions-aggs-max>>
** <<sql-functions-aggs-min>>
** <<sql-functions-aggs-sum>>
** <<sql-functions-aggs-kurtosis>>
** <<sql-functions-aggs-mad>>
** <<sql-functions-aggs-percentile>>
** <<sql-functions-aggs-percentile-rank>>
** <<sql-functions-aggs-skewness>>
** <<sql-functions-aggs-stddev-pop>>
** <<sql-functions-aggs-sum-squares>>
** <<sql-functions-aggs-var-pop>>
SQL: Documentation for LIKE and RLIKE operators (#40623) (cherry picked from commit 9536c5f7b7fecda4592f6b169adef180eadbba54)
2019-04-01 11:01:03 -04:00
* <<sql-functions-grouping>>
Include functions' aliases in the list of functions (#40584) (cherry picked from commit 4034f8f31616353d2f5d09a90753d75e2870ee18)
2019-03-28 08:28:07 -04:00
** <<sql-functions-grouping-histogram>>
SQL: Documentation for LIKE and RLIKE operators (#40623) (cherry picked from commit 9536c5f7b7fecda4592f6b169adef180eadbba54)
2019-04-01 11:01:03 -04:00
* <<sql-functions-datetime-interval, Date-Time Operators>>
* <<sql-functions-current-date, Date-Time Functions>>
Include functions' aliases in the list of functions (#40584) (cherry picked from commit 4034f8f31616353d2f5d09a90753d75e2870ee18)
2019-03-28 08:28:07 -04:00
** <<sql-functions-current-date>>
SQL: Implement CURRENT_TIME/CURTIME functions (#40662) After `TIME` SQL data type is introduced, implement `CURRENT_TIME/CURTIME` functions similarly to CURRENT_TIMESTAMP that return the system's current time (only, without the date part). Closes: #40468 (cherry picked from commit 9feede781409d0e264ce45951a25b28ff129b187)
2019-04-03 13:35:37 -04:00
** <<sql-functions-current-time>>
Include functions' aliases in the list of functions (#40584) (cherry picked from commit 4034f8f31616353d2f5d09a90753d75e2870ee18)
2019-03-28 08:28:07 -04:00
** <<sql-functions-current-timestamp>>
SQL: Implement DATEADD function (#47747) Implement DATEADD/TIMESTAMPADD function as per the MS-SQL spec: https://docs.microsoft.com/en-us/sql/t-sql/functions/dateadd-transact-sql?view=sql-server-2017 which allows a user to add/subtract specified number of specified units to/from a date/datetime field/expression. Closes: #47746 (cherry picked from commit e624bc281bebb4bbe0b0c2e0a8cbc712e50097a8)
2019-10-10 09:24:36 -04:00
** <<sql-functions-datetime-add>>
SQL: Implement DATEDIFF function (#47920) Implement DATEDIFF/TIMESTAMPDIFF function as per the MS-SQL spec: https://docs.microsoft.com/en-us/sql/t-sql/functions/datediff-transact-sql?view=sql-server-2017 which allows a user to substract two date/datetime fields and return the difference in the date/time unit specified. Closes: #47919 (cherry picked from commit 745699f38dc8222670ffd65b66df33b5da39040b)
2019-10-15 08:42:20 -04:00
** <<sql-functions-datetime-diff>>
SQL: Implement DATETIME_FORMAT function for date/time formatting (#54832) (#54942) Implement DATETIME_FORMAT(<date/datetime/time>, ) function which allows for formatting a timestamp to the specified format. The patterns allowed as those of java.time.format.DateTimeFormatter. Related to #53714 (cherry picked from commit 72be0b54a9299e87e785469cdc9aafac2a48c046)
2020-04-08 07:45:47 -04:00
** <<sql-functions-datetime-datetimeformat>>
SQL: Implement DATETIME_PARSE function for parsing strings (#54960) (#55035) Implement DATETIME_PARSE(<datetime_str>, <pattern_str>) function which allows to parse a datetime string according to the specified pattern into a datetime object. The patterns allowed are those of java.time.format.DateTimeFormatter. Relates to #53714 (cherry picked from commit 3febcd8f3cdf9fdda4faf01f23a5f139f38b57e0)
2020-04-09 19:16:29 -04:00
** <<sql-functions-datetime-datetimeparse>>
SQL: Implement TIME_PARSE function for parsing strings into TIME values (#55223) (#57342) Implement TIME_PARSE(<time_str>, <pattern_str>) function which allows to parse a time string according to the specified pattern into a time object. The patterns allowed are those of java.time.format.DateTimeFormatter. Closes #54963 Co-authored-by: Andrei Stefan <astefan@users.noreply.github.com> Co-authored-by: Patrick Jiang(白泽) <patrickjiang0530@gmail.com> (cherry picked from commit 1fe1188d449cad7d0782a202372edc52a4014135)
2020-05-29 09:48:37 -04:00
** <<sql-functions-datetime-timeparse>>
SQL: Implement DATE_PART function (#47206) DATE_PART(<datetime unit>, <date/datetime>) is a function that allows the user to extract the specified unit from a date/datetime field similar to the EXTRACT (<datetime unit> FROM <date/datetime>) but with different names and aliases for the units and it also provides more options like `DATE_PART('tzoffset', datetimeField)`. Implemented following the SQL server's spec: https://docs.microsoft.com/en-us/sql/t-sql/functions/datepart-transact-sql?view=sql-server-2017 with the difference that the <datetime unit> argument is either a literal single quoted string or gets a value from a table field, whereas in SQL server keywords are used (unquoted identifiers) and it's not possible to use a value coming for a table column. Closes: #46372 (cherry picked from commit ead743d3579eb753fd314d4a58fae205e465d72e)
2019-10-01 08:59:25 -04:00
** <<sql-functions-datetime-part>>
SQL: Implement DATE_TRUNC function (#46473) DATE_TRUNC(<truncate field>, <date/datetime>) is a function that allows the user to truncate a timestamp to the specified field by zeroing out the rest of the fields. The function is implemented according to the spec from PostgreSQL: https://www.postgresql.org/docs/current/functions-datetime.html#FUNCTIONS-DATETIME-TRUNC Closes: #46319 (cherry picked from commit b37e96712db1aace09f17b574eb02ff6b942a297)
2019-09-11 14:09:40 -04:00
** <<sql-functions-datetime-trunc>>
Include functions' aliases in the list of functions (#40584) (cherry picked from commit 4034f8f31616353d2f5d09a90753d75e2870ee18)
2019-03-28 08:28:07 -04:00
** <<sql-functions-datetime-day>>
** <<sql-functions-datetime-dow>>
** <<sql-functions-datetime-doy>>
** <<sql-functions-datetime-dayname>>
** <<sql-functions-datetime-hour>>
** <<sql-functions-datetime-isodow>>
** <<sql-functions-datetime-isoweek>>
** <<sql-functions-datetime-minuteofday>>
** <<sql-functions-datetime-minute>>
** <<sql-functions-datetime-month>>
** <<sql-functions-datetime-monthname>>
** <<sql-functions-now>>
** <<sql-functions-datetime-second>>
** <<sql-functions-datetime-quarter>>
** <<sql-functions-today>>
** <<sql-functions-datetime-week>>
** <<sql-functions-datetime-year>>
** <<sql-functions-datetime-extract>>
SQL: Documentation for LIKE and RLIKE operators (#40623) (cherry picked from commit 9536c5f7b7fecda4592f6b169adef180eadbba54)
2019-04-01 11:01:03 -04:00
* <<sql-functions-search>>
Include functions' aliases in the list of functions (#40584) (cherry picked from commit 4034f8f31616353d2f5d09a90753d75e2870ee18)
2019-03-28 08:28:07 -04:00
** <<sql-functions-search-match>>
** <<sql-functions-search-query>>
** <<sql-functions-search-score>>
SQL: Documentation for LIKE and RLIKE operators (#40623) (cherry picked from commit 9536c5f7b7fecda4592f6b169adef180eadbba54)
2019-04-01 11:01:03 -04:00
* <<sql-functions-math>>
Include functions' aliases in the list of functions (#40584) (cherry picked from commit 4034f8f31616353d2f5d09a90753d75e2870ee18)
2019-03-28 08:28:07 -04:00
** <<sql-functions-math-abs>>
** <<sql-functions-math-cbrt>>
** <<sql-functions-math-ceil>>
** <<sql-functions-math-e>>
** <<sql-functions-math-exp>>
** <<sql-functions-math-expm1>>
** <<sql-functions-math-floor>>
** <<sql-functions-math-log>>
** <<sql-functions-math-log10>>
** <<sql-functions-math-pi>>
** <<sql-functions-math-power>>
SQL: Implement TIME_PARSE function for parsing strings into TIME values (#55223) (#57342) Implement TIME_PARSE(<time_str>, <pattern_str>) function which allows to parse a time string according to the specified pattern into a time object. The patterns allowed are those of java.time.format.DateTimeFormatter. Closes #54963 Co-authored-by: Andrei Stefan <astefan@users.noreply.github.com> Co-authored-by: Patrick Jiang(白泽) <patrickjiang0530@gmail.com> (cherry picked from commit 1fe1188d449cad7d0782a202372edc52a4014135)
2020-05-29 09:48:37 -04:00
** <<sql-functions-math-random>>
Include functions' aliases in the list of functions (#40584) (cherry picked from commit 4034f8f31616353d2f5d09a90753d75e2870ee18)
2019-03-28 08:28:07 -04:00
** <<sql-functions-math-round>>
** <<sql-functions-math-sign>>
** <<sql-functions-math-sqrt>>
** <<sql-functions-math-truncate>>
** <<sql-functions-math-acos>>
** <<sql-functions-math-asin>>
** <<sql-functions-math-atan>>
** <<sql-functions-math-atan2>>
** <<sql-functions-math-cos>>
** <<sql-functions-math-cosh>>
** <<sql-functions-math-cot>>
** <<sql-functions-math-degrees>>
** <<sql-functions-math-radians>>
** <<sql-functions-math-sin>>
** <<sql-functions-math-sinh>>
** <<sql-functions-math-tan>>
SQL: Documentation for LIKE and RLIKE operators (#40623) (cherry picked from commit 9536c5f7b7fecda4592f6b169adef180eadbba54)
2019-04-01 11:01:03 -04:00
* <<sql-functions-string>>
Include functions' aliases in the list of functions (#40584) (cherry picked from commit 4034f8f31616353d2f5d09a90753d75e2870ee18)
2019-03-28 08:28:07 -04:00
** <<sql-functions-string-ascii>>
** <<sql-functions-string-bit-length>>
** <<sql-functions-string-char>>
** <<sql-functions-string-char-length>>
** <<sql-functions-string-concat>>
** <<sql-functions-string-insert>>
** <<sql-functions-string-lcase>>
** <<sql-functions-string-left>>
** <<sql-functions-string-length>>
** <<sql-functions-string-locate>>
** <<sql-functions-string-ltrim>>
** <<sql-functions-string-octet-length>>
** <<sql-functions-string-position>>
** <<sql-functions-string-repeat>>
** <<sql-functions-string-replace>>
** <<sql-functions-string-right>>
** <<sql-functions-string-rtrim>>
** <<sql-functions-string-space>>
** <<sql-functions-string-substring>>
SQL: Implement TRIM function (#57518) (#57593) Add `TRIM` function which combines the functionality of both `LTRIM` and `RTRIM` by stripping both leading and trailing whitespaces. Refers to #41195 (cherry picked from commit 6c86c919e12f0c4cb5e39d129aa65ab3e274268f)
2020-06-03 09:19:48 -04:00
** <<sql-functions-string-trim>>
Include functions' aliases in the list of functions (#40584) (cherry picked from commit 4034f8f31616353d2f5d09a90753d75e2870ee18)
2019-03-28 08:28:07 -04:00
** <<sql-functions-string-ucase>>
SQL: Documentation for LIKE and RLIKE operators (#40623) (cherry picked from commit 9536c5f7b7fecda4592f6b169adef180eadbba54)
2019-04-01 11:01:03 -04:00
* <<sql-functions-type-conversion>>
Include functions' aliases in the list of functions (#40584) (cherry picked from commit 4034f8f31616353d2f5d09a90753d75e2870ee18)
2019-03-28 08:28:07 -04:00
** <<sql-functions-type-conversion-cast>>
** <<sql-functions-type-conversion-convert>>
SQL: Documentation for LIKE and RLIKE operators (#40623) (cherry picked from commit 9536c5f7b7fecda4592f6b169adef180eadbba54)
2019-04-01 11:01:03 -04:00
* <<sql-functions-conditional>>
SQL: Implement CASE... WHEN... THEN... ELSE... END (#41349) Implement the ANSI SQL CASE expression which provides the if/else functionality common to most programming languages. The CASE expression can have multiple WHEN branches and becomes a powerful tool for SQL queries as it can be used in SELECT, WHERE, GROUP BY, HAVING and ORDER BY clauses. Closes: #36200 (cherry picked from commit 8b2577406f47ae60d15803058921d128390af0b6)
2019-04-22 12:26:15 -04:00
** <<sql-functions-conditional-case>>
Include functions' aliases in the list of functions (#40584) (cherry picked from commit 4034f8f31616353d2f5d09a90753d75e2870ee18)
2019-03-28 08:28:07 -04:00
** <<sql-functions-conditional-coalesce>>
** <<sql-functions-conditional-greatest>>
** <<sql-functions-conditional-ifnull>>
SQL: Implement IIF(<cond>, <result1>, <result2>) (#41420) Implement a more trivial case of the CASE expression which is expressed as a traditional function with 2 or 3 arguments. e.g.: IIF(a = 1, 'one', 'many') IIF(a > 0, 'positive') Closes: #40917 (cherry picked from commit add02f4f553ad472026dcc1eaa84245a0558a4b0)
2019-04-23 09:30:37 -04:00
** <<sql-functions-conditional-iif>>
Include functions' aliases in the list of functions (#40584) (cherry picked from commit 4034f8f31616353d2f5d09a90753d75e2870ee18)
2019-03-28 08:28:07 -04:00
** <<sql-functions-conditional-isnull>>
** <<sql-functions-conditional-least>>
** <<sql-functions-conditional-nullif>>
** <<sql-functions-conditional-nvl>>
SQL: Add initial geo support (#42031) (#42135) Adds an initial limited implementations of geo features to SQL. This implementation is based on the [OpenGIS® Implementation Standard for Geographic information - Simple feature access](http://www.opengeospatial.org/standards/sfs), which is the current standard for GIS system implementation. This effort is concentrate on SQL option AKA ISO 19125-2. Queries that are supported as a result of this initial implementation Metadata commands - `DESCRIBE table` - returns the correct column types `GEOMETRY` for geo shapes and geo points. - `SHOW FUNCTIONS` - returns a list that includes supported `ST_` functions - `SYS TYPES` and `SYS COLUMNS` display correct types `GEO_SHAPE` and `GEO_POINT` for geo shapes and geo points accordingly. Returning geoshapes and geopoints from elasticsearch - `SELECT geom FROM table` - returns the geoshapes and geo_points as libs/geo objects in JDBC or as WKT strings in console. - `SELECT ST_AsWKT(geom) FROM table;` and `SELECT ST_AsText(geom) FROM table;`- returns the geoshapes ang geopoints in their WKT representation; Using geopoints to elasticsearch - The following functions will be supported for geopoints in queries, sorting and aggregations: `ST_GeomFromText`, `ST_X`, `ST_Y`, `ST_Z`, `ST_GeometryType`, and `ST_Distance`. In most cases when used in queries, sorting and aggregations, these function are translated into script. These functions can be used in the SELECT clause for both geopoints and geoshapes. - `SELECT * FROM table WHERE ST_Distance(ST_GeomFromText(POINT(1 2), point) < 10;` - returns all records for which `point` is located within 10m from the `POINT(1 2)`. In this case the WHERE clause is translated into a range query. Limitations: Geoshapes cannot be used in queries, sorting and aggregations as part of this initial effort. In order to fully take advantage of geoshapes we would need to have access to geoshape doc values, which is coming in #37206. `ST_Z` cannot be used on geopoints in queries, sorting and aggregations since we don't store altitude in geo_point doc values. Relates to #29872 Backport of #42031
2019-05-14 19:57:12 -04:00
* <<sql-functions-geo>>
** <<sql-functions-geo-st-as-wkt>>
** <<sql-functions-geo-st-distance>>
** <<sql-functions-geo-st-geometrytype>>
** <<sql-functions-geo-st-wkt-to-sql>>
** <<sql-functions-geo-st-x>>
** <<sql-functions-geo-st-y>>
** <<sql-functions-geo-st-z>>
SQL: Documentation for LIKE and RLIKE operators (#40623) (cherry picked from commit 9536c5f7b7fecda4592f6b169adef180eadbba54)
2019-04-01 11:01:03 -04:00
* <<sql-functions-system>>
Include functions' aliases in the list of functions (#40584) (cherry picked from commit 4034f8f31616353d2f5d09a90753d75e2870ee18)
2019-03-28 08:28:07 -04:00
** <<sql-functions-system-database>>
** <<sql-functions-system-user>>
DOC: Enhance SQL Functions documentation Split function section into multiple chapters Add String functions Add (small) section on Conversion/Cast functions Add missing aggregation functions Enable documentation testing (was disabled by accident). While at it, fix failing tests Improve spec tests to allow multi-line queries (useful for docs) Add ability to ignore a spec test (name should end with -Ignore)
2018-09-05 18:19:49 -04:00
include::operators.asciidoc[]
SQL: Documentation for LIKE and RLIKE operators (#40623) (cherry picked from commit 9536c5f7b7fecda4592f6b169adef180eadbba54)
2019-04-01 11:01:03 -04:00
include::like-rlike.asciidoc[]
DOC: Enhance SQL Functions documentation Split function section into multiple chapters Add String functions Add (small) section on Conversion/Cast functions Add missing aggregation functions Enable documentation testing (was disabled by accident). While at it, fix failing tests Improve spec tests to allow multi-line queries (useful for docs) Add ability to ignore a spec test (name should end with -Ignore)
2018-09-05 18:19:49 -04:00
include::aggs.asciidoc[]
SQL: Introduce HISTOGRAM grouping function (#36510) Introduce Histogram grouping function for bucketing/grouping data based on a given range. Both date and numeric histograms are supported using the appropriate range declaration (numbers vs intervals). SELECT HISTOGRAM(number, 50) AS h FROM index GROUP BY h SELECT HISTOGRAM(date, INTERVAL 1 YEAR) AS h FROM index GROUP BY h In addition add multiply operator for Intervals Add docs for intervals and histogram Fix #36509
2018-12-14 11:20:37 -05:00
include::grouping.asciidoc[]
DOC: Enhance SQL Functions documentation Split function section into multiple chapters Add String functions Add (small) section on Conversion/Cast functions Add missing aggregation functions Enable documentation testing (was disabled by accident). While at it, fix failing tests Improve spec tests to allow multi-line queries (useful for docs) Add ability to ignore a spec test (name should end with -Ignore)
2018-09-05 18:19:49 -04:00
include::date-time.asciidoc[]
include::search.asciidoc[]
include::math.asciidoc[]
include::string.asciidoc[]
include::type-conversion.asciidoc[]
SQL: Add initial geo support (#42031) (#42135) Adds an initial limited implementations of geo features to SQL. This implementation is based on the [OpenGIS® Implementation Standard for Geographic information - Simple feature access](http://www.opengeospatial.org/standards/sfs), which is the current standard for GIS system implementation. This effort is concentrate on SQL option AKA ISO 19125-2. Queries that are supported as a result of this initial implementation Metadata commands - `DESCRIBE table` - returns the correct column types `GEOMETRY` for geo shapes and geo points. - `SHOW FUNCTIONS` - returns a list that includes supported `ST_` functions - `SYS TYPES` and `SYS COLUMNS` display correct types `GEO_SHAPE` and `GEO_POINT` for geo shapes and geo points accordingly. Returning geoshapes and geopoints from elasticsearch - `SELECT geom FROM table` - returns the geoshapes and geo_points as libs/geo objects in JDBC or as WKT strings in console. - `SELECT ST_AsWKT(geom) FROM table;` and `SELECT ST_AsText(geom) FROM table;`- returns the geoshapes ang geopoints in their WKT representation; Using geopoints to elasticsearch - The following functions will be supported for geopoints in queries, sorting and aggregations: `ST_GeomFromText`, `ST_X`, `ST_Y`, `ST_Z`, `ST_GeometryType`, and `ST_Distance`. In most cases when used in queries, sorting and aggregations, these function are translated into script. These functions can be used in the SELECT clause for both geopoints and geoshapes. - `SELECT * FROM table WHERE ST_Distance(ST_GeomFromText(POINT(1 2), point) < 10;` - returns all records for which `point` is located within 10m from the `POINT(1 2)`. In this case the WHERE clause is translated into a range query. Limitations: Geoshapes cannot be used in queries, sorting and aggregations as part of this initial effort. In order to fully take advantage of geoshapes we would need to have access to geoshape doc values, which is coming in #37206. `ST_Z` cannot be used on geopoints in queries, sorting and aggregations since we don't store altitude in geo_point doc values. Relates to #29872 Backport of #42031
2019-05-14 19:57:12 -04:00
include::geo.asciidoc[]
SQL: [docs] Add documentation for COALESCE (#35740) Follows: #35253
2018-11-20 19:43:05 -05:00
include::conditional.asciidoc[]
SQL: DATABASE() and USER() system functions (#35946)
2018-11-28 08:20:04 -05:00
include::system.asciidoc[]