From 870a913217be6de41c4f0a91c9fa5493017c8554 Mon Sep 17 00:00:00 2001 From: Costin Leau Date: Wed, 13 Jun 2018 13:53:08 +0300 Subject: [PATCH] [DOC] Extend SQL docs Add overview section Add data type section Improve function section --- x-pack/docs/en/sql/functions/index.asciidoc | 50 ++++++++--- x-pack/docs/en/sql/getting-started.asciidoc | 2 +- x-pack/docs/en/sql/index.asciidoc | 18 +++- .../docs/en/sql/language/data-types.asciidoc | 89 ++++++++++++++++++- x-pack/docs/en/sql/overview.asciidoc | 30 +++++++ x-pack/docs/en/sql/standalone.asciidoc | 9 -- 6 files changed, 167 insertions(+), 31 deletions(-) create mode 100644 x-pack/docs/en/sql/overview.asciidoc delete mode 100644 x-pack/docs/en/sql/standalone.asciidoc diff --git a/x-pack/docs/en/sql/functions/index.asciidoc b/x-pack/docs/en/sql/functions/index.asciidoc index 7220c73623056..a4e7028cf39c3 100644 --- a/x-pack/docs/en/sql/functions/index.asciidoc +++ b/x-pack/docs/en/sql/functions/index.asciidoc @@ -1,9 +1,11 @@ [[sql-functions]] == Functions and Operators +{es-sql} provides a number of built-in operators and functions. + === Comparison Operators -Elasticsearch SQL supports the following comparison operators: +{es-sql} supports the following comparison operators: * Equality (`=`) @@ -12,7 +14,7 @@ Elasticsearch SQL supports the following comparison operators: include-tagged::{sql-specs}/filter.sql-spec[whereFieldEquality] -------------------------------------------------- -* Inequality (`<>` or `!=`) +* Inequality (`<>` or `!=` or `<=>`) ["source","sql",subs="attributes,callouts,macros"] -------------------------------------------------- @@ -43,7 +45,7 @@ include-tagged::{sql-specs}/filter.sql-spec[whereIsNotNullAndIsNull] === Logical Operators -Elasticsearch SQL supports the following logical operators: +{es-sql} supports the following logical operators: * `AND` @@ -69,7 +71,7 @@ include-tagged::{sql-specs}/filter.sql-spec[whereFieldEqualityNot] === Math Operators -Elasticsearch SQL supports the following math operators: +{es-sql} supports the following math operators: * Add (`+`) @@ -106,7 +108,7 @@ include-tagged::{sql-specs}/arithmetic.sql-spec[multiply] include-tagged::{sql-specs}/arithmetic.sql-spec[divide] -------------------------------------------------- -* https://en.wikipedia.org/wiki/Modulo_operation[Modulo] (`%`) +* https://en.wikipedia.org/wiki/Modulo_operation[Modulo] or Reminder(`%`) ["source","sql",subs="attributes,callouts,macros"] -------------------------------------------------- @@ -115,25 +117,49 @@ include-tagged::{sql-specs}/arithmetic.sql-spec[mod] === Math Functions -==== Basic -* https://en.wikipedia.org/wiki/Absolute_value[Absolute value] (`ABS`) +All math and trigonometric functions require their input (where applicable) +to be numeric. + +==== Generic + +* `ABS` + +https://en.wikipedia.org/wiki/Absolute_value[Absolute value], returns \[same type as input] ["source","sql",subs="attributes,callouts,macros"] -------------------------------------------------- include-tagged::{sql-specs}/math.sql-spec[abs] -------------------------------------------------- -* https://en.wikipedia.org/wiki/Rounding#Round_half_up[Round] (`ROUND`) +* `CBRT` + +https://en.wikipedia.org/wiki/Cube_root[Cube root], returns `double` // TODO make the example in the tests presentable -NOTE: This rounds "half up" meaning that `ROUND(-1.5)` results in `-1`. +* `CEIL` + +https://en.wikipedia.org/wiki/Floor_and_ceiling_functions[Ceiling], returns `double` -* https://en.wikipedia.org/wiki/Floor_and_ceiling_functions[Ceiling] (`CEIL`) +* `CEILING` + +Same as `CEIL` // TODO make the example in the tests presentable +* `E` + +https://en.wikipedia.org/wiki/E_%28mathematical_constant%29[Euler's number], returns `2.7182818284590452354` + + +* https://en.wikipedia.org/wiki/Rounding#Round_half_up[Round] (`ROUND`) + +// TODO make the example in the tests presentable + +NOTE: This rounds "half up" meaning that `ROUND(-1.5)` results in `-1`. + + * https://en.wikipedia.org/wiki/Floor_and_ceiling_functions[Floor] (`FLOOR`) // TODO make the example in the tests presentable @@ -159,10 +185,6 @@ include-tagged::{sql-specs}/math.sql-spec[log10] include-tagged::{sql-specs}/math.sql-spec[sqrt] -------------------------------------------------- -* https://en.wikipedia.org/wiki/Cube_root[Cube root] (`CBRT`) - -// TODO make the example in the tests presentable - * https://en.wikipedia.org/wiki/Exponential_function[e^x^] (`EXP`) ["source","sql",subs="attributes,callouts,macros"] diff --git a/x-pack/docs/en/sql/getting-started.asciidoc b/x-pack/docs/en/sql/getting-started.asciidoc index 966ac5336cfdd..24f01910551bb 100644 --- a/x-pack/docs/en/sql/getting-started.asciidoc +++ b/x-pack/docs/en/sql/getting-started.asciidoc @@ -1,7 +1,7 @@ [[sql-getting-started]] == Getting Started with SQL -To start using Elasticsearch SQL, create +To start using {es-sql}, create an index with some data to experiment with: [source,js] diff --git a/x-pack/docs/en/sql/index.asciidoc b/x-pack/docs/en/sql/index.asciidoc index 1be44b2d05965..902ea8ada7e22 100644 --- a/x-pack/docs/en/sql/index.asciidoc +++ b/x-pack/docs/en/sql/index.asciidoc @@ -6,6 +6,7 @@ :sql-specs: {sql-tests}/src/main/resources :jdbc-tests: {sql-tests}/src/main/java/org/elasticsearch/xpack/qa/sql/jdbc :security-tests: {sql-tests}/security/src/test/java/org/elasticsearch/xpack/qa/sql/security +:es-sql: Elasticsearch SQL [partintro] -- @@ -13,8 +14,12 @@ experimental[] X-Pack includes a SQL feature to execute SQL against Elasticsearch -indices and return tabular results. There are four main components: +indices and return results in tabular format. +<>:: + Overview of {es-sql} and its features. +<>:: + Start using SQL right away in {es} <>:: Accepts SQL in a JSON document, executes it, and returns the results. @@ -22,12 +27,19 @@ indices and return tabular results. There are four main components: Accepts SQL in a JSON document and translates it into a native Elasticsearch query and returns that. <>:: - Command line application that connects to Elasticsearch to execute + Command-line application that connects to {es} to execute SQL and print tabular results. <>:: - A JDBC driver for Elasticsearch. + A JDBC driver for {es}. +<>:: + List of functions and operators supported. +<>:: + Overview of the {es-sql} language, such as data types, syntax and + reserved keywords. + -- +include::overview.asciidoc[] include::getting-started.asciidoc[] include::endpoints/index.asciidoc[] include::functions/index.asciidoc[] diff --git a/x-pack/docs/en/sql/language/data-types.asciidoc b/x-pack/docs/en/sql/language/data-types.asciidoc index f97299eb0f243..322269bddaf8f 100644 --- a/x-pack/docs/en/sql/language/data-types.asciidoc +++ b/x-pack/docs/en/sql/language/data-types.asciidoc @@ -1,6 +1,87 @@ [[sql-data-types]] -=== Data Type and Mapping +=== Data Types + +Most of {es} <> are available in {es-sql}, as indicated below: + +[cols="^,^,^",options="header"] + +|=== +| {es} type | SQL type | SQL precision + +3+h| Core types + +| <> | `null` | 0 +| <> | `boolean` | 1 +| <> | `tinyint` | 3 +| <> | `smallint` | 5 +| <> | `integer` | 10 +| <> | `long` | 19 +| <> | `double` | 15 +| <> | `real` | 7 +| <> | `float` | 16 +| <> | `float` | 19 +| <> | `varchar` | based on <> +| <> | `varchar` | 2,147,483,647 +| <> | `varbinary` | 2,147,483,647 +| <> | `timestamp` | 24 + +3+h| Complex types + +| <> | `struct` | 0 +| <> | `struct` | 0 + +3+h| Unsupported types + +| _types not mentioned above_ | `unsupported`| 0 + +|=== + +Obviously, not all types in {es} have an equivalent in SQL and vice-versa hence why, {es-sql} +uses the data type _particularities_ of the former over the latter as ultimately {es} is the backing store. + + +[[sql-multi-field]] +[float] +==== SQL and multi-fields + +A core concept in {es} is that of an `analyzed` field, that is a full-text value that is interpreted in order +to be effectively indexed. These fields are of type <> and are not used for sorting or aggregations as their actual value depends on the <> used hence why {es} also offers the <> type for storing the _exact_ +value. + +In most case, and the default actually, is to use both types when for strings which {es} supports through <>, that is the ability to index the same string in multiple ways; for example index it both as `text` for search but also as `keyword` for sorting and aggregations. + +As SQL requires exact values, when encountering a `text` field {es-sql} will search for an exact multi-field that it can use for comparisons, sorting and aggregations. +To do that, it will search for the first `keyword` that it can find that is _not_ normalized and use that as the original field _exact_ value. + +Consider the following `string` mapping: + +[source, js] +---- +{ + "first_name" : { + "type" : "text", + "fields" : { + "raw" : { + "type" : "keyword" + } + } + } +} +---- + +The following SQL query: + +[source, sql] +---- +SELECT first_name FROM index WHERE first_name = 'John' +---- + +is identical to: + +[source, sql] +---- +SELECT first_name FROM index WHERE first_name.raw = 'John' +---- + +as {es-sql} automatically _picks_ up the `raw` multi-field from `raw` for exact matching. -// TODO finish this -List of data types in SQL and how they actually map to Elasticsearch. -Also mention the corner cases - multi-fields, names with dots, etc... diff --git a/x-pack/docs/en/sql/overview.asciidoc b/x-pack/docs/en/sql/overview.asciidoc new file mode 100644 index 0000000000000..34d0dfb538352 --- /dev/null +++ b/x-pack/docs/en/sql/overview.asciidoc @@ -0,0 +1,30 @@ +[[sql-overview]] +== Overview + +{es-sql} aims to provide a powerful yet lightweight SQL interface to {es}. + +[[sql-introduction]] +=== Introduction + +{es-sql} is an X-Pack component that allows SQL-like queries to be executed in real-time against {es}. +Whether using the REST interface, command-line or JDBC, any client can use SQL to search and aggregate data +_natively_ inside {es}. +One can think of {es-sql} as a _translator_, one that understands both SQL and {es} and makes it easy to read and process data in real-time, at scale by leveraging {es} capabilities. + +[[sql-why]] +=== Why {es-sql} ? + +Native integration:: + +{es-sql} is built from the ground up for {es}. Each and every query is efficiently executed against the relevant nodes according to the underlying storage. + +No external parts:: + +No need for additional hardware, processes, runtimes or libraries to query {es}; {es-sql} eliminates extra moving parts by running _inside_ the {es} cluster. + +Lightweight and efficient:: + +{es-sql} does not abstract {es} and its search capabilities - on the contrary, it embrases and exposes to SQL to allow proper full-text search, in real-time, in the same declarative, succint fashion. + + + diff --git a/x-pack/docs/en/sql/standalone.asciidoc b/x-pack/docs/en/sql/standalone.asciidoc deleted file mode 100644 index 6649ce9eb8de9..0000000000000 --- a/x-pack/docs/en/sql/standalone.asciidoc +++ /dev/null @@ -1,9 +0,0 @@ -[[elasticsearch-sql-standalone]] -= Elasticsearch SQL Standalone - -:es-repo-dir: {docdir}/../../../../../elasticsearch/docs - -:edit_url: -include::{es-repo-dir}/reference/index-shared3.asciidoc[] -:edit_url!: -include::index.asciidoc[]