Выполнение запросов

С помощью подкоманды ydb sql вы можете выполнить SQL-запрос. Запрос может быть любого типа (DDL, DML и т.д.), а так же состоять из нескольких подзапросов. Подкоманда ydb sql устанавливает стрим и получает данные через него. Выполнение запроса в стриме позволяет снять ограничение на размер читаемых данных. Эта команда также позволяет записывать данные в YDB, что более эффективно при выполнении повторяющихся запросов с передачей данных через параметры.

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

ydb [global options...] sql [options...]

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

ydb sql --help

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

Имя

Описание

-h, --help

Выводит общую справку по использованию команды.

-hh

Выводит полную справку по использованию команды. Вывод содержит некоторые специфичный команды, которых нет в выводе --help.

-s, --script

Текст скрипта(запроса) для выполнения.

-f, --file

Путь к файлу, содержащему текст запроса для выполнения. Путь - означает, что текст запроса будет прочитан из stdin, при этом передача параметров через stdin будет невозможна.

--stats

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

  • none (по умолчанию) — не собирать;
  • basic: Собирать обобщенную статистику по обновлениям(update) и удалениям(delete) в таблицах.
  • full: К тому, что содержит режим basic добавляется статистика и план выполнения запроса.
  • profile: Собирать детальную статистику выполнения, содержащую статистику по каждому отдельному таску и каналу выолнения запроса.

--explain

Выполнить explain-запрос, будет выведен логический план запроса. Сам запрос не будет выполнен, поэтому не затронет данные в базе.

--explain-ast

То же, что и --explain, но вдобавок к логическому плану выводит AST (abstract syntax tree). Раздел с AST содержит представление на внутреннем языке miniKQL.

--explain-analyze

Выполнить запрос в режиме EXPLAIN ANALYZE. Показывает план выполнения запроса. Возвращаемые в рамках запроса данные игнорируются.
Важное замечание: Запрос фактически выполняется, поэтому может внести изменения в базу.

--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.

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

Подробное описание работы с параметрами с примерами смотрите в статье Выполнение параметризованных запросов.

Примеры

Примечание

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

Совместное выполнение DDL + DML в одном запросе не поддерживается.

# Создание таблицы
ydb -p quickstart sql -s '
  CREATE TABLE series (
    series_id Uint64,
    title Utf8,
    series_info Utf8,
    release_date Date,
    PRIMARY KEY (series_id)
  );
'

# Заполнение данными и получение выборки
ydb -p quickstart sql -s '
    UPSERT INTO series (series_id, title, series_info, release_date) 
    VALUES (1, "Title1", "Info1", Cast("2023-04-20" as Date));
    SELECT * FROM series;
'

# Добавление индекса
ydb -p quickstart sql -s '
    ALTER TABLE series 
    ADD INDEX title_idx GLOBAL ON (title);
'

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

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

Для выполнения запроса из файла (например, script1.yql) с выводом в формате JSON

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

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

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

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

Предыдущая
Обзор
Следующая
Выполнение параметризованных запросов