Команды

В данном разделе перечислены все команды, доступные в 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. Такие команды можно выполнить повторно, используя транзакции.

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

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

Транзакции

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

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

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

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

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

start_tx

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

Семантика:

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

Параметры:

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

• Тип: 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.

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

commit_tx

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

abort_tx

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

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

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

create

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

Семантика:

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

Параметры:

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

• Тип: 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

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

set

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

Семантика:

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

Параметры:

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

• Тип: 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

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

Семантика:

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

Параметры:

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

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

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

• Тип: null.

Пример:

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

get

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

Семантика:

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

Параметры:

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

• Тип: null.

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

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

Пример:

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

list

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

Семантика:

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

Параметры:

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

• Тип: null.

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

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

Пример:

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

lock

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

Семантика:

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

Параметры:

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

• Тип: null.

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

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

Пример:

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

unlock

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

copy

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

Семантика:

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

Параметры:

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

• Тип: null.

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

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

Пример:

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

move

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

link

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

Семантика:

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

Параметры:

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

• Тип: null.

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

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

Пример:

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

exists

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

Семантика:

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

Параметры:

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

• Тип: null.

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

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

Пример:

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

concatenate

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

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

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

add_member

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

remove_member

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

check_permission

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

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

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

write_file

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

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

• upload.

Семантика:

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

Параметры:

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

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

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

• Тип: null.

Пример:

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

read_file

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

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

• download.

Семантика:

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

Параметры:

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

• Тип: null.

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

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

Пример:

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

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

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

put_file_to_cache

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

Семантика:

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

Параметры:

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

• Тип: 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

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

Семантика:

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

Параметры:

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

• Тип: 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) разрешена в любую таблицу, но флаг сортированности у таблицы сбрасывается;
• Команда может быть выполнена внутри транзакции.

Параметры:

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

• Тип: 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.

Семантика:

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

Параметры:

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

• Тип: 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

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

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

Семантика:

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

Параметры:

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

• Тип: null.

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

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

Пример:

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

select_rows

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

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

Семантика:

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

Параметры:

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

• Тип: null.

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

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

Пример:

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

insert_rows

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

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

Семантика:

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

Параметры:

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

• Тип: 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

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

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

Семантика:

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

Параметры:

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

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

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

• Тип: null.

Пример:

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

lock_rows

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

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

Семантика:

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

Параметры:

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

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

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

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

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

lookup_rows

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

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

Семантика:

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

Параметры:

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

• Тип: 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. Нумерация остальных строк при этом не меняется;
• Команда выполняется вне транзакций.

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

mount_table

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

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

unmount_table

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

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

remount_table

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

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

freeze_table

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

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

unfreeze_table

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

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

Семантика:

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

Параметры:

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

• Тип: 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 указывает, на какое количество новых таблетов следует разделить решардируемые. При этом если новое количество таблетов больше старого, то создаются пустые таблеты. Если же меньше, то соответствующее количество "хвостовых" исходных таблетов объединяются в один в естественном порядке.

Параметры:

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

• Тип: 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;
• Команда не поддерживает реплицированные таблицы (допустимо использование независимо на отдельных репликах).

Параметры:

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

• Тип: 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 возможно, лишь если таблица отмонтирована.

Параметры:

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

• Тип: null;

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

• Тип: null;

Пример:

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

alter_table_replica

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

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

get_table_columnar_statistics

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

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

Семантика:

• Получить статистику по набору колонок в заданном наборе таблиц (взятых полностью или частично, по диапазонам);
• Статистика включает в себя:
  • Суммарный data_weight данных из каждой заказанной колонки;
  • Суммарный data_weight всех старых чанков (в которые не была сохранена метаинформация про каждую колонку, так как чанк формировался до поддержания поколоночных статистик);
  • Суммарный вес всех временных меток строк в случае динамической таблицы.
• В путях обязательно должны быть указаны 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

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

Семантика:

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

Параметры:

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

• Тип: 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

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

Семантика:

• Запустить слияние исходных таблиц;
• Подробное описание всех параметров спецификации.

Параметры:

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

• Тип: 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

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

Семантика:

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

Параметры:

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

• Тип: null.

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

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

Пример:

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

map

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

Семантика:

• Запустить map поверх исходных таблиц с записью в выходные таблицы;
• Подробное описание всех параметров спецификации.

Параметры:

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

• Тип: 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 поверх исходных таблиц с записью в выходные таблицы;
• Подробное описании всех параметров спецификации.

Параметры:

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

• Тип: 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

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

Семантика:

• Запустить сортировку исходных таблиц;
• Подробное описании всех параметров спецификации.

Параметры:

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

• Тип: 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 над исходными таблицами;
• Подробное описании всех параметров спецификации.

Параметры:

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

• Тип: 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 указанного кластера;
• Подробное описание всех параметров спецификации.

Параметры:

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

• Тип: 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

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

Семантика:

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

Параметры:

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

• Тип: 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

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: structured;
• Возвращает словарь с заказанными атрибутами операции.

Пример:

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

abort_operation

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

complete_operation

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

suspend_operation

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

resume_operation

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

update_operation_parameters

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

Семантика:

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

Параметры:

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

Настройки 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

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: structured. Map с атрибутами джоба.

Пример:

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

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

Семантика:

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

Параметры:

Параметры 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

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

Семантика:

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

Параметры:

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

• Тип: null

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

• Тип: null.

Пример:

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

abort_job

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

dump_job_context

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

Семантика:

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

Параметры:

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

• Тип: null.

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

• Тип: null.

Пример:

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

get_job_input

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

Семантика:

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

Параметры:

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

• Тип: null.

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

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

Пример:

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

get_job_fail_context

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

Семантика:

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

Параметры:

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

• Тип: null.

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

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

Пример:

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

get_job_stderr

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

Семантика:

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

Параметры:

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

• Тип: 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 в атрибуты.

Параметры:

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

• Тип: 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;

Параметры:

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

• Тип: structured;
• Выполняемые запросы перечисляются в параметре requests, представляющем собой список;
• Каждый элемент данного списка — это словарь с полями:

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

• Тип: structured;
• На выходе получается список той же длины, что и на входе;
• Каждый элемент списка описывает результат выполнения одного запроса. Это словарь следующего вида:

Пример:

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 ответа лежит словарь со следующими полями.

Пример:

PARAMETERS { }
OUTPUT {
    "features" = {
      "primitive_types" = ["int8"; "int16"; ... ];
      "erasure_codecs" = ["none", "isa_lrc_12_2_2"; "isa_reed_solomon_6_3"; ... ];
      "compression_codecs" = ["none"; "snappy"; "brotli_1"; ... ];
    };
}

generate_timestamp

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

Семантика:

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

Параметры:

• Нет

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

• Тип: null.

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

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

Пример:

PARAMETERS { }
OUTPUT {
    "timestamp" = 1723665447133469427u;
}