Атрибуты

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

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

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

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

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

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

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

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

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

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

• Некоторые атрибуты являются наследуемыми: такие атрибуты можно устанавливать на директориях (map-нодах), где они являются 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.