From 9fad0b1ac4409a42c435ed040f41cbaea18930a3 Mon Sep 17 00:00:00 2001 From: Andrei Stefan Date: Fri, 14 Feb 2020 18:58:45 +0200 Subject: [PATCH] SQL: document the use of a filter on _routing (#52355) * Fix "Description"s for various sections in the functions pages. * Added a TIP for searching using a routing key. * Other small polishings --- docs/reference/sql/endpoints/jdbc.asciidoc | 3 +- docs/reference/sql/endpoints/rest.asciidoc | 20 ++++ docs/reference/sql/functions/aggs.asciidoc | 54 +++------ .../sql/functions/conditional.asciidoc | 36 ++---- .../sql/functions/date-time.asciidoc | 100 ++++------------ docs/reference/sql/functions/geo.asciidoc | 28 ++--- .../reference/sql/functions/grouping.asciidoc | 7 +- .../sql/functions/like-rlike.asciidoc | 8 +- docs/reference/sql/functions/math.asciidoc | 110 +++++------------- docs/reference/sql/functions/search.asciidoc | 12 +- docs/reference/sql/functions/string.asciidoc | 80 ++++--------- docs/reference/sql/functions/system.asciidoc | 8 +- .../sql/functions/type-conversion.asciidoc | 8 +- .../syntax/commands/describe-table.asciidoc | 6 +- .../language/syntax/commands/select.asciidoc | 6 +- .../syntax/commands/show-columns.asciidoc | 6 +- .../syntax/commands/show-functions.asciidoc | 6 +- .../syntax/commands/show-tables.asciidoc | 6 +- .../sql/language/syntax/lexic/index.asciidoc | 3 +- 19 files changed, 153 insertions(+), 354 deletions(-) diff --git a/docs/reference/sql/endpoints/jdbc.asciidoc b/docs/reference/sql/endpoints/jdbc.asciidoc index fdacb8b97a232..013506c75fce1 100644 --- a/docs/reference/sql/endpoints/jdbc.asciidoc +++ b/docs/reference/sql/endpoints/jdbc.asciidoc @@ -208,7 +208,8 @@ connection. For example: include-tagged::{jdbc-tests}/SimpleExampleTestCase.java[simple_example] -------------------------------------------------- -NOTE:: {es-sql} doesn't provide a connection pooling mechanism, thus the connections +[NOTE] +{es-sql} doesn't provide a connection pooling mechanism, thus the connections the JDBC driver creates are not pooled. In order to achieve pooled connections, a third-party connection pooling mechanism is required. Configuring and setting up the third-party provider is outside the scope of this documentation. \ No newline at end of file diff --git a/docs/reference/sql/endpoints/rest.asciidoc b/docs/reference/sql/endpoints/rest.asciidoc index 2f9be5da17d65..53ac93bb81c26 100644 --- a/docs/reference/sql/endpoints/rest.asciidoc +++ b/docs/reference/sql/endpoints/rest.asciidoc @@ -371,6 +371,26 @@ Douglas Adams |The Hitchhiker's Guide to the Galaxy|180 |1979-10-12T // TESTRESPONSE[s/\|/\\|/ s/\+/\\+/] // TESTRESPONSE[non_json] +[TIP] +================= +A useful and less obvious usage for standard query DSL filtering is to search documents by a specific <>. +Because {es-sql} does not support a `routing` parameter, one can specify a <> instead: + +[source,console] +-------------------------------------------------- +POST /_sql?format=txt +{ + "query": "SELECT * FROM library", + "filter": { + "terms": { + "_routing": ["abc"] + } + } +} +-------------------------------------------------- +// TEST[setup:library] +================= + [[sql-rest-columnar]] === Columnar results diff --git a/docs/reference/sql/functions/aggs.asciidoc b/docs/reference/sql/functions/aggs.asciidoc index 2beef2c65ea71..2bc1e657c3a60 100644 --- a/docs/reference/sql/functions/aggs.asciidoc +++ b/docs/reference/sql/functions/aggs.asciidoc @@ -25,9 +25,7 @@ AVG(numeric_field) <1> *Output*: `double` numeric value -.Description: - -Returns the https://en.wikipedia.org/wiki/Arithmetic_mean[Average] (arithmetic mean) of input values. +*Description*: Returns the https://en.wikipedia.org/wiki/Arithmetic_mean[Average] (arithmetic mean) of input values. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -49,9 +47,7 @@ COUNT(expression) <1> *Output*: numeric value -.Description: - -Returns the total number (count) of input values. +*Description*: Returns the total number (count) of input values. In case of `COUNT(*)` or `COUNT()`, _all_ values are considered (including `null` or missing ones). @@ -79,9 +75,7 @@ COUNT(ALL field_name) <1> *Output*: numeric value -.Description: - -Returns the total number (count) of all _non-null_ input values. `COUNT()` and `COUNT(ALL )` are equivalent. +*Description*: Returns the total number (count) of all _non-null_ input values. `COUNT()` and `COUNT(ALL )` are equivalent. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -104,9 +98,7 @@ COUNT(DISTINCT field_name) <1> *Output*: numeric value -.Description: - -Returns the total number of _distinct non-null_ values in input values. +*Description*: Returns the total number of _distinct non-null_ values in input values. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -131,9 +123,7 @@ FIRST( *Output*: same type as the input -.Description: - -Returns the first **non-NULL** value (if such exists) of the `field_name` input column sorted by +*Description*: Returns the first **non-NULL** value (if such exists) of the `field_name` input column sorted by the `ordering_field_name` column. If `ordering_field_name` is not provided, only the `field_name` column is used for the sorting. E.g.: @@ -228,10 +218,8 @@ LAST( *Output*: same type as the input -.Description: - -It's the inverse of <>. Returns the last **non-NULL** value (if such exists) of the -`field_name`input column sorted descending by the `ordering_field_name` column. If `ordering_field_name` is not +*Description*: It's the inverse of <>. Returns the last **non-NULL** value (if such exists) of the +`field_name` input column sorted descending by the `ordering_field_name` column. If `ordering_field_name` is not provided, only the `field_name` column is used for the sorting. E.g.: [cols="<,<"] @@ -322,9 +310,7 @@ MAX(field_name) <1> *Output*: same type as the input -.Description: - -Returns the maximum value across input values in the field `field_name`. +*Description*: Returns the maximum value across input values in the field `field_name`. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -350,9 +336,7 @@ MIN(field_name) <1> *Output*: same type as the input -.Description: - -Returns the minimum value across input values in the field `field_name`. +*Description*: Returns the minimum value across input values in the field `field_name`. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -378,9 +362,7 @@ SUM(field_name) <1> *Output*: `bigint` for integer input, `double` for floating points -.Description: - -Returns the sum of input values in the field `field_name`. +*Description*: Returns the sum of input values in the field `field_name`. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -406,7 +388,7 @@ KURTOSIS(field_name) <1> *Output*: `double` numeric value -.Description: +*Description*: https://en.wikipedia.org/wiki/Kurtosis[Quantify] the shape of the distribution of input values in the field `field_name`. @@ -430,7 +412,7 @@ MAD(field_name) <1> *Output*: `double` numeric value -.Description: +*Description*: https://en.wikipedia.org/wiki/Median_absolute_deviation[Measure] the variability of the input values in the field `field_name`. @@ -457,7 +439,7 @@ PERCENTILE( *Output*: `double` numeric value -.Description: +*Description*: Returns the nth https://en.wikipedia.org/wiki/Percentile[percentile] (represented by `numeric_exp` parameter) of input values in the field `field_name`. @@ -485,7 +467,7 @@ PERCENTILE_RANK( *Output*: `double` numeric value -.Description: +*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`. @@ -510,7 +492,7 @@ SKEWNESS(field_name) <1> *Output*: `double` numeric value -.Description: +*Description*: https://en.wikipedia.org/wiki/Skewness[Quantify] the asymmetric distribution of input values in the field `field_name`. @@ -534,7 +516,7 @@ STDDEV_POP(field_name) <1> *Output*: `double` numeric value -.Description: +*Description*: Returns the https://en.wikipedia.org/wiki/Standard_deviations[population standard deviation] of input values in the field `field_name`. @@ -558,7 +540,7 @@ SUM_OF_SQUARES(field_name) <1> *Output*: `double` numeric value -.Description: +*Description*: Returns the https://en.wikipedia.org/wiki/Total_sum_of_squares[sum of squares] of input values in the field `field_name`. @@ -582,7 +564,7 @@ VAR_POP(field_name) <1> *Output*: `double` numeric value -.Description: +*Description*: Returns the https://en.wikipedia.org/wiki/Variance[population variance] of input values in the field `field_name`. diff --git a/docs/reference/sql/functions/conditional.asciidoc b/docs/reference/sql/functions/conditional.asciidoc index 630943f42fe20..c07d761f91523 100644 --- a/docs/reference/sql/functions/conditional.asciidoc +++ b/docs/reference/sql/functions/conditional.asciidoc @@ -26,9 +26,7 @@ an _ELSE *default_result_* clause. Every *condition* should be a boolean express the *default_result* if all _WHEN *condition_* clauses evaluate to `false`. If the optional _ELSE *default_result_* clause is missing and all _WHEN *condition_* clauses evaluate to `false` then `null` is returned. -.Description - -The CASE expression is a generic conditional expression which simulates if/else statements of other programming languages +*Description*: The CASE expression is a generic conditional expression which simulates if/else statements of other programming languages If the condition’s result is true, the value of the result expression that follows the condition will be the returned the subsequent when clauses will be skipped and not processed. @@ -148,9 +146,7 @@ COALESCE can take an arbitrary number of arguments. *Output*: one of the expressions or `null` -.Description - -Returns the first of its arguments that is not null. +*Description*: Returns the first of its arguments that is not null. If all arguments are null, then it returns `null`. @@ -192,9 +188,7 @@ 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. +*Description*: Returns the argument that has the largest value which is not null. If all arguments are null, then it returns `null`. @@ -229,9 +223,7 @@ IFNULL( *Output*: 2nd expression if 1st expression is null, otherwise 1st expression. -.Description - -Variant of <> with only two arguments. +*Description*: Variant of <> with only two arguments. Returns the first of its arguments that is not null. If all arguments are null, then it returns `null`. @@ -270,9 +262,7 @@ IIF( *Output*: 2nd expression if 1st expression (condition) evaluates to `true`. If it evaluates to `false` return 3rd expression. If 3rd expression is not provided return `null`. -.Description - -Conditional function that implements the standard _IF THEN ELSE _ +*Description*: Conditional function that implements the standard _IF THEN ELSE _ logic of programming languages. If the 3rd expression is not provided and the condition evaluates to `false`, `null` is returned. @@ -317,9 +307,7 @@ ISNULL( *Output*: 2nd expression if 1st expression is null, otherwise 1st expression. -.Description - -Variant of <> with only two arguments. +*Description*: Variant of <> with only two arguments. Returns the first of its arguments that is not null. If all arguments are null, then it returns `null`. @@ -363,9 +351,7 @@ all of them must be of the same data type. *Output*: one of the expressions or `null` -.Description - -Returns the argument that has the smallest value which is not null. +*Description*: Returns the argument that has the smallest value which is not null. If all arguments are null, then it returns `null`. @@ -401,9 +387,7 @@ NULLIF( *Output*: `null` if the 2 expressions are equal, otherwise the 1st expression. -.Description - -Returns `null` when the two input expressions are equal and +*Description*: Returns `null` when the two input expressions are equal and if not, it returns the 1st expression. @@ -438,9 +422,7 @@ NVL( *Output*: 2nd expression if 1st expression is null, otherwise 1st expression. -.Description - -Variant of <> with only two arguments. +*Description*: Variant of <> with only two arguments. Returns the first of its arguments that is not null. If all arguments are null, then it returns `null`. diff --git a/docs/reference/sql/functions/date-time.asciidoc b/docs/reference/sql/functions/date-time.asciidoc index 74a58da8fa358..6a9b0c6f8a8e3 100644 --- a/docs/reference/sql/functions/date-time.asciidoc +++ b/docs/reference/sql/functions/date-time.asciidoc @@ -106,9 +106,7 @@ CURDATE() *Output*: date -.Description: - -Returns the date (no time part) when the current query reached the server. +*Description*: Returns the date (no time part) when the current query reached the server. It can be used both as a keyword: `CURRENT_DATE` or as a function with no arguments: `CURRENT_DATE()`. [NOTE] @@ -156,9 +154,7 @@ CURTIME *Output*: time -.Description: - -Returns the time when the current query reached the server. +*Description*: Returns the time when the current query reached the server. As a function, `CURRENT_TIME()` accepts _precision_ as an optional parameter for rounding the second fractional digits (nanoseconds). The default _precision_ is 3, meaning a milliseconds precision current time will be returned. @@ -212,9 +208,7 @@ CURRENT_TIMESTAMP([precision]) <1> *Output*: date/time -.Description: - -Returns the date/time when the current query reached the server. +*Description*: Returns the date/time when the current query reached the server. As a function, `CURRENT_TIMESTAMP()` accepts _precision_ as an optional parameter for rounding the second fractional digits (nanoseconds). The default _precision_ is 3, meaning a milliseconds precision current date/time will be returned. @@ -269,9 +263,7 @@ if a negative value is used it results to a subtraction from the date/datetime *Output*: datetime -.Description: - -Add the given number of date/time units to a date/datetime. If the number of units is negative then it's subtracted from +*Description*: Add the given number of date/time units to a date/datetime. If the number of units is negative then it's subtracted from the date/datetime. If any of the three arguments is `null` a `null` is returned. [WARNING] @@ -346,9 +338,7 @@ DATE_DIFF( *Output*: integer -.Description: - -Subtract the second argument from the third argument and return their difference in multiples of the unit +*Description*: Subtract the second argument from the third argument and return their difference in multiples of the unit specified in the first argument. If the second argument (start) is greater than the third argument (end), then negative values are returned. If any of the three arguments is `null`, a `null` is returned. @@ -432,9 +422,7 @@ DATE_PART( *Output*: integer -.Description: - -Extract the specified unit from a date/datetime. If any of the two arguments is `null` a `null` is returned. +*Description*: Extract the specified unit from a date/datetime. If any of the two arguments is `null` a `null` is returned. It's similar to <> but with different names and aliases for the units and provides more options (e.g.: `TZOFFSET`). @@ -522,9 +510,7 @@ DATE_TRUNC( *Output*: datetime -.Description: - -Truncate the date/datetime to the specified unit by setting all fields that are less significant than the specified +*Description*: Truncate the date/datetime to the specified unit by setting all fields that are less significant than the specified one to zero (or one, for day, day of week and month). If any of the two arguments is `null` a `null` is returned. [cols="^,^"] @@ -592,9 +578,7 @@ DAY_OF_MONTH(datetime_exp) <1> *Output*: integer -.Description: - -Extract the day of the month from a date/datetime. +*Description*: Extract the day of the month from a date/datetime. [source, sql] -------------------------------------------------- @@ -616,9 +600,7 @@ DAY_OF_WEEK(datetime_exp) <1> *Output*: integer -.Description: - -Extract the day of the week from a date/datetime. Sunday is `1`, Monday is `2`, etc. +*Description*: Extract the day of the week from a date/datetime. Sunday is `1`, Monday is `2`, etc. [source, sql] -------------------------------------------------- @@ -640,9 +622,7 @@ DAY_OF_YEAR(datetime_exp) <1> *Output*: integer -.Description: - -Extract the day of the year from a date/datetime. +*Description*: Extract the day of the year from a date/datetime. [source, sql] -------------------------------------------------- @@ -664,9 +644,7 @@ DAY_NAME(datetime_exp) <1> *Output*: string -.Description: - -Extract the day of the week from a date/datetime in text format (`Monday`, `Tuesday`...). +*Description*: Extract the day of the week from a date/datetime in text format (`Monday`, `Tuesday`...). [source, sql] -------------------------------------------------- @@ -688,9 +666,7 @@ HOUR_OF_DAY(datetime_exp) <1> *Output*: integer -.Description: - -Extract the hour of the day from a date/datetime. +*Description*: Extract the hour of the day from a date/datetime. [source, sql] -------------------------------------------------- @@ -712,9 +688,7 @@ ISO_DAY_OF_WEEK(datetime_exp) <1> *Output*: integer -.Description: - -Extract the day of the week from a date/datetime, following the https://en.wikipedia.org/wiki/ISO_week_date[ISO 8601 standard]. +*Description*: Extract the day of the week from a date/datetime, following the https://en.wikipedia.org/wiki/ISO_week_date[ISO 8601 standard]. Monday is `1`, Tuesday is `2`, etc. [source, sql] @@ -737,9 +711,7 @@ ISO_WEEK_OF_YEAR(datetime_exp) <1> *Output*: integer -.Description: - -Extract the week of the year from a date/datetime, following https://en.wikipedia.org/wiki/ISO_week_date[ISO 8601 standard]. The first week +*Description*: Extract the week of the year from a date/datetime, following https://en.wikipedia.org/wiki/ISO_week_date[ISO 8601 standard]. The first week of a year is the first week with a majority (4 or more) of its days in January. [source, sql] @@ -762,9 +734,7 @@ MINUTE_OF_DAY(datetime_exp) <1> *Output*: integer -.Description: - -Extract the minute of the day from a date/datetime. +*Description*: Extract the minute of the day from a date/datetime. [source, sql] -------------------------------------------------- @@ -786,9 +756,7 @@ MINUTE_OF_HOUR(datetime_exp) <1> *Output*: integer -.Description: - -Extract the minute of the hour from a date/datetime. +*Description*: Extract the minute of the hour from a date/datetime. [source, sql] -------------------------------------------------- @@ -810,9 +778,7 @@ MONTH(datetime_exp) <1> *Output*: integer -.Description: - -Extract the month of the year from a date/datetime. +*Description*: Extract the month of the year from a date/datetime. [source, sql] -------------------------------------------------- @@ -834,9 +800,7 @@ MONTH_NAME(datetime_exp) <1> *Output*: string -.Description: - -Extract the month from a date/datetime in text format (`January`, `February`...). +*Description*: Extract the month from a date/datetime in text format (`January`, `February`...). [source, sql] -------------------------------------------------- @@ -856,9 +820,7 @@ NOW() *Output*: datetime -.Description: - -This function offers the same functionality as <> function: returns +*Description*: This function offers the same functionality as <> function: returns the datetime when the current query reached the server. This method always returns the same value for its every occurrence within the same query. @@ -890,9 +852,7 @@ SECOND_OF_MINUTE(datetime_exp) <1> *Output*: integer -.Description: - -Extract the second of the minute from a date/datetime. +*Description*: Extract the second of the minute from a date/datetime. [source, sql] -------------------------------------------------- @@ -914,9 +874,7 @@ QUARTER(datetime_exp) <1> *Output*: integer -.Description: - -Extract the year quarter the date/datetime falls in. +*Description*: Extract the year quarter the date/datetime falls in. [source, sql] -------------------------------------------------- @@ -936,9 +894,7 @@ TODAY() *Output*: date -.Description: - -This function offers the same functionality as <> function: returns +*Description*: This function offers the same functionality as <> function: returns the date when the current query reached the server. This method always returns the same value for its every occurrence within the same query. @@ -970,9 +926,7 @@ WEEK_OF_YEAR(datetime_exp) <1> *Output*: integer -.Description: - -Extract the week of the year from a date/datetime. +*Description*: Extract the week of the year from a date/datetime. [source, sql] -------------------------------------------------- @@ -994,9 +948,7 @@ YEAR(datetime_exp) <1> *Output*: integer -.Description: - -Extract the year from a date/datetime. +*Description*: Extract the year from a date/datetime. [source, sql] -------------------------------------------------- @@ -1021,9 +973,7 @@ EXTRACT( *Output*: integer -.Description: - -Extract fields from a date/datetime by specifying the name of a <>. +*Description*: Extract fields from a date/datetime by specifying the name of a <>. The following [source, sql] diff --git a/docs/reference/sql/functions/geo.asciidoc b/docs/reference/sql/functions/geo.asciidoc index c90d833919ea0..fe1c2f28bdf9a 100644 --- a/docs/reference/sql/functions/geo.asciidoc +++ b/docs/reference/sql/functions/geo.asciidoc @@ -39,9 +39,7 @@ ST_AsWKT( *Output*: string -.Description: - -Returns the WKT representation of the `geometry`. +*Description*: Returns the WKT representation of the `geometry`. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -66,9 +64,7 @@ ST_WKTToSQL( *Output*: geometry -.Description: - -Returns the geometry from WKT representation. +*Description*: Returns the geometry from WKT representation. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -94,9 +90,7 @@ ST_GeometryType( *Output*: string -.Description: - -Returns the type of the `geometry` such as POINT, MULTIPOINT, LINESTRING, MULTILINESTRING, POLYGON, MULTIPOLYGON, GEOMETRYCOLLECTION, ENVELOPE or CIRCLE. +*Description*: Returns the type of the `geometry` such as POINT, MULTIPOINT, LINESTRING, MULTILINESTRING, POLYGON, MULTIPOLYGON, GEOMETRYCOLLECTION, ENVELOPE or CIRCLE. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -120,9 +114,7 @@ ST_X( *Output*: double -.Description: - -Returns the longitude of the first point in the geometry. +*Description*: Returns the longitude of the first point in the geometry. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -146,9 +138,7 @@ ST_Y( *Output*: double -.Description: - -Returns the latitude of the first point in the geometry. +*Description*: Returns the latitude of the first point in the geometry. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -172,9 +162,7 @@ ST_Z( *Output*: double -.Description: - -Returns the altitude of the first point in the geometry. +*Description*: Returns the altitude of the first point in the geometry. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -200,9 +188,7 @@ ST_Distance( *Output*: Double -.Description: - -Returns the distance between geometries in meters. Both geometries have to be points. +*Description*: Returns the distance between geometries in meters. Both geometries have to be points. ["source","sql",subs="attributes,macros"] -------------------------------------------------- diff --git a/docs/reference/sql/functions/grouping.asciidoc b/docs/reference/sql/functions/grouping.asciidoc index 2a2f61790fb66..fe0f4c08d8ca2 100644 --- a/docs/reference/sql/functions/grouping.asciidoc +++ b/docs/reference/sql/functions/grouping.asciidoc @@ -30,16 +30,15 @@ HISTOGRAM( *Output*: non-empty buckets or groups of the given expression divided according to the given interval -.Description - -The histogram function takes all matching values and divides them into buckets with fixed size matching the given interval, using (roughly) the following formula: +*Description*: The histogram function takes all matching values and divides them into buckets with fixed size matching the given interval, using (roughly) the following formula: [source, sql] ---- bucket_key = Math.floor(value / interval) * interval ---- -NOTE:: The histogram in SQL does *NOT* return empty buckets for missing intervals as the traditional <> and <>. Such behavior does not fit conceptually in SQL which treats all missing values as `NULL`; as such the histogram places all missing values in the `NULL` group. +[NOTE] +The histogram in SQL does *NOT* return empty buckets for missing intervals as the traditional <> and <>. Such behavior does not fit conceptually in SQL which treats all missing values as `NULL`; as such the histogram places all missing values in the `NULL` group. `Histogram` can be applied on either numeric fields: diff --git a/docs/reference/sql/functions/like-rlike.asciidoc b/docs/reference/sql/functions/like-rlike.asciidoc index 2d5ef0b62f93f..6ca81d73f930a 100644 --- a/docs/reference/sql/functions/like-rlike.asciidoc +++ b/docs/reference/sql/functions/like-rlike.asciidoc @@ -27,9 +27,7 @@ LIKE constant_exp <2> <1> typically a field, or a constant expression <2> pattern -.Description: - -The SQL `LIKE` operator is used to compare a value to similar values using wildcard operators. There are two wildcards used in conjunction +*Description*: The SQL `LIKE` operator is used to compare a value to similar values using wildcard operators. There are two wildcards used in conjunction with the `LIKE` operator: * The percent sign (%) @@ -67,9 +65,7 @@ RLIKE constant_exp <2> <1> typically a field, or a constant expression <2> pattern -.Description: - -This operator is similar to `LIKE`, but the user is not limited to search for a string based on a fixed pattern with the percent sign (`%`) +*Description*: This operator is similar to `LIKE`, but the user is not limited to search for a string based on a fixed pattern with the percent sign (`%`) and underscore (`_`); the pattern in this case is a regular expression which allows the construction of more flexible patterns. For more details about the regular expressions syntax, https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html[Java's Pattern class javadoc] diff --git a/docs/reference/sql/functions/math.asciidoc b/docs/reference/sql/functions/math.asciidoc index 8f5a24b3a1d93..e54644d75a9bb 100644 --- a/docs/reference/sql/functions/math.asciidoc +++ b/docs/reference/sql/functions/math.asciidoc @@ -25,9 +25,7 @@ ABS(numeric_exp) <1> *Output*: numeric -.Description: - -Returns the https://en.wikipedia.org/wiki/Absolute_value[absolute value] of `numeric_exp`. The return type is the same as the input type. +*Description*: Returns the https://en.wikipedia.org/wiki/Absolute_value[absolute value] of `numeric_exp`. The return type is the same as the input type. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -49,9 +47,7 @@ CBRT(numeric_exp) <1> *Output*: double numeric value -.Description: - -Returns the https://en.wikipedia.org/wiki/Cube_root[cube root] of `numeric_exp`. +*Description*: Returns the https://en.wikipedia.org/wiki/Cube_root[cube root] of `numeric_exp`. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -73,9 +69,7 @@ CEIL(numeric_exp) <1> *Output*: integer or long numeric value -.Description: - -Returns the smallest integer greater than or equal to `numeric_exp`. +*Description*: Returns the smallest integer greater than or equal to `numeric_exp`. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -95,9 +89,7 @@ E() *Output*: `2.718281828459045` -.Description: - -Returns https://en.wikipedia.org/wiki/E_%28mathematical_constant%29[Euler's number]. +*Description*: Returns https://en.wikipedia.org/wiki/E_%28mathematical_constant%29[Euler's number]. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -119,9 +111,7 @@ EXP(numeric_exp) <1> *Output*: double numeric value -.Description: - -Returns https://en.wikipedia.org/wiki/Exponential_function[Euler's number at the power] of `numeric_exp` e^numeric_exp^. +*Description*: Returns https://en.wikipedia.org/wiki/Exponential_function[Euler's number at the power] of `numeric_exp` e^numeric_exp^. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -143,9 +133,7 @@ EXPM1(numeric_exp) <1> *Output*: double numeric value -.Description: - -Returns https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#expm1-double-[Euler's number at the power] of `numeric_exp` minus 1 (e^numeric_exp^ - 1). +*Description*: Returns https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#expm1-double-[Euler's number at the power] of `numeric_exp` minus 1 (e^numeric_exp^ - 1). ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -167,9 +155,7 @@ FLOOR(numeric_exp) <1> *Output*: integer or long numeric value -.Description: - -Returns the largest integer less than or equal to `numeric_exp`. +*Description*: Returns the largest integer less than or equal to `numeric_exp`. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -191,9 +177,7 @@ LOG(numeric_exp) <1> *Output*: double numeric value -.Description: - -Returns the https://en.wikipedia.org/wiki/Natural_logarithm[natural logarithm] of `numeric_exp`. +*Description*: Returns the https://en.wikipedia.org/wiki/Natural_logarithm[natural logarithm] of `numeric_exp`. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -215,9 +199,7 @@ LOG10(numeric_exp) <1> *Output*: double numeric value -.Description: - -Returns the https://en.wikipedia.org/wiki/Common_logarithm[base 10 logarithm] of `numeric_exp`. +*Description*: Returns the https://en.wikipedia.org/wiki/Common_logarithm[base 10 logarithm] of `numeric_exp`. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -237,9 +219,7 @@ PI() *Output*: `3.141592653589793` -.Description: - -Returns https://en.wikipedia.org/wiki/Pi[PI number]. +*Description*: Returns https://en.wikipedia.org/wiki/Pi[PI number]. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -264,9 +244,7 @@ POWER( *Output*: double numeric value -.Description: - -Returns the value of `numeric_exp` to the power of `integer_exp`. +*Description*: Returns the value of `numeric_exp` to the power of `integer_exp`. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -293,9 +271,7 @@ RANDOM(seed) <1> *Output*: double numeric value -.Description: - -Returns a random double using the given seed. +*Description*: Returns a random double using the given seed. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -319,8 +295,7 @@ ROUND( *Output*: numeric -.Description: -Returns `numeric_exp` rounded to `integer_exp` places right of the decimal point. If `integer_exp` is negative, +*Description*: Returns `numeric_exp` rounded to `integer_exp` places right of the decimal point. If `integer_exp` is negative, `numeric_exp` is rounded to |`integer_exp`| places to the left of the decimal point. If `integer_exp` is omitted, the function will perform as if `integer_exp` would be 0. The returned numeric data type is the same as the data type of `numeric_exp`. @@ -350,9 +325,7 @@ SIGN(numeric_exp) <1> *Output*: [-1, 0, 1] -.Description: - -Returns an indicator of the sign of `numeric_exp`. If `numeric_exp` is less than zero, –1 is returned. If `numeric_exp` equals zero, 0 is returned. If `numeric_exp` is greater than zero, 1 is returned. +*Description*: Returns an indicator of the sign of `numeric_exp`. If `numeric_exp` is less than zero, –1 is returned. If `numeric_exp` equals zero, 0 is returned. If `numeric_exp` is greater than zero, 1 is returned. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -375,9 +348,7 @@ SQRT(numeric_exp) <1> *Output*: double numeric value -.Description: - -Returns https://en.wikipedia.org/wiki/Square_root[square root] of `numeric_exp`. +*Description*: Returns https://en.wikipedia.org/wiki/Square_root[square root] of `numeric_exp`. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -401,8 +372,7 @@ TRUNCATE( *Output*: numeric -.Description: -Returns `numeric_exp` truncated to `integer_exp` places right of the decimal point. If `integer_exp` is negative, +*Description*: Returns `numeric_exp` truncated to `integer_exp` places right of the decimal point. If `integer_exp` is negative, `numeric_exp` is truncated to |`integer_exp`| places to the left of the decimal point. If `integer_exp` is omitted, the function will perform as if `integer_exp` would be 0. The returned numeric data type is the same as the data type of `numeric_exp`. @@ -436,9 +406,7 @@ ACOS(numeric_exp) <1> *Output*: double numeric value -.Description: - -Returns the https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arccosine] of `numeric_exp` as an angle, expressed in radians. +*Description*: Returns the https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arccosine] of `numeric_exp` as an angle, expressed in radians. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -460,9 +428,7 @@ ASIN(numeric_exp) <1> *Output*: double numeric value -.Description: - -Returns the https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arcsine] of `numeric_exp` as an angle, expressed in radians. +*Description*: Returns the https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arcsine] of `numeric_exp` as an angle, expressed in radians. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -484,9 +450,7 @@ ATAN(numeric_exp) <1> *Output*: double numeric value -.Description: - -Returns the https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arctangent] of `numeric_exp` as an angle, expressed in radians. +*Description*: Returns the https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arctangent] of `numeric_exp` as an angle, expressed in radians. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -511,9 +475,7 @@ ATAN2( *Output*: double numeric value -.Description: - -Returns the https://en.wikipedia.org/wiki/Atan2[arctangent of the `ordinate` and `abscisa` coordinates] specified as an angle, expressed in radians. +*Description*: Returns the https://en.wikipedia.org/wiki/Atan2[arctangent of the `ordinate` and `abscisa` coordinates] specified as an angle, expressed in radians. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -535,9 +497,7 @@ COS(numeric_exp) <1> *Output*: double numeric value -.Description: - -Returns the https://en.wikipedia.org/wiki/Trigonometric_functions#cosine[cosine] of `numeric_exp`, where `numeric_exp` is an angle expressed in radians. +*Description*: Returns the https://en.wikipedia.org/wiki/Trigonometric_functions#cosine[cosine] of `numeric_exp`, where `numeric_exp` is an angle expressed in radians. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -559,9 +519,7 @@ COSH(numeric_exp) <1> *Output*: double numeric value -.Description: - -Returns the https://en.wikipedia.org/wiki/Hyperbolic_function[hyperbolic cosine] of `numeric_exp`. +*Description*: Returns the https://en.wikipedia.org/wiki/Hyperbolic_function[hyperbolic cosine] of `numeric_exp`. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -583,9 +541,7 @@ COT(numeric_exp) <1> *Output*: double numeric value -.Description: - -Returns the https://en.wikipedia.org/wiki/Trigonometric_functions#Cosecant,_secant,_and_cotangent[cotangent] of `numeric_exp`, where `numeric_exp` is an angle expressed in radians. +*Description*: Returns the https://en.wikipedia.org/wiki/Trigonometric_functions#Cosecant,_secant,_and_cotangent[cotangent] of `numeric_exp`, where `numeric_exp` is an angle expressed in radians. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -607,9 +563,7 @@ DEGREES(numeric_exp) <1> *Output*: double numeric value -.Description: - -Convert from https://en.wikipedia.org/wiki/Radian[radians] +*Description*: Convert from https://en.wikipedia.org/wiki/Radian[radians] to https://en.wikipedia.org/wiki/Degree_(angle)[degrees]. ["source","sql",subs="attributes,macros"] @@ -632,9 +586,7 @@ RADIANS(numeric_exp) <1> *Output*: double numeric value -.Description: - -Convert from https://en.wikipedia.org/wiki/Degree_(angle)[degrees] +*Description*: Convert from https://en.wikipedia.org/wiki/Degree_(angle)[degrees] to https://en.wikipedia.org/wiki/Radian[radians]. ["source","sql",subs="attributes,macros"] @@ -657,9 +609,7 @@ SIN(numeric_exp) <1> *Output*: double numeric value -.Description: - -Returns the https://en.wikipedia.org/wiki/Trigonometric_functions#sine[sine] of `numeric_exp`, where `numeric_exp` is an angle expressed in radians. +*Description*: Returns the https://en.wikipedia.org/wiki/Trigonometric_functions#sine[sine] of `numeric_exp`, where `numeric_exp` is an angle expressed in radians. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -681,9 +631,7 @@ SINH(numeric_exp) <1> *Output*: double numeric value -.Description: - -Returns the https://en.wikipedia.org/wiki/Hyperbolic_function[hyperbolic sine] of `numeric_exp`. +*Description*: Returns the https://en.wikipedia.org/wiki/Hyperbolic_function[hyperbolic sine] of `numeric_exp`. ["source","sql",subs="attributes,macros"] -------------------------------------------------- @@ -705,9 +653,7 @@ TAN(numeric_exp) <1> *Output*: double numeric value -.Description: - -Returns the https://en.wikipedia.org/wiki/Trigonometric_functions#tangent[tangent] of `numeric_exp`, where `numeric_exp` is an angle expressed in radians. +*Description*: Returns the https://en.wikipedia.org/wiki/Trigonometric_functions#tangent[tangent] of `numeric_exp`, where `numeric_exp` is an angle expressed in radians. ["source","sql",subs="attributes,macros"] -------------------------------------------------- diff --git a/docs/reference/sql/functions/search.asciidoc b/docs/reference/sql/functions/search.asciidoc index 34716e070434f..db309c7adaa70 100644 --- a/docs/reference/sql/functions/search.asciidoc +++ b/docs/reference/sql/functions/search.asciidoc @@ -26,9 +26,7 @@ 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 <> +*Description*: A full-text search option, in the form of a predicate, available in {es-sql} that gives the user control over powerful <> and <> {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: @@ -83,9 +81,7 @@ QUERY( <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 in {es}. +*Description*: Just like `MATCH`, `QUERY` is a full-text search predicate that gives the user control over the <> 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: @@ -133,9 +129,7 @@ SCORE() *Output*: `double` numeric value -.Description: - -Returns the {defguide}/relevance-intro.html[relevance] of a given input to the executed query. +*Description*: Returns the {defguide}/relevance-intro.html[relevance] of a given input to the executed query. The higher score, the more relevant the data. NOTE: When doing multiple text queries in the `WHERE` clause then, their scores will be diff --git a/docs/reference/sql/functions/string.asciidoc b/docs/reference/sql/functions/string.asciidoc index a82ac66adce1c..cd3c854de983f 100644 --- a/docs/reference/sql/functions/string.asciidoc +++ b/docs/reference/sql/functions/string.asciidoc @@ -20,9 +20,7 @@ ASCII(string_exp) <1> *Output*: integer -.Description: - -Returns the ASCII code value of the leftmost character of `string_exp` as an integer. +*Description*: Returns the ASCII code value of the leftmost character of `string_exp` as an integer. [source, sql] -------------------------------------------------- @@ -43,9 +41,7 @@ BIT_LENGTH(string_exp) <1> *Output*: integer -.Description: - -Returns the length in bits of the `string_exp` input expression. +*Description*: Returns the length in bits of the `string_exp` input expression. [source, sql] -------------------------------------------------- @@ -66,9 +62,7 @@ CHAR(code) <1> *Output*: string -.Description: - -Returns the character that has the ASCII code value specified by the numeric input. The value should be between 0 and 255; otherwise, the return value is data source–dependent. +*Description*: Returns the character that has the ASCII code value specified by the numeric input. The value should be between 0 and 255; otherwise, the return value is data source–dependent. [source, sql] -------------------------------------------------- @@ -89,9 +83,7 @@ CHAR_LENGTH(string_exp) <1> *Output*: integer -.Description: - -Returns the length in characters of the input, if the string expression is of a character data type; otherwise, returns the length in bytes of the string expression (the smallest integer not less than the number of bits divided by 8). +*Description*: Returns the length in characters of the input, if the string expression is of a character data type; otherwise, returns the length in bytes of the string expression (the smallest integer not less than the number of bits divided by 8). [source, sql] -------------------------------------------------- @@ -115,9 +107,7 @@ CONCAT( *Output*: string -.Description: - -Returns a character string that is the result of concatenating `string_exp1` to `string_exp2`. If one of the string is `NULL`, the other string will be returned. +*Description*: Returns a character string that is the result of concatenating `string_exp1` to `string_exp2`. If one of the string is `NULL`, the other string will be returned. [source, sql] -------------------------------------------------- @@ -145,9 +135,7 @@ INSERT( *Output*: string -.Description: - -Returns a string where `length` characters have been deleted from `source`, beginning at `start`, and where `replacement` has been inserted into `source`, beginning at `start`. +*Description*: Returns a string where `length` characters have been deleted from `source`, beginning at `start`, and where `replacement` has been inserted into `source`, beginning at `start`. [source, sql] -------------------------------------------------- @@ -168,9 +156,7 @@ LCASE(string_exp) <1> *Output*: string -.Description: - -Returns a string equal to that in `string_exp`, with all uppercase characters converted to lowercase. +*Description*: Returns a string equal to that in `string_exp`, with all uppercase characters converted to lowercase. [source, sql] -------------------------------------------------- @@ -194,9 +180,7 @@ LEFT( *Output*: string -.Description: - -Returns the leftmost count characters of `string_exp`. +*Description*: Returns the leftmost count characters of `string_exp`. [source, sql] -------------------------------------------------- @@ -217,9 +201,7 @@ LENGTH(string_exp) <1> *Output*: integer -.Description: - -Returns the number of characters in `string_exp`, excluding trailing blanks. +*Description*: Returns the number of characters in `string_exp`, excluding trailing blanks. [source, sql] -------------------------------------------------- @@ -246,9 +228,7 @@ LOCATE( *Output*: integer -.Description: - -Returns the starting position of the first occurrence of `pattern` within `source`. The search for the first occurrence of `pattern` begins with the first character position in `source` unless the optional argument, `start`, is specified. If `start` is specified, the search begins with the character position indicated by the value of `start`. The first character position in `source` is indicated by the value 1. If `pattern` is not found within `source`, the value 0 is returned. +*Description*: Returns the starting position of the first occurrence of `pattern` within `source`. The search for the first occurrence of `pattern` begins with the first character position in `source` unless the optional argument, `start`, is specified. If `start` is specified, the search begins with the character position indicated by the value of `start`. The first character position in `source` is indicated by the value 1. If `pattern` is not found within `source`, the value 0 is returned. [source, sql] -------------------------------------------------- @@ -274,9 +254,7 @@ LTRIM(string_exp) <1> *Output*: string -.Description: - -Returns the characters of `string_exp`, with leading blanks removed. +*Description*: Returns the characters of `string_exp`, with leading blanks removed. [source, sql] -------------------------------------------------- @@ -297,9 +275,7 @@ OCTET_LENGTH(string_exp) <1> *Output*: integer -.Description: - -Returns the length in bytes of the `string_exp` input expression. +*Description*: Returns the length in bytes of the `string_exp` input expression. [source, sql] -------------------------------------------------- @@ -323,9 +299,7 @@ POSITION( *Output*: integer -.Description: - -Returns the position of the `string_exp1` in `string_exp2`. The result is an exact numeric. +*Description*: Returns the position of the `string_exp1` in `string_exp2`. The result is an exact numeric. [source, sql] -------------------------------------------------- @@ -349,9 +323,7 @@ REPEAT( *Output*: string -.Description: - -Returns a character string composed of `string_exp` repeated `count` times. +*Description*: Returns a character string composed of `string_exp` repeated `count` times. [source, sql] -------------------------------------------------- @@ -377,9 +349,7 @@ REPLACE( *Output*: string -.Description: - -Search `source` for occurrences of `pattern`, and replace with `replacement`. +*Description*: Search `source` for occurrences of `pattern`, and replace with `replacement`. [source, sql] -------------------------------------------------- @@ -403,9 +373,7 @@ RIGHT( *Output*: string -.Description: - -Returns the rightmost count characters of `string_exp`. +*Description*: Returns the rightmost count characters of `string_exp`. [source, sql] -------------------------------------------------- @@ -426,9 +394,7 @@ RTRIM(string_exp) <1> *Output*: string -.Description: - -Returns the characters of `string_exp` with trailing blanks removed. +*Description*: Returns the characters of `string_exp` with trailing blanks removed. [source, sql] -------------------------------------------------- @@ -449,9 +415,7 @@ SPACE(count) <1> *Output*: string -.Description: - -Returns a character string consisting of `count` spaces. +*Description*: Returns a character string consisting of `count` spaces. [source, sql] -------------------------------------------------- @@ -477,9 +441,7 @@ SUBSTRING( *Output*: string -.Description: - -Returns a character string that is derived from `source`, beginning at the character position specified by `start` for `length` characters. +*Description*: Returns a character string that is derived from `source`, beginning at the character position specified by `start` for `length` characters. [source, sql] -------------------------------------------------- @@ -500,9 +462,7 @@ UCASE(string_exp) <1> *Output*: string -.Description: - -Returns a string equal to that of the input, with all lowercase characters converted to uppercase. +*Description*: Returns a string equal to that of the input, with all lowercase characters converted to uppercase. [source, sql] -------------------------------------------------- diff --git a/docs/reference/sql/functions/system.asciidoc b/docs/reference/sql/functions/system.asciidoc index 8271d600c5022..f860a420eec75 100644 --- a/docs/reference/sql/functions/system.asciidoc +++ b/docs/reference/sql/functions/system.asciidoc @@ -18,9 +18,7 @@ DATABASE() *Output*: string -.Description: - -Returns the name of the database being queried. In the case of Elasticsearch SQL, this +*Description*: Returns the name of the database being queried. In the case of Elasticsearch SQL, this is the name of the Elasticsearch cluster. This function should always return a non-null value. @@ -41,9 +39,7 @@ USER() *Output*: string -.Description: - -Returns the username of the authenticated user executing the query. This function can +*Description*: Returns the username of the authenticated user executing the query. This function can return `null` in case <> is disabled. [source, sql] diff --git a/docs/reference/sql/functions/type-conversion.asciidoc b/docs/reference/sql/functions/type-conversion.asciidoc index c6c761305519e..2f4f44698a9fc 100644 --- a/docs/reference/sql/functions/type-conversion.asciidoc +++ b/docs/reference/sql/functions/type-conversion.asciidoc @@ -19,9 +19,7 @@ CAST( <1> Expression to cast <2> Target data type to cast to -.Description - -Casts the result of the given expression to the target <>. +*Description*: Casts the result of the given expression to the target <>. If the cast is not possible (for example because of target type is too narrow or because the value itself cannot be converted), the query fails. @@ -60,9 +58,7 @@ CONVERT( <1> Expression to convert <2> Target data type to convert to -.Description - -Works exactly like <> with slightly different syntax. +*Description*: Works exactly like <> with slightly different syntax. Moreover, apart from the standard <> it supports the corresponding https://docs.microsoft.com/en-us/sql/odbc/reference/appendixes/explicit-data-type-conversion-function?view=sql-server-2017[ODBC data types]. diff --git a/docs/reference/sql/language/syntax/commands/describe-table.asciidoc b/docs/reference/sql/language/syntax/commands/describe-table.asciidoc index 9aad578da479e..c400a35dcd704 100644 --- a/docs/reference/sql/language/syntax/commands/describe-table.asciidoc +++ b/docs/reference/sql/language/syntax/commands/describe-table.asciidoc @@ -3,7 +3,7 @@ [[sql-syntax-describe-table]] === DESCRIBE TABLE -.Synopsis +.Synopsis: [source, sql] ---- DESCRIBE @@ -26,9 +26,7 @@ DESC <1> single table identifier or double quoted es multi index <2> SQL LIKE pattern -.Description - -`DESC` and `DESCRIBE` are aliases to <>. +*Description*: `DESC` and `DESCRIBE` are aliases to <>. [source, sql] ---- diff --git a/docs/reference/sql/language/syntax/commands/select.asciidoc b/docs/reference/sql/language/syntax/commands/select.asciidoc index 0bfc81ee99ad8..c77db198ec4aa 100644 --- a/docs/reference/sql/language/syntax/commands/select.asciidoc +++ b/docs/reference/sql/language/syntax/commands/select.asciidoc @@ -3,7 +3,7 @@ [[sql-syntax-select]] === SELECT -.Synopsis +.Synopsis: [source, sql] ---- SELECT select_expr [, ...] @@ -16,9 +16,7 @@ SELECT select_expr [, ...] [ PIVOT ( aggregation_expr FOR column IN ( value [ [ AS ] alias ] [, ...] ) ) ] ---- -.Description - -Retrieves rows from zero or more tables. +*Description*: Retrieves rows from zero or more tables. The general execution of `SELECT` is as follows: diff --git a/docs/reference/sql/language/syntax/commands/show-columns.asciidoc b/docs/reference/sql/language/syntax/commands/show-columns.asciidoc index 9cb90af6b656f..106374dcb2801 100644 --- a/docs/reference/sql/language/syntax/commands/show-columns.asciidoc +++ b/docs/reference/sql/language/syntax/commands/show-columns.asciidoc @@ -3,7 +3,7 @@ [[sql-syntax-show-columns]] === SHOW COLUMNS -.Synopsis +.Synopsis: [source, sql] ---- SHOW COLUMNS [ FROM | IN ]? @@ -17,9 +17,7 @@ SHOW COLUMNS [ FROM | IN ]? See <> for more information about patterns. -.Description - -List the columns in table and their data type (and other attributes). +*Description*: List the columns in table and their data type (and other attributes). [source, sql] ---- diff --git a/docs/reference/sql/language/syntax/commands/show-functions.asciidoc b/docs/reference/sql/language/syntax/commands/show-functions.asciidoc index 8689788867c20..c7e1f32b97248 100644 --- a/docs/reference/sql/language/syntax/commands/show-functions.asciidoc +++ b/docs/reference/sql/language/syntax/commands/show-functions.asciidoc @@ -3,7 +3,7 @@ [[sql-syntax-show-functions]] === SHOW FUNCTIONS -.Synopsis +.Synopsis: [source, sql] ---- SHOW FUNCTIONS [LIKE pattern?]? <1> @@ -11,9 +11,7 @@ SHOW FUNCTIONS [LIKE pattern?]? <1> <1> SQL match pattern -.Description - -List all the SQL functions and their type. The `LIKE` clause can be used to restrict the list of names to the given pattern. +*Description*: List all the SQL functions and their type. The `LIKE` clause can be used to restrict the list of names to the given pattern. [source, sql] ---- diff --git a/docs/reference/sql/language/syntax/commands/show-tables.asciidoc b/docs/reference/sql/language/syntax/commands/show-tables.asciidoc index d5a40337713d4..7c6127a6bc3bb 100644 --- a/docs/reference/sql/language/syntax/commands/show-tables.asciidoc +++ b/docs/reference/sql/language/syntax/commands/show-tables.asciidoc @@ -3,7 +3,7 @@ [[sql-syntax-show-tables]] === SHOW TABLES -.Synopsis +.Synopsis: [source, sql] ---- SHOW TABLES @@ -20,9 +20,7 @@ See <> for more information about patterns. -.Description - -List the tables available to the current user and their type. +*Description*: List the tables available to the current user and their type. [source, sql] ---- diff --git a/docs/reference/sql/language/syntax/lexic/index.asciidoc b/docs/reference/sql/language/syntax/lexic/index.asciidoc index b1405f0c9cb70..5e784a4d495ad 100644 --- a/docs/reference/sql/language/syntax/lexic/index.asciidoc +++ b/docs/reference/sql/language/syntax/lexic/index.asciidoc @@ -121,7 +121,8 @@ SELECT "first_name" <1> <1> Double quotes `"` used for column and table identifiers <2> Single quotes `'` used for a string literal -NOTE:: to escape single or double quotes, one needs to use that specific quote one more time. For example, the literal `John's` can be escaped like +[NOTE] +To escape single or double quotes, one needs to use that specific quote one more time. For example, the literal `John's` can be escaped like `SELECT 'John''s' AS name`. The same goes for double quotes escaping - `SELECT 123 AS "test""number"` will display as a result a column with the name `test"number`. [[sql-syntax-special-chars]]