Выполнение скрипта (с поддержкой стриминга)

Важно

Данная команда устарела.
Рекомендуемый инструмент для выполнения запросов в YDB CLI — это команда ydb sql.

С помощью подкоманды yql вы можете выполнить YQL-скрипт. Скрипт может содержать запросы разных типов. В отличие от scripting yql, подкоманда yql устанавливает стрим и получает данные через него. Выполнение запроса в стриме позволяет снять ограничение на размер читаемых данных.

Общий вид команды:

ydb [global options...] yql [options...]

Посмотрите описание команды выполнения YQL-скрипта:

ydb yql --help

Параметры подкоманды

Имя

Описание

--timeout

Время, в течение которого должна быть выполнена операция на сервере.

--stats

Режим сбора статистики.
Возможные значения:

  • none (по умолчанию) — не собирать;
  • basic — собирать по основным событиям;
  • full — собирать по всем событиям.

-s, --script

Текст YQL-скрипта для выполнения.

-f, --file

Путь к файлу с текстом YQL-скрипта для выполнения.

--format

Формат вывода.
Возможные значения:

  • pretty (по умолчанию) — человекочитаемый формат;
  • json-unicode — вывод в формате JSON, бинарные строки закодированы в юникод, каждая строка JSON выводится в отдельной строке;
  • json-unicode-array — вывод в формате JSON, бинарные строки закодированы в Юникод, результат выводится в виде массива строк JSON, каждая строка JSON выводится в отдельной строке;
  • json-base64 — вывод в формате JSON, бинарные строки закодированы в Base64, каждая строка JSON выводится в отдельной строке;
  • json-base64-array — вывод в формате JSON, бинарные строки закодированы в Base64, результат выводится в виде массива строк JSON, каждая строка JSON выводится в отдельной строке;
  • parquet: вывод в формате Apache Parquet.
  • csv — вывод в формате CSV;
  • tsv — вывод в формате TSV.

Работа с параметризованными запросами

Ниже приведена краткая справка, расширенное описание с примерами смотрите в статье Выполнение параметризованных YQL-запросов и скриптов.

Имя Описание
-p, --param Значение одного параметра YQL-запроса в формате $name=value, где $name — имя параметра, а value — его значение (корректный JSON value).
--param-file Имя файла в формате JSON в кодировке UTF-8, в котором заданы значения параметров, сопоставляемые с параметрами YQL-запроса по именам ключей.
--input-format Формат представления значений параметров. Действует на все способы их передачи (через параметр команды, файл или stdin).
Возможные значения:
  • json-unicode (по умолчанию) — JSON.
  • json-base64 — JSON, в котором значения параметров с типом «бинарная строка» (DECLARE $par AS String) представлены в кодировке Base64.
--stdin-format Формат представления параметров и фрейминг для stdin. Чтобы задать оба значения, укажите параметр дважды.
Формат представления параметров на stdin
Возможные значения:
  • json-unicode — JSON.
  • json-base64 — JSON, в котором значения параметров с типом «бинарная строка» (DECLARE $par AS String) представлены в кодировке Base64.
  • raw — бинарные данные, имя параметра задается опцией --stdin-par.
  • csv — формат CSV.
  • tsv — формат TSV.
Если формат представления параметров на stdin не задан, то применяется формат, заданный параметром --input-format.

Разделение наборов параметров (фрейминг) для stdin
Возможные значения:
  • no-framing (по умолчанию) — фрейминг не применяется
  • newline-delimited — символ перевода строки отмечает на stdin окончание одного набора параметров, отделяя его от следующего.
--columns Строка с именами колонок, заменяющими header CSV/TSV документа, читаемого со stdin'а. Имена колонок должны быть в том же формате, что и сам документ.
--skip-rows Число строк с начала данных, читаемых со stdin'a, которые нужно пропустить, не включая строку header'a.
--stdin-par Имя параметра, значение которого будет передано через stdin, указывается без символа $.
--batch Режим пакетирования значений наборов параметров, получаемых через stdin.
Возможные значения:
  • iterative (по умолчанию) — пакетирование выключено
  • full - полный пакет
  • adaptive - адаптивное пакетирование
--batch-limit Максимальное количество наборов параметров в пакете для адаптивного режима пакетирования. Установка в 0 снимает ограничение.

Значение по умолчанию — 1000.
--batch-max-delay Максимальная задержка отправки на обработку полученного набора параметров для адаптивного режима пакетирования. Задается в виде числа с размерностью времени - s, ms, m.

Значение по умолчанию — 1s (1 секунда).

Примеры

Примечание

В примерах используется профиль quickstart, подробнее смотрите в Создание профиля для соединения с тестовой БД.

Скрипт создания строковой таблицы, заполнения её данными, и получения выборки из этой таблицы:

ydb -p quickstart yql -s '
    CREATE TABLE series (series_id Uint64, title Utf8, series_info Utf8, release_date Date, PRIMARY KEY (series_id));
    COMMIT;
    UPSERT INTO series (series_id, title, series_info, release_date) values (1, "Title1", "Info1", Cast("2023-04-20" as Date));
    COMMIT;
    SELECT * from series;
  '

Вывод команды:

┌──────────────┬───────────┬─────────────┬──────────┐
| release_date | series_id | series_info | title    |
├──────────────┼───────────┼─────────────┼──────────┤
| "2023-04-20" | 1         | "Info1"     | "Title1" |
└──────────────┴───────────┴─────────────┴──────────┘

Выполнение скрипта из примера выше, записанного в файле script1.yql, с выводом результатов в формате JSON:

ydb -p quickstart yql -f script1.yql --format json-unicode

Вывод команды:

{"release_date":"2023-04-20","series_id":1,"series_info":"Info1","title":"Title1"}

Примеры передачи параметров в скрипты приведены в статье о передаче параметров в команды исполнения YQL.