Add ydb sql documentation and update links to use new command where possible (#15262)

Co-authored-by: anton-bobkov <[email protected]>

Author: pnv1

ydb/docs/en/core/devops/deployment-options/kubernetes/initial-deployment.md

@@ -251,7 +251,7 @@ Check how {{ ydb-short-name }} works:
     ydb \
       --endpoint grpc://database-sample-grpc:2135 \
       --database /root/database-sample \
-      table query execute --query 'SELECT 2 + 2;'
+      sql -s 'SELECT 2 + 2;'
     ```
 
     * `--endpoint`: The database endpoint.

ydb/docs/en/core/recipes/ydb-cli/ttl.md

@@ -25,7 +25,7 @@ To enable data eviction, an [external data source](../../concepts/datamodel/exte
 The example below shows how to enable data eviction by executing a YQL-query from {{ ydb-short-name }} CLI. Rows of the table `mytable` will be moved to the bucket described in the external data source `/Root/s3_cold_data` one hour after the time recorded in the column `created_at` and will be deleted after 24 hours.
 
 ```bash
-$ {{ ydb-cli }} -e <endpoint> -d <database> table query execute -q '
+$ {{ ydb-cli }} -e <endpoint> -d <database> sql -s '
     ALTER TABLE `mytable` SET (
         TTL =
             Interval("PT1H") TO EXTERNAL DATA SOURCE `/Root/s3_cold_data`,

ydb/docs/en/core/reference/kafka-api/examples.md

@@ -110,7 +110,7 @@ Currently, the only available authentication mechanism with Kafka API in {{ ydb-
 
 To use authentication in a multinode self-deployed database:
 
-1. Create a user. [How to do this in YQL](../../yql/reference/syntax/create-user.md). [How to execute YQL from CLI](../ydb-cli/yql.md).
+1. Create a user. [How to do this in YQL](../../yql/reference/syntax/create-user.md). [How to execute YQL from CLI](../ydb-cli/sql.md).
 2. Connect to the Kafka API as shown in the examples below. In all examples, it is assumed that:
 
    - YDB is running locally with the environment variable `YDB_KAFKA_PROXY_PORT=9092`, meaning that the Kafka API is available at `localhost:9092`. For example, you can run YDB in Docker as described [here](../../quickstart.md#install).

ydb/docs/en/core/reference/ydb-cli/_includes/commands.md

@@ -52,15 +52,16 @@ Any command can be run from the command line with the `--help` option to get hel
 | [scheme permissions clear-inheritance](../commands/scheme-permissions.md#clear-inheritance) | Disable permission inheritance |
 | [scheme permissions set-inheritance](../commands/scheme-permissions.md#set-inheritance) | Enable permission inheritance |
 | [scheme rmdir](../commands/dir.md#rmdir) | Deleting a directory |
-| [scripting yql](../scripting-yql.md) | Executing a YQL script |
+| [scripting yql](../scripting-yql.md) | Executing a YQL script (deprecated, use [`ydb sql`](../sql.md)) |
+| [sql](../sql.md) | Execute any query |
 | table attribute add | Adding a table attribute |
 | table attribute drop | Deleting a table attribute |
 | [table drop](../table-drop.md) | Deleting a table |
 | [table index add global-async](../commands/secondary_index.md#add) | Adding an asynchronous index |
 | [table index add global-sync](../commands/secondary_index.md#add) | Adding a synchronous index |
 | [table index drop](../commands/secondary_index.md#drop) | Deleting an index |
-| [table query execute](../table-query-execute.md) | Executing a YQL query |
-| [table query explain](../commands/explain-plan.md) | YQL query execution plan |
+| [table query execute](../table-query-execute.md) | Executing a YQL query (deprecated, use [`ydb sql`](../sql.md)) |
+| [table query explain](../commands/explain-plan.md) | YQL query execution plan (deprecated, use [`ydb sql --explain`](../sql.md)) |
 | [table read](../commands/readtable.md) | Streaming table reads |
 | [table ttl set](../table-ttl-set.md) | Setting TTL parameters |
 | [table ttl reset](../table-ttl-reset.md) | Resetting TTL parameters |
@@ -77,8 +78,8 @@ Any command can be run from the command line with the `--help` option to get hel
 | [topic read](../topic-read.md) | Reading messages from a topic |
 | [topic write](../topic-write.md) | Writing messages to a topic |
 {% if ydb-cli == "ydb" %}
-[update](../commands/service.md) | Update the {{ ydb-short-name }} CLI
-[version](../commands/service.md) | Output details about the {{ ydb-short-name }} CLI version
+| [update](../commands/service.md) | Update the {{ ydb-short-name }} CLI |
+| [version](../commands/service.md) | Output details about the {{ ydb-short-name }} CLI version |
 {% endif %}
-[workload](../commands/workload/index.md) | Generate the workload
-[yql](../yql.md) | Execute a YQL script (with streaming support)
+| [workload](../commands/workload/index.md) | Generate the workload |
+| [yql](../yql.md) | Execute a YQL script (deprecated, use [`ydb sql`](../sql.md)) |

ydb/docs/en/core/reference/ydb-cli/_includes/deprecated_command_warning.md

@@ -0,0 +1,6 @@
+{% note warning %}
+
+This command is deprecated.
+The preferred way to run queries in {{ ydb-short-name }} CLI is to use the [`{{ ydb-cli }} sql`](../sql.md) command.
+
+{% endnote %}

ydb/docs/en/core/reference/ydb-cli/_includes/index.md

@@ -9,7 +9,7 @@ For a full description of {{ ydb-short-name }} CLI commands, see the following a
 * [List of objects](../commands/scheme-ls.md).
 * [Getting information about schema objects](../commands/scheme-describe.md).
 * [Working with directories](../commands/dir.md).
-* [YQL execution](../yql-query-overview.md).
+* [Query execution](../yql-query-overview.md).
 * [Streaming table reads](../commands/readtable.md).
 * [Working with secondary indexes](../commands/secondary_index.md).
 * [Getting a list of DB endpoints](../commands/discovery-list.md).

ydb/docs/en/core/reference/ydb-cli/commands/_includes/scan-query.md

@@ -1,5 +1,7 @@
 # Performing scan queries
 
+{% include notitle [warning](../../_includes/deprecated_command_warning.md) %}
+
 You can run a query using [Scan Queries](../../../../concepts/scan_query.md) via the {{ ydb-short-name }} CLI by adding the `-t scan` flag to the `{{ ydb-cli }} table query execute` command.
 
 Run the data query:

ydb/docs/en/core/reference/ydb-cli/commands/scheme-permissions.md

@@ -51,7 +51,7 @@ Additional parameters `[options...]`:
 Each right must be passed as a separate parameter, for example:
 
 ```bash
-{{ ydb-cli }} scheme permissions grant -p "ydb.access.grant" -p "ydb.generic.read" '/Root/db1/MyApp/Orders' testuser 
+{{ ydb-cli }} scheme permissions grant -p "ydb.access.grant" -p "ydb.generic.read" '/Root/db1/MyApp/Orders' testuser
 ```
 
 ## set
@@ -129,7 +129,7 @@ Parameters:
 For example, if you execute the command over the database state from the previous example [`list`](#list):
 
 ```bash
-{{ ydb-cli }} scheme permissions clear '/Root/db1/MyApp' 
+{{ ydb-cli }} scheme permissions clear '/Root/db1/MyApp'
 ```
 
 And then execute the `list` command again on the object `/Root/db1/MyApp`, you will get the following result:

ydb/docs/en/core/reference/ydb-cli/parameterized-queries-cli.md

@@ -1,3 +1,10 @@
+
+{% note warning %}
+
+This page is outdated. Please refer to [{#T}](parameterized-query-execution.md) for up-to-date information.
+
+{% endnote %}
+
 # Running parametrized YQL queries and scripts
 
 ## Overview
@@ -53,7 +60,7 @@ echo '{"a":10}' > p1.json
 {{ ydb-cli }} -p quickstart table query execute -q 'declare $a as Int64;select $a' --param-file p1.json
 ```
 
-Through `stdin`:
+Via `stdin`:
 
 ```bash
 echo '{"a":10}' | {{ ydb-cli }} -p quickstart table query execute -q 'declare $a as Int64;select $a'
@@ -293,7 +300,7 @@ Command output:
 This example demonstrates the adaptive batching triggered by a processing delay. In the first line of the command below, we generate 1,000 rows at a delay of 0.2 seconds on `stdout` and pipe them to `stdin` to the YQL query execution command. The YQL query execution command shows the parameter batches in each subsequent YQL query call.
 
 ```bash
-for i in $(seq 1 1000);do echo "Line$i";sleep 0.2;done | \
+for i in $(seq 1 1000); do echo "Line$i"; sleep 0.2; done | \
 {{ ydb-cli }} -p quickstart table query execute \
   -q 'DECLARE $x AS List<Utf8>;
       SELECT ListLength($x), $x' \
@@ -335,7 +342,7 @@ This example demonstrates the adaptive batching triggered by a number of paramet
 In this example, we also demonstrate the option to join parameters from different sources and generate JSON at the output.
 
 ```bash
-for i in $(seq 1 200);do echo "Line$i";done | \
+for i in $(seq 1 200); do echo "Line$i"; done | \
 {{ ydb-cli }} -p quickstart table query execute \
   -q 'DECLARE $x AS List<Utf8>;
       DECLARE $p2 AS Int64;
@@ -372,7 +379,7 @@ Let's create a test table:
 Add 100,000 records to it:
 
 ```bash
-for i in $(seq 1 100000);do echo "$i";done | \
+for i in $(seq 1 100000); do echo "$i"; done | \
 {{ ydb-cli }} -p quickstart import file csv -p test_delete_1
 ```