--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://ydb.tech/docs/en/reference/ydb-cli/parameterized-queries-cli.md?version=v25.4 - https://ydb.tech/docs/ru/reference/ydb-cli/parameterized-queries-cli.md?version=v25.4 - href: ru/reference/ydb-cli/parameterized-queries-cli.md type: text/markdown title: Markdown version - href: ../../llms.txt type: text/markdown title: llms.txt sourcePath: ru/core/reference/ydb-cli/parameterized-queries-cli.md --- > **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt {% note warning %} Данная страница устарела. Актуальная версия: [Выполнение параметризованных запросов](https://ydb.tech/docs/ru/reference/ydb-cli/parameterized-query-execution.md?version=v25.4). {% endnote %} # Выполнение параметризованных YQL-запросов и скриптов ## Обзор YDB CLI поддерживает исполнение [параметризованных YQL-запросов](https://en.wikipedia.org/wiki/Prepared_statement). Для работы с параметрами в тексте YQL-запроса должны присутствовать их определения [командой YQL `DECLARE`](https://ydb.tech/docs/ru/yql/reference/syntax/declare.md?version=v25.4). Для выполнения параметризованных YQL-запросов вы можете использовать команды YDB CLI: * [ydb yql](https://ydb.tech/docs/ru/reference/ydb-cli/yql.md?version=v25.4); * [ydb scripting yql](https://ydb.tech/docs/ru/reference/ydb-cli/scripting-yql.md?version=v25.4); * [ydb table query execute](https://ydb.tech/docs/ru/reference/ydb-cli/table-query-execute.md?version=v25.4). Данные команды поддерживают одинаковый синтаксис и возможности передачи параметров запросов. Значения параметров могут быть заданы в командной строке, загружены из файлов в формате [JSON](https://ru.wikipedia.org/wiki/JSON), а также считаны с `stdin` в бинарном формате или в формате [JSON](https://ru.wikipedia.org/wiki/JSON). При передаче параметров через `stdin` поддерживается многократное поточное исполнение YQL-запроса с разными значениями параметров и возможностью пакетирования. {% note warning %} Из всех команд исполнения YQL-запросов только команда `table query execute` применяет политики повторных попыток, обеспечивающие надежное исполнение запросов и продолжение работы при изменении набора партиций в таблицах, а также других стандартных ситуаций в распределенной базе данных, вызывающих кратковременную невозможность выполнения операций над частью данных. {% endnote %} ## Единичное исполнение YQL-запроса {#one-request} Параметры для исполнения YQL-запроса могут быть переданы из командной строки, JSON-файлов, и `stdin`, для чего в командах YDB CLI предназначены следующие параметры: Имя | Описание ---|--- `-p, --param` | Выражение в формате `$name=value`, где `$name` — имя параметра YQL-запроса, а `value` — его значение (корректный [JSON value](https://www.json.org/json-ru.html)). Может быть указано несколько раз.

Все указываемые параметры должны быть декларированы в YQL-запросе [оператором DECLARE](../../yql/reference/syntax/declare.md), иначе будет выдана ошибка «Query does not contain parameter». Если один и тот же параметр указан несколько раз, будет выдана ошибка «Parameter value found in more than one source».

В зависимости от используемой операционной системы может понадобиться экранирование символа `$` или запись выражения в одинарных кавычках `'`. `--param-file` | Имя файла в формате [JSON](https://ru.wikipedia.org/wiki/JSON) в кодировке [UTF-8](https://ru.wikipedia.org/wiki/UTF-8), в котором заданы значения параметров, сопоставляемые с параметрами YQL-запроса по именам ключей. Может быть указано несколько раз.

Если значения декларированного в YQL-запросе параметра будут обнаружены одновременно в нескольких файлах, или заданы в командной строке опцией `--param`, будет выдана ошибка «Parameter value found in more than one source».

Имена ключей в JSON-файле указываются без начального символа `$`. Ключи, которые присутствуют в файле, но не декларированы в YQL-запросе, будут проигнорированы без выдачи сообщения об ошибке. `--input-format` | Формат представления значений параметров. Действует на все способы их передачи (через параметр команды, файл или `stdin`).
Возможные значения: `--stdin-format` | Формат представления значений параметров на `stdin`.
YDB CLI автоматически определяет что на стандартное устройство ввода `stdin` перенаправлен файл или выход другой команды командной оболочки, и в этом случае интерпретирует полученные данные в соответствии с возможными значениями:Если формат представления параметров на `stdin` не задан, то применяется формат, заданный параметром `--input-format`. `--columns` | Строка с именами колонок, заменяющими header CSV/TSV документа, читаемого со stdin'а. Имена колонок должны быть в том же формате, что и сам документ. При указании опции считается, что header отсутствует. Опция допустима только с форматами stdin'a CSV и TSV. `--skip-rows` | Число строк с начала данных, читаемых со stdin'a, которые нужно пропустить, не включая строку header'a, если она имеется. Опция допустима только с форматами stdin'a CSV и TSV. `--stdin-par` | Имя параметра, значение которого передано через `stdin`. Указывается без символа `$`. Обязательно при использовании формата `raw` в `--stdin-format`.

При использовании с JSON-форматами `stdin` интерпретируется не как JSON-документ, а как JSON value, с передачей значения в параметр с указанным именем. Запрос будет отправлен на исполнение на сервер один раз, если значения заданы для всех параметров [в секции `DECLARE`](https://ydb.tech/docs/ru/yql/reference/syntax/declare.md?version=v25.4). Если хотя бы для одного параметра значение не задано, запрос не будет выполнен с выдачей сообщения об ошибке "Missing value for parameter". ### Примеры {#examples-one-request} В примерах используется команда `table query execute`, но они также могут быть выполнены командами `yql` и `scripting yql`. {% note info %} В примерах используется профиль `quickstart`, подробнее смотрите в [Создание профиля для соединения с тестовой БД](https://ydb.tech/docs/ru/reference/ydb-cli/profile/create.md?version=v25.4#quickstart). {% endnote %} #### Передача значения одного параметра {#example-simple} В командной строке: ```bash ydb -p quickstart table query execute -q 'declare $a as Int64;select $a' --param '$a=10' ``` Через файл: ```bash echo '{"a":10}' > p1.json ydb -p quickstart table query execute -q 'declare $a as Int64;select $a' --param-file p1.json ``` Через `stdin`: ```bash echo '{"a":10}' | ydb -p quickstart table query execute -q 'declare $a as Int64;select $a' ``` ```bash echo '10' | ydb -p quickstart table query execute -q 'declare $a as Int64;select $a' --stdin-par a ``` #### Передача значений параметров разных типов из нескольких источников {#example-multisource} ```bash echo '{ "a":10, "b":"Some text", "x":"Ignore me" }' > p1.json echo '{ "c":"2012-04-23T18:25:43.511Z" }' | ydb -p quickstart 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' ``` Вывод команды: ```text ┌─────────┬─────────────┬────────────────────────┬─────────┐ | column0 | column1 | column2 | column3 | ├─────────┼─────────────┼────────────────────────┼─────────┤ | 10 | "Some text" | "2012-04-23T18:25:43Z" | 30 | └─────────┴─────────────┴────────────────────────┴─────────┘ ``` #### Передача бинарных строк в кодировке Base64 {#example-base64} ```bash ydb -p quickstart table query execute \ -q 'declare $a as String; select $a' \ --input-format json-base64 \ --param '$a="SGVsbG8sIHdvcmxkCg=="' ``` Вывод команды: ```text ┌──────────────────┐ | column0 | ├──────────────────┤ | "Hello, world\n" | └──────────────────┘ ``` #### Прямая передача бинарного контента {#example-raw} ```bash curl -Ls http://ydb.tech/docs | ydb -p quickstart table query execute \ -q 'declare $a as String; select LEN($a)' \ --stdin-format raw \ --stdin-par a ``` Вывод команды (точное количество байт может отличаться): ```text ┌─────────┐ | column0 | ├─────────┤ | 66426 | └─────────┘ ``` #### Передача файла в формате CSV {#example-csv} ```bash echo '10,Some text' | ydb -p quickstart table query execute \ -q 'declare $a as Int32; declare $b as String select $a, $b' \ --stdin-format csv \ --columns 'a,b' ``` Вывод команды: ```text ┌─────────┬─────────────┐ | column0 | column1 | ├─────────┼─────────────┤ | 10 | "Some text" | └─────────┴─────────────┘ ``` ## Итеративная потоковая обработка {#streaming-iterate} YDB CLI поддерживает возможность многократного исполнения YQL-запроса с разными наборами значений параметров, при их передаче через `stdin`. При этом соединение с базой данных устанавливается однократно, а план исполнения запроса кешируется, что существенно повышает производительность такого подхода по сравнению с отдельными вызовами CLI. Для того чтобы воспользоваться этой возможностью, необходимо на `stdin` друг за другом передавать разные наборы значений одних и тех параметров, сообщив YDB CLI правило, по которому будет возможно отделить эти наборы друг от друга. YQL-запрос выполняется столько раз, сколько наборов значений параметров получено через `stdin`. Каждый полученный на `stdin` набор объядиняется со значениями параметров, определенными через другие источники (`--param`, `--param-file`). Исполнение команды будет завершено после завершения потока на `stdin`. Каждый запрос исполняется в своей транзакции. Правило отделения наборов параметров друг от друга (фрейминг) дополняет описание формата представления параметров на `stdin`, задаваемое параметром `--stdin-format`: Имя | Описание ---|--- `--stdin-format` | Задает фрейминг для `stdin`.
Возможные значения: {% note warning %} При использовании символа перевода строки в качестве разделителя наборов параметров необходимо гарантировать его отсутствие внутри наборов параметров. Заключение текста в кавычки не делает допустимым перевод строки внутри такого текста. Многострочные JSON-документы не допускаются. {% endnote %} ### Пример {#example-streaming-iterate} #### Потоковая обработка нескольких наборов параметров {#example-iterate} {% list tabs %} - JSON Допустим, нам необходимо выполнить запрос трижды, со следующими наборами значений параметров `a` и `b`: 1. `a` = 10, `b` = 20 2. `a` = 15, `b` = 25 3. `a` = 35, `b` = 48 Создадим файл, который будет содержать строки с JSON-представлением этих наборов: ```bash echo -e '{"a":10,"b":20}\n{"a":15,"b":25}\n{"a":35,"b":48}' > par1.txt cat par1.txt ``` Вывод команды: ```text {"a":10,"b":20} {"a":15,"b":25} {"a":35,"b":48} ``` Исполним запрос, передав на `stdin` содержимое данного файла, с форматированием вывода в JSON: ```bash cat par1.txt | \ ydb -p quickstart table query execute \ -q 'declare $a as Int64; declare $b as Int64; select $a+$b' \ --stdin-format newline-delimited \ --format json-unicode ``` Вывод команды: ```text {"column0":30} {"column0":40} {"column0":83} ``` Полученный в таком формате результат можно использовать для передачи на вход команде исполнения следующего YQL-запроса. - CSV Допустим, нам необходимо выполнить запрос трижды, со следующими наборами значений параметров `a` и `b`: 1. `a` = 10, `b` = 20 2. `a` = 15, `b` = 25 3. `a` = 35, `b` = 48 Создадим файл c наборами значений параметров в формате CSV: ```bash echo -e 'a,b\n10,20\n15,25\n35,48' > par1.txt cat par1.txt ``` Вывод команды: ```text a,b 10,20 15,25 35,48 ``` Исполним запрос, передав на `stdin` содержимое данного файла, с форматированием вывода в CSV: ```bash cat par1.txt | \ ydb -p quickstart table query execute \ -q 'declare $a as Int64; declare $b as Int64; select $a+$b, $a-$b' \ --stdin-format newline-delimited \ --stdin-format csv \ --format csv ``` Вывод команды: ```text 30,-10 40,-10 83,-13 ``` Полученный в таком формате результат можно использовать для передачи на вход команде исполнения следующего YQL-запроса, задав header данным в CSV формате опцией `--columns`. - TSV Допустим, нам необходимо выполнить запрос трижды, со следующими наборами значений параметров `a` и `b`: 1. `a` = 10, `b` = row1 2. `a` = 15, `b` = row 2 3. `a` = 35, `b` = "row"\n3 Создадим файл c наборами значений параметров в формате TSV: ```bash echo -e 'a\tb\n10\trow1\n15\t"row\t2"\n35\t"""row""\n3"' > par1.txt cat par1.txt ``` Вывод команды: ```text a b 10 row1 15 "row 2" 35 """row"" 3" ``` Исполним запрос, передав на `stdin` содержимое данного файла, с форматированием вывода в TSV: ```bash cat par1.txt | \ ydb -p quickstart table query execute \ -q 'declare $a as Int64; declare $b as Utf8; select $a, $b' \ --stdin-format newline-delimited \ --stdin-format tsv \ --format tsv ``` Вывод команды: ```text 10 "row1" 15 "row\t2" 35 "\"row\"\n3" ``` Полученный в таком формате результат можно использовать для передачи на вход команде исполнения следующего YQL-запроса, задав header данным в TSV формате опцией `--columns`. {% endlist %} #### Потоковая обработка с объединением значений параметров из разных источников {#example-iterate-union} Допустим, нам необходимо выполнить запрос трижды, со следующими наборами значений параметров `a` и `b`: 1. `a` = 10, `b` = 100 2. `a` = 15, `b` = 100 3. `a` = 35, `b` = 100 ```bash echo -e '10\n15\n35' | \ ydb -p quickstart table query execute \ -q 'declare $a as Int64; declare $b as Int64; select $a+$b as sum1' \ --param '$b=100' \ --stdin-format newline-delimited \ --stdin-par a \ --format json-unicode ``` Вывод команды: ```text {"sum1":110} {"sum1":115} {"sum1":135} ``` ## Пакетная потоковая обработка {#streaming-batch} YDB CLI поддерживает автоматическую конвертацию наборов параметров в `List<>`, позволяя одним запросом к серверу обработать множество наборов параметров в одной транзакции, что может дополнительно существенно повышать производительность по сравнению с выполнением запросов "по одному". Поддерживаются два режима пакетирования: - Полный - Адаптивный ### Полный режим пакетирования {#batch-full} Полный (`full`) режим является упрощенным вариантом пакетирования, когда запрос выполняется один раз, с заворачиванием в `List<>` всех полученных на `stdin` наборов параметров. Если размер запроса окажется слишком большим, будет выдана ошибка. Данный вариант пакетирования необходим в случае, когда необходимо гарантировать атомарность за счет применения всех параметров в одной транзакции. ### Адаптивный режим пакетирования {#batch-adaptive} При работе в адаптивном (`adaptive`) режиме обработка входного потока разбивается на множество транзакций, с автоматическим подбором размера пакета для каждой из них. Данный режим позволяет эффективно обрабатывать широкий спектр входной нагрузки, с непредсказуемым или бесконечным количеством данных, а также непредсказуемым или сильно меняющимся темпом их появления на входе. В частности, такой профиль характерен при подаче на `stdin` выхода другой команды через оператор `|`. Адаптивный режим решает две основных проблемы обработки динамического потока: 1. Ограничение максимального размера пакета. 2. Ограничение максимальной задержки обработки данных. ### Синтаксис {#batch-syntax} Для того чтобы воспользоваться возможностью пакетирования, необходимо описать параметр типа `List<...>` или `List>` в секции DECLARE YQL-запроса, и выбрать режим следующим параметром: Имя | Описание ---|--- `--batch` | Режим пакетирования значений наборов параметров, получаемых через `stdin`.
Возможные значения: