Аннотации
В данном разделе описываются аннотации таблиц, директорий и других узлов Кипариса.
Предназначение аннотаций
Аннотации — это способ снабдить таблицу, директорию или любой другой узел Кипариса коротким описанием.
Формально таким описанием может служить произвольный текст длиной до 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.