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
GitHub
parent
33e9cf3892
commit
09fa827adc
|
|
@ -16,11 +16,13 @@ be quoted (using double quotes) in order to be used as an identifier, for exampl
|
|||
SELECT "AS" FROM index
|
||||
----
|
||||
|
||||
[cols="^,^,^",options="header"]
|
||||
[cols="^,^,^"]
|
||||
|
||||
|===
|
||||
|
||||
|Keyword |SQL:2016 |SQL-92
|
||||
s|Keyword
|
||||
s|SQL:2016
|
||||
s|SQL-92
|
||||
|
||||
|
||||
|`ALL` |reserved |reserved
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
||||
beta[]
|
||||
|
||||
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:
|
||||
|
|
|
|||
|
|
@ -1,13 +1,13 @@
|
|||
[role="xpack"]
|
||||
[testenv="platinum"]
|
||||
[[sql-client-apps-squirrel]]
|
||||
=== SQquirelL SQL
|
||||
=== SQuirreL SQL
|
||||
|
||||
beta[]
|
||||
|
||||
[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
|
||||
|
|
|
|||
|
|
@ -138,6 +138,8 @@ Opens up a {es-sql} connection to `server` on port `3456`, setting the JDBC conn
|
|||
|
||||
=== API usage
|
||||
|
||||
beta[]
|
||||
|
||||
One can use JDBC through the official `java.sql` and `javax.sql` packages:
|
||||
|
||||
==== `java.sql`
|
||||
|
|
|
|||
|
|
@ -13,158 +13,317 @@ Functions for computing a _single_ result from a set of input values.
|
|||
[[sql-functions-aggs-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]
|
||||
----
|
||||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-aggs-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]
|
||||
----
|
||||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-aggs-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]
|
||||
----
|
||||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-aggs-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]
|
||||
----
|
||||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-aggs-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]
|
||||
----
|
||||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-aggs-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]
|
||||
----
|
||||
--------------------------------------------------
|
||||
|
||||
==== Statistics
|
||||
|
||||
[[sql-functions-aggs-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]
|
||||
----
|
||||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-aggs-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]
|
||||
----
|
||||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-aggs-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]
|
||||
----
|
||||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-aggs-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]
|
||||
----
|
||||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-aggs-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]
|
||||
----
|
||||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-aggs-sum-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]
|
||||
----
|
||||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-aggs-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]
|
||||
----
|
||||
--------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -10,10 +10,10 @@ Functions that return one of their arguments by evaluating in an if-else manner.
|
|||
[[sql-functions-conditional-coalesce]]
|
||||
==== `COALESCE`
|
||||
|
||||
.Synopsis
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
----
|
||||
COALESCE ( expression<1>, expression<2>, ... )
|
||||
COALESCE(expression<1>, expression<2>, ...)
|
||||
----
|
||||
|
||||
*Input*:
|
||||
|
|
@ -51,10 +51,10 @@ include-tagged::{sql-specs}/docs.csv-spec[coalesceReturnNull]
|
|||
[[sql-functions-conditional-ifnull]]
|
||||
==== `IFNULL`
|
||||
|
||||
.Synopsis
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
----
|
||||
IFNULL ( expression<1>, expression<2> )
|
||||
IFNULL(expression<1>, expression<2>)
|
||||
----
|
||||
|
||||
*Input*:
|
||||
|
|
@ -88,10 +88,10 @@ include-tagged::{sql-specs}/docs.csv-spec[ifNullReturnSecond]
|
|||
[[sql-functions-conditional-isnull]]
|
||||
==== `ISNULL`
|
||||
|
||||
.Synopsis
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
----
|
||||
ISNULL ( expression<1>, expression<2> )
|
||||
ISNULL(expression<1>, expression<2>)
|
||||
----
|
||||
|
||||
*Input*:
|
||||
|
|
@ -125,10 +125,10 @@ include-tagged::{sql-specs}/docs.csv-spec[isNullReturnSecond]
|
|||
[[sql-functions-conditional-nvl]]
|
||||
==== `NVL`
|
||||
|
||||
.Synopsis
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
----
|
||||
NVL ( expression<1>, expression<2> )
|
||||
NVL(expression<1>, expression<2>)
|
||||
----
|
||||
|
||||
*Input*:
|
||||
|
|
@ -162,10 +162,10 @@ include-tagged::{sql-specs}/docs.csv-spec[nvlReturnSecond]
|
|||
[[sql-functions-conditional-nullif]]
|
||||
==== `NULLIF`
|
||||
|
||||
.Synopsis
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
----
|
||||
NULLIF ( expression<1>, expression<2> )
|
||||
NULLIF(expression<1>, expression<2>)
|
||||
----
|
||||
|
||||
*Input*:
|
||||
|
|
@ -197,10 +197,10 @@ include-tagged::{sql-specs}/docs.csv-spec[nullIfReturnNull]
|
|||
[[sql-functions-conditional-greatest]]
|
||||
==== `GREATEST`
|
||||
|
||||
.Synopsis
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
----
|
||||
GREATEST ( expression<1>, expression<2>, ... )
|
||||
GREATEST(expression<1>, expression<2>, ...)
|
||||
----
|
||||
|
||||
*Input*:
|
||||
|
|
@ -239,10 +239,10 @@ include-tagged::{sql-specs}/docs.csv-spec[greatestReturnNull]
|
|||
[[sql-functions-conditional-least]]
|
||||
==== `LEAST`
|
||||
|
||||
.Synopsis
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
----
|
||||
LEAST ( expression<1>, expression<2>, ... )
|
||||
LEAST(expression<1>, expression<2>, ...)
|
||||
----
|
||||
|
||||
*Input*:
|
||||
|
|
|
|||
|
|
@ -11,24 +11,20 @@ beta[]
|
|||
==== Intervals
|
||||
|
||||
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>>.
|
||||
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}:
|
||||
|
||||
[cols="^m,^m",options="header"]
|
||||
|
||||
|===
|
||||
| {es} | {es-sql}
|
||||
|
||||
[cols="^m,^m"]
|
||||
|==========================
|
||||
s|{es}
|
||||
s|{es-sql}
|
||||
2+h| Index/Table date math
|
||||
|
||||
2+|<index-{now/M{YYYY.MM}}>
|
||||
|
||||
2+h| Query date math
|
||||
|
||||
| 1y | INTERVAL 1 YEAR
|
||||
| 2M | INTERVAL 2 MONTH
|
||||
| 3w | INTERVAL 21 DAY
|
||||
|
|
@ -36,8 +32,7 @@ The table below shows the mapping between {es} and {es-sql}:
|
|||
| 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`.
|
||||
|
||||
|
|
@ -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:
|
||||
|
||||
[cols="^,^",options="header"]
|
||||
[cols="^,^"]
|
||||
|
||||
|===
|
||||
| Interval | Description
|
||||
|
||||
s|Interval
|
||||
s|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
|
||||
|
|
@ -58,7 +53,6 @@ Example of the possible combinations below:
|
|||
| `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
|
||||
|
||||
|===
|
||||
|
||||
==== Operators
|
||||
|
|
@ -100,19 +94,18 @@ include-tagged::{sql-specs}/docs.csv-spec[dtIntervalMul]
|
|||
beta[]
|
||||
|
||||
[[sql-functions-current-timestamp]]
|
||||
==== `CURRENT_TIMESTAMP`/`NOW`
|
||||
==== `CURRENT_TIMESTAMP`
|
||||
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
--------------------------------------------------
|
||||
CURRENT_TIMESTAMP
|
||||
CURRENT_TIMESTAMP(precision <1>)
|
||||
NOW()
|
||||
--------------------------------------------------
|
||||
|
||||
*Input*:
|
||||
|
||||
<1> fractional digits - optional
|
||||
<1> fractional digits; optional
|
||||
|
||||
*Output*: date/time
|
||||
|
||||
|
|
@ -139,7 +132,8 @@ include-tagged::{sql-specs}/docs.csv-spec[curTsFunction]
|
|||
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"]
|
||||
--------------------------------------------------
|
||||
|
|
@ -147,7 +141,7 @@ include-tagged::{sql-specs}/docs.csv-spec[filterNow]
|
|||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-datetime-day]]
|
||||
==== `DAY_OF_MONTH`/`DOM`/`DAY`
|
||||
==== `DAY_OF_MONTH/DOM/DAY`
|
||||
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
|
|
@ -171,7 +165,7 @@ include-tagged::{sql-specs}/docs.csv-spec[dayOfMonth]
|
|||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-datetime-dow]]
|
||||
==== `DAY_OF_WEEK`/`DAYOFWEEK`/`DOW`
|
||||
==== `DAY_OF_WEEK/DAYOFWEEK/DOW`
|
||||
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
|
|
@ -195,7 +189,7 @@ include-tagged::{sql-specs}/docs.csv-spec[dayOfWeek]
|
|||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-datetime-doy]]
|
||||
==== `DAY_OF_YEAR`/`DOY`
|
||||
==== `DAY_OF_YEAR/DOY`
|
||||
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
|
|
@ -219,7 +213,7 @@ include-tagged::{sql-specs}/docs.csv-spec[dayOfYear]
|
|||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-datetime-dayname]]
|
||||
==== `DAY_NAME`/`DAYNAME`
|
||||
==== `DAY_NAME/DAYNAME`
|
||||
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
|
|
@ -243,7 +237,7 @@ include-tagged::{sql-specs}/docs.csv-spec[dayName]
|
|||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-datetime-hour]]
|
||||
==== `HOUR_OF_DAY`/`HOUR`
|
||||
==== `HOUR_OF_DAY/HOUR`
|
||||
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
|
|
@ -267,7 +261,7 @@ include-tagged::{sql-specs}/docs.csv-spec[hourOfDay]
|
|||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-datetime-isodow]]
|
||||
==== `ISO_DAY_OF_WEEK`/`ISODAYOFWEEK`/`ISODOW`/`IDOW`
|
||||
==== `ISO_DAY_OF_WEEK/ISODAYOFWEEK/ISODOW/IDOW`
|
||||
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
|
|
@ -292,7 +286,7 @@ include-tagged::{sql-specs}/docs.csv-spec[isoDayOfWeek]
|
|||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-datetime-isoweek]]
|
||||
==== `ISO_WEEK_OF_YEAR`/`ISOWEEKOFYEAR`/`ISOWEEK`/`IWOY`/`IW`
|
||||
==== `ISO_WEEK_OF_YEAR/ISOWEEKOFYEAR/ISOWEEK/IWOY/IW`
|
||||
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
|
|
@ -341,7 +335,7 @@ include-tagged::{sql-specs}/docs.csv-spec[minuteOfDay]
|
|||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-datetime-minute]]
|
||||
==== `MINUTE_OF_HOUR`/`MINUTE`
|
||||
==== `MINUTE_OF_HOUR/MINUTE`
|
||||
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
|
|
@ -365,7 +359,7 @@ include-tagged::{sql-specs}/docs.csv-spec[minuteOfHour]
|
|||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-datetime-month]]
|
||||
==== `MONTH_OF_YEAR`/`MONTH`
|
||||
==== `MONTH_OF_YEAR/MONTH`
|
||||
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
|
|
@ -389,7 +383,7 @@ include-tagged::{sql-specs}/docs.csv-spec[monthOfYear]
|
|||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-datetime-monthname]]
|
||||
==== `MONTH_NAME`/`MONTHNAME`
|
||||
==== `MONTH_NAME/MONTHNAME`
|
||||
|
||||
.Synopsis:
|
||||
[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]
|
||||
--------------------------------------------------
|
||||
|
||||
[[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]]
|
||||
==== `SECOND_OF_MINUTE`/`SECOND`
|
||||
==== `SECOND_OF_MINUTE/SECOND`
|
||||
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
|
|
@ -461,7 +486,7 @@ include-tagged::{sql-specs}/docs.csv-spec[quarter]
|
|||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-datetime-week]]
|
||||
==== `WEEK_OF_YEAR`/`WEEK`
|
||||
==== `WEEK_OF_YEAR/WEEK`
|
||||
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
|
|
|
|||
|
|
@ -11,11 +11,11 @@ as part of the <<sql-syntax-group-by, grouping>>.
|
|||
[[sql-functions-grouping-histogram]]
|
||||
==== `HISTOGRAM`
|
||||
|
||||
.Synopsis
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
----
|
||||
HISTOGRAM ( numeric_exp<1>, numeric_interval<2>)
|
||||
HISTOGRAM ( date_exp<3>, date_time_interval<4>)
|
||||
HISTOGRAM(numeric_exp<1>, numeric_interval<2>)
|
||||
HISTOGRAM(date_exp<3>, date_time_interval<4>)
|
||||
----
|
||||
|
||||
*Input*:
|
||||
|
|
|
|||
|
|
@ -65,13 +65,11 @@ include-tagged::{sql-specs}/docs.csv-spec[mathInlineCbrtWithNegativeValue]
|
|||
[source, sql]
|
||||
--------------------------------------------------
|
||||
CEIL(numeric_exp<1>)
|
||||
CEILING(numeric_exp<2>)
|
||||
--------------------------------------------------
|
||||
|
||||
*Input*:
|
||||
|
||||
<1> numeric expression
|
||||
<2> numeric expression
|
||||
|
||||
*Output*: integer or long numeric value
|
||||
|
||||
|
|
@ -279,7 +277,7 @@ include-tagged::{sql-specs}/docs.csv-spec[mathInlinePowerNegative]
|
|||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-math-random]]
|
||||
===== `RANDOM`
|
||||
===== `RANDOM/RAND`
|
||||
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
|
|
@ -334,7 +332,7 @@ include-tagged::{sql-specs}/docs.csv-spec[mathRoundWithNegativeParameter]
|
|||
--------------------------------------------------
|
||||
|
||||
[[sql-functions-math-sign]]
|
||||
===== `SIGN`
|
||||
===== `SIGN/SIGNUM`
|
||||
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ include-tagged::{sql-specs}/filter.sql-spec[whereFieldLessThan]
|
|||
include-tagged::{sql-specs}/filter.sql-spec[whereBetween]
|
||||
--------------------------------------------------
|
||||
|
||||
* `IS NULL`/`IS NOT NULL`
|
||||
* `IS NULL/IS NOT NULL`
|
||||
|
||||
["source","sql",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
|
|
@ -64,6 +64,8 @@ include-tagged::{sql-specs}/filter.sql-spec[whereWithInAndMultipleValues]
|
|||
[[sql-operators-logical]]
|
||||
=== Logical Operators
|
||||
|
||||
beta[]
|
||||
|
||||
Boolean operator for evaluating one or two expressions.
|
||||
|
||||
* `AND`
|
||||
|
|
@ -90,6 +92,8 @@ include-tagged::{sql-specs}/filter.sql-spec[whereFieldEqualityNot]
|
|||
[[sql-operators-math]]
|
||||
=== Math Operators
|
||||
|
||||
beta[]
|
||||
|
||||
Perform mathematical operations affecting one or two values.
|
||||
The result is a value of numeric type.
|
||||
|
||||
|
|
|
|||
|
|
@ -13,7 +13,17 @@ such as `0` or `NULL`.
|
|||
[[sql-functions-search-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.
|
||||
The higher score, the more relevant the data.
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ These functions return metadata type of information about the system being queri
|
|||
DATABASE()
|
||||
--------------------------------------------------
|
||||
|
||||
*Input*:
|
||||
*Input*: _none_
|
||||
|
||||
*Output*: string
|
||||
|
||||
|
|
@ -39,14 +39,14 @@ include-tagged::{sql-specs}/docs.csv-spec[database]
|
|||
--------------------------------------------------
|
||||
USER()
|
||||
--------------------------------------------------
|
||||
*Input*:
|
||||
*Input*: _none_
|
||||
|
||||
*Output*: string
|
||||
|
||||
.Description:
|
||||
|
||||
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"]
|
||||
--------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -10,10 +10,10 @@ Functions for converting an expression of one data type to another.
|
|||
[[sql-functions-type-conversion-cast]]
|
||||
==== `CAST`
|
||||
|
||||
.Synopsis
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
----
|
||||
CAST ( expression<1> AS data_type<2> )
|
||||
CAST(expression<1> AS data_type<2>)
|
||||
----
|
||||
|
||||
<1> Expression to cast
|
||||
|
|
@ -44,10 +44,10 @@ include-tagged::{sql-specs}/docs.csv-spec[conversionStringToDateCast]
|
|||
[[sql-functions-type-conversion-convert]]
|
||||
==== `CONVERT`
|
||||
|
||||
.Synopsis
|
||||
.Synopsis:
|
||||
[source, sql]
|
||||
----
|
||||
CONVERT ( expression<1>, data_type<2> )
|
||||
CONVERT(expression<1>, data_type<2>)
|
||||
----
|
||||
|
||||
<1> Expression to convert
|
||||
|
|
|
|||
|
|
@ -45,6 +45,8 @@ indices and return results in tabular format.
|
|||
syntax.
|
||||
<<sql-functions,Functions and Operators>>::
|
||||
List of functions and operators supported.
|
||||
<<sql-limitations,Limitations>>::
|
||||
{es-sql} current limitations.
|
||||
--
|
||||
|
||||
include::overview.asciidoc[]
|
||||
|
|
@ -55,5 +57,6 @@ include::endpoints/index.asciidoc[]
|
|||
include::language/index.asciidoc[]
|
||||
include::functions/index.asciidoc[]
|
||||
include::appendix/index.asciidoc[]
|
||||
include::limitations.asciidoc[]
|
||||
|
||||
:jdbc-tests!:
|
||||
|
|
|
|||
|
|
@ -7,10 +7,12 @@ beta[]
|
|||
|
||||
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
|
||||
|
||||
|
|
@ -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:
|
||||
|
||||
[cols="^m,^",options="header"]
|
||||
[cols="^m,^"]
|
||||
|
||||
|===
|
||||
| SQL type | SQL precision
|
||||
s|SQL type
|
||||
s|SQL precision
|
||||
|
||||
|
||||
| interval_year | 7
|
||||
|
|
|
|||
|
|
@ -62,9 +62,11 @@ an empty table is returned.
|
|||
|
||||
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 | `"` | `'`
|
||||
| Inclusion | Yes | Yes
|
||||
|
|
|
|||
|
|
@ -268,7 +268,7 @@ include-tagged::{sql-specs}/docs.csv-spec[groupByHavingMultiple]
|
|||
[float]
|
||||
===== 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.
|
||||
|
||||
In this example, `HAVING` matches:
|
||||
|
|
@ -301,8 +301,8 @@ where:
|
|||
|
||||
`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_ `
|
||||
The direction, if not specified, is by default `ASC` (ascending). `
|
||||
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).
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -2128,5 +2128,5 @@ SELECT NOW() AS result;
|
|||
result
|
||||
------------------------
|
||||
2018-12-12T14:48:52.448Z
|
||||
// end::nowIgnore
|
||||
// end::nowFunction
|
||||
;
|
||||
|
|
|
|||
Loading…
Reference in New Issue