Атрибуты

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

Общая информация

С каждым объектом в системе YTsaurus связан набор атрибутов. Множество атрибутов представляет собой словарь ключ-значение, который доступен для чтения и изменения. Именами атрибутов могут выступать произвольные непустые строки. Значениями — произвольные YSON-структуры.

Атрибуты бывают двух видов: системные и пользовательские.

Для обращения к атрибутам объекта используется специальный модификатор пути /@ и команды get, list, set, remove. Помимо обращения к атрибутам целиком можно адресовать их части (в случае, когда значение атрибута — составной тип).

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

У команд get и list можно опционально указать список атрибутов, которые требуется вернуть вместе c найденными объектами.

Системные атрибуты

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

Системные атрибуты бывают изменяемыми (может изменять пользователь), например compression_codec, и неизменяемыми, например compressed_data_size. При попытке установить неизменяемый атрибут система вернет ошибку. Попытка удаления системного атрибута также приведет к ошибке.

Некоторые атрибуты являются наследуемыми: compression_codec, erasure_codec, primary_medium, media, replication_factor, vital, tablet_cell_bundle, atomicity, commit_ordering, in_memory_mode, optimize_for. Помимо объектов, для которых семантика этих атрибутов очевидна (таблицы, файлы и т.п.), данные атрибуты можно устанавливать на композитных узлах (т.е. на map- и list-нодах). На них наследуемые атрибуты являются nullable, то есть могут не иметь никакого значения. Когда при создании нового объекта не указано значение наследуемого атрибута, данный атрибут получит значение ближайшего узла-предка или значение по умолчанию, если ни у одного предка вплоть до корня атрибут не установлен.

Также системные атрибуты могут быть непрозрачными (вычисляемыми, opaque), то есть их значение будет доступно только при явном запросе командой get, но не будет доступно (а точнее, значение атрибута будет равно entity) при запросе всех атрибутов. Чаще всего непрозрачными объявляются атрибуты, имеющие большое значение (в смысле объема данных), либо вычисление которых требует значительного времени. То есть, если данные в атрибуте составляют более сотни килобайт, имеет смысл делать их непрозрачными. В таком случае при запросе всех атрибутов, они не будут возвращаться, и чтение всех атрибутов будет быстрее. Если требуется получить эти значения, нужно явно их запросить. Примером непрозрачного атрибута будет список всех чанков таблицы (атрибут chunk_ids) или суммарное использование ресурсов по поддереву Кипариса (атрибут recursive_resource_usage).

Ниже представлен список атрибутов объектов системы YTsaurus:

• атрибуты любого объекта;
• атрибуты узлов Кипариса;
• атрибуты статических таблиц;
• атрибуты динамических таблиц;
• атрибуты файлов;
• атрибуты compression_codec и erasure_codec для таблиц и файлов;
• атрибуты транзакций;
• атрибуты ссылок;
• атрибуты аккаунтов;
• атрибуты медиумов.

Пользовательские атрибуты

Пользователь может самостоятельно устанавливать произвольные атрибуты.

Как атрибуты хранятся в системе

Системные атрибуты могут храниться различными способами, зависящими от типа объекта. Они могут не храниться, а рассчитываться во время вычислений. Пользовательские атрибуты хранятся в виде словаря ключ-значение. Значение закодировано в виде YSON, поэтому обращение к значению атрибута требует распаковки.

yt set //tmp/@my_attribute '{x=10; y=["hello"; "world"]}'
yt get //tmp/@my_attribute/x
10
yt get //tmp/@my_attribute/y/1
"world"

yt set //tmp/@my_attribute/y/@inner_attribute attr
yt get //tmp/@my_attribute/y/@inner_attribute
"attr"

Примеры

# Получение всех атрибутов объекта
yt get //tmp/@
{
  "creation_time" = "2013-12-06T19:00:48.256444Z";
  "locks" = [];
 ...
}

# Получение конкретного атрибута объекта
yt get //tmp/@type
"map_node"

# Установка конкретного атрибута объекта
yt set //tmp/@my_attribute "my_value"

# Удаление атрибута
yt remove //tmp/@my_attribute

# создание таблицы
echo '{"a": 10, "b": "hello"}' | yt write //tmp/my_table --format json

# Получение первого чанка таблицы
yt get //tmp/my_table/@chunk_ids/0
"3ab1-cd56f-3ec0064-c8998820"

# Удаление таблицы
yt remove //tmp/my_table --force


# Запрос списка с атрибутами
yt list / --attribute type --format '<format=pretty>yson'
[
    <
        "type" = "map_node"
    > "home";
    <
        "type" = "map_node"
    > "kiwi";
   ....
]

Атрибуты на путях

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