[Docs] move files from Explore & Analyze -> SQL to Reference content

docs/reference/query-languages/sql.md

@@ -1,20 +1,60 @@
-# SQL
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-spec.html
+navigation_title: SQL
+---
 
-:::{note}
-This section provides detailed **reference information**.
+# SQL overview [sql-overview]
 
-Refer to [SQL overview](docs-content://explore-analyze/query-filter/languages/sql.md) in the **Explore and analyze** section for overview and conceptual information about the SQL query language.
-:::
+Elasticsearch SQL aims to provide a powerful yet lightweight SQL interface to {{es}}.
 
+## What's SQL in {{es}}? [sql-introduction]
 
-[SQL language](sql/sql-spec.md)
-:   SQL syntax and semantics
+Elasticsearch SQL is a feature 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 Elasticsearch 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.
 
-[Functions and operators](sql/sql-functions.md)
-:    Built-in functions and operators
+## Why Elasticsearch SQL ? [sql-why]
 
-[Reserved keywords](sql/sql-syntax-reserved.md)
-:   Keywords reserved for Elasticsearch SQL
+Native integration
+:   Elasticsearch 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}}; Elasticsearch SQL eliminates extra moving parts by running *inside* the {{es}} cluster.
+
+Lightweight and efficient
+:   Elasticsearch SQL does not abstract {{es}} and its search capabilities - on the contrary, it embraces and exposes SQL to allow proper full-text search, in real-time, in the same declarative, succinct fashion.
+
+The following chapters aim to cover everything from usage, to syntax and drivers. Experienced users might want to jump directly to the list of SQL [commands](elasticsearch://reference/query-languages/sql/sql-commands.md) and [functions](elasticsearch://reference/query-languages/sql/sql-functions.md).
+
+[Getting started](sql/sql-getting-started.md)
+:   Start using SQL right away in {{es}}.
+
+[Concepts and terminology](sql/sql-concepts.md)
+:   Language conventions across SQL and {{es}}.
+
+[Security](sql/sql-security.md)
+:   Secure Elasticsearch SQL and {{es}}.
+
+[REST API](sql/sql-rest.md)
+:   Execute SQL in JSON format over REST.
+
+[Translate API](sql/sql-translate.md)
+:   Translate SQL in JSON format to {{es}} native query.
+
+[JDBC](sql/sql-jdbc.md)
+:   JDBC driver for {{es}}.
+
+[ODBC](sql/sql-odbc.md)
+:   ODBC driver for {{es}}.
+
+[Client Applications](sql/sql-client-apps.md)
+:   Setup various SQL/BI tools with Elasticsearch SQL.
+
+[SQL Language](sql/sql-spec.md)
+:   Overview of the Elasticsearch SQL language, such as supported data types, commands and syntax.
+
+[Functions and Operators](sql/sql-functions.md)
+:   List of functions and operators supported.
+
+[Limitations](sql/sql-limitations.md)
+:   Elasticsearch SQL current limitations.
 
-[SQL limitations](sql/sql-limitations.md)
-:   Limitations for Elasticsearch SQL

docs/reference/query-languages/sql/sql-async.md

@@ -0,0 +1,125 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-async.html
+applies_to:
+  stack: ga
+  serverless: ga
+products:
+  - id: elasticsearch
+---
+
+# Run an async SQL search [sql-async]
+
+By default, SQL searches are synchronous. They wait for complete results before returning a response. However, results can take longer for searches across large data sets or [frozen data](docs-content://manage-data/lifecycle/data-tiers.md).
+
+To avoid long waits, run an async SQL search. Set `wait_for_completion_timeout` to a duration you’d like to wait for synchronous results.
+
+```console
+POST _sql?format=json
+{
+  "wait_for_completion_timeout": "2s",
+  "query": "SELECT * FROM library ORDER BY page_count DESC",
+  "fetch_size": 5
+}
+```
+
+If the search doesn’t finish within this period, the search becomes async. The API returns:
+
+* An `id` for the search.
+* An `is_partial` value of `true`, indicating the search results are incomplete.
+* An `is_running` value of `true`, indicating the search is still running in the background.
+
+For CSV, TSV, and TXT responses, the API returns these values in the respective `Async-ID`, `Async-partial`, and `Async-running` HTTP headers instead.
+
+```console-result
+{
+  "id": "FnR0TDhyWUVmUmVtWXRWZER4MXZiNFEad2F5UDk2ZVdTVHV1S0xDUy00SklUdzozMTU=",
+  "is_partial": true,
+  "is_running": true,
+  "rows": [ ]
+}
+```
+
+To check the progress of an async search, use the search ID with the [get async SQL search status API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-sql-get-async-status).
+
+```console
+GET _sql/async/status/FnR0TDhyWUVmUmVtWXRWZER4MXZiNFEad2F5UDk2ZVdTVHV1S0xDUy00SklUdzozMTU=
+```
+
+If `is_running` and `is_partial` are `false`, the async search has finished with complete results.
+
+```console-result
+{
+  "id": "FnR0TDhyWUVmUmVtWXRWZER4MXZiNFEad2F5UDk2ZVdTVHV1S0xDUy00SklUdzozMTU=",
+  "is_running": false,
+  "is_partial": false,
+  "expiration_time_in_millis": 1611690295000,
+  "completion_status": 200
+}
+```
+
+To get the results, use the search ID with the [get async SQL search API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-sql-get-async). If the search is still running, specify how long you’d like to wait using `wait_for_completion_timeout`. You can also specify the response `format`.
+
+```console
+GET _sql/async/FnR0TDhyWUVmUmVtWXRWZER4MXZiNFEad2F5UDk2ZVdTVHV1S0xDUy00SklUdzozMTU=?wait_for_completion_timeout=2s&format=json
+```
+
+
+## Change the search retention period [sql-async-retention]
+
+By default, {{es}} stores async SQL searches for five days. After this period, {{es}} deletes the search and its results, even if the search is still running. To change this retention period, use the `keep_alive` parameter.
+
+```console
+POST _sql?format=json
+{
+  "keep_alive": "2d",
+  "wait_for_completion_timeout": "2s",
+  "query": "SELECT * FROM library ORDER BY page_count DESC",
+  "fetch_size": 5
+}
+```
+
+You can use the get async SQL search API’s `keep_alive` parameter to later change the retention period. The new period starts after the request runs.
+
+```console
+GET _sql/async/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=?keep_alive=5d&wait_for_completion_timeout=2s&format=json
+```
+
+Use the [delete async SQL search API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-sql-delete-async) to delete an async search before the `keep_alive` period ends. If the search is still running, {{es}} cancels it.
+
+```console
+DELETE _sql/async/delete/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=
+```
+
+
+## Store synchronous SQL searches [sql-store-searches]
+
+By default, {{es}} only stores async SQL searches. To save a synchronous search, specify `wait_for_completion_timeout` and set `keep_on_completion` to `true`.
+
+```console
+POST _sql?format=json
+{
+  "keep_on_completion": true,
+  "wait_for_completion_timeout": "2s",
+  "query": "SELECT * FROM library ORDER BY page_count DESC",
+  "fetch_size": 5
+}
+```
+
+If `is_partial` and `is_running` are `false`, the search was synchronous and returned complete results.
+
+```console-result
+{
+  "id": "Fnc5UllQdUVWU0NxRFNMbWxNYXplaFEaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQTo0NzA=",
+  "is_partial": false,
+  "is_running": false,
+  "rows": ...,
+  "columns": ...,
+  "cursor": ...
+}
+```
+
+You can get the same results later using the search ID with the [get async SQL search API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-sql-get-async).
+
+Saved synchronous searches are still subject to the `keep_alive` retention period. When this period ends, {{es}} deletes the search results. You can also delete saved searches using the [delete async SQL search API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-sql-delete-async).
+

docs/reference/query-languages/sql/sql-cli.md

@@ -0,0 +1,153 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-cli.html
+applies_to:
+  stack: ga
+  serverless: ga
+products:
+  - id: elasticsearch
+---
+
+# SQL CLI [sql-cli]
+
+Elasticsearch ships with a script to run the SQL CLI in its `bin` directory:
+
+```bash
+$ ./bin/elasticsearch-sql-cli
+```
+
+You can pass the URL of the Elasticsearch instance to connect to as the first parameter:
+
+```bash
+$ ./bin/elasticsearch-sql-cli https://some.server:9200
+```
+
+If security is enabled on your cluster, you can pass the username and password in the form `username:password@host_name:port` to the SQL CLI:
+
+```bash
+$ ./bin/elasticsearch-sql-cli https://sql_user:[email protected]:9200
+```
+
+Once the CLI is running you can use any [query](elasticsearch://reference/query-languages/sql/sql-spec.md) that Elasticsearch supports:
+
+```sql
+sql> SELECT * FROM library WHERE page_count > 500 ORDER BY page_count DESC;
+     author      |        name        |  page_count   | release_date
+-----------------+--------------------+---------------+---------------
+Peter F. Hamilton|Pandora's Star      |768            |1078185600000
+Vernor Vinge     |A Fire Upon the Deep|613            |707356800000
+Frank Herbert    |Dune                |604            |-144720000000
+Alastair Reynolds|Revelation Space    |585            |953078400000
+James S.A. Corey |Leviathan Wakes     |561            |1306972800000
+```
+
+The jar containing the SQL CLI is a stand alone Java application and the scripts just launch it. You can move it around to other machines without having to install Elasticsearch on them. Without the already provided script files, you can use a command similar to the following to start the SQL CLI:
+
+```bash
+$ ./java -jar [PATH_TO_CLI_JAR]/elasticsearch-sql-cli-[VERSION].jar https://some.server:9200
+```
+
+or
+
+```bash
+$ ./java -cp [PATH_TO_CLI_JAR]/elasticsearch-sql-cli-[VERSION].jar org.elasticsearch.xpack.sql.cli.Cli https://some.server:9200
+```
+
+The jar name will be different for each Elasticsearch version (for example `elasticsearch-sql-cli-7.3.2.jar`), thus the generic `VERSION` specified in the example above. Furthermore, if not running the command from the folder where the SQL CLI jar resides, you’d have to provide the full path, as well.
+
+
+## CLI commands [cli-commands]
+
+Apart from SQL queries, CLI can also execute some specific commands:
+
+`allow_partial_search_results = <boolean>` (default `false`)
+:   If `true`, returns partial results if there are shard request timeouts or [shard failures](docs-content://deploy-manage/distributed-architecture/reading-and-writing-documents.md#shard-failures). If `false`, returns an error with no partial results.
+
+```sql
+sql> allow_partial_search_results = true;
+allow_partial_search_results set to true
+```
+
+`fetch_size = <number>` (default `1000`)
+:   Allows to change the size of fetches for query execution. Each fetch is delimited by fetch separator (if explicitly set).
+
+```sql
+sql> fetch_size = 2000;
+fetch size set to 2000
+```
+
+`fetch_separator = <string>` (empty string by default)
+:   Allows to change the separator string between fetches.
+
+```sql
+sql> fetch_separator = "---------------------";
+fetch separator set to "---------------------"
+```
+
+`lenient = <boolean>` (default `false`)
+:   If `false`, Elasticsearch SQL returns an error for fields containing [array values](elasticsearch://reference/elasticsearch/mapping-reference/array.md). If `true`, Elasticsearch SQL returns the first value from the array with no guarantee of consistent results.
+
+```sql
+sql> lenient = true;
+lenient set to true
+```
+
+`info`
+:   Returns server information.
+
+```sql
+sql> info;
+Node:mynode Cluster:elasticsearch Version:8.3
+```
+
+`exit`
+:   Closes the CLI.
+
+```sql
+sql> exit;
+Bye!
+```
+
+`cls`
+:   Clears the screen.
+
+```sql
+sql> cls;
+```
+
+`logo`
+:   Prints Elastic logo.
+
+```sql
+sql> logo;
+
+                       asticElasticE
+                     ElasticE  sticEla
+          sticEl  ticEl            Elast
+        lasti Elasti                   tic
+      cEl       ast                     icE
+     icE        as                       cEl
+     icE        as                       cEl
+     icEla     las                        El
+   sticElasticElast                     icElas
+ las           last                    ticElast
+El              asti                 asti    stic
+El              asticEla           Elas        icE
+El            Elas  cElasticE   ticEl           cE
+Ela        ticEl         ticElasti              cE
+ las     astic               last              icE
+   sticElas                   asti           stic
+     icEl                      sticElasticElast
+     icE                       sticE   ticEla
+     icE                       sti       cEla
+     icEl                      sti        Ela
+      cEl                      sti       cEl
+       Ela                    astic    ticE
+         asti               ElasticElasti
+           ticElasti  lasticElas
+              ElasticElast
+
+                       SQL
+                      8.3.0
+```
+