[review] [YDB] Check translate ydb yql

Clear log

7 files changed, 285 insertions, 7 deletions

diff --git a/ydb/docs/en/core/reference/ydb-cli/_includes/commands.md b/ydb/docs/en/core/reference/ydb-cli/_includes/commands.md
index 2955c33bf51..d198a4bb0ed 100644
--- a/ydb/docs/en/core/reference/ydb-cli/_includes/commands.md
+++ b/ydb/docs/en/core/reference/ydb-cli/_includes/commands.md
@@ -50,14 +50,14 @@ Any command can be run from the command line with the `--help` option to get hel
 | scheme permissions revoke | Revoking a permission |
 | scheme permissions set | Setting permissions |
 | [scheme rmdir](../commands/dir.md#rmdir) | Deleting a directory |
-| scripting yql | Executing a YQL script |
+| [scripting yql](../scripting-yql.md) | Executing a YQL script |
 | table attribute add | Adding a table attribute |
 | table attribute drop | Deleting a table attribute |
 | table drop | 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](../commands/query.md) | Executing a YQL query |
+| [table query execute](../table-query-execute.md) | Executing a YQL query |
 | [table query explain](../commands/explain-plan.md) | YQL query execution plan |
 | [table readtable](../commands/readtable.md) | Streaming table reads |
 | table ttl drop | Deleting TTL parameters |
diff --git a/ydb/docs/en/core/reference/ydb-cli/_includes/index.md b/ydb/docs/en/core/reference/ydb-cli/_includes/index.md
index c49fd1e0ecc..ba93a68ba05 100644
--- a/ydb/docs/en/core/reference/ydb-cli/_includes/index.md
+++ b/ydb/docs/en/core/reference/ydb-cli/_includes/index.md
@@ -4,7 +4,7 @@ The {{ ydb-short-name }} CLI provides software for managing your data in {{ ydb-
 
 To learn how to use the {{ ydb-short-name }} CLI, see [Installing the {{ ydb-short-name }} CLI](../install.md).
 
-When connecting to a database, you need to authenticate. For the first connection, you can use the quick recipe from the [Authentication](../../../getting_started/auth.md) article in the "Getting started" section.
+When connecting to a database, you need to authenticate. To connect for the first time, you can use the quick recipe from the [Authentication](../../../getting_started/auth.md) section under "Getting started".
 
 Full information about defining DB connection and authentication parameters is given in the [Connecting to a database and authenticating with the {{ ydb-short-name }} CLI](../connect.md) article in this section.
 
@@ -13,9 +13,8 @@ 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).
-* [Making a DB query](../commands/query.md).
+* [YQL 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).
 * [Load testing](../commands/workload/index.md).
-
diff --git a/ydb/docs/en/core/reference/ydb-cli/scripting-yql.md b/ydb/docs/en/core/reference/ydb-cli/scripting-yql.md
new file mode 100644
index 00000000000..d922a8540e1
--- /dev/null
+++ b/ydb/docs/en/core/reference/ydb-cli/scripting-yql.md
@@ -0,0 +1,98 @@
+# Running a script
+
+You can use the `scripting yql` subcommand to run a YQL script. The script can include queries of different types. Unlike `yql`, the `scripting yql` command has a limit on the number of returned rows and accessed data.
+
+General format of the command:
+
+```bash
+{{ ydb-cli }} [global options...] scripting yql [options...]
+```
+
+* `global options`: [Global parameters](commands/global-options.md).
+* `options`: [Parameters of the subcommand](#options).
+
+View the description of the YQL script command:
+
+```bash
+ydb scripting yql --help
+```
+
+## Parameters of the subcommand {#options}
+
+| Name | Description |
+---|---
+| `--timeout` | The time within which the operation should be completed on the server. |
+| `--stats` | Statistics mode.<br>Acceptable values:<ul><li>`none`: Do not collect statistics.</li><li>`basic`: Collect statistics for basic events.</li><li>`full`: Collect statistics for all events.</li></ul>Defaults to `none`. |
+| `-s`, `--script` | Text of the YQL query to be executed. |
+| `-f`, `--file` | Path to the text of the YQL query to be executed. |
+| `--explain` | Show the query execution plan. |
+| `--show-response-metadata` | Show the response metadata. |
+| `-p`, `--param` | [Query parameters](../../getting_started/yql.md#param) (for data queries and scan queries).<br>You can specify multiple parameters. To change the input format, use the `--input-format` subcommand parameter. |
+| `--input-format` | Input format.<br>Acceptable values:<ul><li>`json-unicode`: [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %} input with binary strings [Unicode]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Юникод){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Unicode){% endif %}-encoded.</li><li>`json-base64`: JSON input with binary strings [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}-encoded.</li></ul> |
+| `--format` | Input format.<br>Default value: `pretty`.<br>Acceptable values:<ul><li>`pretty`: A human-readable format.</li><li>`json-unicode`: [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %} output with binary strings [Unicode]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Юникод){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Unicode){% endif %}-encoded and each JSON string in a separate line.</li><li>`json-unicode-array`: JSON output with binary strings Unicode-encoded and the result output as an array of JSON strings with each JSON string in a separate line.</li><li>`json-base64`: JSON output with binary strings [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}-encoded and each JSON string in a separate line.</li><li>`json-base64-array`: JSON output with binary strings Base64-encoded and the result output as an array of JSON strings with each JSON string in a separate line.</li></ul> |
+
+## Examples {#examples}
+
+{% include [ydb-cli-profile](../../_includes/ydb-cli-profile.md) %}
+
+### Running queries with a timeout {#example-timeout}
+
+Run a query with a timeout of 500 ms:
+
+```bash
+ydb yql \
+  --script \
+  "CREATE TABLE series ( \
+  series_id Uint64, \
+  title Utf8, \
+  series_info Utf8, \
+  release_date Uint64, \
+  PRIMARY KEY (series_id) \
+  );" \
+  --timeout 500
+```
+
+If the server couldn't complete the query in 500 ms, it returns an error. If the client couldn't get an error message from the server, the query is interrupted on the client side in 500+200 ms.
+
+### Running a parameterized query {#example-param}
+
+Run the parameterized query with statistics enabled:
+
+```bash
+ydb yql \
+  --stats full \
+  --script \
+  "DECLARE \$myparam AS Uint64; \
+  SELECT * FROM series WHERE series_id=\$myparam;" \
+  --param '$myparam=1'
+```
+
+Result:
+
+```text
+┌──────────────┬───────────┬──────────────────────────────────────────────────────────────────────────────┬────────────┐
+| release_date | series_id | series_info                                                                  | title      |
+├──────────────┼───────────┼──────────────────────────────────────────────────────────────────────────────┼────────────┤
+| 13182        | 1         | "The IT Crowd is a British sitcom produced by Channel 4, written by Graham L | "IT Crowd" |
+|              |           | inehan, produced by Ash Atalla and starring Chris O'Dowd, Richard Ayoade, Ka |            |
+|              |           | therine Parkinson, and Matt Berry."                                          |            |
+└──────────────┴───────────┴──────────────────────────────────────────────────────────────────────────────┴────────────┘
+
+Statistics:
+query_phases {
+  duration_us: 14294
+  table_access {
+    name: "/my-db/series"
+    reads {
+      rows: 1
+      bytes: 209
+    }
+    partitions_count: 1
+  }
+  cpu_time_us: 783
+  affected_shards: 1
+}
+process_cpu_time_us: 5083
+total_duration_us: 81373
+total_cpu_time_us: 5866
+```
diff --git a/ydb/docs/en/core/reference/ydb-cli/table-query-execute.md b/ydb/docs/en/core/reference/ydb-cli/table-query-execute.md
new file mode 100644
index 00000000000..e2e2ad265bb
--- /dev/null
+++ b/ydb/docs/en/core/reference/ydb-cli/table-query-execute.md
@@ -0,0 +1,62 @@
+# Running a query
+
+You can use the `table query execute` subcommand to run single ad-hoc queries of certain types, for the purposes of testing and troubleshooting.
+
+General format of the command:
+
+```bash
+{{ ydb-cli }} [global options...] table query execute [options...]
+```
+
+* `global options`: [Global parameters](commands/global-options.md).
+* `options`: [Parameters of the subcommand](#options).
+
+View the description of the YQL query command:
+
+```bash
+{{ ydb-cli }} table query execute --help
+```
+
+## Parameters of the subcommand {#options}
+
+| Name | Description |
+---|---
+| `--timeout` | The time within which the operation should be completed on the server. |
+| `-t`, `--type` | Query type.<br>Acceptable values:<ul><li>`data`: A data query.</li><li>`scheme`: A scheme query.</li><li>`scan`: A [scan query](../../concepts/scan_query.md).</li></ul>The default value is `data`. |
+| `--stats` | Statistics mode.<br>Acceptable values:<ul><li>`none`: Do not collect statistics.</li><li>`basic`: Collect statistics for basic events.</li><li>`full`: Collect statistics for all events.</li></ul>Defaults to `none`. |
+| `-s` | Enable statistics collection in the `basic` mode. |
+| `--tx-mode` | Specify the [transaction mode](../../concepts/transactions.md#modes) (for `data` queries).<br>Acceptable values:<ul><li>`serializable-rw`: The result of parallel transactions is equivalent to their serial execution.</li><li>`online-ro`: Each of the reads in the transaction reads data that is most recent at the time of its execution.</li><li>`stale-ro`: Data reads in a transaction return results with a possible delay (fractions of a second).</li></ul>Default value: `serializable-rw`. |
+| `-q`, `--query` | Text of the YQL query to be executed. |
+| `-f,` `--file` | Path to the text of the YQL query to be executed. |
+| `-p`, `--param` | [Query parameters](../../getting_started/yql.md#param) (for data queries and scan queries).<br>You can specify multiple parameters. To change the input format, use the `--input-format` subcommand parameter. |
+| `--input-format` | Input format.<br>Acceptable values:<ul><li>`json-unicode`: [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %} input with binary strings [Unicode]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Юникод){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Unicode){% endif %}-encoded.</li><li>`json-base64`: JSON input with binary strings [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}-encoded.</li></ul> |
+| `--format` | Input format.<br>Default value: `pretty`.<br>Acceptable values:<ul><li>`pretty`: A human-readable format.</li><li>`json-unicode`: [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %} output with binary strings [Unicode]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Юникод){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Unicode){% endif %}-encoded and each JSON string in a separate line.</li><li>`json-unicode-array`: JSON output with binary strings Unicode-encoded and the result output as an array of JSON strings with each JSON string in a separate line.</li><li>`json-base64`: JSON output with binary strings [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}-encoded and each JSON string in a separate line.</li><li>`json-base64-array`: JSON output with binary strings Base64-encoded and the result output as an array of JSON strings with each JSON string in a separate line.</li></ul> |
+
+## Examples {#examples}
+
+{% include [ydb-cli-profile](../../_includes/ydb-cli-profile.md) %}
+
+Run the data query:
+
+```bash
+{{ ydb-cli }} table query execute \
+  --query "SELECT season_id, episode_id, title \
+  FROM episodes \
+  WHERE series_id = 1 AND season_id > 1 \
+  ORDER BY season_id, episode_id \
+  LIMIT 3"
+```
+
+Result:
+
+```text
+┌───────────┬────────────┬──────────────────────────────┐
+| season_id | episode_id | title                        |
+├───────────┼────────────┼──────────────────────────────┤
+| 2         | 1          | "The Work Outing"            |
+├───────────┼────────────┼──────────────────────────────┤
+| 2         | 2          | "Return of the Golden Child" |
+├───────────┼────────────┼──────────────────────────────┤
+| 2         | 3          | "Moss and the German"        |
+└───────────┴────────────┴──────────────────────────────┘
+```
diff --git a/ydb/docs/en/core/reference/ydb-cli/toc_i.yaml b/ydb/docs/en/core/reference/ydb-cli/toc_i.yaml
index d5fd5fd269f..10dd3732aec 100644
--- a/ydb/docs/en/core/reference/ydb-cli/toc_i.yaml
+++ b/ydb/docs/en/core/reference/ydb-cli/toc_i.yaml
@@ -23,8 +23,6 @@ items:
       href: commands/tools/rename.md
   - name: Operations with data
     items:
-    - name: Making a DB query
-      href: commands/query.md
     - name: Getting a query execution plan and AST
       href: commands/explain-plan.md
     - name: Streaming table reads
@@ -53,6 +51,16 @@ items:
       href: topic-write.md
     - name: Message pipeline processing
       href: topic-pipeline.md
+  - name: YQL execution
+    items:
+    - name: Overview
+      href: yql-query-overview.md
+    - name: Running a script (with streaming support)
+      href: yql.md
+    - name: Running a script
+      href: scripting-yql.md
+    - name: Running a query
+      href: table-query-execute.md
 #  - name: Utilities
 #    items:
     # - name: Copy tables
diff --git a/ydb/docs/en/core/reference/ydb-cli/yql-query-overview.md b/ydb/docs/en/core/reference/ydb-cli/yql-query-overview.md
new file mode 100644
index 00000000000..402de003c7e
--- /dev/null
+++ b/ydb/docs/en/core/reference/ydb-cli/yql-query-overview.md
@@ -0,0 +1,15 @@
+# Overview
+
+You can use the following {{ ydb-short-name }} CLI commands to run YQL queries:
+
+* [ydb yql](yql.md): Runs YQL queries and scripts with streaming enabled (without limiting the amount of returned data).
+* [ydb scripting yql](scripting-yql.md): Runs YQL queries and scripts, limiting the amount of data returned. You can also use this command to view the query execution plan and the response metadata.
+* [ydb table query execute](table-query-execute.md): Runs single queries of a specified type. You can set the mode of transaction isolation.
+
+{% note info %}
+
+To run YQL queries, we recommend the `ydb yql` command.
+
+In the future, it is planned to abandon `ydb scripting yql` and `ydb table query execute` commands providing all the necessary functionality with `ydb yql` command.
+
+{% endnote %}
diff --git a/ydb/docs/en/core/reference/ydb-cli/yql.md b/ydb/docs/en/core/reference/ydb-cli/yql.md
new file mode 100644
index 00000000000..a3c091ce742
--- /dev/null
+++ b/ydb/docs/en/core/reference/ydb-cli/yql.md
@@ -0,0 +1,96 @@
+# Running a script (with streaming support)
+
+You can use the `yql` subcommand to run a YQL script. The script can include queries of different types. Unlike `scripting yql`, the `yql` subcommand establishes a streaming connection and retrieves data through it. With the in-stream query execution, no limit is imposed on the amount of data read.
+
+General format of the command:
+
+```bash
+{{ ydb-cli }} [global options...] yql [options...]
+```
+
+* `global options`: [Global parameters](commands/global-options.md).
+* `options`: [Parameters of the subcommand](#options).
+
+View the description of the YQL script command:
+
+```bash
+{{ ydb-cli }} yql --help
+```
+
+## Parameters of the subcommand {#options}
+
+| Name | Description |
+---|---
+| `--timeout` | The time within which the operation should be completed on the server. |
+| `--stats` | Statistics mode.<br>Acceptable values:<ul><li>`none`: Do not collect statistics.</li><li>`basic`: Collect statistics for basic events.</li><li>`full`: Collect statistics for all events.</li></ul>Defaults to `none`. |
+| `-s`, `--script` | Text of the YQL query to be executed. |
+| `-f`, `--file` | Path to the text of the YQL query to be executed. |
+| `-p`, `--param` | [Query parameters](../../getting_started/yql.md#param) (for data queries and scan queries).<br>You can specify multiple parameters. To change the input format, use the `--input-format` parameter. |
+| `--input-format` | Input format.<br>Acceptable values:<ul><li>`json-unicode`: [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %} input with binary strings [Unicode]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Юникод){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Unicode){% endif %}-encoded.</li><li>`json-base64`: JSON input with binary strings [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}-encoded.</li></ul> |
+| `--format` | Input format.<br>Default value: `pretty`.<br>Acceptable values:<ul><li>`pretty`: A human-readable format.</li><li>`json-unicode`: [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %} output with binary strings [Unicode]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Юникод){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Unicode){% endif %}-encoded and each JSON string in a separate line.</li><li>`json-unicode-array`: JSON output with binary strings Unicode-encoded and the result output as an array of JSON strings with each JSON string in a separate line.</li><li>`json-base64`: JSON output with binary strings [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}-encoded and each JSON string in a separate line.</li><li>`json-base64-array`: JSON output with binary strings Base64-encoded and the result output as an array of JSON strings with each JSON string in a separate line.</li></ul> |
+
+## Examples {#examples}
+
+{% include [ydb-cli-profile](../../_includes/ydb-cli-profile.md) %}
+
+### Running queries with a timeout {#example-timeout}
+
+Run a query with a timeout of 500 ms:
+
+```bash
+ydb yql \
+  --script \
+  "CREATE TABLE series ( \
+  series_id Uint64, \
+  title Utf8, \
+  series_info Utf8, \
+  release_date Uint64, \
+  PRIMARY KEY (series_id) \
+  );" \
+  --timeout 500
+```
+
+If the server couldn't complete the query in 500 ms, it returns an error. If the client couldn't get an error message from the server, the query is interrupted on the client side in 500+200 ms.
+
+### Running a parameterized query {#example-param}
+
+Run the parameterized query with statistics enabled:
+
+```bash
+ydb yql \
+  --stats full \
+  --script \
+  "DECLARE \$myparam AS Uint64; \
+  SELECT * FROM series WHERE series_id=\$myparam;" \
+  --param '$myparam=1'
+```
+
+Result:
+
+```text
+┌──────────────┬───────────┬──────────────────────────────────────────────────────────────────────────────┬────────────┐
+| release_date | series_id | series_info                                                                  | title      |
+├──────────────┼───────────┼──────────────────────────────────────────────────────────────────────────────┼────────────┤
+| 13182        | 1         | "The IT Crowd is a British sitcom produced by Channel 4, written by Graham L | "IT Crowd" |
+|              |           | inehan, produced by Ash Atalla and starring Chris O'Dowd, Richard Ayoade, Ka |            |
+|              |           | therine Parkinson, and Matt Berry."                                          |            |
+└──────────────┴───────────┴──────────────────────────────────────────────────────────────────────────────┴────────────┘
+
+Statistics:
+query_phases {
+  duration_us: 14294
+  table_access {
+    name: "/my-db/series"
+    reads {
+      rows: 1
+      bytes: 209
+    }
+    partitions_count: 1
+  }
+  cpu_time_us: 783
+  affected_shards: 1
+}
+process_cpu_time_us: 5083
+total_duration_us: 81373
+total_cpu_time_us: 5866
+```