Команды

В данном разделе перечислены все команды, доступные в API системы YTsaurus, с полным описанием их опций.

Структура

Упрощенно каждая команда представляет собой:

  • Имя команды (строка);
  • Описание входного и выходного форматов (YSON-строка с атрибутами);
  • Параметры исполняемого действия (YSON-структура);
  • Входной и выходной потоки данных.

Каждая команда также определяет тип входных и выходных данных. Ниже перечислены возможные варианты входных и выходных данных:

  • Данные отсутствуют (null);
  • Данные являются бинарным потоком (binary). Например содержимое файлов;
  • Данные структурированы (structured). Например обычные узлы Кипариса;
  • Данные являются табличным потоком (tabular). Например содержимое таблиц.

Кроме того, каждая команда может быть:

  • Мутирующей или нет (меняет ли она что-нибудь в метасостоянии или нет);
  • Легкой или тяжелой (легкие команды передают в запросе только параметры команды, тяжелые же пишут или читают поток данных).

Форматы

Если команда работает со структурированными или табличными данными, для неё следует указать формат. Для входного потока данных служит параметр input_format, для выходного потока параметр output_format соответственно.

В случае структурированных данных поддерживаются форматы yson (используется по умолчанию) и json. Для табличных данных существует множество различных форматов.

Повторное выполнение (ретраи)

Под повторным выполнением команды мы понимаем возможность повторить запрос в случае возникновения транзиентных (временных) ошибок. Ожидается, что ответ на повторный запрос будет не отличим от ответа на исходный запрос, как если бы транзиентных ошибок не возникло. Это не означает, что ответ на повторный запрос действительно будет тем же самым, что на исходные, то есть гарантируется лишь стандартный уровень "изоляции".

Возможность повторно выполнить команду и механизм повторения зависит от свойств команды.

Легкие команды

Для немутирующих легких команд можно повторить исходный запрос.

Мутирующие легкие команды изменяют состояние системы, поэтому необходимо системе подсказать, что такой запрос уже задавался. Для этого, перед тем как выполнять команду, необходимо сгенерировать mutation_id для команды. Это стандартный GUID, состоящий из 4-х 32-битных чисел в HEX-формате, разделенных символом -.

Сгенерированный mutation_id необходимо указать в параметрах как исходного запроса, так и повторных запросов. Кроме того, в исходный запрос необходимо добавить параметр retry со значением false, а в повторные параметр retry со значением true. Некоторые легкие мутирующие команды не поддерживают повторное выполнение: к таким относится concatenate. Такие команды можно выполнить повторно, используя транзакции.

Примечание

mutation_id обычно хранится 5-10 минут.

Тяжелые команды

Тяжелые команды нельзя выполнить повторно. Однако, пользуясь транзакциями, можно написать механизм повторного выполнения.

Транзакции

Транзакции являются неотъемлемым свойством Кипариса. Многие команды, которые так или иначе работают с Кипарисом, являются транзакционными. У каждой команды или группы команд отдельно отмечено, является команда транзакционной или нет. Если команда является транзакционной, у неё поддерживаются следующие параметры:

Параметр Обязательный Значение по умолчанию Описание
transaction_id Нет null-transaction-id Идентификатор текущей транзакции.
ping_ancestor_transactions Нет false Пинговать ли все родительские транзакции в процессе выполнения операции.

Другие параметры запросов

Также имеется возможность указывать пререквизиты у запросов, а также для легких немутирующих запросов указывать, откуда производить чтение. Подробную информацию можно найти в разделе Параметры запросов.

Работа с транзакциями

Подробную информацию про транзакции можно найти в статье Транзакции.

start_tx

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Начать новую транзакцию в контексте текущей транзакции.
  • Новая транзакция является вложенной (внутренней) по отношению к указанной.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
transaction_id Нет null-transaction-id Идентификатор текущей транзакции (которая станет родительской для транзакции, созданной командой).
ping_ancestor_transactions Нет false Пинговать (продлевать время жизни) все родительские транзакции в процессе выполнения операции.
timeout Нет 15000 Время жизни транзакции с момента последнего продления (в мс).
deadline Нет missing Дедлайн на время выполнения транзакции (в UTC).
attributes Нет missing Позволяет задать атрибуты создаваемой транзакции.
type Нет master Позволяет задать тип транзакции: master или tablet.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Значение: идентификатор новой транзакции.

Пример:

PARAMETERS { "transaction_id" = "0-54b-1-36223d20" }
OUTPUT "0-54c-1-bb49086d"

ping_tx

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Обновить транзакцию.

Подробное описание:

  • ping_tx пингует транзакцию на сервере (включая все родительские, если указан ping_ancestors), тем самым обновляя время ее жизни.
  • Если транзакция была начата в момент времени s с таймаутом (временем жизни) t, то по умолчанию транзакция завершится в момент времени s + t.
  • Если ее пинговать в момент времени r (s < r < s + t), то транзакция будет продлена вплоть до момента r + t.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
transaction_id Да Идентификатор родительской транзакции.
ping_ancestor_transactions Нет false Пинговать ли все родительские транзакции в процессе выполнения операции.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "transaction_id" = "0-54b-1-36223d20" }

commit_tx

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Успешно завершить транзакцию.
  • При наличии незавершенных внутренних транзакций успешное завершение внешней транзакции невозможно.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
transaction_id Да Идентификатор транзакции.
ping_ancestor_transactions Нет false Пинговать ли все родительские транзакции в процессе выполнения операции.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "transaction_id" = "0-54b-1-36223d20" }

abort_tx

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Прервать транзакцию.
  • Все активные внутренние транзакции прерываются.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
transaction_id Да Идентификатор транзакции.
ping_ancestor_transactions Нет false Пинговать ли все родительские транзакции в процессе выполнения операции.
force Нет false Принудительно прерывает транзакцию, даже если это может привести к потере консистентности (в случае tablet-транзакции и двухфазного коммита).

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "transaction_id" = "0-54b-1-36223d20" }

Работа с Кипарисом

Подробную информацию про дерево метаинформации можно найти в статье Кипарис.

Примечание

Все команды для работы с Кипарисом являются транзакционными.

create

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Создать узел заданного типа в Кипарисе.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до узла в Кипарисе. При настройках по умолчанию путь не должен существовать.
type Да Тип узла.
recursive Нет false Создавать ли рекурсивно промежуточные узлы.
attributes Нет {} Позволяет задать атрибуты создаваемого узла.
ignore_existing Нет false В случае, если заказанный узел уже существует, то он не пересоздается заново. В частности, переданные атрибуты игнорируются. Также тип существующего узла и заказываемого должны совпадать, иначе выполнение запроса завершится ошибкой.
lock_existing Нет false Установить на указанный узел exclusive-блокировку, даже если он уже существует. Используется только вместе с ignore_existing. Если невозможно установить блокировку, команда завершится ошибкой.
force Нет false Если указанный узел уже существует, то он удаляется и на его месте создается новый. При этом существующий узел может быть любого типа. При пересоздании меняется идентификатор узла.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Значение: идентификатор созданного узла.

Примеры:

PARAMETERS { "path" = "//tmp/table" ; "type" = "table" }
OUTPUT "0-4-191-6c07cd58"
PARAMETERS { "type" = "user" ; attributes = { name = 'kulichek-robot' } }
OUTPUT "7727-417b1-1f5-d4f116ca"
PARAMETERS { "path" = "//tmp/document" ; "type" = "document" ; attributes = { value = {} } }
OUTPUT "7727-417b1-1f5-d4f116ca"

remove

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Удалить узел Кипариса.
  • Успешно удаляет узел, даже если из него растет непустое поддерево.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до узла в Кипарисе. Путь должен существовать.
recursive Нет false Позволяет удалить все поддерево в случае, если удаляемый узел является составным типом.
force Нет false Позволяет считать команду успешно выполненной, если удаляемый узел отсутствует.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "path" = "//tmp/table" }

set

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Записать новое содержимое узла Кипариса.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до узла в Кипарисе. Если recursive == false, то путь должен существовать за исключением, возможно, последнего токена.
recursive Нет false Создать все несуществующие промежуточные узлы пути.
force Нет false Позволяет менять любые узлы Кипариса, а не только атрибуты и документы.

Входные данные:

  • Тип: structured.
  • Значение: содержимое узла;

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "path" = "//tmp/node" }
INPUT {
    "my_integer" = 4 ;
    "my_double" = 2.718281828 ;
    "map" = { "a" = 1 ; "b" = 2 } ;
    "list" = [ 1, 2, 3 ]
}

multiset_attributes

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Выставить несколько атрибутов по заданному пути (если атрибуты уже существуют, они будут перезаписаны).

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до атрибутов узла в Кипарисе, путь должен существовать.

Входные данные:

  • Тип: structured.
  • Значение: map-узел, содержащий новые значения атрибутов.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "path" = "//tmp/node/@" }
INPUT {
    "attribute1" = 4 ;
    "attribute2" = "attribute2 value";
}

get

Свойства команды: Немутирующая, Легкая.

Семантика:

  • Получить содержимое узла Кипариса.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до узла в Кипарисе. Путь должен существовать.
attributes Нет [] Список атрибутов, которые нужно получить вместе с каждым узлом.
max_size Нет missing Ограничение на количество детей, которые будут выданы в случае виртуальных составных узлов (для обычных map-узлов в настоящий момент эта опция не имеет смысла).
ignore_opaque Нет false Игнорировать атрибут opaque при выполнении запроса (никогда не используйте эту опцию без явных рекомендаций от разработчиков YTsaurus).

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Значение: содержимое узла.

Пример:

PARAMETERS { "path" = "//tmp/node" }
OUTPUT {
    "my_integer" = 4 ;
    "my_double" = 2.718281828 ;
    "map" = { "a" = 1 ; "b" = 2 } ;
    "list" = [ 1, 2, 3 ]
}

list

Свойства команды: Немутирующая, Легкая.

Семантика:

  • Получить список потомков узла Кипариса.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до узла в Кипарисе. Путь должен существовать.
attributes Нет [] Список атрибутов, которые нужно получить вместе с каждым узлом.
max_size Нет missing Ограничение на количество детей, которые будут выданы.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured
  • Значение: список потомков узла.

Пример:

PARAMETERS { "path" = "//tmp/node" }
OUTPUT [
    "home" ;
    "sys" ;
    "statbox" ;
    "tmp"
]

lock

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Установить блокировку на узел Кипариса.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до узла в Кипарисе. Путь должен существовать.
mode Нет exclusive Тип блокировки (snapshot, shared, exclusive).
waitable Нет false В случае конфликта не завершаться ошибкой, а встать в очередь. Была ли блокировка установлена фактически, можно узнать с помощью атрибута state объекта блокировки. См. Транзакции.
child_key Нет Ключ в словаре, по которому надо взять блокировку (только для типа shared).
attribute_key Нет Имя атрибута, по которому надо взять блокировку (только для типа shared).

Примечание

Для данной команды необходимо указывать идентификатор транзакции.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured.
  • Значение: идентификатор созданной блокировки и идентификатор узла в момент ответвления.

Пример:

PARAMETERS { "path" = "//tmp/node" }
OUTPUT {
OUTPUT   "lock_id" = "0-1-3fe00c8-353e9ba4";
OUTPUT   "node_id" = "0-1-3fe012f-9ad48d90";
OUTPUT }

unlock

Внимание

Блокировки автоматически снимаются по завершении транзакции. Не следует использовать команду unlock без веской необходимости. См. Транзакции.

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Снять с узла Кипариса все блокировки для заданной транзакции.
  • Снимать можно только явные блокировки.
  • Снимаются как уже взятые, так и ожидающие в очереди блокировки.
  • Если узел не заблокирован, команда считается успешной.
  • Если заблокированная версия узла содержит изменения в сравнении с оригинальной, разблокировка завершается ошибкой.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до узла в Кипарисе. Путь должен существовать.

Примечание

Для данной команды необходимо указывать идентификатор транзакции.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "path" = "//tmp/node" }

copy

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Скопировать узел Кипариса по новому адресу.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
source_path Да Путь до исходного узла в Кипарисе; путь должен существовать.
destination_path Да Путь, по которому будет создана копия; путь не должен существовать.
recursive Нет false Создавать ли пропущенные уровни (map-узлы) по пути назначения.
ignore_existing Нет false Если узел по пути destination_path уже существует, ничего не делать (нельзя указывать одновременно с force = %true).
lock_existing Нет false Установить на узел по пути destination_path exclusive-блокировку, даже если он уже существует. Используется только вместе с ignore_existing. В случае невозможности установить блокировку команда завершится ошибкой.
force Нет false Разрешает указывать в качестве пути назначения уже существующий узел, который должен быть заменен.
preserve_account Нет false Сохранять ли аккаунты исходных узлов или использовать аккаунт пути назначения.
preserve_expiration_time Нет false Копировать ли атрибут expiration_time или оставлять его пустым.
preserve_expiration_timeout Нет false Копировать ли атрибут expiration_timeout или оставлять его пустым.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Значение: идентификатор созданного узла.

Пример:

PARAMETERS {
    "source_path" = "//tmp/from" ;
    "destination_path" = "//tmp/to" ;
}
OUTPUT "0-4-191-6c07cd58"

move

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Перенести узел Кипариса по новому адресу.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
source_path Да Путь до исходного узла в Кипарисе. Путь должен существовать.
destination_path Да Новый путь в Кипарисе; путь не должен существовать.
recursive Нет false Создавать ли пропущенные уровни (map-узлы) по пути назначения.
force Нет false Разрешает указывать в качестве пути назначения уже существующий узел, который должен быть заменен.
preserve_account Нет false Сохранять ли аккаунты исходных узлов или использовать аккаунт пути назначения.
preserve_expiration_timeout Нет false Копировать ли атрибут expiration_timeout или оставлять его пустым.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS {
    "source_path" = "//tmp/from" ;
    "destination_path" = "//tmp/to" ;
}

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Создать символическую ссылку на объект по новому адресу.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
link_path Да Путь, по которому будет создана ссылка; путь не должен существовать.
target_path Да Путь до исходного узла в Кипарисе; путь должен существовать
attributes Нет missing Атрибуты узла, созданного в результате выполнения команды.
recursive Нет false Создавать ли рекурсивно промежуточные узлы.
ignore_existing Нет false Позволяет не падать с ошибкой, если указанный узел уже существует и является ссылкой. Вызов вернёт ошибку если узел существует, но ссылкой не является.
lock_existing Нет false Установить на узел исключительную блокировку, даже если он уже существует. Используется только вместе с параметром ignore_existing.
force Нет false Пересоздать ссылку, если путь, по которому будет создана ссылка, уже существует.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Значение: идентификатор созданного узла.

Пример:

PARAMETERS {
    "target_path" = "//tmp/from" ;
    "link_path" = "//tmp/to" ;
}
OUTPUT "0-4-191-6c07cd58"

exists

Свойства команды: Немутирующая, Легкая.

Семантика:

  • Проверяет существование узла.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до исходного узла в Кипарисе.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Значение: строка true или false.

Пример:

PARAMETERS {
    "path" = "//tmp/my_table/@_format" ;
}

concatenate

Семантика:

  • Склеить набор файлов или таблиц (в том порядке, в котором указаны пути).

Параметры:

Параметр Обязательный Значение по умолчанию Описание
transaction_id Нет null-transaction-id Идентификатор текущей транзакции.
ping_ancestor_transactions Нет false Пинговать ли все родительские транзакции в процессе выполнения операции.
source_paths Да Список путей до входных файлов или таблиц в Кипарисе; пути должны существовать и все являться либо файлами, либо таблицами.
destination_path Да Путь до файла или таблицы в Кипарисе; путь должен существовать.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS {
    "source_paths" = ["//tmp/file1"; "//tmp/file2"];
    "destination_path" = "//tmp/file";
}

Работа с контролем доступа

Подробную информацию про права доступа можно найти в разделе Контроль доступа.

Примечание

Данный набор команд не является транзакционным.

add_member

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Добавить пользователя или другую группу в группу.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
member Да Имя пользователя или группы, которую необходимо добавить в группу.
group Да Имя группы, в которую необходимо добавить.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS {
    "group" = "admins";
    "member" = "devs";
}

remove_member

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Удалить пользователя или другую группу из группу.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
member Да Имя пользователя или группы, которое необходимо удалить из группы.
group Да Имя группы, из которой необходимо удалить.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS {
    "group" = "admins";
    "member" = "devs";
}

check_permission

Свойства команды: Немутирующая, Легкая.

Семантика:

  • Проверить, есть ли у пользователя определённое право на определённый узел Кипариса.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до узла в Кипарисе.
user Да Имя пользователя, для которого необходимо проверить наличие права.
permission Да Название права, наличие которого необходимо проверить.
columns Нет Список колонок, доступ к которым требуется проверить.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS {
    "path" = "//sys/accounts/statbox";
    "permission" = "use";
    "user" = "vasya";
}

Работа с файлами

Подробную информацию про файлы можно найти в статье Файлы.

Примечание

Все команды для работы с файлами являются транзакционными.

write_file

Свойства команды: Мутирующая, Тяжелая.

Синонимы (поддерживаются, но не рекомендуются):

  • upload.

Семантика:

  • Загрузить содержимое в файл;
  • Файл должен существовать;
  • Если на пути path к файлу указан атрибут append=%true, то данные добавляются в конец, иначе файл переписывается.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
transaction_id Нет null-transaction-id Идентификатор текущей транзакции.
ping_ancestor_transactions Нет false Пинговать ли все родительские транзакции в процессе выполнения операции.
path Да Путь до файла в Кипарисе; путь должен существовать.
compute_md5 Нет false Подсчитывать ли MD5-сумму по записываемому файлу; если compute_md5=%true и append=%true , но у файла нет атрибута md5 (то есть раньше его писали без compute_md5=%true ), возникнет ошибка.

Входные данные:

  • Тип: binary;
  • Значение: содержимое файла.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS {"path" = "//tmp/file"}
INPUT this is sample file content

read_file

Свойства команды: Немутирующая, Тяжелая.

Синонимы (поддерживаются, но не рекомендуются):

  • download.

Семантика:

  • Получить содержимое файла из Кипариса.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
transaction_id Нет null-transaction-id Идентификатор текущей транзакции.
ping_ancestor_transactions Нет false Пинговать ли все родительские транзакции в процессе выполнения операции.
path Да Путь до файла в Кипарисе; путь должен существовать.
offset Нет 0 Позиция, начиная с которой нужно читать данные.
length Нет Длина данных, которые необходимо вычитать, по умолчанию файл читается до конца.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: binary;
  • Значение: содержимое файла.

Пример:

PARAMETERS { "path" = "//tmp/file" }
OUTPUT this is sample file content

Работа с файловым кешем

Подробную информацию про файловый кеш можно найти в разделе Файловый кеш.

put_file_to_cache

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Положить файл в кеш;
  • Проверяет, что по переданному пути лежит файл, MD5 хеш которого соответствует переданному в опциях команды.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь к файлу в Кипарисе.
md5 Да Ожидаемый MD5 хеш файла.
cache_path Да Путь к файловому кешу.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Значение: путь к файлу в кеше.

Пример:

PARAMETERS {
    "path" = "//tmp/file";
    "md5" = "a3dcb4d229de6fde0db5686dee47145d";
    "cache_path" = "//tmp/yt_wrapper/file_storage/new_cache";
}
OUTPUT "//tmp/yt_wrapper/file_storage/new_cache/5d/a3dcb4d229de6fde0db5686dee47145d"

get_file_from_cache

Свойства команды: Немутирующая, Легкая.

Семантика:

  • Получить путь к файлу в кеше.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
md5 Да MD5 хеш файла.
cache_path Да Путь к файловому кешу.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Значение: путь к файлу в кэше.

Пример:

PARAMETERS {
    "md5" = "a3dcb4d229de6fde0db5686dee47145d";
    "cache_path" = "//tmp/yt_wrapper/file_storage/new_cache";
}
OUTPUT "//tmp/yt_wrapper/file_storage/new_cache/5d/a3dcb4d229de6fde0db5686dee47145d"

Работа с таблицами

Подробную информацию про статические таблицы можно найти в разделе Статические таблицы.

Подробную информацию про динамические таблицы можно найти в разделе Динамические таблицы.

write_table

Свойства команды: Мутирующая, Тяжелая.

Применимость: Статические таблицы.

Синонимы (поддерживаются, но не рекомендуются):

  • write.

Семантика:

  • Добавить новые записи в статическую таблицу;
  • Таблица должна существовать;
  • Если на пути path к таблице указан атрибут append=%true, то записи добавляются в конец, иначе таблица перезаписывается;
  • Если на пути path к таблице указан атрибут sorted_by, то проверяется, что данные отсортированы по указанному набору ключей и результирующая таблица помечается как сортированная. Запись сортированных данных (с указанным атрибутом sorted_by) разрешена только в случае, если все новые ключи не меньше всех старых;
  • Запись несортированных данных (без атрибута sorted_by) разрешена в любую таблицу, но флаг сортированности у таблицы сбрасывается;
  • Команда может быть выполнена внутри транзакции.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до таблицы в Кипарисе; путь должен существовать.
table_writer Нет Из конфигурации драйвера Опции записи таблицы.

Входные данные:

  • Тип: tabular;
  • Значение: содержимое таблицы.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS {
    "path" = "//tmp/node" ;
    "table_writer" = { "codec_id" = "gzip" };
}
INPUT { "id" = 1; "value" = 1.125; };
INPUT { "id" = 2; "value" = 2.000; };
INPUT { "id" = 3; "value" = 3.850; };

read_table

Свойства команды: Немутирующая, Тяжелая.

Применимость: Статические и динамические таблицы.

Синонимы (поддерживаются, но не рекомендуются):

  • read.

Семантика:

  • Получить записи из таблицы в Кипарисе;
  • Команда может быть выполнена внутри транзакции.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до таблицы в Кипарисе; путь должен существовать.
table_reader Нет Из конфигурации драйвера Опции чтения таблицы.
control_attributes Нет Из конфигурации драйвера Конфигурация контрольных атрибутов чтения.
unordered Нет false Производить ли чтения параллельно, не заботясь о порядке записей.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: tabular;
  • Значение: содержимое таблицы.

Пример:

PARAMETERS { "path" = "//tmp/node" }
OUTPUT { "id" = 1; "value" = 1.125; };
OUTPUT { "id" = 2; "value" = 2.000; };
OUTPUT { "id" = 3; "value" = 3.850; };

read_blob_table

Свойства команды: Немутирующая, Тяжелая.

Применимость: Статические таблицы с бинарными данными.

Семантика:

  • Получить бинарный поток данных из отдельной колонки таблицы в Кипарисе.
  • Команда может быть выполнена внутри транзакции.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до таблицы в Кипарисе; путь должен существовать.
table_reader Нет Из конфига драйвера Опции чтения таблицы.
part_index_column_name Нет part_index Имя колонки, в котором хранятся индексы блобов.
data_column_name Нет data Имя колонки, в котором хранятся данные.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: binary;
  • Значение: содержимое колонки с данными в таблицы.

Пример:

PARAMETERS { "path" = "//tmp/node" }
OUTPUT "Hello world"

select_rows

Свойства команды: Немутирующая, Тяжелая.

Применимость: Динамические таблицы.

Семантика:

  • Выполнить SQL-подобный запрос для динамической таблицы в соответствии с поддерживаемыми возможностями;
  • Транзакция может быть выполнена относительно слепка данных с указанной меткой времени.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
query Да Строка запроса.
timestamp Нет sync last committed Относительно какой временной метки следует выполнить запрос.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: tabular;
  • Значение: набор строк с результатом.

Пример:

PARAMETERS { "query" = "key, value from [//tmp/sometable]" }
OUTPUT { "key" = 1; "value" = "hello"; };
OUTPUT { "key" = 2; "value" = "world; };

insert_rows

Свойства команды: Мутирующая, Тяжелая.

Применимость: Динамические таблицы.

Семантика:

  • Записать строки в динамическую таблицу.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до динамической таблицы.
update Нет false Если выставлено false, колонки, которые отсутствуют во входных данных, будут записаны со значением Null (перезаписывая текущее значение в таблице). Если выставлено true, такие колонки сохранят своё предыдущее значение в таблице.
aggregate Нет false Если выставлено false, агрегирующие колонки перезатерты новым значением. Если выставлено true, такие колонки применят дельту из входных данных.
atomicity Нет full Поддерживаются значения none и full. Если выставлено none, запись будет происходить на каждом таблете, независимо от других. Если выставленоfull, будут записаны либо все переданные строки, либо ничего. Подробнее.
require-sync-replica Нет true Опция имеет смысл только в случае репликации. Если выставлено в true, то вставка произойдёт только при наличии у таблицы синхронной реплики. Если выставлено в false, то наличие синхронной реплики необязательно.

Входные данные:

  • Тип: tabular;
  • Значение: содержимое таблицы.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "path" = "//home/user/table" }
INPUT { "id" = 1; "value" = 1.125; };
INPUT { "id" = 2; "value" = 2.000; };
INPUT { "id" = 3; "value" = 3.850; };

delete_rows

Свойства команды: Мутирующая, Тяжелая.

Применимость: Динамические таблицы.

Семантика:

  • Удалить из динамической таблицы строки с указанными ключами.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до динамической таблицы.

Входные данные:

  • Тип: tabular;
  • Значение: набор строк с ключами.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "path" = "//tmp/sometable" }
INPUT { "id" = 1; };
INPUT { "id" = 2; };
INPUT { "id" = 3; };

lock_rows

Свойства команды: Мутирующая, Тяжелая.

Применимость: Динамические таблицы.

Семантика:

  • Заблокировать строки на запись в динамической таблице на время выполнения текущей транзакции.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до динамической таблицы.
locks Да Список затрагиваемых групп блокировок (lock group в схеме таблицы).
lock_type Нет shared strong Виды блокировок: shared weak, shared strong, exclusive.

Shared-блокировка может быть взята из множества разных транзакций одновременно. Exclusive-блокировка - из одной транзакции, обычно меняющей данную строку.

При использовании блокировок на чтение (в отличие от блокировок на запись) одна строка может быть заблокирована из множества разных транзакций. Таким образом, при непрерывном потоке транзакций, берущих shared-блокировку на некоторую строку, строка будет заблокирована постоянно, и модифицировать её не получится. Этот эффект называется write starvation. В случае write-write конфликтов такого быть не может, так как берется exclusive lock, который отпускается каждый раз при завершении транзакции с записью.

Для ослабления эффекта write starvation можно понижать изоляцию shared-блокировок. Для этого можно указывать режим блокировки weak или strong. Режим weak отличается тем, что в момент завершения транзакции не запоминаются временные метки, до которых строки были заблокированы разделяемыми блокировками. На практике это означает, что не блокируется запись, которая происходит в транзакции, пересекающейся по времени с данной, но завершение которой происходит позже. При этом если завершение write-транзакции произошло раньше, то транзакция с shared-блокировкой не будет применена. В режиме weak shared-блокировка становится асимметричной.

Входные данные:

  • Тип: tabular;
  • Значение: набор строк с ключами.

lookup_rows

Свойства команды: Немутирующая, Тяжелая.

Применимость: Динамические таблицы.

Семантика:

  • Выбрать из таблицы строки с указанными ключами;
  • Команда может быть выполнена относительно слепка данных с указанной меткой времени;
  • Гарантируется, что относительный порядок найденных строк в ответе будет совпадать с порядком ключей в запросе.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до динамической таблицы. Путь должен быть простым (не содержать колонок, диапазонов и т.д.)
column_names Нет Какие колонки включить в ответ.
keep_missing_rows Нет false Включать ли в ответ строки, соответствующие не найденным ключам; если выставлено true, на соответствующих позициях будут # (entity).
timestamp Нет sync last committed Относительно какой метки времени следует выполнить запрос.

Входные данные:

  • Тип: tabular;
  • Значение: набор строк с ключами.

Выходные данные:

  • Тип: tabular;
  • Значение: набор строк с указанными ключами и запрошенными колонками.

Пример:

PARAMETERS { "path" = "//tmp/sometable" }
INPUT { "id" = 1; };
INPUT { "id" = 2; };
INPUT { "id" = 3; };
OUTPUT { "id" = 1; "value" = 1.125; };
OUTPUT { "id" = 2; "value" = 2.000; };
OUTPUT { "id" = 3; "value" = 3.850; };

trim_rows

Свойства команды: Мутирующая, Тяжелая.

Применимость: Упорядоченные динамические таблицы.

Семантика:

  • Удалить строки из начала таблета упорядоченной динамической таблицы. После этого удаленные данные уже нельзя прочитать командой select_rows. Нумерация остальных строк при этом не меняется;
  • Команда выполняется вне транзакций.

Параметры:

параметр Обязательный Значение по умолчанию Описание
path Да Путь до динамической таблицы.
tablet_index Да Номер обрезаемого таблета.
trimmed_row_count Да Количество удаляемых строк.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "path" = "//home/user/table"; tablet_index = 10; trimmed_row_count = 43 }

mount_table

Свойства команды: Мутирующая, Легкая.

Применимость: Динамические таблицы.

Семантика:

  • Монтирует таблеты динамической таблицы.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до динамической таблицы.
first_tablet_index Нет 0 Номер первого монтируемого таблета.
last_tablet_index Нет tablet_count - 1 Номер последнего монтируемого таблета.
cell_id Нет Если указано, то монтирование таблетов происходит в данный селл. Если нет, то система сама выбирает подходящие селлы (и в большинстве случаев стоит отдать ей этот выбор).
freeze Нет false Если выставлено в true то таблеты монтируются в замороженное состояние. См. также описание команды freeze_table.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "path" = "//home/user/table" }

unmount_table

Свойства команды: Мутирующая, Легкая.

Применимость: Динамические таблицы.

Семантика:

  • Отмонтирует таблеты динамической таблицы.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до динамической таблицы.
first_tablet_index Нет 0 Номер первого отмонтируемого таблета.
last_tablet_index Нет tablet_count - 1 Номер последнего отмонтируемого таблета.
force Нет false Принудительно отмонтировать таблеты. Существует риск потери данных, поэтому для использования флага необходимы права администратора YTsaurus.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "path" = "//home/user/table"; "first_tablet_index" = 10; "last_tablet_index" = 20; }

remount_table

Свойства команды: Мутирующая, Легкая.

Применимость: Динамические таблицы.

Семантика:

  • Позволяет обновлять ряд настроек динамических таблиц без отмонтирования;
  • При таком перемонтировании таблица остается доступной на чтение и запись;
  • Настройки берутся из атрибутов таблицы и в итоге доходят до узла, где происходит обработка таблетов.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до динамической таблицы.
first_tablet_index Нет 0 Номер первого перемонтируемого таблета.
last_tablet_index Нет tablet_count - 1 Номер последнего перемонтируемого таблета.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "path" = "//home/user/table" }

freeze_table

Свойства команды: Мутирующая, Легкая.

Применимость: Динамические таблицы.

Семантика:

  • Переводит таблеты динамической таблицы в замороженное состояние, сбрасывая все данные на диск. В этом состоянии возможно чтение данных, но невозможна новая запись. При этом все ранее записанные данные оказываются в чанках, так что они, например, доступны для map-reduce операций (даже без использования опции enable_dynamic_store_read).

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до динамической таблицы.
first_tablet_index Нет 0 Номер первого замораживаемого таблета.
last_tablet_index Нет tablet_count - 1 Номер последнего замораживаемого таблета.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "path" = "//home/user/table" }

unfreeze_table

Свойства команды: Мутирующая, Легкая.

Применимость: Динамические таблицы.

Семантика:

  • Отменяет ранее выполненную (например командой freeze_table) заморозку таблицы, открывая таблицу на запись.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до динамической таблицы.
first_tablet_index Нет 0 Номер первого размораживаемого таблета.
last_tablet_index Нет tablet_count - 1 Номер последнего размораживаемого таблета.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "path" = "//home/user/table" }

reshard_table

Свойства команды: Мутирующая, Легкая.

Применимость: Динамические таблицы.

Семантика:

  • Изменяет состав таблетов динамической таблицы;
  • Затронутые таблеты должны быть отмонтированы;
  • Для упорядоченной таблицы должен быть указан tablet_count. Для сортированной таблицы можно указать как tablet_count, так и pivot_keys. При этом затронутые таблеты заменяются на набор новых;
  • В случае сортированной таблицы:
    • при передаче pivot_keys первый ключ в pivot_keys должен совпадать с первым ключом первого решардируемого таблета. Количество ключей pivot_keys равно количеству таблетов, на которые разбиваются затронутые таблеты;
    • при передаче tablet_count система сама выберет pivot-ключи исходя из имеющихся данных в таблице, по возможности равномерно. Если таблица недостаточного размера, в результате может получиться меньше таблетов, чем заказано. При настройках по умолчанию получаемые таблеты не могут оказаться размером менее, чем примерно 200 МБ. Для более мелкой нарезки следует использовать опцию enable_slicing;
    • если первая ключевая колонка таблицы имеет целочисленный тип, вместе с tablet_count можно указать параметр uniform=True. В этом случае в качестве pivot-ключей будут выбраны равномерные значения из диапазона соответствующего типа. 0, 2^64/n, 2^64\*2/n, ... для беззнакового 64-битного типа и -2^63, -2^63 + 2^64/n, -2^63 + 2^64\*2/n, ... для знакового.
  • В случае упорядоченной таблицы tablet_count указывает, на какое количество новых таблетов следует разделить решардируемые. При этом если новое количество таблетов больше старого, то создаются пустые таблеты. Если же меньше, то соответствующее количество "хвостовых" исходных таблетов объединяются в один в естественном порядке.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до таблицы.
first_tablet_index Нет 0 Номер первого решардируемого таблета.
last_tablet_index Нет tablet_count - 1 Номер последнего решардируемого таблета.
pivot_keys Нет Граничные ключи для новых таблетов (в случае сортированной таблицы).
tablet_count Нет Количество новых таблетов.
uniform Нет false Равномерно решардировать по целочисленной ключевой колонке.
enable_slicing Нет false Использовать семплирование для повышения гранулярности (более точного разделения на таблеты) при автоматическом выборе pivot-ключей. Полезно, если одному ключу соответствует большое число записей, а другому малое.
slicing_accuracy Нет 0.05 Допустимая погрешность при равномерном решардировании на заданное число таблетов.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "path" = "//home/user/table"; "schema" = [{"name" = "key"; type = "int64"; "sort_order" = "ascending"}; {"name" = "value"; type = "string"}]; }

reshard_table_automatic

Свойства команды: Мутирующая, Легкая.

Применимость: Сортированные динамические таблицы.

Семантика:

  • Форсированно запускает итерацию фонового балансировщика таблетов, т.е. решардирует таблеты, выходящие за границы min_tablet_sizemax_tablet_size;
  • В отличие от reshard_table, работает с примонтированными таблицами. В процессе работы может отмонтировать таблеты;
  • По умолчанию запускается асинхронно, но при указании параметра keep_actions возвращает список идентификаторов, по которым можно отслеживать прогресс. Большинство API делают это автоматически при передаче флага sync=True;
  • Команда не поддерживает реплицированные таблицы (допустимо использование независимо на отдельных репликах).

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до таблицы.
keep_actions Нет false Если задано true, вернуть в ответ список идентификаторов для отслеживания прогресса.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured.
  • Значение: список tablet_action_id, если keep_actions=True. Иначе пустой список.

Пример:

PARAMETERS { "path" = "//home/user/table"; }
OUTPUT [
    "11-22-33-44";
]

alter_table

Свойства команды: Мутирующая, Легкая.

Применимость: Статические и динамические таблицы.

Семантика:

  • Выполняет изменение схемы и других настроек таблицы (как статической, так и динамической);
  • Через alter_table обычно меняются настройки, которые требуют комплексной совместной валидации. Через атрибуты меняются настройки, имеющие рекомендательный смысл и влияющие только на новые данные;
  • При изменении схемы происходят разнообразные проверки корректности, т.к. система должна быть уверена, что существующие данные соответствуют схеме;
  • Статическую таблицу можно сделать динамической, но не наоборот;
  • Изменение схемы динамической таблицы, а также upstream_replica_id возможно, лишь если таблица отмонтирована.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь до таблицы.
schema Нет Если указано, то устанавливает для таблицы новую схему.
dynamic Нет Если указано, то изменяет динамичность таблицы. Изменение данной настройки возможно только вне транзакции.
upstream_replica_id Нет Если указано, то изменяет идентификатор объекта-реплики на метакластере. Подробнее можно прочесть в разделе Реплицированные динамические таблицы.

Входные данные:

  • Тип: null;

Выходные данные:

  • Тип: null;

Пример:

PARAMETERS { "path" = "//home/user/table"; "schema" = [{"name" = "key"; type = "int64"; "sort_order" = "ascending"}; {"name" = "value"; type = "string"}]; }

alter_table_replica

Свойства команды: Мутирующая, Легкая.

Применимость: Реплицированные динамические таблицы.

Семантика:

  • Изменяет свойства реплики: включает/выключает её или меняет её режим.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
replica_id Да Идентификатор реплики.
enabled Нет не меняет включённость реплики Если выставлено true, включает таблицу. Если выставлено false, выключает.
mode Нет не меняет режим реплики Меняет режим реплики sync / async.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "replica_id" = "730e-8611b-3ff02c5-f647333f"; "enabled" = %true; }

get_table_columnar_statistics

Свойства команды: Немутирующая, Легкая.

Применимость: Статические и динамические таблицы.

Семантика:

  • Получить статистику по набору колонок в заданном наборе таблиц (взятых полностью или частично, по диапазонам);
  • Статистика включает в себя:
    • Суммарный data_weight данных из каждой заказанной колонки;
    • Суммарный data_weight всех старых чанков (в которые не была сохранена метаинформация про каждую колонку, так как чанк формировался до поддержания поколоночных статистик);
    • Суммарный вес всех временных меток строк в случае динамической таблицы.
  • В путях обязательно должны быть указаны column selectors;
  • Команда может быть выполнена внутри транзакции.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
paths Да Список путей до таблиц в Кипарисе; таблицы должны существовать; на путях должны быть указаны column selectors.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Значение: поколоночные статистики для заказанных колонок.

Пример:

PARAMETERS {
    "paths" = ["//tmp/table1{a,b,c}"; "//tmp/table2{a,b,c}"];
    "transaction_id" = "1234-abcd-abcd-7890"
}
OUTPUT {
    "column_data_weights" = {
        "a" = 8124;
        "b" = 124241241;
        "c" = 3121414;
    };
    "legacy_chunks_data_weight" = 100242;
    "timestamp_total_weight" = 50056;
}

Запуск операций

Подробную информацию про запуск операций обработки данных можно найти в разделе Обработка данных.

Все операции выполняются асинхронно, указанные команды лишь запускают их. Чтобы узнать, закончилась операция или нет, запросите статус операции командой get_operation.
Также все команды для работы с операциями являются транзакционными. Это означает, что вся работа с таблицами в пределах операции будет делаться в рамках указанной транзакции при запуске операции. Узел отвечающей операции (//sys/operations/<OP_ID>) обновляется планировщиком вне любых транзакций.

start_operation

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Запустить операцию указанного типа.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
operation_type Да Тип операции (один из map, reduce, map_reduce, remote-copy, erase, sort, merge, vanilla).
spec Да Спецификация операции. Подробнее в разделе Настройка операций.

Входные данные:

  • Тип: null;

Выходные данные:

  • Тип: structured;
  • Значение: идентификатор запущенной операции.

Пример:

PARAMETERS {  "operation_type" = "map_reduce";
    "spec" = {
        "input_table_paths" = [ "//tmp/table_in", "//tmp/table_in" ] ;
        "output_table_path" = "//tmp/table_out"
    }
}
OUTPUT "37878b-ba919c15-cdc97f3a-8a983ece"

merge

Свойства команды: Мутирующая, Легкая.

Семантика:

Параметры:

Параметр Обязательный Значение по умолчанию Описание
spec Да Спецификация операции.
spec[input_table_paths] Да Список входных таблиц.
spec[output_table_path] Да Выходная таблица.
spec[mode] Нет unordered Режим слияния ( unordered, ordered, sorted).

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Значение: идентификатор запущенной операции.

Пример:

PARAMETERS {
    "spec" = {
        "input_table_paths" = [ "//tmp/table_in", "//tmp/table_in" ] ;
        "output_table_path" = "//tmp/table_out"
    }
}
OUTPUT "37878b-ba919c15-cdc97f3a-8a983ece"

erase

Свойства команды: Мутирующая, Легкая.

Семантика:

Параметры:

Параметр Обязательный Значение по умолчанию Описание
spec Да Спецификация операции.
spec[table_path] Да Входная таблица с указанным селектором по строкам, она же будет выходной.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Значение: идентификатор запущенной операции.

Пример:

PARAMETERS {
    "spec" = {
        "table_path" = "//tmp/table[#0:#500]" ;
    }
}
OUTPUT "3f9e62-ce8d2965-6350842b-3e4628d2"

map

Свойства команды: Мутирующая, Легкая.

Семантика:

Параметры:

Параметр Обязательный Значение по умолчанию Описание
spec Да Спецификация операции (см. ниже релевантные поля).
spec[input_table_paths] Да Список входных таблиц.
spec[output_table_paths] Да Список выходных таблиц.
spec[mapper][command] Да Команда запуска маппера.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Значение: идентификатор запущенной операции.

Пример:

PARAMETERS {
    "spec" = {
      "mapper" = {
          "command" = "cat"
      } ;
      "input_table_paths"  = [ "//tmp/table_in", "//tmp/table_in" ] ;
      "output_table_paths" = [ "//tmp/table_out" ]
    }
}
OUTPUT "33ab3f-bf1df917-b35fe9ed-c70a4bf4"

reduce

Свойства команды: Мутирующая, Легкая.

Семантика:

Параметры:

Параметр Обязательный Значение по умолчанию Описание
spec Да Спецификация операции (см. ниже релевантные поля).
spec[input_table_paths] Да Список входных таблиц.
spec[output_table_paths] Да Список выходных таблиц.
spec[reduce_by] Да Колонки, по которым выполняется reduce.
spec[reducer][command] Да Команда запуска reducer.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Значение: идентификатор запущенной операции.

Пример:

PARAMETERS {
    "spec" = {
      "reducer" = {
          "command" = "cat" ;
      } ;
      "input_table_paths"  = [ "//tmp/table_in", "//tmp/table_in" ] ;
      "output_table_paths" = [ "//tmp/table_out" ] ;
      "reduce_by"          = [ "my_key" ] ;
    }
}
OUTPUT "33ab3f-bf1df917-b35fe9ed-c70a4bf4"

sort

Свойства команды: Мутирующая, Легкая.

Семантика:

Параметры:

Параметр Обязательный Значение по умолчанию Описание
spec Да Спецификация операции (см. ниже релевантные поля).
spec[input_table_paths] Да Список входных таблиц.
spec[output_table_path] Да Выходная таблица.
spec[sort_by] Да Непустой набор имен колонок, образующих ключ сортировки.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Значение: идентификатор запущенной операции.

Пример:

PARAMETERS {
    "spec" = {
      "input_table_paths" = [ "//tmp/table_in", "//tmp/table_in" ] ;
      "output_table_path" = "//tmp/table_out" ;
      "sort_by"           = [ "mykey" ];
    }
}
OUTPUT "37878b-ba919c15-cdc97f3a-8a983ece"

map_reduce

Свойства команды: Мутирующая, Легкая.

Семантика:

Параметры:

Параметр Обязательный Значение по умолчанию Описание
spec Да Спецификация операции (см. ниже релевантные поля).
spec[input_table_paths] Да Список входных таблиц.
spec[output_table_paths] Да Список выходных таблиц.
spec[mapper][command] Нет Команда запуска маппера.
spec[sort_by] Нет Непустой набор имен колонок по которым будут отсортированы данные для редьюсеров.
spec[reduce_by] Да Колонки, по которым выполняется reduce.
spec[reducer][command] Да Команда запуска reducer.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Значение: идентификатор запущенной операции.

Пример:

PARAMETERS {
    "spec" = {
      "mapper" = {
          "command" = "cat"
      } ;
      "reducer" = {
          "command" = "cat"
      } ;
      "input_table_paths" = [ "//tmp/table_in", "//tmp/table_in" ] ;
      "output_table_path" = "//tmp/table_out" ;
      "reduce_by" = [ "my_key" ] ;
    }
}
OUTPUT "37878b-ba919c15-cdc97f3a-8a983ece"

remote-copy

Свойства команды: Мутирующая, Легкая.

Семантика:

Параметры:

Параметр Обязательный Значение по умолчанию Описание
spec Да Спецификация операции (см. ниже релевантные поля).
spec[input_table_paths] Да Список входных таблиц.
spec[output_table_paths] Да Список выходных таблиц.
spec[cluster_name] Да Кластер с исходными таблицами.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Значение: идентификатор запущенной операции.

Пример:

PARAMETERS {
    "spec" = {
      "input_table_paths" = [ "//tmp/table_in", "//tmp/table_in" ] ;
      "output_table_path" = "//tmp/table_out" ;
      "cluster_name" = <cluster-name>;
    }
}
OUTPUT "37878b-ba919c15-cdc97f3a-8a983ece"

Работа с операциями

Примечание

Все команды для работы с операциями не являются транзакционными.

list_operations

Внимание

Данная команда может создавать значительную нагрузку на кластер, не используйте её в процессах без согласования с администратором.

Свойства команды: Немутирующая, Легкая.

Семантика:

  • Получить список операций, удовлетворяющих фильтрам.

Параметры:

Параметр Тип Обязательный Значение по умолчанию Описание
attributes list<string> Нет Null Список атрибутов операций, которые вернутся в ответе.
from_time ISO 8601 string Нет Null Ограничение снизу на диапазон времени для выбора операций (по времени начала операции).
to_time ISO 8601 string Нет Null Ограничение сверху на диапазон времени для выбора операций (по времени начала операции).
cursor_time ISO 8601 string Нет Null Время, начиная с которого требуется вернуть список операций.
cursor_direction {past, future} Нет past Направление перечисления операций по времени.
user string Нет Null Имя пользователя для фильтрации.
state string Нет Null Состояние операции для фильтрации.
type string Нет Null Тип операции для фильтрации.
filter string Нет Null Подстрока, которая должна присутствовать в filter_factors у операции.
pool string Нет Null Пул для фильтрации.
with_failed_jobs bool Нет Null Возвращать только операции, у которых есть джобы со статусом failed.
access map Нет Null Словарь с обязательными полями subject (строка) и permissions (список строк), задающий фильтр по правам доступа. Если указан, возвращаются только операции, к которым субъект subject имеет каждое из прав в списке permissions.
include_archive bool Нет false Запрашивать ли операции из архива.
include_counters bool Нет true Возвращать ли статистику по запрошенным операциям.
limit int Нет 100 Количество операций, которые необходимо вернуть в ответе.
enable_ui_mode bool Нет false Возвращать ответ в старом UI-совместимом формате.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Возвращает словарь со следующими полями:
    • operations — список с непосредственным описанием операций. Каждая операция представляет из себя словарь с частью атрибутов операции: id, type, state, authenticated_user, brief_progress, brief_spec, start_time, suspended, weight. Атрибуты weight, brief_progress, brief_spec являются опциональными;
    • incomplete — является ли список операций полным (то есть перечислены ли все операции в диапазоне from_timeto_time);
    • pool_counts — статистика по пулам;
    • user_counts — статистика по пользователям;
    • state_counts — статистика по состоянию операций;
    • type_counts — статистика по типу операций;
    • failed_jobs_count — количество упавших (failed) джобов у операций.

Пример:

PARAMETERS { }
OUTPUT {
      "operations" = [
          {
              "id" = "7001208d-fef089b3-3fe03e8-453d99a1";
              "type" = "remote-copy";
              "state" = "initializing";
              "authenticated_user" = "user-name";
              "brief_progress" = {};
              "brief_spec" = {
                  ...
              };
              "start_time" = "2018-02-06T11:06:34.200591Z";
              "suspended" = %false;
              "weight" = 1.;
          };
      ];
      "incomplete" = %true;
      "pool_counts" = {
          "pool-counts-example" = 2;
          "user-name-1" = 2;
          ...
      };
      "user_counts" = {
          "yql" = 52;
          "user-name-1" = 2;
      };
      "state_counts" = {
          "materializing" = 10;
          "pending" = 763;
          "running" = 1848;
          "completed" = 6654;
          "aborted" = 37;
          "failed" = 98;
      };
      "type_counts" = {
          "map" = 4294;
          "merge" = 1337;
          "erase" = 97;
          "sort" = 1126;
          "reduce" = 886;
          "map_reduce" = 1609;
          "remote-copy" = 24;
      };
      "failed_jobs_count" = 109;
}

get_operation

Свойства команды: Немутирующая, Легкая.

Семантика:

  • Получить информацию об операции.

Параметры:

Параметр Тип Обязательный Значение по умолчанию Описание
operation_id GUID Да Идентификатор операции.
attributes list Нет [] Атрибуты операции.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;
  • Возвращает словарь с заказанными атрибутами операции.
Поле Тип Описание
id string Строковое представление id операции (например, d840bb39-3d893e5b-3fe03e8-f009b1fb).
type string Тип операции (например, map, reduce, map_reduce).
state string Текущее состояние операции (например, completed, running,failed).
authenticated_user string Пользователь, запустивший операцию.
start_time ISO 8601 string Время начала.
finish_time ISO 8601 string Время окончания (если операция завершилась).
brief_progress map Краткие статистики по джобам.
progress map Полные статистики по джобам.
brief_spec map Часть спецификации с лёгкими полями.
spec map Спецификация, указанная пользователем при начале операции.
full_spec map Спецификация, в которой все не указанные пользователем поля заполнены значениями по умолчанию.
unrecognized_spec map Поля спецификации, указанные пользователем, но не распознанные планировщиком.
controller_agent_address string Адрес контроллер-агента (хост:порт), который отвечает за операцию.
events list<map> Список событий (изменений состояния), произошедших с операцией.
alerts map Алёрты (в виде словаря <имя_алёрта> : <map с атрибутами>), выставленные на операции в данный момент.
result map Map с полем error, в котором может содержаться ошибка в случае упавшей операции.
committed bool Закоммичены ли результаты операции.
suspended bool Приостановлена ли операция в данный момент.

Пример:

PARAMETERS {  "operation_id" = "33ab3f-bf1df917-b35fe9ed-c70a4bf4"; attributes = [ "state" ] }
OUTPUT {
    "state" = "running";
}

abort_operation

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Прервать операцию.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
operation_id Да Идентификатор операции.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "operation_id" = "33ab3f-bf1df917-b35fe9ed-c70a4bf4" }

complete_operation

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Мгновенно завершить операцию с сохранением уже посчитанного результата.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
operation_id Да Идентификатор операции.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "operation_id" = "33ab3f-bf1df917-b35fe9ed-c70a4bf4" }

suspend_operation

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Приостановить выполнение операции;
  • Выполняется мгновенно, после этого перестают запускаться новые джобы операции, а также опционально прерываются уже запущенные джобы.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
operation_id Да Идентификатор операции.
abort_running_jobs Нет false Стоит ли прервать выполняющиеся джобы операции.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "operation_id" = "33ab3f-bf1df917-b35fe9ed-c70a4bf4" }

resume_operation

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Продолжить выполнение приостановленной операции;
  • Выполняется мгновенно.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
operation_id Да Идентификатор операции.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "operation_id" = "33ab3f-bf1df917-b35fe9ed-c70a4bf4" }

update_operation_parameters

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Обновить параметры запущенной операции.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
operation_id Да Идентификатор операции.
parameters Да Словарь с параметрами операции.
parameters[owners] Нет (deprecated, будет удалено) Список новых владельцев операции.
parameters[acl] Нет Новый ACL операции (накладывается на base ACL).
parameters[pool] Нет Имя пула, на который надо переключить операцию во всех её деревьях.
parameters[weight] Нет Новый вес операции во всех деревьях.
parameters[scheduling_options_per_pool_tree] Нет Словарь {имя дерева: настройки планировщика для данного дерева}. Описание настроек ниже. Подробнее про планировщик можно прочесть в разделе Планировщик и пулы.
parameters[options_per_job_shell] Нет Словарь {имя Job Shell: настройки для данного Job Shell}. Описание настроек ниже.

Настройки планировщика для дерева:

Параметр Обязательный Значение по умолчанию Описание
weight Нет Вес операции в дереве.
pool Нет Пул операции в дереве.
resource_limits Нет Словарь {имя ресурса: лимит}. Лимиты ресурсов в дереве.

Настройки Job Shell:

Параметр Обязательный Значение по умолчанию Описание
owners Нет Субъекты (пользователи или группы), которым будет разрешен доступ до Job Shell.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS {"operation_id" = "33ab3f-bf1df917-b35fe9ed-c70a4bf4"; "parameters" = {"pool" = "username"; "scheduling_options_per_pool_tree" = {"physical" = {"weight" = 2; "resource_limits" = { "user_slots" = 1; "cpu" = 0.5; "network" = 10; "memory" = 1000000000}}}}}

Работа с джобами

Примечание

Все команды для работы с джобами не являются транзакционными.

get_job

Свойства команды: Немутирующая, Легкая.

Семантика:

  • Получить информацию о джобе. Команда работает как для запущенных, так и для завершившихся джобов, в случае если информация о джобе была сохранена;

Параметры:

Параметр Обязательный Значение по умолчанию Описание
operation_id Да Идентификатор операции
job_id Да Идентификатор джоба

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured. Map с атрибутами джоба.
Поле Тип Описание
job_id string Строковое представление id джоба (например, d840bb39-3d893e5b-3fe03e8-f009b1fb).
operation_id string Строковое представление id операции (например, d840bb39-3d893e5b-3fe03e8-f009b1fb ).
type string Тип джоба (например, vanilla, map, partition_reduce).
state string Текущее состояние джоба (например, running, failed, completed).
address string Адрес узла (хост:порт), на которой был запущен джоб.
task_name string Название таска, которому отвечает джоб.
start_time ISO 8601 string Время начала.
finish_time ISO 8601 string Время окончания.
pool string Название пула, в котором был запущен джоб.
pool_tree string Название дерева пулов, в котором был запущен джоб.
progress float in [0,1] Оценка доли работы, выполненной джобом к текущему моменту.
stderr_size integer Размер сохранённого stderr джоба (сам stderr можно получить с помощью команды get_job_stderr).
error map Словарь с описанием ошибки (для неуспешно завершившегося джоба).
statistics map Словарь со статистиками джоба.
brief_statistics map Словарь с краткими статистиками.
input_paths list<YPath> Список путей к таблицам (с диапазонами строк), которые обрабатывает джоб.
core_infos list<map> Список словарей, описывающих корки, отложенные джобом.
events list<map> Список словарей, описывающих события (изменения состояния или фазы), произошедшие с джобом.
is_stale bool Является ли информация о джобе устаревшей (если %true, то некоторые поля могут быть в неактуальном состоянии). Информация о джобе считается устаревшей, если она давно не обновлялась. Обновлением информации в архиве джобов занимается нода, на которой джоб бежит, а также контроллер операции. Это происходит асинхронно. Если нода и контроллер одновременно рестартовали по какой-то причине (например, в результате обновления), информация о конечном состоянии джоба (completed, failed или aborted) может не попасть в архив, и в результате джоб будет всегда возвращаться как stale. Несмотря на статус running, обычно такие джобы уже давно не бегут, их следует игнорировать.

Пример:

PARAMETERS { "operation_id" = "e13c5406-e5dd6f5d-3fe03e8-fe05f0d3"; "job_id" = "f11ae559-a0375703-3fe0384-8f1"}
OUTPUT {
      "operation_id" = "e13c5406-e5dd6f5d-3fe03e8-fe05f0d3";
      "job_id" = "f11ae559-a0375703-3fe0384-8f1";
      "state" = "completed";
      "start_time" = "2018-02-06T09:37:02.858492Z";
      "finish_time" = "2018-02-06T09:42:19.185525Z";
      "address" = "hostname.net:9012";
      "statistics" = {
          "data" = {
               ...
          };
      };
      "events" = [
          ...
      ];
}

list_jobs

Внимание

Данная команда может создавать значительную нагрузку на кластер, не используйте её в ваших процессах без согласования с администратором.

Свойства команды: Немутирующая, Легкая.

Семантика:

  • Для заданной операции получить все джобы, удовлетворяющие фильтрам.

Параметры:

Параметр Тип Обязательный Значение по умолчанию Описание
operation_id GUID Да Идентификатор операции.
type (job_type) EJobType Нет Null При указании параметра в ответе будут только джобы с указанным job_type.
state (job_state) EJobState Нет Null При указании параметра в ответе будут только джобы с указанным job_state.
address string Нет Null При указании параметра в ответе будут только джобы с адресом, начинающимся на address.
with_stderr bool Нет Null При Null возвращаются все джобы; при True возвращаются только джобы с непустым stderr; при False возвращаются только джобы с пустым stderr.
with_fail_context bool Нет Null При Null возвращаются все джобы; при True возвращаются только джобы, у которых сохранен fail_context; при False возвращаются только джобы, у которых нет fail_context.
with_spec bool Нет Null При Null возвращаются все джобы; при True возвращаются только джобы, у которых сохранена спецификация; при False возвращаются только джобы, у которых нет спецификации.
with_competitors bool Нет Null При Null возвращаются все джобы; при True возвращаются только джобы, для которых были запущены спекулятивные копии вместе с этими копиями; при False возвращаются только джобы, у которых нет спекулятивных копий.
job_competition_id GUID Нет Null При указании параметра в ответе будет джоб с идентификатором job_competition_id и все его спекулятивные копии (если они есть).
with_monitoring_descriptor bool Нет Null При Null возвращаются все джобы; при True возвращаются только джобы, у которых есть monitoring_descriptor; при False возвращаются только джобы, у которых нет monitoring_descriptor.
task_name string Нет Null При указании параметра в ответе будут только джобы с указанным task_name.
sort_field {none,type,state,start_time,finish_time,address,duration,progress,id} Нет none Поле сортировки.
sort_order {ascending,descending} Нет ascending Порядок сортировки.
limit int Нет 1000 Ограничение на кол-во возвращаемых джобов.
offset int Нет 0 Смещение на определенное количество джобов.
data_source EDataSource Нет auto Источник данных, возможные значения: runtime, archive, auto.

Параметры job_type, job_state, address, with_stderr, with_fail_context, with_competitors, with_spec, with_monitoring_descriptor, задают фильтр джобов. В ответе будут перечислены только джобы, удовлетворяющие условию фильтрации.

Параметры sort_field, sort_order задают порядок джобов в ответе. При этом параметры limit и offset определяют срез (подмножество) джобов в ответе: отбрасываются первые offset джобов и далее выбираются limit оставшихся.

Параметр data_source регулирует источник данных, из которого будут браться джобы:

  • В режиме runtime джобы извлекаются из контроллер-агента и Кипариса и мёржатся.
  • В режиме archive джобы достаются из архива и контроллер-агента и мёржатся.
  • В режиме auto автоматически определяется источник джобов на основании наличия операции в контроллер-агенте.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured;

  • Структура с полями jobs, cypress_job_count, controller_agent_job_count, archive_job_count;

  • Поля *_count — количество найденных джобов по заданной операции в соответствующих источниках данных без фильтрации. Если все три числа равны 0, то это значит, что информации о джобах операции нет. Если все три числа не равны 0, но ответ jobs пуст, то это значит, что все джобы были отфильтрованы. Если вместо числа пришел null, то соответствующий источник данных не опрашивался.

  • Поле jobs — список структур, описывающих каждый джоб. У каждого джоба возможны следующие поля:

    • id (guid), type (string), state (string), address (string) — обязательные;
    • start_time (instant), finish_time (instant), progress (double), stderr_size (int) — опциональные;
    • error, brief_statistics, input_paths, core_infos — опциональные.

Пример:

PARAMETERS { "operation_id" = "4505e8eb-28fa88e2-3fe03e8-c6fcd8fa"; }
OUTPUT {
      "jobs" = [
          {
              "id" = "55aff293-7ef14284-3fe0384-3e07";
              "type" = "map";
              "state" = "failed";
              "address" = "hostname.net:9012";
              "start_time" = "2018-05-05T00:41:27.433832Z";
              "finish_time" = "2018-05-05T00:49:04.288196Z";
              "fail_context_size" = 973230u;
              "error" = {
                  "code" = 1205;
                  "message" = "User job failed";
                  ...
              };
              ...
          };
          ...
          {
              "id" = "69ae20a7-887b25ab-3fe0384-3cff";
              "type" = "map";
              "state" = "running";
              "address" = "hostname.net:9012";
              "start_time" = "2018-05-07T13:04:03.339873Z";
              "progress" = 0.;
              "brief_statistics" = <
                  "timestamp" = "2018-05-07T13:04:08.431740Z";
              > {
                  "processed_input_compressed_data_size" = 0;
                  "processed_input_data_weight" = 0;
                  "processed_output_uncompressed_data_size" = 0;
                  "processed_output_compressed_data_size" = 0;
                  "processed_input_uncompressed_data_size" = 0;
                  "processed_input_row_count" = 0;
              };
          };
      ];
      "cypress_job_count" = 200;
      "scheduler_job_count" = 208;
      "archive_job_count" = #;
      "type_counts" = {
          "map" = 408;
      };
      "state_counts" = {
          "running" = 208;
          "failed" = 200;
      };
}

abandon_job

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Прервать джоб и считать, что его входные данные успешно обработаны.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
job_id Да Идентификатор джоба.

Входные данные:

  • Тип: null

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "job_id" = "1225d-1f2fb8c4-f1075d39-5fb7cdff" }

abort_job

Свойства команды: Мутирующая, Легкая.

Семантика:

  • Прервать джоб, в дальнейшем он будет перезапущен планировщиком (как и любой прерванный джоб операции).

Параметры:

Параметр Обязательный Значение по умолчанию Описание
job_id Да Идентификатор джоба.
interrupt_timeout Нет Таймаут на возможность успешного завершения джоба после того, как в него перестают подавать входные данные.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "job_id" = "1225d-1f2fb8c4-f1075d39-5fb7cdff" }

dump_job_context

Свойства команды: Немутирующая, Легкая.

Семантика:

  • Получить input context джоба.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
job_id Да Идентификатор джоба.
path Да Путь, по которому нужно сохранить набор входных параметров, которые получил джоб, компоненты пути должны существовать (кроме самого файла).

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: null.

Пример:

PARAMETERS { "job_id" = "1225d-1f2fb8c4-f1075d39-5fb7cdff"; "path" = "//tmp/input_context" }

get_job_input

Свойства команды: Немутирующая, Тяжелая.

Семантика:

  • Получить полный вход джоба. Команда работает для запущенных джобов и для упавших джобов, у которых сохранена спецификация и доступны все входные данные.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
job_id Да Идентификатор джоба.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: binary;
  • Значение: вход джоба.

Пример:

PARAMETERS { "job_id" = "1225d-1f2fb8c4-f1075d39-5fb7cdff"}

get_job_fail_context

Свойства команды: Немутирующая, Тяжелая.

Семантика:

  • Получить fail context джоба. Команда работает для упавших джобов.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
operation_id Да Идентификатор операции.
job_id Да Идентификатор джоба.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: binary;
  • Значение: fail context джоба.

Пример:

PARAMETERS { "operation_id" = "33ab3f-bf1df917-b35fe9ed-c70a4bf4"; "job_id" = "1225d-1f2fb8c4-f1075d39-5fb7cdff"}

get_job_stderr

Свойства команды: Немутирующая, Тяжелая.

Семантика:

  • Получить stderr джоба. Команда работает для запущенных джобов и для упавших джобов.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
operation_id Да Идентификатор операции.
job_id Да Идентификатор джоба.
offset Нет Смещение от начала в байтах.
limit Нет Максимальный размер в байтах.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: binary;
  • Значение: stderr джоба.

Пример:

PARAMETERS { "operation_id" = "33ab3f-bf1df917-b35fe9ed-c70a4bf4"; "job_id" = "1225d-1f2fb8c4-f1075d39-5fb7cdff"; "offset" = 500; "limit" = 100 }
OUTPUT {
OUTPUT   "total_size" = 1000;
OUTPUT   "end_offset" = 600;
OUTPUT }

Прочее

parse_ypath

Свойства команды: Немутирующая, Легкая.

Семантика:

  • Выполнить разбор переданного YPath-пути, переложив все идентификаторы сложного YPath в атрибуты.

Параметры:

Параметр Обязательный Значение по умолчанию Описание
path Да Путь, который необходимо распарсить.

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured.

Пример:

PARAMETERS { "path" = "//tmp/table[#1:#2]" }
OUTPUT { "path" = "<ranges=[{lower_limit={row_index=1};upper_limit={row_index=2}}]>//tmp/table" }

execute_batch

Свойства команды: Мутирующая, если в наборе есть мутирующие команды, Легкая.

Семантика:

  • Выполнить за один запрос набор команд, переданных в параметрах;
  • Команды могут (и будут) выполняться параллельно, так что если в одном наборе будет одновременно запись узла и его чтение, то результат чтения может быть как старым значением, так и новым;
  • В наборе могут участвовать только легкие команды;
  • В наборе могут участвовать только команды с типом входа null или structured;
  • В наборе могут участвовать только команды с типом выхода null или structured;

Параметры:

Параметр Обязательный Значение по умолчанию Описание
requests Да Описание выполняемых запросов.
concurrency Нет 50 Численный параметр, который ограничивает сверху число команд выполняющихся на кластере одновременно, можно использовать, чтобы не исчерпать свой request rate limit.

Входные данные:

  • Тип: structured;
  • Выполняемые запросы перечисляются в параметре requests, представляющем собой список;
  • Каждый элемент данного списка — это словарь с полями:
Параметр Обязательный Значение по умолчанию Описание
command Да Имя команды.
parameters Да Словарь с параметрами команды.
input Нет Вход для запроса (для команд с типом входа structured, например set).

Выходные данные:

  • Тип: structured;
  • На выходе получается список той же длины, что и на входе;
  • Каждый элемент списка описывает результат выполнения одного запроса. Это словарь следующего вида:
Параметр Обязательный Описание
error Нет Ошибка, возникшая при выполнении запроса (если есть).
output Нет Выход запроса (для успешных команд с типом выхода structured , например get).

Пример:

PARAMETERS {
    "requests" = [
      {
        "command" = "set";
        "parameters" = {"path" = "//tmp/a"};
        "input" = "value_a";
      };
      {
        "command" = "get";
        "parameters" = {"path" = "//tmp/b"};
      };
      {
        "command" = "get";
        "parameters" = {"path" = "//nonexisting"};
      };
    ];
}
OUTPUT [
    { };
    { output = "value_b"; };
    { error = {...} };
]

get_supported_features

Свойства команды: Немутирующая, Легкая.

Семантика:

  • Возвращает словарь с полем features, в котором описаны поддерживаемые кластером примитивные типы данных, кодеки сжатия, erasure-кодеки и т. п.

Параметры:

  • Нет

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured. В ключе features ответа лежит словарь со следующими полями.
Ключ Тип значения Описание
primitive_types список строк Примитивные типы.
erasure_codecs список строк Erasure-кодеки.
compression_codecs список строк Кодеки сжатия.

Пример:

PARAMETERS { }
OUTPUT {
    "features" = {
      "primitive_types" = ["int8"; "int16"; ... ];
      "erasure_codecs" = ["lrc_12_2_2"; "reed_solomon_6_3"; ... ];
      "compression_codecs" = ["none"; "snappy"; "brotli_1"; ... ];
    };
}

generate_timestamp

Свойства команды: Немутирующая, Легкая.

Семантика:

  • Генерирует монотонную временную метку.

Параметры:

  • Нет

Входные данные:

  • Тип: null.

Выходные данные:

  • Тип: structured. В ключе timestamp ответа лежит значение типа uint64.

Пример:

PARAMETERS { }
OUTPUT {
    "timestamp" = 1723665447133469427u;
}
Предыдущая