Работа с деревом метаинформации

В данном разделе собраны наиболее популярные примеры по работе с Кипарисом из командной строки (CLI), более подробное описание команд и их параметров можно найти в разделе Команды.

List

Данная команда выводит список всех ключей узла <path>, узел обязан иметь тип map_node.

Описание команды list

$ yt list [-l] [--format FORMAT] [--attribute ATTRIBUTES]
[--max-size MAX_SIZE] [--absolute] <path>

Опция -l позволяет показывать дополнительные атрибуты (тип узла, аккаунт, объем занимаемого места, дата последнего изменения).

Вызов команды list

$ yt list -l --max-size 3 //home/dev
string_node   dev            0 2018-12-22 09:30 some_key1
  map_node    dev         1248 2019-01-22 13:14 username1
  map_node    dev  69856453509 2019-02-26 09:05 username2
WARNING: list is incomplete, check --max-size option

Опция --format определяет формат выходных данных. Поддерживаются форматы json и yson. Подробнее можно прочитать в разделе Форматы. Опцию --format нельзя указывать вместе с опцией -l.

Вызов команды list с опцией format

$ yt list --format json //home/dev
["some_key1","username1","username2","some_key2","username3","some_key3"]

С помощью опции --attribute (которая может быть указана несколько раз) могут быть запрошены дополнительные атрибуты узлов, соответствующих перечисляемым ключам. К примеру, --attribute account добавит к каждому ключу аккаунт, которому принадлежит данный узел. Опцию --attribute можно использовать только совместно с опцией --format.

Вызов команды list с опцией attribute

$ yt list --attribute account --attribute owner --format "<format=pretty>json" --max-size 3 //home/dev
{
    "$attributes": {
        "incomplete": true
    },
    "$value": [
        {
            "$attributes": {
                "account": "dev",
                "owner": "username1"
            },
            "$value": "some_key1"
        },
        {
            "$attributes": {
                "account": "dev",
                "owner": "username2"
            },
            "$value": "some_key2"
        },
        {
            "$attributes": {
                "account": "dev",
                "owner": "username3"
            },
            "$value": "some_key3"
        }
    ]
}

Опция --max-size позволяет ограничить количество возвращаемых элементов. Будут показаны произвольные элементы.

Вызов команды list с опцией max-size

$ yt list --max-size 3 //home/dev
some_key1
username1
username2
WARNING: list is incomplete, check --max-size option

Опция --absolute покажет абсолютные пути.

Вызов команды list с опцией absolute

$ yt list --absolute --max-size 3 //home/dev
//home/dev/some_key1
//home/dev/username1
//home/dev/username2
WARNING: list is incomplete, check --max-size option

Create

Данная команда создает узел указанного типа <type> по пути <path>. Команда возвращает идентификатор созданного объекта. Поддерживаемые объекты перечислены в разделе Объекты.

Описание команды create

$ yt create [-r, --recursive] [-i,--ignore-existing] [-l,--lock-existing] [-f, --force] [--attributes ATTRIBUTES] <type> <path>

Опция -r, --recursive создаст все промежуточные узлы типа map_node.

Вызов команды create с опцией recursive

$ yt create --recursive map_node //home/dev/test1/test2/test3
127c1-388f86-3fe012f-6f994b03

Опция -i, --ignore-existing не будет пересоздавать заново указанный узел, если он уже существует. Кроме того тип существующего узла и заказываемого должны совпадать, иначе выполнение запроса завершится ошибкой.

Вызов команды create без опции ignore-existing

$ yt create map_node //home/dev/test1/test2/test3
Node //home/dev/test1/test2/test3 already exists

Вызов команды create с опцией ignore-existing

$ yt create --ignore-existing map_node //home/dev/test1/test2/test3
127c1-388f86-3fe012f-6f994b03

Опцию -l, --lock-existing можно указывать вместе с --ignore-existing. Тогда на указанный узел будет взята exclusive-блокировка, даже если он уже существует. (В случае конфликта блокировки команда завершится ошибкой.) Т.к. фактическое создание узла всегда неявно (автоматически) берет на него блокировку, опция позволяет сделать эффект команды при использовании --ignore-existing более предсказуемым.

Опция -f, --force позволяет принудительно создать объект. В случае, если указанный узел уже существует, он удаляется и на его месте создается новый. При этом существующий узел может быть любого типа. При пересоздании меняется id узла.

Вызов команды create с опцией force

$ yt create --force map_node //home/dev/test1/test2/test3
127c1-4352be-3fe012f-6acab448

С помощью опции --attributes можно задать атрибуты создаваемого узла.

Вызов команды create с опцией attributes

$ yt create --attributes "{test_attr=test1;}" map_node //home/dev/test1/test2/test3
127c2-1b78-3fe012f-288106fe

Проверка результата команды create с опцией attributes

$ yt get //home/dev/test1/test2/test3/@test_attr
"test1"

Remove

Данная команда удаляет узел по указанному пути <path>. Если узел является составным и не пустым, то команда завершится с ошибкой.

Описание команды remove

$ yt remove [-r, --recursive] [-f, --force] <path>

Опция -r, --recursive позволяет удалить все поддерево рекурсивно.

Вызов команды remove без опции recursive

$ yt remove //home/dev/test1
Cannot remove non-empty composite node

Вызов команды remove с опцией recursive

$ yt remove --recursive //home/dev/test1

Опция -f, --force позволяет игнорировать отсутствие указанного узла.

Вызов команды remove без опции force

$ yt remove //home/dev/test1
Node //home/dev has no child with key "test1"

Вызов команды remove с опцией force

$ yt remove --force //home/dev/test1

Exists

Данная команда проверяет существование переданного ей узла <path>.

Описание команды exists

$ yt exists <path>

Вызов команды exists над существующим узлом

$ yt exists //home/dev/test1/test2/test3
true

Вызов команды exists над несуществующим узлом

$ yt exists //home/dev/test1/test2/test4
false

Get

Данная команда выводит все поддерево Кипариса, находящееся по пути <path>.

Описание команды get

$ yt get [--max-size MAX_SIZE] [--format FORMAT] [--attribute ATTRIBUTES] <path>

Путь <path> должен существовать.

Вызов команды get над несуществующим узлом

$ yt get //home/dev/test1/test2/test4
Error resolving path //home/dev/test1/test2/test4
Node //home/dev/test1/test2 has no child with key "test4"

Вызов команды get над существующим узлом

$ yt get //home/dev/test1/test2
{
    "test3" = {};
}

Вызов команды get над атрибутом узла

$ yt get //home/dev/test1/test2/@account
"dev"

Опция --max-size позволяет ограничить количество узлов, которые будут выданы в случае виртуальных составных узлов.

Вызов команды get без опции max-size

$ yt get //sys/transactions/@type
"transaction_map"

Вызов команды get с опцией max-size

$ yt get --max-size 3 //sys/transactions
<
    "incomplete" = %true;
> {
    "12814-3b9ce8-3fe0001-3b10627" = #;
    "12817-1cc292-3fe0001-fcdca56f" = #;
    "1268e-42d32d-3fe0001-d0fc5c4f" = #;
}

Опция --format определяет формат выходных данных. Поддерживаются форматы json и yson. Подробнее можно прочитать в разделе Форматы.

Вызов команды get с опцией format

$ yt get --format "<format=pretty>json" //home/dev/test1
{
    "test2": {
        "test3": {

        }
    }
}

Объекты специальных типов, а также непрозрачные узлы (объекты с атрибутом opaque равным %true ) выводятся как entity. Атрибуты, связанные с узлами поддерева, по умолчанию не выводятся. Но их можно заказать для вывода с помощью опции --attribute, аналогично команде list.

Вызов команды get с опцией attribute

$ yt get --attribute opaque //home/dev/test1/test2
<
    "opaque" = %false;
> {
    "test3" = <
        "opaque" = %false;
    > {};

Некоторые узлы могут вернуться как непрозрачные (у таких узлов не будет никаких дополнительных атрибутов), в случае если обходимое поддерево оказывается слишком большим.

Set

Команда set присваивает указанное значение value в формате YSON по указанному пути <path>.

Описание команды set

$ yt set [--format FORMAT] [-r, --recursive] [-f, --force]<path> <value>

Вызов команды set

$ yt set //home/dev/test1/@some_attr test

Проверка вызова команды set

$ yt get //home/dev/test1/@some_attr
"test"

Опция --format определяет формат значения value. Поддерживаются форматы json и yson. Подробнее можно прочитать в разделе Форматы.

Вызов команды set с опцией format

$ yt set --format json //home/dev/test1/test2/test4 '{"some_test_key":"some_test_value"}'

Вызов команды set без опции format

$ yt get //home/dev/test1/test2/test4
{
    "some_test_key" = "some_test_value";
}

Опция -r, --recursive позволяет создать все несуществующие промежуточные узлы пути.

Вызов команды set без опции recursive

$ yt set //home/dev/test1/test2/test3 some_test_value
Node //home/dev has no child with key "test1"

Вызов команды set с опцией recursive

$ yt set --recursive //home/dev/test1/test2/test3 some_test_value

Опция -f, --force позволяет менять любые узлы Кипариса, а не только атрибуты и документы.

Copy, Move

Данная команда копирует/перемещает узел из пути <source_path> в <destination_path>. При копировании файлов или таблиц чанки физически не копируются, все изменения происходят на уровне метаинформации.

Описание команды copy/move

$ yt copy/move [--preserve-account | --no-preserve-account]
               [--preserve-expiration-time] [--preserve-expiration-timeout]
               [--preserve-creation-time]
               [-r, --recursive] [-f, --force]
               <source_path> <destination_path>

Опция --preserve-account позволяет сохранить аккаунт копируемого узла, вместо того, чтобы использовать аккаунт родительского каталога узла назначения.

Опция --preserve-expiration-time позволяет сохранить назначенное время удаления копируемого узла.

Опция --preserve-expiration-timeout позволяет сохранить назначенный интервал удаления копируемого узла.

Опция --preserve-creation-time позволяет сохранить время создания копируемого узла. Только для копирования.

Проверка аккаунта

$ yt get //home/dev/test1/test_file/@account
"dev"

Вызов команды copy

$ yt copy //home/dev/test1/test_file //home/dev/test1/test2/test_file_new

yt get //home/dev/test1/test2/test_file_new/@account
"tmp"

Вызов команды copy с опцией preserve-account

$ yt copy --preserve-account //home/dev/test1/test_file //home/dev/test1/test2/test_file_new_p

yt get //home/dev/test1/test2/test_file_new_p/@account
"dev"

Опция -r, --recursive регулирует поведение в случае, если не существуют промежуточные узлы <destination_path> . В случае, если опция включена, данные узлы будут рекурсивно созданы, иначе команда выдаст ошибку.

Вызов команды copy без опции recursive

$ yt copy //home/dev/test1/test_file //home/dev/test1/test2/test3/test_file_new
Node //home/dev/test1/test2 has no child with key "test3"

Вызов команды copy с опцией recursive

$ yt copy --recursive //home/dev/test1/test_file //home/dev/test1/test2/test3/test_file_new

Опция -f, --force позволяет выполнить команду, даже если узел назначения существует. Существующий узел при этом удаляется.

Вызов команды copy без опции force

$ yt copy //home/dev/test1/test_file //home/dev/test1/test2/test_file_new
Node //home/dev/test1/test2/test_file_new already exists

Вызов команды copy с опцией force

$ yt copy --force //home/dev/test1/test_file //home/dev/test1/test2/test_file_new

Link

Данная команда создает символическую ссылку по пути <link_path> на объект, находящийся по пути <target_path>.

Описание команды link

$ yt link [-r, --recursive]
          [-i, --ignore-existing] [-l, --lock-existing]
          [-f, --force]
          <target_path> <link_path>

Опция -r, --recursive регулирует поведение в случае, если не существуют промежуточные узлы <link_path> . В случае, если опция включена, данные узлы будут рекурсивно созданы, иначе команда выдаст ошибку.

Вызов команды link без опции recursive

$ yt link //home/dev/test1/test_file //home/dev/test1/test2/link_test_file
Node //home/dev/test1 has no child with key "test2"

Вызов команды link с опцией recursive

$ yt link --recursive  //home/dev/test1/test_file //home/dev/test1/test2/link_test_file

Опция -i, --ignore-existing не будет пересоздавать заново указанную ссылку, если она уже существует.

Вызов команды link без опции ignore-existing

$ yt link //home/dev/test1/test_file //home/dev/test1/test2/link_test_file
Node //home/dev/test1/test2/link_test_file already exists

Вызов команды link с опцией ignore-existing

$ yt link --ignore-existing //home/dev/test1/test_file //home/dev/test1/test2/link_test_file

Опция -l, --lock-existing гарантирует, что на ссылку будет установлена exclusive-блокировка, даже если ссылка уже существует. (Имеет смысл только вместе с --ignore-existing; в случае невозможности установить блокировку команда завершится ошибкой).

Опция -f, --force позволяет выполнить команду, даже если узел назначения существует. Существующий узел при этом удаляется.

Concatenate

Команда concatenate объединяет данные из узлов <source_paths> в узел <destination_path>. Все узлы обязаны существовать и также иметь одинаковый тип – быть либо таблицами, либо файлами.

Описание команды concatenate

$ yt concatenate --src <source_paths> --dst <destination_path>