YDB CLI params

7 files changed, 194 insertions, 23 deletions

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..b0571617b4 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/scripting-yql.md
+++ b/ydb/docs/ru/core/reference/ydb-cli/scripting-yql.md
@@ -21,15 +21,17 @@ ydb scripting yql --help
 
 Имя | Описание
 ---|---
-`--timeout` | Время, в течение которого должна быть выполнена операция на сервере.
-`--stats` | Режим сбора статистики.<br>Возможные значения:<ul><li>`none` — не собирать;</li><li>`basic` — собирать по основным событиям;</li><li>`full` — собирать по всем событиям.</li></ul>Значение по умолчанию — `none`.
 `-s`, `--script` | Текст YQL-скрипта для выполнения.
 `-f`, `--file` | Путь к файлу с текстом YQL-скрипта для выполнения.
+`--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>
 `--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>
+`--timeout` | Время, в течение которого должна быть выполнена операция на сервере.
+`--stats` | Режим сбора статистики.<br>Возможные значения:<ul><li>`none` — не собирать;</li><li>`basic` — собирать по основным событиям;</li><li>`full` — собирать по всем событиям.</li></ul>Значение по умолчанию — `none`.
+
+## Передача параметров {#parameters}
+
+Опции для передачи значений параметров запросов из командной строки, файлов и `stdin`, а также примеры, описаны в статье ["Передача параметров в команды исполнения YQL-запросов"](yql-query-parameters.md).
 
 ## Примеры {#examples}
 
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..2392e3de42 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).
 
 Общий вид команды:
 
@@ -21,16 +21,22 @@
 
 Имя | Описание
 ---|---
+`-q`, `--query` | Текст YQL-запроса для выполнения.
+`-f,` `--file` | Путь к файлу с текстом YQL-запроса для выполнения.
+`--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>
 `--timeout` | Время, в течение которого должна быть выполнена операция на сервере.
 `-t`, `--type` | Тип запроса.<br>Возможные значения:<ul><li>`data` — запрос над данными;</li><li>`scheme` — запрос над схемой данных;</li><li>`scan` — [скан-запрос](../../concepts/scan_query.md).</li></ul>Значение по умолчанию — `data`.
 `--stats` | Режим сбора статистики.<br>Возможные значения:<ul><li>`none` — не собирать;</li><li>`basic` — собирать по основным событиям;</li><li>`full` — собирать по всем событиям.</li></ul>Значение по умолчанию — `none`.
 `-s` | Включить сбор статистики в режиме `basic`.
 `--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>
+
+## Передача параметров {#parameters}
+
+Запрсы типа `data` или `scan` могут [быть параметризованы](../ydb-sdk/parameterized_queries.md).
+
+Опции для передачи значений параметров запросов из командной строки, файлов и `stdin`, а также примеры, описаны в статье ["Передача параметров в команды исполнения YQL-запросов"](yql-query-parameters.md).
+
+При исполнении YQL-запроса командой `table query execute` применяются политики повторных попыток, обеспечивающие надежное исполнение запроса и продолжение обработки потока параметров на `stdin` при изменении набора партиций в таблицах, а также других стандартных ситауциях в распределенной базе данных, вызывающих кратковременную невозможность выполнения операций над частью данных.
 
 ## Примеры {#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..1c4f1d9d88 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: Передача параметров
+      href: yql-query-parameters.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..ae5867bf64 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,25 @@
   {{ 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
+  ```
+
+Больше о возможностях передачи параметров в команды исполнения YQL-запросов можно [прочитать здесь](yql-query-parameters.md).
\ No newline at end of file
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..736efed35e 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,14 +2,7 @@
 
 Для выполнения YQL-запросов вы можете использовать следующие команды {{ ydb-short-name }} CLI:
 
+* [ydb table query execute](table-query-execute.md) - выполняет DML запросы с заданным уровнем изоляции транзакции, и применением типовой политики повторных попыток
 * [ydb yql](yql.md) - выполняет запросы и скрипты YQL с поддержкой стриминга (без ограничения на объем возвращаемых данных).
 * [ydb scripting yql](scripting-yql.md) — выполняет запросы и скрипты YQL, имеет ограничения на объем возвращаемых данных. Также с помощью этой команды вы можете просмотреть план выполнения запроса и метаданные ответа.
-* [ydb table query execute](table-query-execute.md) - выполняет единичные запросы указанного типа. Вы можете задать режим изоляции транзакций.
 
-{% note info %}
-
-Для выполнения YQL рекомендуется использовать команду `ydb yql`.
-
-В будущем планируется отказаться от команд `ydb scripting yql` и `ydb table query execute`, предоставив всю необходимую функциональность в рамках `ydb yql`.
-
-{% endnote %}
diff --git a/ydb/docs/ru/core/reference/ydb-cli/yql-query-parameters.md b/ydb/docs/ru/core/reference/ydb-cli/yql-query-parameters.md
new file mode 100644
index 0000000000..25e8bd3083
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-cli/yql-query-parameters.md
@@ -0,0 +1,144 @@
+# Передача параметров в команды исполнения YQL-запросов
+
+Команды исполнения YQL-запросов [`yql`](yql.md), [`scripting yql`](scripting-yql.md) и [`table query execute`](table-query-execute.md) поддерживают одинаковый синтаксис и возможности передачи параметров, описанные в данной статье.
+
+Для работы с параметрами в YQL-запросе должны присутствовать их определения [командой YQL `DECLARE`](../../yql/reference/syntax/declare.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-запроса с разными значениями параметров, с возможностью пакетирования.
+
+Для управления передачей параметров поддерживаются следующие опции:
+
+Имя | Описание
+---|---
+`-p, --param STR` | Значение параметра в формате `$name=value`, где `$name` -- имя параметра, а `value` - значение, являющееся корректным value для формата [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% else %}(https://en.wikipedia.org/wiki/JSON){% endif %}. Опция может быть указана несколько раз для разных параметров.<br><br>Все указываемые параметры должны быть декларированы в YQL-запросе [оператором `DECLARE`](../../yql/reference/syntax/declare.md). Если заданный опцией параметр не декларирован, будет выдана ошибка "Query does not contain parameter".<br><br>Если значения одного и того же параметра заданы несколько раз, будет выдана ошибка "Parameter value found in more than one source".<br><br>Обратите внимание, что символ `$` является специальным во многих операционных системах, поэтому для его корректной передачи он должен либо быть экранирован, либо использована фиксированная строковая константа (в Linux обрамленная символами одиночной кавычки `'`).
+`--param-file PATH` | Имя файла в формате [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>Имена ключей в json-файле указываются без начального символа `$`. В файле могут присутствовать не только ключи для задекларированных в YQL-запросе параметров, но также и произвольные дополнительные ключи, значения которых будут проигнорированы без выдачи сообщений об ошибке.<br><br>Опция может быть задана несколько раз. Если значения задекларированного в YQL-запросе параметра будут обнаружены одновременно в нескольких файлах, или заданы в командной строке опцией `--param`, будет выдана ошибка "Parameter value found in more than one source".
+`STDIN` | YDB CLI автоматически определяет что `stdin` не связан с терминалом ввода, без указания каких-либо специальных опций.<br><br>Использование `stdin` позволяет передавать на вход содержимое файлов операторами `>`/`<`, или перенаправлять вывод другой команды оператором `\|`. По-умолчанию переданный контент интерпретируется так же, как и файл в опции `--param-file` (документ JSON). При этом, передача контента через `stdin` позволяет воспользоваться дополнительными возможностями при использовани опций `--stdin-format`, `--stdin-par`, и `--batch`, описанных ниже.
+`--input-format STR` | Базовый формат представления значений параметров, действующий на все способы их передачи (командная строка, файл, `stdin`).<br><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 CLI.</li></ul>
+`--stdin-format STR` | Формат представления параметров на `stdin`.<br><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 CLI.</li><li>`raw` - бинарные данные, представлящие значение параметра, имя которого задается опцией `--stdin-par`.</li></ul>Если формат представления параметров на `stdin` не задан, то применяется формат, заданный общей опцией `--input-format`.
+`--stdin-format STR` | Определение правил разделения наборов параметров (фрейминга) для `stdin`.<br><br>Возможные значения:<ul><li>`no-framing` (по умолчанию) - `stdin` не используется, либо на `stdin` ожидается один набор параметров, с однократным исполнением YQL-запроса после завершения чтения `stdin`.</li><li>`newline-delimited` - символ перевода строки отмечает на `stdin` окончание одного набора параметров, отделяя его от следующего. Момент отправки YQL-запроса на сервер определяется опцией `--batch`.</li></ul>
+`--stdin-par STR` | Задает имя параметра для `stdin`, позволяя передавать на него только значения без имен параметров.<br><br> Указывается без символа `$`. Опция обязательна при использовании `raw` формата. При использовании с JSON-форматами ожидает на входе только значение в корректном для JSON представлении. При включенном фрейминге опция может быть задана несколько раз с разными именами параметров, в этом случае подстановка будет осуществляться с чередованием имен параметров.
+`--batch STR` | Режим пакетирования значений наборов параметров, получаемых через `stdin`.<br><br>Возможные значения:<ul><li>`iterative` (по умолчанию) - <b>Пакетирование выключено.</b> YQL-запрос исполняется для каждого полученного набора параметров, то есть ровно один раз при выключенном фрейминге или отсутствии активного `stdin`. При включенном фрейминге очередной YQL-запрос уходит на исполнение по факту получения на `stdin` разделителя наборов параметров, а исполнение команды завершается при закрытии потока на `stdin`.</li><li>`full` - <b>Полный пакет.</b> YQL-запрос исполняется один раз после закрытия потока на `stdin`, все полученные наборы параметров заворачиваются в `List<>`, имя параметра задается опцией `--stdin-par`.</li><li>`adaptive` - <b>Адаптивное пакетирование.</b> YQL-запрос исполняется каждый раз, когда срабатывает ограничение на количество наборов параметров в одном запросе (`--batch-limit`) или на задержку обработки (`--batch-max-delay`). Все полученные к этому моменту наборы параметров заворачиваются в `List<>`, имя параметра задается опцией `--stdin-par`.
+`--batch-limit NUM` | Максимальное количество наборов параметров в пакете для адаптивного режима пакетирования.<br><br>Следующий пакет будет отправлен на исполнение YQL-запросом, если количество наборов данных в нем достигло указанного значения. Значение по умолчанию `1000`. Установка в `0` снимает ограничение.<br><br>Необходимо учитывать, что параметры передаются в YQL без стриминга, и общий объем одного GRPC-запроса, в который включаются значения параметров, имеет верхнюю границу около 5 мегабайт.
+`--batch-max-delay VAL` | Максимальная задержка отправки на обработку полученного набора параметров для адаптивного режима пакетирования.<br><br>Задается в виде числа с размерностью времени - `s`, `ms`, `m`. По умолчанию `1s` (1 секунда). YDB CLI будет отсчитывать время с момента получения первого набора параметров для пакета, и отправит накопившийся пакет на исполнение как только время превысит значение, указанное в данной опции. Опция позволяет получить эффективное пакетирование в случае непредсказуемого темпа появления новых наборов параметров на `stdin`.
+
+## Примеры {#examples}
+
+{% include [ydb-cli-profile](../../_includes/ydb-cli-profile.md) %}
+
+Примеры написаны для команды `table query execute`, но при этом работоспособны и для любой другой команды исполнения YQL-скрипта.
+
+### Простейший параметризованный запрос {#example-simple}
+
+Значение в командной строке:
+
+```bash
+{{ ydb-cli }} -p db1 table query execute -q 'declare $a as Int64;select $a' --param '$a=10'
+```
+
+Передача в виде JSON через stdin:
+
+```bash
+echo '{"a":10}' | {{ ydb-cli }} -p db1 table query execute -q 'declare $a as Int64;select $a'
+```
+
+Чтение из 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}
+
+#### Триггер по задержке обработки
+
+Для демонстрации работы адаптивного пакетирования со срабатыванием триггера по задержке обработки в первой строке команды ниже производится генерация 1000 строк с задержкой в 0.2 секунды. Команда будет отображать пакеты параметров в каждом следующем вызове YQL-запроса.
+
+В данном примере использован вариант передачи параметров без имени в типизированный список, применимый для полного и адаптивного режимов пакетирования.
+
+```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
+```
+
+Значение `--batch-max-delay` по умолчанию установлено в 1 секунду, поэтому в каждый запрос будет попадать около 5 строк. При этом в первый пакет пойдут все строки, накопившиеся за время открытия соединения с БД, и он будет больше чем последующие.
+
+#### Триггер по количеству записей
+
+Для демонстрации работы адаптивного пакетирования со срабатыванием триггера по количеству наборов параметров в первой строке команды ниже производится генерация 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}
+
+Примеры передачи потока считываемых из топика сообщений в качестве параметров для исполнения YQL-запросов приведены в [этой статье](topic-pipeline.md#example-read-to-yql-param), среди других примеров работы с топиками.
\ No newline at end of file
diff --git a/ydb/docs/ru/core/reference/ydb-cli/yql.md b/ydb/docs/ru/core/reference/ydb-cli/yql.md
index cedf6a12cd..7fb3a8c56f 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/yql.md
+++ b/ydb/docs/ru/core/reference/ydb-cli/yql.md
@@ -21,13 +21,15 @@
 
 Имя | Описание
 ---|---
-`--timeout` | Время, в течение которого должна быть выполнена операция на сервере.
-`--stats` | Режим сбора статистики.<br>Возможные значения:<ul><li>`none` — не собирать;</li><li>`basic` — собирать по основным событиям;</li><li>`full` — собирать по всем событиям.</li></ul>Значение по умолчанию — `none`.
 `-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>
+`--timeout` | Время, в течение которого должна быть выполнена операция на сервере.
+`--stats` | Режим сбора статистики.<br>Возможные значения:<ul><li>`none` — не собирать;</li><li>`basic` — собирать по основным событиям;</li><li>`full` — собирать по всем событиям.</li></ul>Значение по умолчанию — `none`.
+
+## Передача параметров {#parameters}
+
+Опции для передачи значений параметров запросов из командной строки, файлов и `stdin`, а также примеры, описаны в статье ["Передача параметров в команды исполнения YQL-запросов"](yql-query-parameters.md).
 
 ## Примеры {#examples}