Аннотации
В данном разделе описываются аннотации таблиц, директорий и других узлов Кипариса.
Предназначение аннотаций
Аннотации — это способ снабдить таблицу, директорию или любой другой узел Кипариса коротким описанием.
Формально таким описанием может служить произвольный текст длиной до 1 КБ, состоящий из неуправляющих ASCII-символов, однако рекомендуется придерживаться формата Markdown.
Примечание
Аннотации хранятся в памяти мастер-серверов YTsaurus. Рекомендуется ограничивать содержимое аннотаций одним-двумя предложениями и ссылками на более подробную документацию.
Атрибут annotation
У всех узлов Кипариса имеется атрибут annotation, значением которого является YSON string. Значение можно задать, как и для других атрибутов:
yt set //home/project/path/table/@annotation '"This table contains valuable data."'
Удаление производится обычным образом:
yt remove //home/project/path/table/@annotation
Примечание
Атрибут annotation присутствует всегда, но по умолчанию равен null. Удаление сбрасывает атрибут до значения null, однако формально он продолжает существовать.
Таким образом, проверка существования атрибута annotation всегда возвращает положительный результат и потому бесполезна. Вместо этого следует проверять атрибут на равенство null.
Такая особенность поведения связана с наследованием.
Наследование
Аннотация может сопровождать как таблицу, так и целое поддерево. Чтобы добавить аннотацию поддерева, установите ее на соответствующую директорию. После этого любой узел, рекурсивно содержащийся в ней и не обладающий собственной аннотацией, отобразит ее в своем атрибуте annotation.
Иными словами, атрибут annotation наследуется: в нем всегда отображается ближайшая ненулевая аннотация предка. Поиск начинается с самого узла.
Чтобы понять, какому предку принадлежит отображаемая аннотация, существует атрибут annotation_path. Он доступен только для чтения и содержит полный путь к соответствующему предку или к самому узлу, если аннотирован непосредственно он.
Поддержка в веб-интерфейсе
Веб-интерфейс поддерживает отображение аннотаций и воспринимает формат Markdown — диалект YFM, который поддерживается пакетом @doc-tools/transform.
Аннотации отображаются в разделе Navigation, на вкладке Annotation выбранного узла. Чтобы отредактировать аннотацию, нажмите Edit metadata и перейдите на вкладку Description.