From 09fa827adcef24acee4b2dad44da90cada9c0590 Mon Sep 17 00:00:00 2001 From: Andrei Stefan Date: Fri, 21 Dec 2018 23:25:54 +0200 Subject: [PATCH] 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 --- .../sql/appendix/syntax-reserved.asciidoc | 6 +- docs/reference/sql/concepts.asciidoc | 2 + .../endpoints/client-apps/squirrel.asciidoc | 4 +- docs/reference/sql/endpoints/jdbc.asciidoc | 2 + docs/reference/sql/functions/aggs.asciidoc | 289 ++++++++++++++---- .../sql/functions/conditional.asciidoc | 28 +- .../sql/functions/date-time.asciidoc | 87 ++++-- .../reference/sql/functions/grouping.asciidoc | 6 +- docs/reference/sql/functions/math.asciidoc | 6 +- .../sql/functions/operators.asciidoc | 6 +- docs/reference/sql/functions/search.asciidoc | 12 +- docs/reference/sql/functions/system.asciidoc | 6 +- .../sql/functions/type-conversion.asciidoc | 8 +- docs/reference/sql/index.asciidoc | 3 + .../sql/language/data-types.asciidoc | 11 +- .../sql/language/index-patterns.asciidoc | 6 +- .../sql/language/syntax/select.asciidoc | 6 +- docs/reference/sql/limitations.asciidoc | 71 +++++ .../sql/qa/src/main/resources/docs.csv-spec | 2 +- 19 files changed, 421 insertions(+), 140 deletions(-) create mode 100644 docs/reference/sql/limitations.asciidoc diff --git a/docs/reference/sql/appendix/syntax-reserved.asciidoc b/docs/reference/sql/appendix/syntax-reserved.asciidoc index 977e6a7328c..f83939359a4 100644 --- a/docs/reference/sql/appendix/syntax-reserved.asciidoc +++ b/docs/reference/sql/appendix/syntax-reserved.asciidoc @@ -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 diff --git a/docs/reference/sql/concepts.asciidoc b/docs/reference/sql/concepts.asciidoc index a3ea1f02e72..0d68380a497 100644 --- a/docs/reference/sql/concepts.asciidoc +++ b/docs/reference/sql/concepts.asciidoc @@ -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: diff --git a/docs/reference/sql/endpoints/client-apps/squirrel.asciidoc b/docs/reference/sql/endpoints/client-apps/squirrel.asciidoc index 2c2e59a24a2..efec4f135dd 100644 --- a/docs/reference/sql/endpoints/client-apps/squirrel.asciidoc +++ b/docs/reference/sql/endpoints/client-apps/squirrel.asciidoc @@ -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 diff --git a/docs/reference/sql/endpoints/jdbc.asciidoc b/docs/reference/sql/endpoints/jdbc.asciidoc index 47e5e465e06..e9af3492adc 100644 --- a/docs/reference/sql/endpoints/jdbc.asciidoc +++ b/docs/reference/sql/endpoints/jdbc.asciidoc @@ -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` diff --git a/docs/reference/sql/functions/aggs.asciidoc b/docs/reference/sql/functions/aggs.asciidoc index c64417cae07..d55da5a45a0 100644 --- a/docs/reference/sql/functions/aggs.asciidoc +++ b/docs/reference/sql/functions/aggs.asciidoc @@ -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] ----- +-------------------------------------------------- diff --git a/docs/reference/sql/functions/conditional.asciidoc b/docs/reference/sql/functions/conditional.asciidoc index dd5de6d58e8..63138bcfce8 100644 --- a/docs/reference/sql/functions/conditional.asciidoc +++ b/docs/reference/sql/functions/conditional.asciidoc @@ -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*: diff --git a/docs/reference/sql/functions/date-time.asciidoc b/docs/reference/sql/functions/date-time.asciidoc index 2ec6529f8f8..416e9279039 100644 --- a/docs/reference/sql/functions/date-time.asciidoc +++ b/docs/reference/sql/functions/date-time.asciidoc @@ -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 <> both inside <> and <>. 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+| - 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 <> 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 <> 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 <> 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] diff --git a/docs/reference/sql/functions/grouping.asciidoc b/docs/reference/sql/functions/grouping.asciidoc index b80b08a39f4..9784f4e9b74 100644 --- a/docs/reference/sql/functions/grouping.asciidoc +++ b/docs/reference/sql/functions/grouping.asciidoc @@ -11,11 +11,11 @@ as part of the <>. [[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*: diff --git a/docs/reference/sql/functions/math.asciidoc b/docs/reference/sql/functions/math.asciidoc index 2ad40a17de8..84764de4aad 100644 --- a/docs/reference/sql/functions/math.asciidoc +++ b/docs/reference/sql/functions/math.asciidoc @@ -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] diff --git a/docs/reference/sql/functions/operators.asciidoc b/docs/reference/sql/functions/operators.asciidoc index 7eb0b3e08f4..a5d522b7e5b 100644 --- a/docs/reference/sql/functions/operators.asciidoc +++ b/docs/reference/sql/functions/operators.asciidoc @@ -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. diff --git a/docs/reference/sql/functions/search.asciidoc b/docs/reference/sql/functions/search.asciidoc index c6284b27411..95ebfa942ae 100644 --- a/docs/reference/sql/functions/search.asciidoc +++ b/docs/reference/sql/functions/search.asciidoc @@ -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. diff --git a/docs/reference/sql/functions/system.asciidoc b/docs/reference/sql/functions/system.asciidoc index 82182339d53..2570a5c856a 100644 --- a/docs/reference/sql/functions/system.asciidoc +++ b/docs/reference/sql/functions/system.asciidoc @@ -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"] -------------------------------------------------- diff --git a/docs/reference/sql/functions/type-conversion.asciidoc b/docs/reference/sql/functions/type-conversion.asciidoc index 3ff0bfed242..dec7ccb77ae 100644 --- a/docs/reference/sql/functions/type-conversion.asciidoc +++ b/docs/reference/sql/functions/type-conversion.asciidoc @@ -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 diff --git a/docs/reference/sql/index.asciidoc b/docs/reference/sql/index.asciidoc index 3c9b628a14d..5c6b23f0091 100644 --- a/docs/reference/sql/index.asciidoc +++ b/docs/reference/sql/index.asciidoc @@ -45,6 +45,8 @@ indices and return results in tabular format. syntax. <>:: List of functions and operators supported. +<>:: + {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!: diff --git a/docs/reference/sql/language/data-types.asciidoc b/docs/reference/sql/language/data-types.asciidoc index 572fd094dbc..a4a407f175e 100644 --- a/docs/reference/sql/language/data-types.asciidoc +++ b/docs/reference/sql/language/data-types.asciidoc @@ -7,10 +7,12 @@ beta[] Most of {es} <> 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 diff --git a/docs/reference/sql/language/index-patterns.asciidoc b/docs/reference/sql/language/index-patterns.asciidoc index bc2352d3854..434e03d186f 100644 --- a/docs/reference/sql/language/index-patterns.asciidoc +++ b/docs/reference/sql/language/index-patterns.asciidoc @@ -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 diff --git a/docs/reference/sql/language/syntax/select.asciidoc b/docs/reference/sql/language/syntax/select.asciidoc index d82a5b95b87..eb05087fab3 100644 --- a/docs/reference/sql/language/syntax/select.asciidoc +++ b/docs/reference/sql/language/syntax/select.asciidoc @@ -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 <> 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 <> 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. diff --git a/docs/reference/sql/limitations.asciidoc b/docs/reference/sql/limitations.asciidoc new file mode 100644 index 00000000000..b66c246bc42 --- /dev/null +++ b/docs/reference/sql/limitations.asciidoc @@ -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. diff --git a/x-pack/plugin/sql/qa/src/main/resources/docs.csv-spec b/x-pack/plugin/sql/qa/src/main/resources/docs.csv-spec index fb7207d4c5c..af16675ab81 100644 --- a/x-pack/plugin/sql/qa/src/main/resources/docs.csv-spec +++ b/x-pack/plugin/sql/qa/src/main/resources/docs.csv-spec @@ -2128,5 +2128,5 @@ SELECT NOW() AS result; result ------------------------ 2018-12-12T14:48:52.448Z -// end::nowIgnore +// end::nowFunction ;