Added interactive cli docs

6 files changed, 204 insertions, 10 deletions

diff --git a/ydb/docs/en/core/reference/ydb-cli/interactive-cli.md b/ydb/docs/en/core/reference/ydb-cli/interactive-cli.md
new file mode 100644
index 00000000000..8910bbcbec0
--- /dev/null
+++ b/ydb/docs/en/core/reference/ydb-cli/interactive-cli.md
@@ -0,0 +1,95 @@
+# Interactive query execution mode
+
+After executing `ydb` command without subcommands, the interactive query execution mode will be launched. The console or terminal will be switched to interactive mode. After that, you can enter queries directly into the console or terminal, and when you enter a newline character, the query is considered complete and it starts to execute. The query text can be either a YQL query or a [special command](#spec-commands). Also, query history is saved between runs, command autocomplete is available, and there is a search function for query history.
+
+General format of the command:
+
+```bash
+{{ ydb-cli }} [global options...]
+```
+
+* `global options` — [global parameters](commands/global-options.md).
+
+## Hotkeys {#hotkeys}
+
+Hotkey | Description
+---|---
+`CTRL + D` | Allows you to exit interactive mode.
+`Up arrow` | Scrolls through query history toward older queries.
+`Down arrow` | Scrolls through query history toward newer queries.
+`TAB` | Autocompletes the entered text to a suitable YQL command.
+`CTRL + R` | Allows searching for a query in history containing a specified substring.
+
+## Special commands {#spec-commands}
+
+Special commands are CLI-specific commands and are not part of the YQL syntax. They are intended for performing various functions that cannot be accomplished through a YQL query. Special commands are case sensitive.
+
+Command | Description
+---|---
+| `SET param = value` | The `SET` command sets the value of the [internal variable](#internal-vars) `param` to `value`. |
+| `EXPLAIN query-text` | Outputs the query plan for `query-text`. Equivalent to the command [ydb table query explain](commands/explain-plan.md#explain-plan). |
+| `EXPLAIN AST query-text` | Outputs the query plan for `query-text` along with the [AST](commands/explain-plan.md). Equivalent to the command [ydb table query explain --ast](commands/explain-plan.md#ast). |
+
+### List of internal variables {#internal-vars}
+
+Internal variables determine the behavior of commands and are set using the [special command](#spec-commands) `SET`.
+
+Variable | Description
+---|---
+| `stats` | The statistics collection mode for subsequent queries.<br>Acceptable values:<ul><li>`none` (default): Do not collect.</li><li>`basic`: Collect statistics.</li><li>`full`: Collect statistics and query plan.</li></ul> |
+
+## Examples {#examples}
+
+Executing a query in the `full` statistics collection mode:
+
+```bash
+$ ydb
+ydb> SET stats = full
+ydb> select * from table1 limit 1
+┌────┬─────┬───────┐
+│ id │ key │ value │
+├────┼─────┼───────┤
+│ 10 │ 0   │ ""    │
+└────┴─────┴───────┘
+
+Statistics:
+query_phases {
+  duration_us: 14987
+  table_access {
+    name: "/ru-central1/a1v7bqj3vtf10qjleyow/laebarufb61tguph3g22/table1"
+    reads {
+      rows: 9937
+      bytes: 248426
+    }
+  }
+  cpu_time_us: 2925
+  affected_shards: 1
+}
+process_cpu_time_us: 3816
+total_duration_us: 79530
+total_cpu_time_us: 6741
+
+
+Full statistics:
+Query 0:
+ResultSet
+└──Limit (Limit: 1)
+   TotalCpuTimeUs: 175
+   TotalTasks: 1
+   TotalInputBytes: 6
+   TotalInputRows: 1
+   TotalOutputBytes: 16
+   TotalDurationMs: 0
+   TotalOutputRows: 1
+   └──<UnionAll>
+      └──Limit (Limit: 1)
+      └──TableFullScan (ReadColumns: ["id","key","value"], ReadRanges: ["key (-∞, +∞)"], Table: impex_table)
+         Tables: ["table1"]
+         TotalCpuTimeUs: 154
+         TotalTasks: 1
+         TotalInputBytes: 0
+         TotalInputRows: 0
+         TotalOutputBytes: 16
+         TotalDurationMs: 0
+         TotalOutputRows: 1
+```
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 1efedeb1104..b37dd00be8a 100644
--- a/ydb/docs/en/core/reference/ydb-cli/toc_i.yaml
+++ b/ydb/docs/en/core/reference/ydb-cli/toc_i.yaml
@@ -79,6 +79,8 @@ items:
       href: table-query-execute.md
     - name: Running parameterized queries
       href: parameterized-queries-cli.md
+    - name: Interactive query execution mode
+      href: interactive-cli.md
 #  - name: Utilities
 #    items:
     # - name: Backup
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
index 9d723f7b93f..d46c335bde0 100644
--- a/ydb/docs/en/core/reference/ydb-cli/yql-query-overview.md
+++ b/ydb/docs/en/core/reference/ydb-cli/yql-query-overview.md
@@ -2,9 +2,9 @@
 
 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 [DML queries](https://en.wikipedia.org/wiki/Data_manipulation_language#SQL) with a given level of transaction isolation and a standard retry policy.
-
-All the above commands support the same functionality for [query parameterization in YQL](parameterized-queries-cli.md).
+1. [ydb yql](yql.md): Runs YQL queries and scripts with streaming enabled (without limiting the amount of returned data).
+2. [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.
+3. [ydb table query execute](table-query-execute.md): Runs [DML queries](https://en.wikipedia.org/wiki/Data_manipulation_language#SQL) with a given level of transaction isolation and a standard retry policy.
+4. [ydb](interactive-cli.md): Switches the console to interactive mode and executes YQL queries and scripts.
 
+Commands [1-3] support the same functionality for [query parameterization in YQL](parameterized-queries-cli.md).
diff --git a/ydb/docs/ru/core/reference/ydb-cli/interactive-cli.md b/ydb/docs/ru/core/reference/ydb-cli/interactive-cli.md
new file mode 100644
index 00000000000..356d356bfe2
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-cli/interactive-cli.md
@@ -0,0 +1,95 @@
+# Интерактивный режим выполнения запросов
+
+Выполнив команду `ydb` без подкоманд, запустится интерактивный режим выполнения запросов. Консоль или терминал будут переведены в интерактивный режим. После этого можно вводить запросы напрямую в консоль или терминал, при вводе символа перевода строки запрос считается законченным и он начинает исполняться. Текст запроса может представлять из себя как YQL запрос, так и [специальную команду](#spec-commands). Также между запусками сохраняется история запросов, доступны автодополнение команд и поиск по истории запросов.
+
+Общий вид команды:
+
+```bash
+{{ ydb-cli }} [global options...]
+```
+
+* `global options` — [глобальные параметры](commands/global-options.md).
+
+## Горячие клавиши {#hotkeys}
+
+Горячая клавиша | Описание
+---|---
+`CTRL + D` | Позволяет выйти из интерактивного режима.
+`Up arrow` | Пролистывает историю запросов в сторону более старых запросов.
+`Down arrow` | Пролистывает историю запросов в сторону более новых запросов.
+`TAB` | Дополняет введенный текст до подходящей YQL команды.
+`CTRL + R` | Позволяет найти в истории запрос, содержащий заданную подстроку.
+
+## Специальные команды {#spec-commands}
+
+Специальные команды специфичны для CLI и не являются частью синтаксиса YQL. Они предназначены для выполнения различных функций, которые нельзя выполнить через YQL запрос. Специальные команды чувствительны к регистру.
+
+Команда | Описание
+---|---
+`SET param = value` | Команда `SET` устанавливает значение [внутренней переменной](#internal-vars) `param` в `value`.
+`EXPLAIN query-text` | Выводит план запроса `query-text`. Эквивалентна команде [ydb table query explain](commands/explain-plan.md#explain-plan).
+`EXPLAIN AST query-text` | Выводит план запроса `query-text` вместе с [AST](commands/explain-plan.md). Эквивалентна команде [ydb table query explain --ast](commands/explain-plan.md#ast).
+
+### Список внутренних переменных {#internal-vars}
+
+Внутренние переменные устанавливают поведение команд и задаются с помощью [специальной команды](#spec-commands) `SET`.
+
+Переменная | Описание
+---|---
+`stats` | Режим сбора статистики для последующих запросов.<br>Возможные значения:<ul><li>`none` (по умолчанию) — не собирать;</li><li>`basic` — собирать статистику;</li><li>`full` — собирать статистику и план запроса.</li></ul>
+
+## Примеры {#examples}
+
+Выполнение запроса в режиме сбора статистики `full`:
+
+```bash
+$ ydb
+ydb> SET stats = full
+ydb> select * from table1 limit 1
+┌────┬─────┬───────┐
+│ id │ key │ value │
+├────┼─────┼───────┤
+│ 10 │ 0   │ ""    │
+└────┴─────┴───────┘
+
+Statistics:
+query_phases {
+  duration_us: 14987
+  table_access {
+    name: "/ru-central1/a1v7bqj3vtf10qjleyow/laebarufb61tguph3g22/table1"
+    reads {
+      rows: 9937
+      bytes: 248426
+    }
+  }
+  cpu_time_us: 2925
+  affected_shards: 1
+}
+process_cpu_time_us: 3816
+total_duration_us: 79530
+total_cpu_time_us: 6741
+
+
+Full statistics:
+Query 0:
+ResultSet
+└──Limit (Limit: 1)
+   TotalCpuTimeUs: 175
+   TotalTasks: 1
+   TotalInputBytes: 6
+   TotalInputRows: 1
+   TotalOutputBytes: 16
+   TotalDurationMs: 0
+   TotalOutputRows: 1
+   └──<UnionAll>
+      └──Limit (Limit: 1)
+      └──TableFullScan (ReadColumns: ["id","key","value"], ReadRanges: ["key (-∞, +∞)"], Table: impex_table)
+         Tables: ["table1"]
+         TotalCpuTimeUs: 154
+         TotalTasks: 1
+         TotalInputBytes: 0
+         TotalInputRows: 0
+         TotalOutputBytes: 16
+         TotalDurationMs: 0
+         TotalOutputRows: 1
+```
diff --git a/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml b/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml
index e8180ee068e..11d60702034 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml
+++ b/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml
@@ -82,6 +82,8 @@ items:
       href: table-query-execute.md
     - name: Выполнение параметризованных запросов
       href: parameterized-queries-cli.md
+    - name: Интерактивный режим выполнения запросов
+      href: interactive-cli.md
 #  - name: Утилиты
 #    items:
     # - name: Снятие бэкапа
diff --git a/ydb/docs/ru/core/reference/ydb-cli/yql-query-overview.md b/ydb/docs/ru/core/reference/ydb-cli/yql-query-overview.md
index bcfa1aa1bd3..a1b8892e7a8 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/yql-query-overview.md
+++ b/ydb/docs/ru/core/reference/ydb-cli/yql-query-overview.md
@@ -2,9 +2,9 @@
 
 Для выполнения YQL-запросов вы можете использовать следующие команды {{ ydb-short-name }} CLI:
 
-* [ydb yql](yql.md) - выполняет запросы и скрипты YQL с поддержкой стриминга (без ограничения на объем возвращаемых данных).
-* [ydb scripting yql](scripting-yql.md) — выполняет запросы и скрипты YQL, имеет ограничения на объем возвращаемых данных. Также с помощью этой команды вы можете просмотреть план выполнения запроса и метаданные ответа.
-* [ydb table query execute](table-query-execute.md) - выполняет [DML-запросы](https://en.wikipedia.org/wiki/Data_manipulation_language#SQL) с заданным уровнем изоляции транзакции и применением типовой политики повторных попыток.
-
-Все перечисленные команды поддерживают одинаковые возможности [параметризации запросов YQL](parameterized-queries-cli.md).
+1. [ydb yql](yql.md) — выполняет запросы и скрипты YQL с поддержкой стриминга (без ограничения на объем возвращаемых данных).
+2. [ydb scripting yql](scripting-yql.md) — выполняет запросы и скрипты YQL, имеет ограничения на объем возвращаемых данных. Также с помощью этой команды вы можете просмотреть план выполнения запроса и метаданные ответа.
+3. [ydb table query execute](table-query-execute.md) — выполняет [DML-запросы](https://en.wikipedia.org/wiki/Data_manipulation_language#SQL) с заданным уровнем изоляции транзакции и применением типовой политики повторных попыток.
+4. [ydb](interactive-cli.md) — переключает консоль в интерактивный режим и выполняет запросы и скрипты YQL.
 
+Команды [1-3] поддерживают одинаковые возможности [параметризации запросов YQL](parameterized-queries-cli.md).