honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

SQL: documentation improvements and updates (#36918) 

* Added Limitations page
* Made the aggregations page follow the common template for functions
* Modified all tables to have the first row's cells content centered
* Polishing in other various sections
This commit is contained in:
Andrei Stefan 2018-12-21 23:25:54 +02:00 committed by GitHub
parent 33e9cf3892
commit 09fa827adc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
19 changed files with 421 additions and 140 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/reference/sql/appendix/syntax-reserved.asciidoc
View File

@ -16,11 +16,13 @@ be quoted (using double quotes) in order to be used as an identifier, for exampl
SELECT "AS" FROM index SELECT "AS" FROM index
---- ----
[cols="^,^,^",options="header"] [cols="^,^,^"]
|=== |===
|Keyword |SQL:2016 |SQL-92 s|Keyword
s|SQL:2016
s|SQL-92
|`ALL` |reserved |reserved |`ALL` |reserved |reserved

2
docs/reference/sql/concepts.asciidoc
View File

@ -15,6 +15,8 @@ Last but not least, {es-sql} tries to obey the https://en.wikipedia.org/wiki/Pri
=== Mapping concepts across SQL and {es} === Mapping concepts across SQL and {es}
beta[]
While SQL and {es} have different terms for the way the data is organized (and different semantics), essentially their purpose is the same. While SQL and {es} have different terms for the way the data is organized (and different semantics), essentially their purpose is the same.
So let's start from the bottom; these roughly are: So let's start from the bottom; these roughly are:

4
docs/reference/sql/endpoints/client-apps/squirrel.asciidoc
View File

@ -1,13 +1,13 @@
[role="xpack"] [role="xpack"]
[testenv="platinum"] [testenv="platinum"]
[[sql-client-apps-squirrel]] [[sql-client-apps-squirrel]]
=== SQquirelL SQL === SQuirreL SQL
beta[] beta[]
[quote, http://squirrel-sql.sourceforge.net/] [quote, http://squirrel-sql.sourceforge.net/]
____ ____
http://squirrel-sql.sourceforge.net/[SQuirelL SQL] is a graphical, [multi-platform] Java program that will allow you to view the structure of a JDBC compliant database [...]. http://squirrel-sql.sourceforge.net/[SQuirreL SQL] is a graphical, [multi-platform] Java program that will allow you to view the structure of a JDBC compliant database [...].
____ ____
==== Prerequisites ==== Prerequisites

2
docs/reference/sql/endpoints/jdbc.asciidoc
View File

@ -138,6 +138,8 @@ Opens up a {es-sql} connection to `server` on port `3456`, setting the JDBC conn
=== API usage === API usage
beta[]
One can use JDBC through the official `java.sql` and `javax.sql` packages: One can use JDBC through the official `java.sql` and `javax.sql` packages:
==== `java.sql` ==== `java.sql`

289
docs/reference/sql/functions/aggs.asciidoc
View File

@ -13,158 +13,317 @@ Functions for computing a _single_ result from a set of input values.
[[sql-functions-aggs-avg]] [[sql-functions-aggs-avg]]
===== `AVG` ===== `AVG`
*Input*: Numeric, *Output*: `double` .Synopsis:
[source, sql]
--------------------------------------------------
AVG(numeric_field<1>)
--------------------------------------------------
https://en.wikipedia.org/wiki/Arithmetic_mean[Average] (arithmetic mean) of input values. *Input*:
<1> numeric field
["source","sql",subs="attributes,callouts,macros"] *Output*: `double` numeric value
----
.Description:
Returns the https://en.wikipedia.org/wiki/Arithmetic_mean[Average] (arithmetic mean) of input values.
["source","sql",subs="attributes,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/docs.csv-spec[aggAvg] include-tagged::{sql-specs}/docs.csv-spec[aggAvg]
---- --------------------------------------------------
[[sql-functions-aggs-count]] [[sql-functions-aggs-count]]
===== `COUNT` ===== `COUNT`
*Input*: Any, *Output*: `bigint` .Synopsis:
[source, sql]
--------------------------------------------------
COUNT(expression<1>)
--------------------------------------------------
Total number (count) of input values. *Input*:
["source","sql",subs="attributes,callouts,macros"] <1> a field name, wildcard (`*`) or any numeric value
----
*Output*: numeric value
.Description:
Returns the total number (count) of input values.
["source","sql",subs="attributes,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/docs.csv-spec[aggCountStar] include-tagged::{sql-specs}/docs.csv-spec[aggCountStar]
---- --------------------------------------------------
[[sql-functions-aggs-count-distinct]] [[sql-functions-aggs-count-distinct]]
===== `COUNT(DISTINCT)` ===== `COUNT(DISTINCT)`
*Input*: Any, *Output*: `bigint` .Synopsis:
[source, sql]
--------------------------------------------------
COUNT(DISTINCT field_name<1>)
--------------------------------------------------
Total number of _distinct_ values in input values. *Input*:
["source","sql",subs="attributes,callouts,macros"] <1> a field name
----
*Output*: numeric value
.Description:
Returns the total number of _distinct_ values in input values.
["source","sql",subs="attributes,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/docs.csv-spec[aggCountDistinct] include-tagged::{sql-specs}/docs.csv-spec[aggCountDistinct]
---- --------------------------------------------------
[[sql-functions-aggs-max]] [[sql-functions-aggs-max]]
===== `MAX` ===== `MAX`
*Input*: Numeric, *Output*: Same as input .Synopsis:
[source, sql]
--------------------------------------------------
MAX(field_name<1>)
--------------------------------------------------
Maximum value across input values. *Input*:
["source","sql",subs="attributes,callouts,macros"] <1> a numeric field
----
*Output*: same type as the input
.Description:
Returns the maximum value across input values in the field `field_name`.
["source","sql",subs="attributes,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/docs.csv-spec[aggMax] include-tagged::{sql-specs}/docs.csv-spec[aggMax]
---- --------------------------------------------------
[[sql-functions-aggs-min]] [[sql-functions-aggs-min]]
===== `MIN` ===== `MIN`
*Input*: Numeric, *Output*: Same as input .Synopsis:
[source, sql]
--------------------------------------------------
MIN(field_name<1>)
--------------------------------------------------
Minimum value across input values. *Input*:
["source","sql",subs="attributes,callouts,macros"] <1> a numeric field
----
*Output*: same type as the input
.Description:
Returns the minimum value across input values in the field `field_name`.
["source","sql",subs="attributes,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/docs.csv-spec[aggMin] include-tagged::{sql-specs}/docs.csv-spec[aggMin]
---- --------------------------------------------------
[[sql-functions-aggs-sum]] [[sql-functions-aggs-sum]]
===== `SUM` ===== `SUM`
*Input*: Numeric, *Output*: `bigint` for integer input, `double` for floating points .Synopsis:
[source, sql]
--------------------------------------------------
SUM(field_name<1>)
--------------------------------------------------
Sum of input values. *Input*:
["source","sql",subs="attributes,callouts,macros"] <1> a numeric field
----
*Output*: `bigint` for integer input, `double` for floating points
.Description:
Returns the sum of input values in the field `field_name`.
["source","sql",subs="attributes,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/docs.csv-spec[aggSum] include-tagged::{sql-specs}/docs.csv-spec[aggSum]
---- --------------------------------------------------
==== Statistics ==== Statistics
[[sql-functions-aggs-kurtosis]] [[sql-functions-aggs-kurtosis]]
===== `KURTOSIS` ===== `KURTOSIS`
*Input*: Numeric, *Output*: `double` .Synopsis:
[source, sql]
--------------------------------------------------
KURTOSIS(field_name<1>)
--------------------------------------------------
https://en.wikipedia.org/wiki/Kurtosis[Quantify] the shape of the distribution of input values. *Input*:
["source","sql",subs="attributes,callouts,macros"] <1> a numeric field
----
*Output*: `double` numeric value
.Description:
https://en.wikipedia.org/wiki/Kurtosis[Quantify] the shape of the distribution of input values in the field `field_name`.
["source","sql",subs="attributes,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/docs.csv-spec[aggKurtosis] include-tagged::{sql-specs}/docs.csv-spec[aggKurtosis]
---- --------------------------------------------------
[[sql-functions-aggs-percentile]] [[sql-functions-aggs-percentile]]
===== `PERCENTILE` ===== `PERCENTILE`
*Input*: Numeric, *Output*: `double` .Synopsis:
[source, sql]
--------------------------------------------------
PERCENTILE(field_name<1>, numeric_exp<2>)
--------------------------------------------------
The nth https://en.wikipedia.org/wiki/Percentile[percentile] of input values. *Input*:
["source","sql",subs="attributes,callouts,macros"] <1> a numeric field
---- <2> a numeric expression
*Output*: `double` numeric value
.Description:
Returns the nth https://en.wikipedia.org/wiki/Percentile[percentile] (represented by `numeric_exp` parameter)
of input values in the field `field_name`.
["source","sql",subs="attributes,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/docs.csv-spec[aggPercentile] include-tagged::{sql-specs}/docs.csv-spec[aggPercentile]
---- --------------------------------------------------
[[sql-functions-aggs-percentile-rank]] [[sql-functions-aggs-percentile-rank]]
===== `PERCENTILE_RANK` ===== `PERCENTILE_RANK`
*Input*: Numeric, *Output*: `double` .Synopsis:
[source, sql]
--------------------------------------------------
PERCENTILE_RANK(field_name<1>, numeric_exp<2>)
--------------------------------------------------
The https://en.wikipedia.org/wiki/Percentile_rank[percentile rank] of input values of input values. *Input*:
["source","sql",subs="attributes,callouts,macros"] <1> a numeric field
---- <2> a numeric expression
*Output*: `double` numeric value
.Description:
Returns the nth https://en.wikipedia.org/wiki/Percentile_rank[percentile rank] (represented by `numeric_exp` parameter)
of input values in the field `field_name`.
["source","sql",subs="attributes,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/docs.csv-spec[aggPercentileRank] include-tagged::{sql-specs}/docs.csv-spec[aggPercentileRank]
---- --------------------------------------------------
[[sql-functions-aggs-skewness]] [[sql-functions-aggs-skewness]]
===== `SKEWNESS` ===== `SKEWNESS`
*Input*: Numeric, *Output*: `double` .Synopsis:
[source, sql]
--------------------------------------------------
SKEWNESS(field_name<1>)
--------------------------------------------------
https://en.wikipedia.org/wiki/Skewness[Quantify] the asymmetric distribution of input values. *Input*:
["source","sql",subs="attributes,callouts,macros"] <1> a numeric field
----
*Output*: `double` numeric value
.Description:
https://en.wikipedia.org/wiki/Skewness[Quantify] the asymmetric distribution of input values in the field `field_name`.
["source","sql",subs="attributes,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/docs.csv-spec[aggSkewness] include-tagged::{sql-specs}/docs.csv-spec[aggSkewness]
---- --------------------------------------------------
[[sql-functions-aggs-stddev-pop]] [[sql-functions-aggs-stddev-pop]]
===== `STDDEV_POP` ===== `STDDEV_POP`
*Input*: Numeric, *Output*: `double` .Synopsis:
[source, sql]
--------------------------------------------------
STDDEV_POP(field_name<1>)
--------------------------------------------------
https://en.wikipedia.org/wiki/Standard_deviations[Population standard deviation] of input values. *Input*:
["source","sql",subs="attributes,callouts,macros"] <1> a numeric field
----
*Output*: `double` numeric value
.Description:
Returns the https://en.wikipedia.org/wiki/Standard_deviations[population standard deviation] of input values in the field `field_name`.
["source","sql",subs="attributes,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/docs.csv-spec[aggStddevPop] include-tagged::{sql-specs}/docs.csv-spec[aggStddevPop]
---- --------------------------------------------------
[[sql-functions-aggs-sum-squares]] [[sql-functions-aggs-sum-squares]]
===== `SUM_OF_SQUARES` ===== `SUM_OF_SQUARES`
*Input*: Numeric, *Output*: `double` .Synopsis:
[source, sql]
--------------------------------------------------
SUM_OF_SQUARES(field_name<1>)
--------------------------------------------------
https://en.wikipedia.org/wiki/Total_sum_of_squares[Sum of squares] of input values. *Input*:
["source","sql",subs="attributes,callouts,macros"] <1> a numeric field
----
*Output*: `double` numeric value
.Description:
Returns the https://en.wikipedia.org/wiki/Total_sum_of_squares[sum of squares] of input values in the field `field_name`.
["source","sql",subs="attributes,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/docs.csv-spec[aggSumOfSquares] include-tagged::{sql-specs}/docs.csv-spec[aggSumOfSquares]
---- --------------------------------------------------
[[sql-functions-aggs-var-pop]] [[sql-functions-aggs-var-pop]]
===== `VAR_POP` ===== `VAR_POP`
*Input*: Numeric, *Output*: `double` .Synopsis:
[source, sql]
--------------------------------------------------
VAR_POP(field_name<1>)
--------------------------------------------------
https://en.wikipedia.org/wiki/Variance[Population] variance of input values. *Input*:
["source","sql",subs="attributes,callouts,macros"] <1> a numeric field
----
*Output*: `double` numeric value
.Description:
Returns the https://en.wikipedia.org/wiki/Variance[population variance] of input values in the field `field_name`.
["source","sql",subs="attributes,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/docs.csv-spec[aggVarPop] include-tagged::{sql-specs}/docs.csv-spec[aggVarPop]
---- --------------------------------------------------

14
docs/reference/sql/functions/conditional.asciidoc
View File

@ -10,7 +10,7 @@ Functions that return one of their arguments by evaluating in an if-else manner.
[[sql-functions-conditional-coalesce]] [[sql-functions-conditional-coalesce]]
==== `COALESCE` ==== `COALESCE`
.Synopsis .Synopsis:
[source, sql] [source, sql]
---- ----
COALESCE(expression<1>, expression<2>, ...) COALESCE(expression<1>, expression<2>, ...)
@ -51,7 +51,7 @@ include-tagged::{sql-specs}/docs.csv-spec[coalesceReturnNull]
[[sql-functions-conditional-ifnull]] [[sql-functions-conditional-ifnull]]
==== `IFNULL` ==== `IFNULL`
.Synopsis .Synopsis:
[source, sql] [source, sql]
---- ----
IFNULL(expression<1>, expression<2>) IFNULL(expression<1>, expression<2>)
@ -88,7 +88,7 @@ include-tagged::{sql-specs}/docs.csv-spec[ifNullReturnSecond]
[[sql-functions-conditional-isnull]] [[sql-functions-conditional-isnull]]
==== `ISNULL` ==== `ISNULL`
.Synopsis .Synopsis:
[source, sql] [source, sql]
---- ----
ISNULL(expression<1>, expression<2>) ISNULL(expression<1>, expression<2>)
@ -125,7 +125,7 @@ include-tagged::{sql-specs}/docs.csv-spec[isNullReturnSecond]
[[sql-functions-conditional-nvl]] [[sql-functions-conditional-nvl]]
==== `NVL` ==== `NVL`
.Synopsis .Synopsis:
[source, sql] [source, sql]
---- ----
NVL(expression<1>, expression<2>) NVL(expression<1>, expression<2>)
@ -162,7 +162,7 @@ include-tagged::{sql-specs}/docs.csv-spec[nvlReturnSecond]
[[sql-functions-conditional-nullif]] [[sql-functions-conditional-nullif]]
==== `NULLIF` ==== `NULLIF`
.Synopsis .Synopsis:
[source, sql] [source, sql]
---- ----
NULLIF(expression<1>, expression<2>) NULLIF(expression<1>, expression<2>)
@ -197,7 +197,7 @@ include-tagged::{sql-specs}/docs.csv-spec[nullIfReturnNull]
[[sql-functions-conditional-greatest]] [[sql-functions-conditional-greatest]]
==== `GREATEST` ==== `GREATEST`
.Synopsis .Synopsis:
[source, sql] [source, sql]
---- ----
GREATEST(expression<1>, expression<2>, ...) GREATEST(expression<1>, expression<2>, ...)
@ -239,7 +239,7 @@ include-tagged::{sql-specs}/docs.csv-spec[greatestReturnNull]
[[sql-functions-conditional-least]] [[sql-functions-conditional-least]]
==== `LEAST` ==== `LEAST`
.Synopsis .Synopsis:
[source, sql] [source, sql]
---- ----
LEAST(expression<1>, expression<2>, ...) LEAST(expression<1>, expression<2>, ...)

87
docs/reference/sql/functions/date-time.asciidoc
View File

@ -11,24 +11,20 @@ beta[]
==== Intervals ==== Intervals
A common requirement when dealing with date/time in general revolves around A common requirement when dealing with date/time in general revolves around
the notion of ``interval``s, a topic that is worth exploring in the context of {es} and {es-sql}. the notion of `interval`, a topic that is worth exploring in the context of {es} and {es-sql}.
{es} has comprehensive support for <<date-math, date math>> both inside <<date-math-index-names, index names>> and <<mapping-date-format, queries>>. {es} has comprehensive support for <<date-math, date math>> both inside <<date-math-index-names, index names>> and <<mapping-date-format, queries>>.
Inside {es-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`. Inside {es-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 {es-sql}: The table below shows the mapping between {es} and {es-sql}:
[cols="^m,^m",options="header"] [cols="^m,^m"]
|==========================
|=== s|{es}
| {es} | {es-sql} s|{es-sql}
2+h| Index/Table date math 2+h| Index/Table date math
2+|<index-{now/M{YYYY.MM}}> 2+|<index-{now/M{YYYY.MM}}>
2+h| Query date math 2+h| Query date math
| 1y | INTERVAL 1 YEAR | 1y | INTERVAL 1 YEAR
| 2M | INTERVAL 2 MONTH | 2M | INTERVAL 2 MONTH
| 3w | INTERVAL 21 DAY | 3w | INTERVAL 21 DAY
@ -36,8 +32,7 @@ The table below shows the mapping between {es} and {es-sql}:
| 5h | INTERVAL 5 HOUR | 5h | INTERVAL 5 HOUR
| 6m | INTERVAL 6 MINUTE | 6m | INTERVAL 6 MINUTE
| 7s | INTERVAL 7 SECOND | 7s | INTERVAL 7 SECOND
|==========================
|===
`INTERVAL` allows either `YEAR` and `MONTH` to be mixed together _or_ `DAY`, `HOUR`, `MINUTE` and `SECOND`. `INTERVAL` allows either `YEAR` and `MONTH` to be mixed together _or_ `DAY`, `HOUR`, `MINUTE` and `SECOND`.
@ -45,11 +40,11 @@ TIP: {es-sql} accepts also the plural for each time unit (e.g. both `YEAR` and `
Example of the possible combinations below: Example of the possible combinations below:
[cols="^,^",options="header"] [cols="^,^"]
|=== |===
| Interval | Description s|Interval
s|Description
| `INTERVAL '1-2' YEAR TO MONTH` | 1 year and 2 months | `INTERVAL '1-2' YEAR TO MONTH` | 1 year and 2 months
| `INTERVAL '3 4' DAYS TO HOURS` | 3 days and 4 hours | `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 '5 6:12' DAYS TO MINUTES` | 5 days, 6 hours and 12 minutes
@ -58,7 +53,6 @@ Example of the possible combinations below:
| `INTERVAL '123:45' HOUR TO MINUTES` | 123 hours and 45 minutes | `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 '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 | `INTERVAL '45:01.23' MINUTES TO SECONDS` | 45 minutes, 1 second and 230000000 nanoseconds
|=== |===
==== Operators ==== Operators
@ -100,19 +94,18 @@ include-tagged::{sql-specs}/docs.csv-spec[dtIntervalMul]
beta[] beta[]
[[sql-functions-current-timestamp]] [[sql-functions-current-timestamp]]
==== `CURRENT_TIMESTAMP`/`NOW` ==== `CURRENT_TIMESTAMP`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
-------------------------------------------------- --------------------------------------------------
CURRENT_TIMESTAMP CURRENT_TIMESTAMP
CURRENT_TIMESTAMP(precision <1>) CURRENT_TIMESTAMP(precision <1>)
NOW()
-------------------------------------------------- --------------------------------------------------
*Input*: *Input*:
<1> fractional digits - optional <1> fractional digits; optional
*Output*: date/time *Output*: date/time
@ -139,7 +132,8 @@ include-tagged::{sql-specs}/docs.csv-spec[curTsFunction]
include-tagged::{sql-specs}/docs.csv-spec[curTsFunctionPrecision] include-tagged::{sql-specs}/docs.csv-spec[curTsFunctionPrecision]
-------------------------------------------------- --------------------------------------------------
Typically this function is used for relative date/time filtering: Typically, this function (as well as its twin <<sql-functions-now,NOW())>> function is used for
relative date/time filtering:
["source","sql",subs="attributes,callouts,macros"] ["source","sql",subs="attributes,callouts,macros"]
-------------------------------------------------- --------------------------------------------------
@ -147,7 +141,7 @@ include-tagged::{sql-specs}/docs.csv-spec[filterNow]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-datetime-day]] [[sql-functions-datetime-day]]
==== `DAY_OF_MONTH`/`DOM`/`DAY` ==== `DAY_OF_MONTH/DOM/DAY`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -171,7 +165,7 @@ include-tagged::{sql-specs}/docs.csv-spec[dayOfMonth]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-datetime-dow]] [[sql-functions-datetime-dow]]
==== `DAY_OF_WEEK`/`DAYOFWEEK`/`DOW` ==== `DAY_OF_WEEK/DAYOFWEEK/DOW`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -195,7 +189,7 @@ include-tagged::{sql-specs}/docs.csv-spec[dayOfWeek]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-datetime-doy]] [[sql-functions-datetime-doy]]
==== `DAY_OF_YEAR`/`DOY` ==== `DAY_OF_YEAR/DOY`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -219,7 +213,7 @@ include-tagged::{sql-specs}/docs.csv-spec[dayOfYear]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-datetime-dayname]] [[sql-functions-datetime-dayname]]
==== `DAY_NAME`/`DAYNAME` ==== `DAY_NAME/DAYNAME`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -243,7 +237,7 @@ include-tagged::{sql-specs}/docs.csv-spec[dayName]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-datetime-hour]] [[sql-functions-datetime-hour]]
==== `HOUR_OF_DAY`/`HOUR` ==== `HOUR_OF_DAY/HOUR`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -267,7 +261,7 @@ include-tagged::{sql-specs}/docs.csv-spec[hourOfDay]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-datetime-isodow]] [[sql-functions-datetime-isodow]]
==== `ISO_DAY_OF_WEEK`/`ISODAYOFWEEK`/`ISODOW`/`IDOW` ==== `ISO_DAY_OF_WEEK/ISODAYOFWEEK/ISODOW/IDOW`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -292,7 +286,7 @@ include-tagged::{sql-specs}/docs.csv-spec[isoDayOfWeek]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-datetime-isoweek]] [[sql-functions-datetime-isoweek]]
==== `ISO_WEEK_OF_YEAR`/`ISOWEEKOFYEAR`/`ISOWEEK`/`IWOY`/`IW` ==== `ISO_WEEK_OF_YEAR/ISOWEEKOFYEAR/ISOWEEK/IWOY/IW`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -341,7 +335,7 @@ include-tagged::{sql-specs}/docs.csv-spec[minuteOfDay]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-datetime-minute]] [[sql-functions-datetime-minute]]
==== `MINUTE_OF_HOUR`/`MINUTE` ==== `MINUTE_OF_HOUR/MINUTE`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -365,7 +359,7 @@ include-tagged::{sql-specs}/docs.csv-spec[minuteOfHour]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-datetime-month]] [[sql-functions-datetime-month]]
==== `MONTH_OF_YEAR`/`MONTH` ==== `MONTH_OF_YEAR/MONTH`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -389,7 +383,7 @@ include-tagged::{sql-specs}/docs.csv-spec[monthOfYear]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-datetime-monthname]] [[sql-functions-datetime-monthname]]
==== `MONTH_NAME`/`MONTHNAME` ==== `MONTH_NAME/MONTHNAME`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -412,8 +406,39 @@ Extract the month from a datetime in text format (`January`, `February`...).
include-tagged::{sql-specs}/docs.csv-spec[monthName] include-tagged::{sql-specs}/docs.csv-spec[monthName]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-now]]
==== `NOW`
.Synopsis:
[source, sql]
--------------------------------------------------
NOW()
--------------------------------------------------
*Input*: _none_
*Output*: date/time
.Description:
This function offers the same functionality as <<sql-functions-current-timestamp,CURRENT_TIMESTAMP()>> function: returns the date/time
when the current query reached the server. This method always returns the same value within a query.
["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/docs.csv-spec[nowFunction]
--------------------------------------------------
Typically, this function (as well as its twin <<sql-functions-current-timestamp,CURRENT_TIMESTAMP())>> function is used for
relative date/time filtering:
["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/docs.csv-spec[filterNow]
--------------------------------------------------
[[sql-functions-datetime-second]] [[sql-functions-datetime-second]]
==== `SECOND_OF_MINUTE`/`SECOND` ==== `SECOND_OF_MINUTE/SECOND`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -461,7 +486,7 @@ include-tagged::{sql-specs}/docs.csv-spec[quarter]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-datetime-week]] [[sql-functions-datetime-week]]
==== `WEEK_OF_YEAR`/`WEEK` ==== `WEEK_OF_YEAR/WEEK`
.Synopsis: .Synopsis:
[source, sql] [source, sql]

2
docs/reference/sql/functions/grouping.asciidoc
View File

@ -11,7 +11,7 @@ as part of the <<sql-syntax-group-by, grouping>>.
[[sql-functions-grouping-histogram]] [[sql-functions-grouping-histogram]]
==== `HISTOGRAM` ==== `HISTOGRAM`
.Synopsis .Synopsis:
[source, sql] [source, sql]
---- ----
HISTOGRAM(numeric_exp<1>, numeric_interval<2>) HISTOGRAM(numeric_exp<1>, numeric_interval<2>)

6
docs/reference/sql/functions/math.asciidoc
View File

@ -65,13 +65,11 @@ include-tagged::{sql-specs}/docs.csv-spec[mathInlineCbrtWithNegativeValue]
[source, sql] [source, sql]
-------------------------------------------------- --------------------------------------------------
CEIL(numeric_exp<1>) CEIL(numeric_exp<1>)
CEILING(numeric_exp<2>)
-------------------------------------------------- --------------------------------------------------
*Input*: *Input*:
<1> numeric expression <1> numeric expression
<2> numeric expression
*Output*: integer or long numeric value *Output*: integer or long numeric value
@ -279,7 +277,7 @@ include-tagged::{sql-specs}/docs.csv-spec[mathInlinePowerNegative]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-random]] [[sql-functions-math-random]]
===== `RANDOM` ===== `RANDOM/RAND`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -334,7 +332,7 @@ include-tagged::{sql-specs}/docs.csv-spec[mathRoundWithNegativeParameter]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-sign]] [[sql-functions-math-sign]]
===== `SIGN` ===== `SIGN/SIGNUM`
.Synopsis: .Synopsis:
[source, sql] [source, sql]

6
docs/reference/sql/functions/operators.asciidoc
View File

@ -47,7 +47,7 @@ include-tagged::{sql-specs}/filter.sql-spec[whereFieldLessThan]
include-tagged::{sql-specs}/filter.sql-spec[whereBetween] include-tagged::{sql-specs}/filter.sql-spec[whereBetween]
-------------------------------------------------- --------------------------------------------------
* `IS NULL`/`IS NOT NULL` * `IS NULL/IS NOT NULL`
["source","sql",subs="attributes,callouts,macros"] ["source","sql",subs="attributes,callouts,macros"]
-------------------------------------------------- --------------------------------------------------
@ -64,6 +64,8 @@ include-tagged::{sql-specs}/filter.sql-spec[whereWithInAndMultipleValues]
[[sql-operators-logical]] [[sql-operators-logical]]
=== Logical Operators === Logical Operators
beta[]
Boolean operator for evaluating one or two expressions. Boolean operator for evaluating one or two expressions.
* `AND` * `AND`
@ -90,6 +92,8 @@ include-tagged::{sql-specs}/filter.sql-spec[whereFieldEqualityNot]
[[sql-operators-math]] [[sql-operators-math]]
=== Math Operators === Math Operators
beta[]
Perform mathematical operations affecting one or two values. Perform mathematical operations affecting one or two values.
The result is a value of numeric type. The result is a value of numeric type.

12
docs/reference/sql/functions/search.asciidoc
View File

@ -13,7 +13,17 @@ such as `0` or `NULL`.
[[sql-functions-search-score]] [[sql-functions-search-score]]
==== `SCORE` ==== `SCORE`
*Input*: None, *Output*: `double` .Synopsis:
[source, sql]
--------------------------------------------------
SCORE()
--------------------------------------------------
*Input*: _none_
*Output*: `double` numeric value
.Description:
Returns the {defguide}/relevance-intro.html[relevance] of a given input to the executed query. Returns the {defguide}/relevance-intro.html[relevance] of a given input to the executed query.
The higher score, the more relevant the data. The higher score, the more relevant the data.

6
docs/reference/sql/functions/system.asciidoc
View File

@ -16,7 +16,7 @@ These functions return metadata type of information about the system being queri
DATABASE() DATABASE()
-------------------------------------------------- --------------------------------------------------
*Input*: *Input*: _none_
*Output*: string *Output*: string
@ -39,14 +39,14 @@ include-tagged::{sql-specs}/docs.csv-spec[database]
-------------------------------------------------- --------------------------------------------------
USER() USER()
-------------------------------------------------- --------------------------------------------------
*Input*: *Input*: _none_
*Output*: string *Output*: string
.Description: .Description:
Returns the username of the authenticated user executing the query. This function can Returns the username of the authenticated user executing the query. This function can
return `null` in case Security is disabled. return `null` in case {stack-ov}/elasticsearch-security.html[Security] is disabled.
["source","sql",subs="attributes,callouts,macros"] ["source","sql",subs="attributes,callouts,macros"]
-------------------------------------------------- --------------------------------------------------

4
docs/reference/sql/functions/type-conversion.asciidoc
View File

@ -10,7 +10,7 @@ Functions for converting an expression of one data type to another.
[[sql-functions-type-conversion-cast]] [[sql-functions-type-conversion-cast]]
==== `CAST` ==== `CAST`
.Synopsis .Synopsis:
[source, sql] [source, sql]
---- ----
CAST(expression<1> AS data_type<2>) CAST(expression<1> AS data_type<2>)
@ -44,7 +44,7 @@ include-tagged::{sql-specs}/docs.csv-spec[conversionStringToDateCast]
[[sql-functions-type-conversion-convert]] [[sql-functions-type-conversion-convert]]
==== `CONVERT` ==== `CONVERT`
.Synopsis .Synopsis:
[source, sql] [source, sql]
---- ----
CONVERT(expression<1>, data_type<2>) CONVERT(expression<1>, data_type<2>)

3
docs/reference/sql/index.asciidoc
View File

@ -45,6 +45,8 @@ indices and return results in tabular format.
syntax. syntax.
<<sql-functions,Functions and Operators>>:: <<sql-functions,Functions and Operators>>::
List of functions and operators supported. List of functions and operators supported.
<<sql-limitations,Limitations>>::
{es-sql} current limitations.
-- --
include::overview.asciidoc[] include::overview.asciidoc[]
@ -55,5 +57,6 @@ include::endpoints/index.asciidoc[]
include::language/index.asciidoc[] include::language/index.asciidoc[]
include::functions/index.asciidoc[] include::functions/index.asciidoc[]
include::appendix/index.asciidoc[] include::appendix/index.asciidoc[]
include::limitations.asciidoc[]
:jdbc-tests!: :jdbc-tests!:

11
docs/reference/sql/language/data-types.asciidoc
View File

@ -7,10 +7,12 @@ beta[]
Most of {es} <<mapping-types, data types>> are available in {es-sql}, as indicated below: Most of {es} <<mapping-types, data types>> are available in {es-sql}, as indicated below:
[cols="^,^m,^",options="header"] [cols="^,^m,^"]
|=== |===
| {es} type | SQL type | SQL precision s|{es} type
s|SQL type
s|SQL precision
3+h| Core types 3+h| Core types
@ -50,10 +52,11 @@ Such types cannot be loaded from {es} (as it does not know about them) however c
The table below indicates these types: The table below indicates these types:
[cols="^m,^",options="header"] [cols="^m,^"]
|=== |===
| SQL type | SQL precision s|SQL type
s|SQL precision
| interval_year | 7 | interval_year | 7

6
docs/reference/sql/language/index-patterns.asciidoc
View File

@ -62,9 +62,11 @@ an empty table is returned.
In a nutshell, the differences between the two type of patterns are: In a nutshell, the differences between the two type of patterns are:
[cols="^h,^,^",options="header"] [cols="^h,^,^"]
|=== |===
| Feature | Multi index | SQL `LIKE` s|Feature
s|Multi index
s|SQL `LIKE`
| Type of quoting | `"` | `'` | Type of quoting | `"` | `'`
| Inclusion | Yes | Yes | Inclusion | Yes | Yes

6
docs/reference/sql/language/syntax/select.asciidoc
View File

@ -268,7 +268,7 @@ include-tagged::{sql-specs}/docs.csv-spec[groupByHavingMultiple]
[float] [float]
===== Implicit Grouping ===== Implicit Grouping
As indicated above, it is possible to have a `HAVING` clause without a ``GROUP BY``. In this case, the so-called <<sql-syntax-group-by-implicit, __implicit grouping__>> is applied, meaning all selected rows are considered to form a single group and `HAVING` can be applied on any of the aggregate functions specified on this group. ` As indicated above, it is possible to have a `HAVING` clause without a `GROUP BY`. In this case, the so-called <<sql-syntax-group-by-implicit, __implicit grouping__>> is applied, meaning all selected rows are considered to form a single group and `HAVING` can be applied on any of the aggregate functions specified on this group.
As such, the query emits only a single row (as there is only a single group) and `HAVING` condition returns either one row (the group) or zero if the condition fails. As such, the query emits only a single row (as there is only a single group) and `HAVING` condition returns either one row (the group) or zero if the condition fails.
In this example, `HAVING` matches: In this example, `HAVING` matches:
@ -301,8 +301,8 @@ where:
`expression`:: `expression`::
Represents an input column, an output column or an ordinal number of the position (starting from one) of an output column. Additionally, ordering can be done based on the results _score_ ` Represents an input column, an output column or an ordinal number of the position (starting from one) of an output column. Additionally, ordering can be done based on the results _score_.
The direction, if not specified, is by default `ASC` (ascending). ` The direction, if not specified, is by default `ASC` (ascending).
Regardless of the ordering specified, null values are ordered last (at the end). Regardless of the ordering specified, null values are ordered last (at the end).
IMPORTANT: When used along-side, `GROUP BY` expression can point _only_ to the columns used for grouping. IMPORTANT: When used along-side, `GROUP BY` expression can point _only_ to the columns used for grouping.

71
docs/reference/sql/limitations.asciidoc Normal file
View File

@ -0,0 +1,71 @@
[role="xpack"]
[testenv="basic"]
[[sql-limitations]]
== SQL Limitations
beta[]
[float]
=== Nested fields in `SYS COLUMNS` and `DESCRIBE TABLE`
{es} has a special type of relationship fields called `nested` fields. In {es-sql} they can be used by referencing their inner
sub-fields. Even though `SYS COLUMNS` 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:
[source, sql]
--------------------------------------------------
[nested_field_name].[sub_field_name]
--------------------------------------------------
For example:
[source, sql]
--------------------------------------------------
SELECT dep.dep_name.keyword FROM test_emp GROUP BY languages;
--------------------------------------------------
[float]
=== Multi-nested fields
{es-sql} doesn't support multi-nested documents, so a query cannot reference more than one nested field in an index.
This applies to multi-level nested fields, but also multiple nested fields defined on the same level. For example, for this index:
[source, 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, {es-sql} will display an error message.
[float]
=== Paginating nested inner hits
When SELECTing a nested field, pagination will not work as expected, {es-sql} will return __at least__ the page size records.
This is because of the way nested queries work in {es}: the root nested field will be returned and it's matching inner nested fields as well,
pagination taking place on the **root nested document and not on its inner hits**.
[float]
=== Normalized `keyword` fields
`keyword` fields in {es} can be normalized by defining a `normalizer`. Such fields are not supported in {es-sql}.
[float]
=== Array type of fields
Array fields are not supported due to the "invisible" way in which {es} handles an array of values: the mapping doesn't indicate whether
a field is an array (has multiple values) or not, so without reading all the data, {es-sql} cannot know whether a field is a single or multi value.
[float]
=== Sorting by aggregation
When doing aggregations (`GROUP BY`) {es-sql} relies on {es}'s `composite` aggregation for its support for paginating results.
But this type of aggregation does come with a limitation: sorting can only be applied on the key used for the aggregation's buckets. This
means that queries like `SELECT * FROM test GROUP BY age ORDER BY COUNT(*)` are not possible.

2
x-pack/plugin/sql/qa/src/main/resources/docs.csv-spec
View File

@ -2128,5 +2128,5 @@ SELECT NOW() AS result;
result result
------------------------ ------------------------
2018-12-12T14:48:52.448Z 2018-12-12T14:48:52.448Z
// end::nowIgnore // end::nowFunction
; ;