Команды
В данном разделе перечислены все команды, доступные в 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
Свойства команды: Мутирующая, Легкая.
Семантика:
- Создать символическую ссылку на объект по новому адресу.
Параметры:
Параметр | Обязательный | Значение по умолчанию | Описание |
---|---|---|---|
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_size
–max_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
Свойства команды: Мутирующая, Легкая.
Семантика:
- Запустить 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
Свойства команды: Мутирующая, Легкая.
Семантика:
- Запустить 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
Свойства команды: Мутирующая, Легкая.
Семантика:
- Запустить 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
Свойства команды: Мутирующая, Легкая.
Семантика:
- Скопировать исходные таблицы c указанного кластера;
- Подробное описание всех параметров спецификации.
Параметры:
Параметр | Обязательный | Значение по умолчанию | Описание |
---|---|---|---|
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_time
—to_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;
}