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

SQL: MATCH and QUERY documentation; one list of functions (#40494) 

* Document MATCH and QUERY function predicates.
* Polish the functions pages and add a list of functions to the main Functions & Operators page.

(cherry picked from commit 4cec0ae1b962ec7ea011a290aec72740386eb808)
This commit is contained in:
Andrei Stefan 2019-03-27 17:18:14 +02:00 committed by Andrei Stefan
parent 760cfffe4b
commit 99dca30197
8 changed files with 465 additions and 173 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -124,7 +124,8 @@ Query timeout (in seconds). That is the maximum amount of time waiting for a que
[float] [float]
==== Mapping ==== Mapping
`field.multi.value.leniency` (default `true`):: Whether to be lenient and return the first value for fields with multiple values (true) or throw an exception. `field.multi.value.leniency` (default `true`):: Whether to be lenient and return the first value (without any guarantees of what that
will be - typically the first in natural ascending order) for fields with multiple values (true) or throw an exception.
[float] [float]
==== Additional ==== Additional

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

@ -6,10 +6,12 @@
Functions for computing a _single_ result from a set of input values. Functions for computing a _single_ result from a set of input values.
{es-sql} supports aggregate functions only alongside <<sql-syntax-group-by,grouping>> (implicit or explicit). {es-sql} supports aggregate functions only alongside <<sql-syntax-group-by,grouping>> (implicit or explicit).
==== General Purpose [[sql-functions-aggs-general]]
[float]
=== General Purpose
[[sql-functions-aggs-avg]] [[sql-functions-aggs-avg]]
===== `AVG` ==== `AVG`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -33,7 +35,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggAvg]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-aggs-count]] [[sql-functions-aggs-count]]
===== `COUNT` ==== `COUNT`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -63,7 +65,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggCountStar]
[[sql-functions-aggs-count-all]] [[sql-functions-aggs-count-all]]
===== `COUNT(ALL)` ==== `COUNT(ALL)`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -88,7 +90,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggCountAll]
[[sql-functions-aggs-count-distinct]] [[sql-functions-aggs-count-distinct]]
===== `COUNT(DISTINCT)` ==== `COUNT(DISTINCT)`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -112,7 +114,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggCountDistinct]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-aggs-first]] [[sql-functions-aggs-first]]
===== `FIRST/FIRST_VALUE` ==== `FIRST/FIRST_VALUE`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -207,7 +209,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[firstValueWithTwoArgsAndGroupBy]
the field is also <<before-enabling-fielddata,saved as a keyword>>. the field is also <<before-enabling-fielddata,saved as a keyword>>.
[[sql-functions-aggs-last]] [[sql-functions-aggs-last]]
===== `LAST/LAST_VALUE` ==== `LAST/LAST_VALUE`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -302,7 +304,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[lastValueWithTwoArgsAndGroupBy]
the field is also <<before-enabling-fielddata,`saved as a keyword`>>. the field is also <<before-enabling-fielddata,`saved as a keyword`>>.
[[sql-functions-aggs-max]] [[sql-functions-aggs-max]]
===== `MAX` ==== `MAX`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -330,7 +332,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggMax]
<<sql-functions-aggs-last>> and therefore, it cannot be used in `HAVING` clause. <<sql-functions-aggs-last>> and therefore, it cannot be used in `HAVING` clause.
[[sql-functions-aggs-min]] [[sql-functions-aggs-min]]
===== `MIN` ==== `MIN`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -358,7 +360,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggMin]
<<sql-functions-aggs-first>> and therefore, it cannot be used in `HAVING` clause. <<sql-functions-aggs-first>> and therefore, it cannot be used in `HAVING` clause.
[[sql-functions-aggs-sum]] [[sql-functions-aggs-sum]]
===== `SUM` ==== `SUM`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -381,10 +383,12 @@ Returns the sum of input values in the field `field_name`.
include-tagged::{sql-specs}/docs/docs.csv-spec[aggSum] include-tagged::{sql-specs}/docs/docs.csv-spec[aggSum]
-------------------------------------------------- --------------------------------------------------
==== Statistics [[sql-functions-aggs-statistics]]
[float]
=== Statistics
[[sql-functions-aggs-kurtosis]] [[sql-functions-aggs-kurtosis]]
===== `KURTOSIS` ==== `KURTOSIS`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -408,7 +412,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggKurtosis]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-aggs-mad]] [[sql-functions-aggs-mad]]
===== `MAD` ==== `MAD`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -432,7 +436,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggMad]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-aggs-percentile]] [[sql-functions-aggs-percentile]]
===== `PERCENTILE` ==== `PERCENTILE`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -458,7 +462,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggPercentile]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-aggs-percentile-rank]] [[sql-functions-aggs-percentile-rank]]
===== `PERCENTILE_RANK` ==== `PERCENTILE_RANK`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -484,7 +488,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggPercentileRank]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-aggs-skewness]] [[sql-functions-aggs-skewness]]
===== `SKEWNESS` ==== `SKEWNESS`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -508,7 +512,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggSkewness]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-aggs-stddev-pop]] [[sql-functions-aggs-stddev-pop]]
===== `STDDEV_POP` ==== `STDDEV_POP`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -532,7 +536,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggStddevPop]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-aggs-sum-squares]] [[sql-functions-aggs-sum-squares]]
===== `SUM_OF_SQUARES` ==== `SUM_OF_SQUARES`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -556,7 +560,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggSumOfSquares]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-aggs-var-pop]] [[sql-functions-aggs-var-pop]]
===== `VAR_POP` ==== `VAR_POP`
.Synopsis: .Synopsis:
[source, sql] [source, sql]

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

@ -45,6 +45,46 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[coalesceReturnNonNull]
include-tagged::{sql-specs}/docs/docs.csv-spec[coalesceReturnNull] include-tagged::{sql-specs}/docs/docs.csv-spec[coalesceReturnNull]
---- ----
[[sql-functions-conditional-greatest]]
==== `GREATEST`
.Synopsis:
[source, sql]
----
GREATEST(expression<1>, expression<2>, ...)
----
*Input*:
<1> 1st expression
<2> 2nd expression
...
**N**th expression
GREATEST can take an arbitrary number of arguments and
all of them must be of the same data type.
*Output*: one of the expressions or `null`
.Description
Returns the argument that has the largest value which is not null.
If all arguments are null, then it returns `null`.
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[greatestReturnNonNull]
----
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[greatestReturnNull]
----
[[sql-functions-conditional-ifnull]] [[sql-functions-conditional-ifnull]]
==== `IFNULL` ==== `IFNULL`
@ -120,120 +160,6 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[isNullReturnSecond]
---- ----
[[sql-functions-conditional-nvl]]
==== `NVL`
.Synopsis:
[source, sql]
----
NVL(expression<1>, expression<2>)
----
*Input*:
<1> 1st expression
<2> 2nd expression
*Output*: 2nd expression if 1st expression is null, otherwise 1st expression.
.Description
Variant of <<sql-functions-conditional-coalesce>> with only two arguments.
Returns the first of its arguments that is not null.
If all arguments are null, then it returns `null`.
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[nvlReturnFirst]
----
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[nvlReturnSecond]
----
[[sql-functions-conditional-nullif]]
==== `NULLIF`
.Synopsis:
[source, sql]
----
NULLIF(expression<1>, expression<2>)
----
*Input*:
<1> 1st expression
<2> 2nd expression
*Output*: `null` if the 2 expressions are equal, otherwise the 1st expression.
.Description
Returns `null` when the two input expressions are equal and
if not, it returns the 1st expression.
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[nullIfReturnFirst]
----
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[nullIfReturnNull]
----
[[sql-functions-conditional-greatest]]
==== `GREATEST`
.Synopsis:
[source, sql]
----
GREATEST(expression<1>, expression<2>, ...)
----
*Input*:
<1> 1st expression
<2> 2nd expression
...
**N**th expression
GREATEST can take an arbitrary number of arguments and
all of them must be of the same data type.
*Output*: one of the expressions or `null`
.Description
Returns the argument that has the largest value which is not null.
If all arguments are null, then it returns `null`.
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[greatestReturnNonNull]
----
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[greatestReturnNull]
----
[[sql-functions-conditional-least]] [[sql-functions-conditional-least]]
==== `LEAST` ==== `LEAST`
@ -274,3 +200,77 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[leastReturnNonNull]
---- ----
include-tagged::{sql-specs}/docs/docs.csv-spec[leastReturnNull] include-tagged::{sql-specs}/docs/docs.csv-spec[leastReturnNull]
---- ----
[[sql-functions-conditional-nullif]]
==== `NULLIF`
.Synopsis:
[source, sql]
----
NULLIF(expression<1>, expression<2>)
----
*Input*:
<1> 1st expression
<2> 2nd expression
*Output*: `null` if the 2 expressions are equal, otherwise the 1st expression.
.Description
Returns `null` when the two input expressions are equal and
if not, it returns the 1st expression.
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[nullIfReturnFirst]
----
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[nullIfReturnNull]
----
[[sql-functions-conditional-nvl]]
==== `NVL`
.Synopsis:
[source, sql]
----
NVL(expression<1>, expression<2>)
----
*Input*:
<1> 1st expression
<2> 2nd expression
*Output*: 2nd expression if 1st expression is null, otherwise 1st expression.
.Description
Variant of <<sql-functions-conditional-coalesce>> with only two arguments.
Returns the first of its arguments that is not null.
If all arguments are null, then it returns `null`.
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[nvlReturnFirst]
----
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[nvlReturnSecond]
----

101
docs/reference/sql/functions/index.asciidoc
View File

@ -7,14 +7,115 @@
* <<sql-operators, Operators>> * <<sql-operators, Operators>>
* <<sql-functions-aggs, Aggregate>> * <<sql-functions-aggs, Aggregate>>
** <<sql-functions-aggs-avg, AVG>>
** <<sql-functions-aggs-count, COUNT>>
** <<sql-functions-aggs-count-all, COUNT(ALL)>>
** <<sql-functions-aggs-count-distinct, COUNT(DISTINCT)>>
** <<sql-functions-aggs-first, FIRST>>
** <<sql-functions-aggs-last, LAST>>
** <<sql-functions-aggs-max, MAX>>
** <<sql-functions-aggs-min, MIN>>
** <<sql-functions-aggs-sum, SUM>>
** <<sql-functions-aggs-kurtosis, KURTOSIS>>
** <<sql-functions-aggs-mad, MAD>>
** <<sql-functions-aggs-percentile, PERCENTILE>>
** <<sql-functions-aggs-percentile-rank, PERCENTILE_RANK>>
** <<sql-functions-aggs-skewness, SKEWNESS>>
** <<sql-functions-aggs-stddev-pop, STDDEV_POP>>
** <<sql-functions-aggs-sum-squares, SUM_OF_SQUARES>>
** <<sql-functions-aggs-var-pop, VAR_POP>>
* <<sql-functions-grouping, Grouping>> * <<sql-functions-grouping, Grouping>>
** <<sql-functions-grouping-histogram, HISTOGRAM>>
* <<sql-functions-datetime, Date-Time>> * <<sql-functions-datetime, Date-Time>>
** <<sql-functions-datetime-interval, INTERVAL>>
** <<sql-functions-current-date, CURRENT_DATE>>
** <<sql-functions-current-timestamp, CURRENT_TIMESTAMP>>
** <<sql-functions-datetime-day, DAY>>
** <<sql-functions-datetime-dow, DAY_OF_WEEK>>
** <<sql-functions-datetime-doy, DAY_OF_YEAR>>
** <<sql-functions-datetime-dayname, DAY_NAME>>
** <<sql-functions-datetime-hour, HOUR>>
** <<sql-functions-datetime-isodow, ISO_DAY_OF_WEEK>>
** <<sql-functions-datetime-isoweek, ISO_WEEK_OF_YEAR>>
** <<sql-functions-datetime-minuteofday, MINUTE_OF_DAY>>
** <<sql-functions-datetime-minute, MINUTE_OF_HOUR>>
** <<sql-functions-datetime-month, MONTH_OF_YEAR>>
** <<sql-functions-datetime-monthname, MONTH_NAME>>
** <<sql-functions-now, NOW>>
** <<sql-functions-datetime-second, SECOND_OF_MINUTE>>
** <<sql-functions-datetime-quarter, QUARTER>>
** <<sql-functions-today, TODAY>>
** <<sql-functions-datetime-week, WEEK_OF_YEAR>>
** <<sql-functions-datetime-year, YEAR>>
** <<sql-functions-datetime-extract, EXTRACT>>
* <<sql-functions-search, Full-Text Search>> * <<sql-functions-search, Full-Text Search>>
** <<sql-functions-search-match, MATCH>>
** <<sql-functions-search-query, QUERY>>
** <<sql-functions-search-score, SCORE>>
* <<sql-functions-math, Mathematical>> * <<sql-functions-math, Mathematical>>
** <<sql-functions-math-abs, ABS>>
** <<sql-functions-math-cbrt, CBRT>>
** <<sql-functions-math-ceil, CEIL>>
** <<sql-functions-math-e, E>>
** <<sql-functions-math-exp, EXP>>
** <<sql-functions-math-expm1, EXPM1>>
** <<sql-functions-math-floor, FLOOR>>
** <<sql-functions-math-log, LOG>>
** <<sql-functions-math-log10, LOG10>>
** <<sql-functions-math-pi, PI>>
** <<sql-functions-math-power, POWER>>
** <<sql-functions-math-random, RANDOM>>
** <<sql-functions-math-round, ROUND>>
** <<sql-functions-math-sign, SIGN>>
** <<sql-functions-math-sqrt, SQRT>>
** <<sql-functions-math-truncate, TRUNCATE>>
** <<sql-functions-math-acos, ACOS>>
** <<sql-functions-math-asin, ASIN>>
** <<sql-functions-math-atan, ATAN>>
** <<sql-functions-math-atan2, ATAN2>>
** <<sql-functions-math-cos, COS>>
** <<sql-functions-math-cosh, COSH>>
** <<sql-functions-math-cot, COT>>
** <<sql-functions-math-degrees, DEGREES>>
** <<sql-functions-math-radians, RADIANS>>
** <<sql-functions-math-sin, SIN>>
** <<sql-functions-math-sinh, SINH>>
** <<sql-functions-math-tan, TAN>>
* <<sql-functions-string, String>> * <<sql-functions-string, String>>
** <<sql-functions-string-ascii, ASCII>>
** <<sql-functions-string-bit-length, BIT_LENGTH>>
** <<sql-functions-string-char, CHAR>>
** <<sql-functions-string-char-length, CHAR_LENGTH>>
** <<sql-functions-string-concat, CONCAT>>
** <<sql-functions-string-insert, INSERT>>
** <<sql-functions-string-lcase, LCASE>>
** <<sql-functions-string-left, LEFT>>
** <<sql-functions-string-length, LENGTH>>
** <<sql-functions-string-locate, LOCATE>>
** <<sql-functions-string-ltrim, LTRIM>>
** <<sql-functions-string-octet-length, OCTET_LENGTH>>
** <<sql-functions-string-position, POSITION>>
** <<sql-functions-string-repeat, REPEAT>>
** <<sql-functions-string-replace, REPLACE>>
** <<sql-functions-string-right, RIGHT>>
** <<sql-functions-string-rtrim, RTRIM>>
** <<sql-functions-string-space, SPACE>>
** <<sql-functions-string-substring, SUBSTRING>>
** <<sql-functions-string-ucase, UCASE>>
* <<sql-functions-type-conversion, Type Conversion>> * <<sql-functions-type-conversion, Type Conversion>>
** <<sql-functions-type-conversion-cast, CAST>>
** <<sql-functions-type-conversion-convert, CONVERT>>
* <<sql-functions-conditional, Conditional>> * <<sql-functions-conditional, Conditional>>
** <<sql-functions-conditional-coalesce, COALESCE>>
** <<sql-functions-conditional-greatest, GREATEST>>
** <<sql-functions-conditional-ifnull, IFNULL>>
** <<sql-functions-conditional-isnull, ISNULL>>
** <<sql-functions-conditional-least, LEAST>>
** <<sql-functions-conditional-nullif, NULLIF>>
** <<sql-functions-conditional-nvl, NVL>>
* <<sql-functions-system, System>> * <<sql-functions-system, System>>
** <<sql-functions-system-database, DATABASE>>
** <<sql-functions-system-user, USER>>
include::operators.asciidoc[] include::operators.asciidoc[]
include::aggs.asciidoc[] include::aggs.asciidoc[]

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

@ -6,10 +6,12 @@
All math and trigonometric functions require their input (where applicable) All math and trigonometric functions require their input (where applicable)
to be numeric. to be numeric.
==== Generic [[sql-functions-math-generic]]
[float]
=== Generic
[[sql-functions-math-abs]] [[sql-functions-math-abs]]
===== `ABS` ==== `ABS`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -33,7 +35,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[abs]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-cbrt]] [[sql-functions-math-cbrt]]
===== `CBRT` ==== `CBRT`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -57,7 +59,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineCbrtWithNegativeValue]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-ceil]] [[sql-functions-math-ceil]]
===== `CEIL/CEILING` ==== `CEIL/CEILING`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -81,7 +83,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineCeiling]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-e]] [[sql-functions-math-e]]
===== `E` ==== `E`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -103,7 +105,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathEulersNumber]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-exp]] [[sql-functions-math-exp]]
===== `EXP` ==== `EXP`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -127,7 +129,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathExpInline]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-expm1]] [[sql-functions-math-expm1]]
===== `EXPM1` ==== `EXPM1`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -151,7 +153,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathExpm1Inline]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-floor]] [[sql-functions-math-floor]]
===== `FLOOR` ==== `FLOOR`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -175,7 +177,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineFloor]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-log]] [[sql-functions-math-log]]
===== `LOG` ==== `LOG`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -199,7 +201,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineLog]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-log10]] [[sql-functions-math-log10]]
===== `LOG10` ==== `LOG10`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -223,7 +225,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineLog10]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-pi]] [[sql-functions-math-pi]]
===== `PI` ==== `PI`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -245,7 +247,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathPINumber]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-power]] [[sql-functions-math-power]]
===== `POWER` ==== `POWER`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -275,7 +277,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlinePowerNegative]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-random]] [[sql-functions-math-random]]
===== `RANDOM/RAND` ==== `RANDOM/RAND`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -299,7 +301,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathRandom]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-round]] [[sql-functions-math-round]]
===== `ROUND` ==== `ROUND`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -330,7 +332,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathRoundWithNegativeParameter]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-sign]] [[sql-functions-math-sign]]
===== `SIGN/SIGNUM` ==== `SIGN/SIGNUM`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -355,7 +357,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineSign]
[[sql-functions-math-sqrt]] [[sql-functions-math-sqrt]]
===== `SQRT` ==== `SQRT`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -379,7 +381,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineSqrt]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-truncate]] [[sql-functions-math-truncate]]
===== `TRUNCATE` ==== `TRUNCATE`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -409,10 +411,12 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathTruncateWithPositiveParameter
include-tagged::{sql-specs}/docs/docs.csv-spec[mathTruncateWithNegativeParameter] include-tagged::{sql-specs}/docs/docs.csv-spec[mathTruncateWithNegativeParameter]
-------------------------------------------------- --------------------------------------------------
==== Trigonometric [[sql-functions-math-trigonometric]]
[float]
=== Trigonometric
[[sql-functions-math-acos]] [[sql-functions-math-acos]]
===== `ACOS` ==== `ACOS`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -436,7 +440,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineAcos]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-asin]] [[sql-functions-math-asin]]
===== `ASIN` ==== `ASIN`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -460,7 +464,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineAsin]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-atan]] [[sql-functions-math-atan]]
===== `ATAN` ==== `ATAN`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -484,7 +488,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineAtan]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-atan2]] [[sql-functions-math-atan2]]
===== `ATAN2` ==== `ATAN2`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -509,7 +513,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineAtan2]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-cos]] [[sql-functions-math-cos]]
===== `COS` ==== `COS`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -533,7 +537,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineCosine]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-cosh]] [[sql-functions-math-cosh]]
===== `COSH` ==== `COSH`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -557,7 +561,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineCosh]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-cot]] [[sql-functions-math-cot]]
===== `COT` ==== `COT`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -581,7 +585,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineCotangent]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-degrees]] [[sql-functions-math-degrees]]
===== `DEGREES` ==== `DEGREES`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -606,7 +610,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineDegrees]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-radians]] [[sql-functions-math-radians]]
===== `RADIANS` ==== `RADIANS`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -631,7 +635,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineRadians]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-sin]] [[sql-functions-math-sin]]
===== `SIN` ==== `SIN`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -655,7 +659,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineSine]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-sinh]] [[sql-functions-math-sinh]]
===== `SINH` ==== `SINH`
.Synopsis: .Synopsis:
[source, sql] [source, sql]
@ -679,7 +683,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineSinh]
-------------------------------------------------- --------------------------------------------------
[[sql-functions-math-tan]] [[sql-functions-math-tan]]
===== `TAN` ==== `TAN`
.Synopsis: .Synopsis:
[source, sql] [source, sql]

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

@ -8,6 +8,118 @@ when the `MATCH` or `QUERY` predicates are being used.
Outside a, so-called, search context, these functions will return default values Outside a, so-called, search context, these functions will return default values
such as `0` or `NULL`. such as `0` or `NULL`.
[[sql-functions-search-match]]
==== `MATCH`
.Synopsis:
[source, sql]
--------------------------------------------------
MATCH(field_exp<1>, constant_exp<2>[, options]<3>)
--------------------------------------------------
*Input*:
<1> field(s) to match
<2> matching text
<3> additional parameters; optional
.Description:
A full-text search option, in the form of a predicate, available in {es-sql} that gives the user control over powerful <<query-dsl-match-query,match>>
and <<query-dsl-multi-match-query,multi_match>> {es} queries.
The first parameter is the field or fields to match against. In case it receives one value only, {es-sql} will use a `match` query to perform the search:
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[simpleMatch]
----
However, it can also receive a list of fields and their corresponding optional `boost` value. In this case, {es-sql} will use a
`multi_match` query to match the documents:
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[multiFieldsMatch]
----
NOTE: The `multi_match` query in {es} has the option of <<query-dsl-multi-match-query,per-field boosting>> that gives preferential weight
(in terms of scoring) to fields being searched in, using the `^` character. In the example above, the `name` field has a greater weight in
the final score than the `author` field when searching for `frank dune` text in both of them.
Both options above can be used in combination with the optional third parameter of the `MATCH()` predicate, where one can specify
additional configuration parameters (separated by semicolon `;`) for either `match` or `multi_match` queries. For example:
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[optionalParamsForMatch]
----
In the more advanced example above, the `cutoff_frequency` parameter allows specifying an absolute or relative document frequency where
high frequency terms are moved into an optional subquery and are only scored if one of the low frequency (below the cutoff) terms in the
case of an `or` operator or all of the low frequency terms in the case of an `and` operator match. More about this you can find in the
<<query-dsl-match-query-cutoff>> page.
NOTE: The allowed optional parameters for a single-field `MATCH()` variant (for the `match` {es} query) are: `analyzer`, `auto_generate_synonyms_phrase_query`,
`cutoff_frequency`, `lenient`, `fuzzy_transpositions`, `fuzzy_rewrite`, `minimum_should_match`, `operator`,
`max_expansions`, `prefix_length`.
NOTE: The allowed optional parameters for a multi-field `MATCH()` variant (for the `multi_match` {es} query) are: `analyzer`, `auto_generate_synonyms_phrase_query`,
`cutoff_frequency`, `lenient`, `fuzzy_transpositions`, `fuzzy_rewrite`, `minimum_should_match`, `operator`,
`max_expansions`, `prefix_length`, `slop`, `tie_breaker`, `type`.
[[sql-functions-search-query]]
==== `QUERY`
.Synopsis:
[source, sql]
--------------------------------------------------
QUERY(constant_exp<1>[, options]<2>)
--------------------------------------------------
*Input*:
<1> query text
<2> additional parameters; optional
.Description:
Just like `MATCH`, `QUERY` is a full-text search predicate that gives the user control over the <<query-dsl-query-string-query,query_string>> query in {es}.
The first parameter is basically the input that will be passed as is to the `query_string` query, which means that anything that `query_string`
accepts in its `query` field can be used here as well:
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[simpleQueryQuery]
----
A more advanced example, showing more of the features that `query_string` supports, of course possible with {es-sql}:
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[advancedQueryQuery]
----
The query above uses the `_exists_` query to select documents that have values in the `author` field, a range query for `page_count` and
regex and fuzziness queries for the `name` field.
If one needs to customize various configuration options that `query_string` exposes, this can be done using the second _optional_ parameter.
Multiple settings can be specified separated by a semicolon `;`:
["source","sql",subs="attributes,callouts,macros"]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[optionalParameterQuery]
----
NOTE: The allowed optional parameters for `QUERY()` are: `allow_leading_wildcard`, `analyze_wildcard`, `analyzer`,
`auto_generate_synonyms_phrase_query`, `default_field`, `default_operator`, `enable_position_increments`,
`escape`, `fuzzy_max_expansions`, `fuzzy_prefix_length`, `fuzzy_rewrite`, `fuzzy_transpositions`, `lenient`,
`locale`, `lowercase_expanded_terms`, `max_determinized_states`, `minimum_should_match`, `phrase_slop`, `rewrite`,
`quote_analyzer`, `quote_field_suffix`, `tie_breaker`, `time_zone`, `type`.
[[sql-functions-search-score]] [[sql-functions-search-score]]
==== `SCORE` ==== `SCORE`

8
docs/reference/sql/language/syntax/commands/select.asciidoc
View File

@ -71,7 +71,6 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[wildcardWithOrder]
which essentially returns all(top-level fields, sub-fields, such as multi-fields are ignored] columns found. which essentially returns all(top-level fields, sub-fields, such as multi-fields are ignored] columns found.
[[sql-syntax-from]] [[sql-syntax-from]]
[float]
==== FROM Clause ==== FROM Clause
The `FROM` clause specifies one table for the `SELECT` and has the following syntax: The `FROM` clause specifies one table for the `SELECT` and has the following syntax:
@ -111,7 +110,6 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[fromTableAlias]
---- ----
[[sql-syntax-where]] [[sql-syntax-where]]
[float]
==== WHERE Clause ==== WHERE Clause
The optional `WHERE` clause is used to filter rows from the query and has the following syntax: The optional `WHERE` clause is used to filter rows from the query and has the following syntax:
@ -133,7 +131,6 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[basicWhere]
---- ----
[[sql-syntax-group-by]] [[sql-syntax-group-by]]
[float]
==== GROUP BY ==== GROUP BY
The `GROUP BY` clause is used to divide the results into groups of rows on matching values from the designated columns. It has the following syntax: The `GROUP BY` clause is used to divide the results into groups of rows on matching values from the designated columns. It has the following syntax:
@ -208,7 +205,6 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[groupByAndMultipleAggs]
---- ----
[[sql-syntax-group-by-implicit]] [[sql-syntax-group-by-implicit]]
[float]
===== Implicit Grouping ===== Implicit Grouping
When an aggregation is used without an associated `GROUP BY`, an __implicit grouping__ is applied, meaning all selected rows are considered to form a single default, or implicit group. When an aggregation is used without an associated `GROUP BY`, an __implicit grouping__ is applied, meaning all selected rows are considered to form a single default, or implicit group.
@ -229,7 +225,6 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[groupByImplicitMultipleAggs]
---- ----
[[sql-syntax-having]] [[sql-syntax-having]]
[float]
==== HAVING ==== HAVING
The `HAVING` clause can be used _only_ along aggregate functions (and thus `GROUP BY`) to filter what groups are kept or not and has the following syntax: The `HAVING` clause can be used _only_ along aggregate functions (and thus `GROUP BY`) to filter what groups are kept or not and has the following syntax:
@ -263,7 +258,6 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[groupByHavingMultiple]
---- ----
[[sql-syntax-having-group-by-implicit]] [[sql-syntax-having-group-by-implicit]]
[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.
@ -285,7 +279,6 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[groupByHavingImplicitMatch]
[[sql-syntax-order-by]] [[sql-syntax-order-by]]
[float]
==== ORDER BY ==== ORDER BY
The `ORDER BY` clause is used to sort the results of `SELECT` by one or more expressions: The `ORDER BY` clause is used to sort the results of `SELECT` by one or more expressions:
@ -373,7 +366,6 @@ Trying to return `score` from a non full-text query will return the same value f
all are equally relevant. all are equally relevant.
[[sql-syntax-limit]] [[sql-syntax-limit]]
[float]
==== LIMIT ==== LIMIT
The `LIMIT` clause restricts (limits) the number of rows returns using the format: The `LIMIT` clause restricts (limits) the number of rows returns using the format:

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

@ -929,6 +929,84 @@ null |25324
// end::orderByAgg // end::orderByAgg
; ;
simpleMatch
// tag::simpleMatch
SELECT author, name FROM library WHERE MATCH(author, 'frank');
author | name
---------------+-------------------
Frank Herbert |Dune
Frank Herbert |Dune Messiah
Frank Herbert |Children of Dune
Frank Herbert |God Emperor of Dune
// end::simpleMatch
;
multiFieldsMatch
// tag::multiFieldsMatch
SELECT author, name, SCORE() FROM library WHERE MATCH('author^2,name^5', 'frank dune');
author | name | SCORE()
---------------+-------------------+---------------
Frank Herbert |Dune |11.443176
Frank Herbert |Dune Messiah |9.446629
Frank Herbert |Children of Dune |8.043278
Frank Herbert |God Emperor of Dune|7.0029488
// end::multiFieldsMatch
;
optionalParamsForMatch
// tag::optionalParamsForMatch
SELECT author, name, SCORE() FROM library WHERE MATCH(name, 'to the star', 'operator=or;cutoff_frequency=0.2');
author | name | SCORE()
-----------------+------------------------------------+---------------
Peter F. Hamilton|Pandora's Star |3.0997515
Douglas Adams |The Hitchhiker's Guide to the Galaxy|3.1756816
// end::optionalParamsForMatch
;
simpleQueryQuery
// tag::simpleQueryQuery
SELECT author, name, SCORE() FROM library WHERE QUERY('name:dune');
author | name | SCORE()
---------------+-------------------+---------------
Frank Herbert |Dune |2.2886353
Frank Herbert |Dune Messiah |1.8893257
Frank Herbert |Children of Dune |1.6086556
Frank Herbert |God Emperor of Dune|1.4005898
// end::simpleQueryQuery
;
advancedQueryQuery
// tag::advancedQueryQuery
SELECT author, name, page_count, SCORE() FROM library WHERE QUERY('_exists_:"author" AND page_count:>200 AND (name:/star.*/ OR name:duna~)');
author | name | page_count | SCORE()
------------------+-------------------+---------------+---------------
Frank Herbert |Dune |604 |3.7164764
Frank Herbert |Dune Messiah |331 |3.4169943
Frank Herbert |Children of Dune |408 |3.2064917
Frank Herbert |God Emperor of Dune|454 |3.0504425
Peter F. Hamilton |Pandora's Star |768 |3.0
Robert A. Heinlein|Starship Troopers |335 |3.0
// end::advancedQueryQuery
;
optionalParameterQuery
// tag::optionalParameterQuery
SELECT author, name, SCORE() FROM library WHERE QUERY('dune god', 'default_operator=and;default_field=name');
author | name | SCORE()
---------------+-------------------+---------------
Frank Herbert |God Emperor of Dune|3.6984892
// end::optionalParameterQuery
;
orderByScore orderByScore
// tag::orderByScore // tag::orderByScore
SELECT SCORE(), * FROM library WHERE MATCH(name, 'dune') ORDER BY SCORE() DESC; SELECT SCORE(), * FROM library WHERE MATCH(name, 'dune') ORDER BY SCORE() DESC;