YDB CLI parameterized query tail it.2

updated

YDB CLI params

9 files changed, 192 insertions, 104 deletions

diff --git a/ydb/docs/ru/core/_includes/parameterized-query.md b/ydb/docs/ru/core/_includes/parameterized-query.md
new file mode 100644
index 0000000000..124aacd6f0
--- /dev/null
+++ b/ydb/docs/ru/core/_includes/parameterized-query.md
@@ -0,0 +1,14 @@
+{{ ydb-short-name }} CLI автоматически определяет что `stdin` не связан с терминалом ввода. Использование `stdin` позволяет передавать на вход содержимое файлов операторами `>`/`<` или перенаправить вывод другой команды оператором `\|`. По умолчанию переданный контент интерпретируется так же, как и файл в `--param-file` (документ JSON). Передача через `stdin` позволяет воспользоваться дополнительными возможностями с помощью параметров `--stdin-format`, `--stdin-par`, и `--batch`.
+
+Следующие параметры могут быть использованы с любой из команд выполнения YQL-запросов {{ ydb-short-name }} CLI. Примеры смотрите в [{#T}](../reference/ydb-cli/parameterized-queries-cli.md).
+
+Имя | Описание
+---|---
+`-p, --param` | Выражение в формате `$name=value`, где `$name` — имя параметра YQL-запроса, а `value` — его значение (корректный [JSON value](https://www.json.org/json-ru.html)). Может быть указано несколько раз.<br><br>Все указываемые параметры должны быть декларированы в YQL-запросе [оператором DECLARE](../yql/reference/syntax/declare.md), иначе будет выдана ошибка «Query does not contain parameter». Если один и тот же параметр указан несколько раз, будет выдана ошибка «Parameter value found in more than one source».<br><br>В зависимости от используемой операционной системы может понадобиться экранирование символа `$` или запись выражения в одинарных кавычках `'`.
+`--param-file` | Имя файла в формате [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %} в кодировке [UTF-8]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/UTF-8){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/UTF-8){% endif %}, в котором заданы значения параметров, сопоставляемые с параметрами YQL-запроса по именам ключей. Может быть указано несколько раз.<br><br>Если значения декларированного в YQL-запросе параметра будут обнаружены одновременно в нескольких файлах, или заданы в командной строке опцией `--param`, будет выдана ошибка «Parameter value found in more than one source».<br><br>Имена ключей в JSON-файле указываются без начального символа `$`. Ключи, которые присутствуют в файле, но не декларированы в YQL-запросе, будут проигнорированы без выдачи сообщения об ошибке.
+`--input-format` | Формат представления значений параметров. Действует на все способы их передачи (через параметр команды, файл или `stdin`).<br>Возможные значения:<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 %}.</li><li>`json-base64` — [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %}, в котором значения параметров с типом «бинарная строка» (`DECLARE $par AS String`) представлены в кодировке [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}. Такая возможность позволяет передавать любые бинарные данные, декодирование которых из Base64 выполнит {{ ydb-short-name }} CLI.</li></ul>
+`--stdin-format` | Задает формат представления параметров и фрейминг для `stdin`. Чтобы задать оба значения, укажите параметр дважды.<br>**Формат представления параметров на `stdin`**<br>Возможные значения:<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 %}.</li><li>`json-base64` — [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %}, в котором значения параметров с типом «бинарная строка» (`DECLARE $par AS String`) представлены в кодировке [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}. Такая возможность позволяет передавать любые бинарные данные, декодирование которых из Base64 выполнит {{ ydb-short-name }} CLI.</li><li>`raw` - бинарные данные, представляющие значение параметра, имя которого задается параметром `--stdin-par`.</li></ul>Если формат представления параметров на `stdin` не задан, то применяется формат, заданный параметром `--input-format`.<br><br>**Разделение наборов параметров (фрейминг) для `stdin`**<br>Возможные значения:<ul><li>`no-framing` (по умолчанию) — `stdin` не используется, либо на `stdin` ожидается один набор параметров, YQL-запрос исполняется однократно после завершения чтения `stdin`.</li><li>`newline-delimited` — символ перевода строки отмечает на `stdin` окончание одного набора параметров, отделяя его от следующего. Момент отправки YQL-запроса на сервер определяется параметром `--batch`.</li></ul>
+`--stdin-par` | Имя параметра, значение которого будет передано через `stdin`. Указывается без символа `$`. Обязательно при использовании формата `raw` в `--stdin-format`.<br><br>При использовании с JSON-форматами команда ожидает на входе только значение в корректном для JSON представлении. При включенном фрейминге может быть указано несколько разных имен, в этом случае подстановка будет осуществляться с чередованием имен параметров.
+`--batch` | Режим пакетирования значений наборов параметров, получаемых через `stdin`.<br>Возможные значения:<ul><li>`iterative` (по умолчанию) — пакетирование выключено. YQL-запрос исполняется для каждого полученного набора параметров, то есть ровно один раз при выключенном фрейминге или отсутствии активного `stdin`. При включенном фрейминге очередной YQL-запрос уходит на исполнение при получении разделителя наборов параметров на `stdin`, а исполнение команды завершается при закрытии потока на `stdin`.</li><li>`full` - полный пакет. YQL-запрос исполняется один раз после закрытия потока на `stdin`, все полученные наборы параметров заворачиваются в `List<>`, имя параметра задается опцией `--stdin-par`.</li><li>`adaptive` - адаптивное пакетирование. YQL-запрос исполняется каждый раз, когда срабатывает ограничение на количество наборов параметров в одном запросе (`--batch-limit`) или на задержку обработки (`--batch-max-delay`). Все полученные к этому моменту наборы параметров заворачиваются в `List<>`, имя параметра задается опцией `--stdin-par`.
+`--batch-limit` | Максимальное количество наборов параметров в пакете для адаптивного режима пакетирования. Следующий пакет будет отправлен на исполнение YQL-запросом, если количество наборов данных в нем достигло указанного значения. Установка в `0` снимает ограничение.<br><br>Значение по умолчанию — `1000`.<br><br>Параметры передаются в YQL без стриминга и общий объем одного GRPC-запроса, в который включаются значения параметров, имеет верхнюю границу около 5 МБ.
+`--batch-max-delay` | Максимальная задержка отправки на обработку полученного набора параметров для адаптивного режима пакетирования. Задается в виде числа с размерностью времени - `s`, `ms`, `m`.<br><br>Значение по умолчанию — `1s` (1 секунда).<br><br>{{ ydb-short-name }} CLI будет отсчитывать время с момента получения первого набора параметров для пакета и отправит накопившийся пакет на исполнение, как только время превысит указанное значение. Параметр позволяет получить эффективное пакетирование в случае непредсказуемого темпа появления новых наборов параметров на `stdin`.
diff --git a/ydb/docs/ru/core/operations/toc_i.yaml b/ydb/docs/ru/core/operations/toc_i.yaml
index 92e82469fe..4c44d6ac74 100644
--- a/ydb/docs/ru/core/operations/toc_i.yaml
+++ b/ydb/docs/ru/core/operations/toc_i.yaml
@@ -4,3 +4,4 @@ items:
   hidden: true
 - name: Пользовательские атрибуты таблицы
   href: manage-users-attr.md
+  
\ No newline at end of file
diff --git a/ydb/docs/ru/core/reference/ydb-cli/parameterized-queries-cli.md b/ydb/docs/ru/core/reference/ydb-cli/parameterized-queries-cli.md
new file mode 100644
index 0000000000..974250a553
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-cli/parameterized-queries-cli.md
@@ -0,0 +1,135 @@
+# Передача параметров в команды выполнения YQL-запросов
+
+{{ ydb-short-name }} поддерживает и рекомендует к использованию [параметризованные запросы](https://en.wikipedia.org/wiki/Prepared_statement). Для выполнения параметризованных YQL-запросов вы можете использовать команды {{ ydb-short-name }} CLI:
+
+* [ydb yql](yql.md);
+* [ydb scripting yql](scripting-yql.md);
+* [ydb table query execute](table-query-execute.md).
+
+Команды поддерживают одинаковый синтаксис и возможности передачи параметров запросов. Значения параметров могут быть заданы в командной строке, загружены из файлов в формате [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %}, а также считаны с `stdin` в бинарном формате или в формате [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %}. При передаче параметров через `stdin` поддерживается многократное поточное исполнение YQL-запроса с разными значениями параметров и возможностью пакетирования.
+
+Для работы с параметрами в YQL-запросе должны присутствовать их определения [командой YQL `DECLARE`](../../yql/reference/syntax/declare.md).
+
+В примерах используется команда `table query execute`, они также выполняются для любой команды исполнения YQL-скрипта.
+
+{% include [ydb-cli-profile](../../_includes/ydb-cli-profile.md) %}
+
+## Простой параметризованный запрос {#example-simple}
+
+Передача значения параметра `a` через `--param`:
+
+```bash
+{{ ydb-cli }} -p db1 table query execute -q 'declare $a as Int64;select $a' --param '$a=10'
+```
+
+Передача значения параметра `a` в JSON-формате через `stdin`:
+
+```bash
+echo '{"a":10}' | {{ ydb-cli }} -p db1 table query execute -q 'declare $a as Int64;select $a'
+```
+
+Передача значения параметра `a` в JSON-формате через файл `p1.json`:
+
+```bash
+echo '{"a":10}' > p1.json
+{{ ydb-cli }} -p db1 table query execute -q 'declare $a as Int64;select $a' --param-file p1.json
+```
+
+## Передача значений параметров разных типов из нескольких источников {#example-multisource}
+
+```bash
+echo '{ "a":10, "b":"Some text", "x":"Ignore me" }' > p1.json
+echo '{ "c":"2012-04-23T18:25:43.511Z" }' | {{ ydb-cli }} -p db1 table query execute \
+  -q 'declare $a as Int64;declare $b as Utf8;declare $c as DateTime;declare $d as Int64;
+      select $a, $b, $c, $d' \
+  --param-file p1.json \
+  --param '$d=30'
+```
+
+## Передача бинарных строк в кодировке Base64 {#example-base64}
+
+```bash
+{{ ydb-cli }} -p db1 table query execute \
+  -q 'declare $a as String;select $a' \
+  --input-format json-base64 \
+  --param '$a="SGVsbG8sIHdvcmxkCg=="' 
+```
+
+## Передача бинарного контента в поле типа «бинарная строка» {#example-raw}
+
+```bash
+curl -L http://ydb.tech/docs | {{ ydb-cli }} -p db1 table query execute \
+  -q 'declare $a as String;select LEN($a)' \
+  --stdin-format raw \
+  --stdin-par a
+```
+
+## Итеративная обработка нескольких наборов параметров {#example-iterate}
+
+```bash
+echo -e '{"a":10,"b":20}\n{"a":15,"b":25}\n{"a":35,"b":48}' > p1.json
+cat p1.json | {{ ydb-cli }} -p db1 table query execute \
+  -q 'declare $a as Int64;declare $b as Int64;select $a+$b' \
+  --stdin-format newline-delimited
+```
+
+## Полная пакетная обработка {#example-full}
+
+В данном примере использован вариант передачи именованных параметров в список структур, применимый для полного и адаптивного режимов пакетирования.
+
+```bash
+echo -e '{"a":10,"b":20}\n{"a":15,"b":25}\n{"a":35,"b":48}' | \
+{{ ydb-cli }} -p db1 table query execute \
+  -q 'declare $x as List<Struct<a:Int64,b:Int64>>;select ListLength($x), $x' \
+  --stdin-format newline-delimited \
+  --stdin-par x \
+  --batch full
+```
+
+## Адаптивная пакетная обработка {#example-adaptive}
+
+### Триггер по задержке обработки {#example-adaptive-delay}
+
+Для демонстрации работы адаптивного пакетирования со срабатыванием триггера по задержке обработки в первой строке команды ниже производится генерация 1000 строк с задержкой в 0.2 секунды. Команда будет отображать пакеты параметров в каждом следующем вызове YQL-запроса.
+
+В данном примере использован вариант передачи параметров без имени в типизированный список, применимый для полного и адаптивного режимов пакетирования.
+
+Значение `--batch-max-delay` по умолчанию установлено в 1 секунду, поэтому в каждый запрос будет попадать около 5 строк. При этом в первый пакет пойдут все строки, накопившиеся за время открытия соединения с БД, и он будет больше чем последующие.
+
+```bash
+for i in $(seq 1 1000);do echo "Line$i";sleep 0.2;done | \
+{{ ydb-cli }} -p db1 table query execute \
+  -q 'declare $x as List<Utf8>;select ListLength($x), $x' \
+  --stdin-format newline-delimited \
+  --stdin-format raw \
+  --stdin-par x \
+  --batch adaptive
+```
+
+### Триггер по количеству записей {#example-adaptive-limit}
+
+Для демонстрации работы адаптивного пакетирования со срабатыванием триггера по количеству наборов параметров в первой строке команды ниже производится генерация 200 строк. Команда будет отображать пакеты параметров в каждом следующем вызове YQL-запроса, учитывая заданное ограничение `--batch-limit` равное 20 (по умолчанию 1000).
+
+В данном примере также показана возможность объединения параметров из разных источников, и формирование JSON на выходе.
+
+```bash
+for i in $(seq 1 200);do echo "Line$i";done | \
+{{ ydb-cli }} -p db1 table query execute \
+  -q 'declare $x as List<Utf8>;declare $p2 as Int64;
+      select ListLength($x) as count, $p2 as p2, $x as items' \
+  --stdin-format newline-delimited \
+  --stdin-format raw \
+  --stdin-par x \
+  --batch adaptive \
+  --batch-limit 20 \
+  --param '$p2=10' \
+  --format json-unicode
+```
+
+## Конвейерная обработка сообщений, считываемых из топика {#example-adaptive-pipeline-from-topic}
+
+О конвейерной обработке сообщений, считываемых из топика, читайте в статье [{#T}](topic-pipeline.md#example-read-to-yql-param).
+
+## См. также {#see-also}
+
+* [Параметризованные YQL-запросы в {{ ydb-short-name }} SDK](../ydb-sdk/parameterized_queries.md)
diff --git a/ydb/docs/ru/core/reference/ydb-cli/scripting-yql.md b/ydb/docs/ru/core/reference/ydb-cli/scripting-yql.md
index cc606ea199..e1b468a70a 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/scripting-yql.md
+++ b/ydb/docs/ru/core/reference/ydb-cli/scripting-yql.md
@@ -27,10 +27,12 @@ ydb scripting yql --help
 `-f`, `--file` | Путь к файлу с текстом YQL-скрипта для выполнения.
 `--explain` | Показать план выполнения запроса.
 `--show-response-metadata` | Показать метаданные ответа.
-`-p`, `--param` | [Параметры запроса](../../getting_started/yql.md#param) (для запросов над данными и скан-запросах).<br>Может быть указано несколько параметров. Для изменения формата ввода используйте параметр подкоманды `--input-format`.
-`--input-format` | Формат ввода.<br>Возможные значения:<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 %}, бинарные строки закодированы в [Юникод]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Юникод){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Unicode){% endif %};</li><li>`json-base64` — ввод в формате JSON, бинарные строки закодированы в [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}.</li></ul>
 `--format` | Формат вывода.<br>Значение по умолчанию — `pretty`.<br>Возможные значения:<ul><li>`pretty` — человекочитаемый формат;</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 %}, бинарные строки закодированы в [Юникод]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Юникод){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Unicode){% endif %}, каждая строка JSON выводится в отдельной строке;</li><li>`json-unicode-array` — вывод в формате JSON, бинарные строки закодированы в Юникод, результат выводится в виде массива строк JSON, каждая строка JSON выводится в отдельной строке;</li><li>`json-base64` — вывод в формате JSON, бинарные строки закодированы в [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}, каждая строка JSON выводится в отдельной строке;</li><li>`json-base64-array` — вывод в формате JSON, бинарные строки закодированы в Base64, результат выводится в виде массива строк JSON, каждая строка JSON выводится в отдельной строке.</li></ul>
 
+### Параметры для работы с параметризованными запросами {#parameterized-query}
+
+{% include [parameterized-query](../../_includes/parameterized-query.md) %}
+
 ## Примеры {#examples}
 
 {% include [ydb-cli-profile](../../_includes/ydb-cli-profile.md) %}
@@ -53,46 +55,3 @@ ydb yql \
 ```
 
 Если сервер не успеет выполнить запрос за 500 мс, он ответит ошибкой. Если по какой либо причине клиент не сможет получить сообщение сервера об ошибке, то операция будет прервана через 500+200 мс на стороне клиента.
-
-### Выполнение параметризированного запроса {#example-param}
-
-Выполните параметризированный запрос со сбором статистики:
-
-```bash
-ydb yql \
-  --stats full \
-  --script \
-  "DECLARE \$myparam AS Uint64; \
-  SELECT * FROM series WHERE series_id=\$myparam;" \
-  --param '$myparam=1'
-```
-
-Результат:
-
-```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/ru/core/reference/ydb-cli/table-query-execute.md b/ydb/docs/ru/core/reference/ydb-cli/table-query-execute.md
index 4c9367e25c..7bc39c77ea 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/table-query-execute.md
+++ b/ydb/docs/ru/core/reference/ydb-cli/table-query-execute.md
@@ -1,6 +1,6 @@
 # Выполнение запроса
 
-С помощью подкоманды `table query execute` вы можете выполнять единичные ad hoc запросы конкретных типов для тестирования и диагностики.
+Подкоманда `table query execute` предназначена для надежного исполнения YQL-запросов, не содержащих команд управления транзакциями или [DDL-операторов]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Data_definition_language){% else %}(https://en.wikipedia.org/wiki/Data_definition_language){% endif %}. Подкоманда обеспечивает успешное исполнение запроса при кратковременной недоступности отдельных партиций таблиц, например, связанной с [их разделением или слиянием](../../concepts/datamodel/table.md#partitioning), за счет применения встроенных политик повторных попыток (retry policies).
 
 Общий вид команды:
 
@@ -28,9 +28,13 @@
 `--tx-mode` | Указать [режим транзакций](../../concepts/transactions.md#modes) (для запросов типа `data`).<br>Возможные значения:<ul><li>`serializable-rw` — результат успешно выполненных параллельных транзакций эквивалентен определенному последовательному порядку их выполнения;</li><li>`online-ro` — каждое из чтений в транзакции читает последние на момент своего выполнения данные;</li><li>`stale-ro`  — чтения данных в транзакции возвращают результаты с возможным отставанием от актуальных (доли секунды).</li></ul>Значение по умолчанию — `serializable-rw`.
 `-q`, `--query` | Текст YQL-запроса для выполнения.
 `-f,` `--file` | Путь к файлу с текстом YQL-запроса для выполнения.
-`-p`, `--param` | [Параметры запроса](../../getting_started/yql.md#param) (для запросов над данными и скан-запросах).<br>Может быть указано несколько параметров. Для изменения формата ввода используйте параметр подкоманды `--input-format`.
-`--input-format` | Формат ввода.<br>Возможные значения:<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 %}, бинарные строки закодированы в [Юникод]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Юникод){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Unicode){% endif %};</li><li>`json-base64` — ввод в формате JSON, бинарные строки закодированы в [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}.</li></ul>
-`--format` | Формат вывода.<br>Значение по умолчанию — `pretty`.<br>Возможные значения:<ul><li>`pretty` — человекочитаемый формат;</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 %}, бинарные строки закодированы в [Юникод]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Юникод){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Unicode){% endif %}, каждая строка JSON выводится в отдельной строке;</li><li>`json-unicode-array` — вывод в формате JSON, бинарные строки закодированы в Юникод, результат выводится в виде массива строк JSON, каждая строка JSON выводится в отдельной строке;</li><li>`json-base64` — вывод в формате JSON, бинарные строки закодированы в [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}, каждая строка JSON выводится в отдельной строке;</li><li>`json-base64-array` — вывод в формате JSON, бинарные строки закодированы в Base64, результат выводится в виде массива строк JSON, каждая строка JSON выводится в отдельной строке.</li></ul>
+`--format` | Формат вывода.<br>Возможные значения:<ul><li>`pretty` (по умолчанию) — человекочитаемый формат;</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 %}, бинарные строки закодированы в [Юникод]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Юникод){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Unicode){% endif %}, каждая строка JSON выводится в отдельной строке;</li><li>`json-unicode-array` — вывод в формате JSON, бинарные строки закодированы в Юникод, результат выводится в виде массива строк JSON, каждая строка JSON выводится в отдельной строке;</li><li>`json-base64` — вывод в формате JSON, бинарные строки закодированы в [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}, каждая строка JSON выводится в отдельной строке;</li><li>`json-base64-array` — вывод в формате JSON, бинарные строки закодированы в Base64, результат выводится в виде массива строк JSON, каждая строка JSON выводится в отдельной строке;</li><li>`csv` —вывод в формате [CSV](https://ru.wikipedia.org/wiki/CSV);</li><li>`tsv` —вывод в формате [TSV](https://ru.wikipedia.org/wiki/TSV).</li></ul>
+
+При исполнении YQL-запроса командой `table query execute` применяются политики повторных попыток, обеспечивающие надежное исполнение запроса и продолжение обработки потока параметров на `stdin` при изменении набора партиций в таблицах, а также других стандартных ситауциях в распределенной базе данных, вызывающих кратковременную невозможность выполнения операций над частью данных.
+
+### Параметры для работы с параметризованными запросами {#parameterized-query}
+
+{% include [parameterized-query](../../_includes/parameterized-query.md) %}
 
 ## Примеры {#examples}
 
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 cf7f7b83ef..234668e910 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml
+++ b/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml
@@ -75,6 +75,8 @@ items:
       href: scripting-yql.md
     - name: Выполнение запроса
       href: table-query-execute.md
+    - name: Передача параметров в команды выполнения YQL-запросов
+      href: parameterized-queries-cli.md
 #  - name: Утилиты
 #    items:
     # - name: Снятие бэкапа
diff --git a/ydb/docs/ru/core/reference/ydb-cli/topic-pipeline.md b/ydb/docs/ru/core/reference/ydb-cli/topic-pipeline.md
index c505b62f08..49746cebb2 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/topic-pipeline.md
+++ b/ydb/docs/ru/core/reference/ydb-cli/topic-pipeline.md
@@ -38,3 +38,23 @@
   {{ ydb-cli }} -p db1 yql -s "select * from series" --format json-unicode | \
   {{ ydb-cli }} -p db1 topic write topic1 --format newline-delimited
   ```
+
+### Исполнение YQL-запроса с передачей сообщений из топика в качестве параметров {#example-read-to-yql-param}
+
+* Исполнение YQL-запроса с передачей параметром каждого сообщения, считанного из топика `topic1`
+
+  ```bash
+  {{ ydb-cli }} -p db1 topic read topic1 -c c1 --format newline-delimited -w | \
+  {{ ydb-cli }} -p db1 table query execute -q 'declare $s as String;select Len($s) as Bytes' \
+  --stdin-format newline-delimited --stdin-par s --stdin-format raw
+  ```
+
+* Исполнение YQL-запроса с адаптивным пакетированием параметров из сообщений, считанных из топика `topic1`
+
+  ```bash
+  {{ ydb-cli }} -p db1 topic read topic1 -c c1 --format newline-delimited -w | \
+  {{ ydb-cli }} -p db1 table query execute \
+  -q 'declare $s as List<String>;select ListLength($s) as Count, $s as Items' \
+  --stdin-format newline-delimited --stdin-par s --stdin-format raw \
+  --batch adaptive
+  ```
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 4318485693..7481eeec24 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
@@ -4,12 +4,6 @@
 
 * [ydb yql](yql.md) - выполняет запросы и скрипты YQL с поддержкой стриминга (без ограничения на объем возвращаемых данных).
 * [ydb scripting yql](scripting-yql.md) — выполняет запросы и скрипты YQL, имеет ограничения на объем возвращаемых данных. Также с помощью этой команды вы можете просмотреть план выполнения запроса и метаданные ответа.
-* [ydb table query execute](table-query-execute.md) - выполняет единичные запросы указанного типа. Вы можете задать режим изоляции транзакций.
+* [ydb table query execute](table-query-execute.md) - выполняет [DML-запросы](https://en.wikipedia.org/wiki/Data_manipulation_language#SQL) с заданным уровнем изоляции транзакции и применением типовой политики повторных попыток.
 
-{% note info %}
-
-Для выполнения YQL рекомендуется использовать команду `ydb yql`.
-
-В будущем планируется отказаться от команд `ydb scripting yql` и `ydb table query execute`, предоставив всю необходимую функциональность в рамках `ydb yql`.
-
-{% endnote %}
+О выполнении параметризованных запросов в {{ ydb-short-name }} CLI читайте в статье [{#T}](./parameterized-queries-cli.md).
diff --git a/ydb/docs/ru/core/reference/ydb-cli/yql.md b/ydb/docs/ru/core/reference/ydb-cli/yql.md
index cedf6a12cd..d0074d5d0c 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/yql.md
+++ b/ydb/docs/ru/core/reference/ydb-cli/yql.md
@@ -22,12 +22,14 @@
 Имя | Описание
 ---|---
 `--timeout` | Время, в течение которого должна быть выполнена операция на сервере.
-`--stats` | Режим сбора статистики.<br>Возможные значения:<ul><li>`none` — не собирать;</li><li>`basic` — собирать по основным событиям;</li><li>`full` — собирать по всем событиям.</li></ul>Значение по умолчанию — `none`.
+`--stats` | Режим сбора статистики.<br>Возможные значения:<ul><li>`none` (по умолчанию) — не собирать;</li><li>`basic` — собирать по основным событиям;</li><li>`full` — собирать по всем событиям.</li></ul>
 `-s`, `--script` | Текст YQL-скрипта для выполнения.
 `-f`, `--file` | Путь к файлу с текстом YQL-скрипта для выполнения.
-`-p`, `--param` | [Параметры запроса](../../getting_started/yql.md#param) (для запросов над данными и скан-запросов).<br>Может быть указано несколько параметров. Для изменения формата ввода используйте параметр `--input-format`.
-`--input-format` | Формат ввода.<br>Возможные значения:<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 %}, бинарные строки закодированы в [Юникод]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Юникод){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Unicode){% endif %};</li><li>`json-base64` — ввод в формате JSON, бинарные строки закодированы в [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}.</li></ul>
-`--format` | Формат вывода.<br>Значение по умолчанию — `pretty`.<br>Возможные значения:<ul><li>`pretty` — человекочитаемый формат;</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 %}, бинарные строки закодированы в [Юникод]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Юникод){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Unicode){% endif %}, каждая строка JSON выводится в отдельной строке;</li><li>`json-unicode-array` — вывод в формате JSON, бинарные строки закодированы в Юникод, результат выводится в виде массива строк JSON, каждая строка JSON выводится в отдельной строке;</li><li>`json-base64` — вывод в формате JSON, бинарные строки закодированы в [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}, каждая строка JSON выводится в отдельной строке;</li><li>`json-base64-array` — вывод в формате JSON, бинарные строки закодированы в Base64, результат выводится в виде массива строк JSON, каждая строка JSON выводится в отдельной строке.</li></ul>
+`--format` | Формат вывода.<br>Возможные значения:<ul><li>`pretty` (по умолчанию) — человекочитаемый формат;</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 %}, бинарные строки закодированы в [Юникод]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Юникод){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Unicode){% endif %}, каждая строка JSON выводится в отдельной строке;</li><li>`json-unicode-array` — вывод в формате JSON, бинарные строки закодированы в Юникод, результат выводится в виде массива строк JSON, каждая строка JSON выводится в отдельной строке;</li><li>`json-base64` — вывод в формате JSON, бинарные строки закодированы в [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}, каждая строка JSON выводится в отдельной строке;</li><li>`json-base64-array` — вывод в формате JSON, бинарные строки закодированы в Base64, результат выводится в виде массива строк JSON, каждая строка JSON выводится в отдельной строке;</li><li>`csv` —вывод в формате [CSV](https://ru.wikipedia.org/wiki/CSV);</li><li>`tsv` —вывод в формате [TSV](https://ru.wikipedia.org/wiki/TSV).</li></ul>
+
+### Параметры для работы с параметризованными запросами {#parameterized-query}
+
+{% include [parameterized-query](../../_includes/parameterized-query.md) %}
 
 ## Примеры {#examples}
 
@@ -51,46 +53,3 @@ ydb yql \
 ```
 
 Если сервер не успеет выполнить запрос за 500 мс, он ответит ошибкой. Если по какой либо причине клиент не сможет получить сообщение сервера об ошибке, то операция будет прервана через 500+200 мс на стороне клиента.
-
-### Выполнение параметризированного запроса {#example-param}
-
-Выполните параметризированный запрос со сбором статистики:
-
-```bash
-ydb yql \
-  --stats full \
-  --script \
-  "DECLARE \$myparam AS Uint64; \
-  SELECT * FROM series WHERE series_id=\$myparam;" \
-  --param '$myparam=1'
-```
-
-Результат:
-
-```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
-```