--- metadata: - name: generator content: Diplodoc Platform v5.50.6 alternate: - https://ytsaurus.tech/docs/en/user-guide/storage/cypress.md - https://ytsaurus.tech/docs/ru/user-guide/storage/cypress.md --- > **Documentation Index:** Fetch the complete configuration index at https://ytsaurus.tech/docs/ru/llms.txt # Дерево метаинформации Кипарис — дерево метаинформации, содержащее в себе различную системную информации и данные о том, где хранятся пользовательские данные. Вы познакомитесь с [общим представлением дерева](#description), [атрибутами узлов Кипариса](#attributes) и [TTL для узлов Кипариса](#TTL). ## Общее представление дерева { #description } С пользовательской точки зрения Кипарис похож на дерево [файловой системы](https://ru.wikipedia.org/wiki/Файловая_система) в Linux, но имеет ряд существенных отличий: * С каждым узлом в дереве связан [набор атрибутов](https://ytsaurus.tech/docs/ru/user-guide/storage/attributes.md), в том числе задаваемых пользователем. * Дерево является [транзакционным](https://ytsaurus.tech/docs/ru/user-guide/storage/transactions.md). * В качестве узла Кипариса могут быть не только файлы и директории, но и [другие объекты](https://ytsaurus.tech/docs/ru/user-guide/storage/objects.md). По аналогии с файловой системой в Кипарисе поддерживается [система контроля доступов](https://ytsaurus.tech/docs/ru/user-guide/storage/access-control.md). ### Что еще важно знать {#what-else-is-important} * Корневым элементом Кипариса является `/`, который имеет тип **map_node** (то есть является директорией). Адресация узлов в Кипарисе осуществляется с помощью [YPath](https://ytsaurus.tech/docs/ru/user-guide/storage/ypath.md). * Количество дочерних узлов директории ограничено. По умолчанию лимит равен 50000, но зависит от конфигурации кластера. * Глубина Кипариса в теории не ограничена, но стоит помнить о том, что в [YPath](https://ytsaurus.tech/docs/ru/user-guide/storage/ypath.md) существует лимит на глубину разрешения пути. ### Примеры {#examples} Примеры путей: `//tmp` – временная директория, `//tmp/@` – атрибуты этой директории, `//tmp/table/@type` – путь до атрибута `type` узла `//tmp/table`. С использованием YPath Кипарис может быть изображен следующим образом: ``` / /home /user1 /table /@id /@chunk_ids /@type ... ... /user2 ... /tmp /sys /chunks ... ... ... ``` {% note info %} С Кипарисом можно работать с помощью [CLI](https://ytsaurus.tech/docs/ru/api/cli/cli.md). {% endnote %} ## Атрибуты узлов Кипариса { #attributes } У узлов Кипариса есть общие для всех объектов [атрибуты](https://ytsaurus.tech/docs/ru/user-guide/storage/attributes.md). Также есть дополнительные атрибуты, представленные в таблице: | **Атрибут** | **Тип** | **Значение** | | -------------------------- | ------------------ | ------------------------------------------------------------ | | `parent_id` | `string` | Идентификатор узла-родителя (отсутствует в корне) | | `locks` | `array` | [Список блокировок](transactions.md), взятых на узел | | `lock_mode` | `LockMode` | Текущий [режим блокировки](transactions.md) узла (зависит от транзакции) | | `path` | `string` | Полный путь к узлу | | `key` | `string` | Ключ, по которому данный узел доступен в родительском каталоге (если узел лежит в таковом) | | `creation_time` | `DateTime` | Время [создания](#time_attributes) узла | | `modification_time` | `DateTime` | Время [последней модификации](#time_attributes) узла | | `access_time` | `DateTime` | Время [последнего доступа](#time_attributes) к узлу | | `expiration_time` | `DateTime` | Время, когда узел будет [автоматически удален](#TTL). Опциональный атрибут | | `expiration_timeout` | `DateTime` | Интервал времени, после которого узел будет [автоматически удален](#TTL), если к нему не было обращений. Опциональный атрибут | | `touch_time` | `DateTime` | Время последнего доступа к узлу, используемое для [автоматического удаления](#TTL) через `expiration_timeout`. Присутствует только при наличии `expiration_timeout` | | `access_counter` | `integer` | Количество обращений к узлу с момента создания | | `revision` | `integer` | [Ревизия](#time_attributes) узла | | `resource_usage` | `ClusterResources` | Ресурсы кластера, занимаемые узлом | | `recursive_resource_usage` | `ClusterResources` | Ресурсы кластера, занимаемые узлом и всем его поддеревом | | `account` | `string` | Аккаунт, используемый при учете ресурсов, занимаемых данным узлом | | `annotation` | `string` | Человекочитаемая [аннотация](annotations.md) объекта | Каждый узел имеет свой дескриптор, отвечающий за управление доступом, поэтому среди его атрибутов есть `inherit_acl`, `acl` и `owner`. Подробнее можно прочитать в разделе [Система контроля доступов](https://ytsaurus.tech/docs/ru/user-guide/storage/access-control.md). ### Атрибуты времени { #time_attributes } #| || **Название атрибута** | **Описание атрибута** || || Атрибут `creation_time` | Хранит время, когда узел был создан. || || Атрибут `modification_time` | Хранит время, когда узел, его пользовательские атрибуты или некоторые системные атрибуты в последний раз изменялись. Не учитывает изменение сыновей узла, т.е. атрибут `modification_time` у `map_node` не меняется, если где-то в глубине дерева происходят изменения. || || Атрибут `revision` | Обновляется системой при создании и при каждом изменении узла. Хранит неотрицательное целое число. Изменяется одновременно с `modification_time`. Гарантируется, что ревизия с течением времени растет строго монотонно. Ревизии можно использовать для проверки того факта, что узел не изменился. || || Атрибут `access_time` | Хранит время последнего обращения к содержимому узла. Обращение к атрибутам при этом не учитывается (обращением к атрибуту считается указание полного пути к атрибуту внутри [YPath](https://ytsaurus.tech/docs/ru/user-guide/storage/ypath.md)). Также не учитываются запросы с включенной опцией `suppress_access_tracking`. Для повышения эффективности система не изменяет данный атрибут на каждое обращение, а накапливает факты обращений и обновляет атрибут `access_time` с периодичностью порядка секунды. || |# {% note warning "Внимание" %} В редких случаях возможна ситуация, когда к узлу было обращение, но в результате сбоя мастер-сервера атрибут `access_time` не будет обновлен. {% endnote %} {% note warning "Внимание" %} Атрибуты `modification_time` и `access_time` для динамических таблиц в настоящий момент не несут в себе никакой полезной информации. Их обновление (или необновление) никак не связано с операциями чтения и записи, выполняемыми пользователями. В будущем данное поведение может измениться. {% endnote %} Для большинства команд, при помощи которых происходит чтение или запись, существуют опции `suppress_access_tracking` и `suppress_modification_tracking`, которые позволяют отключить обновления атрибутов `access_time`, `modification_time` и `revision` при чтении и записи соответственно. В частности, веб-интерфейс использует `suppress_access_tracking`, так что просмотры содержимого через web UI не приводят к обновлению `access_time`. {% note info "Примечание" %} В случае создания или модификации узла под транзакцией описанные атрибуты устанавливаются один раз: во время изменений внутри транзакции. Таким образом, узел может стать видимым в родительских транзакциях существенно позже, чем его `creation_time`, только после коммита соответствующей транзакции. {% endnote %} ## TTL для узлов Кипариса { #TTL } Кипарис может автоматически удалять узлы по наступлении указанного момента времени или в случае отсутствия обращений к узлу на протяжении указанного интервала времени. Для управления этой возможностью существуют атрибуты `expiration_time` и `expiration_timeout`. По умолчанию атрибуты отсутствуют, в этом случае система не будет автоматически удалять узел. Для работы TTL необходимо: - указать в атрибуте `expiration_time` момент времени, при наступлении которого узел будет удален. Если узел композитный, то будет также удалено все его поддерево; - указать в атрибуте `expiration_timeout` интервал времени, в течение которого к узлу должны отсутствовать обращения, чтобы узел (и все его поддерево, если узел композитный) был удален. Для учета времени последнего запроса используется время из атрибута `touch_time`. ### Особенности атрибута touch_time {#touch-time-features} * Атрибут `touch_time` по аналогии с `access_time` хранит время последнего обращения к узлу. Данный атрибут присутствует только у узлов с присутствующим атрибутом `expiration_timeout`. * В отличие от `access_time`, `touch_time` обновляется при обращении к атрибутам узла, а также при обращениях к узлу через веб-интерфейс. * Атрибут `touch_time` не учитывает изменение сыновей узла, т.е. атрибут `touch_time` у `map_node` не меняется, если где-то в глубине дерева происходят обращения. Также `touch_time` не обновляется в запросах с включенной опцией `suppress_expiration_timeout_renewal`. {% note warning "Внимание" %} Данные, удаленные с помощью описанного механизма, невозможно восстановить. Используйте его с осторожностью. {% endnote %} ### Пример {#example} Момент времени необходимо указать либо строкой в isoformat, либо целым числом миллисекунд с начала эпохи. Эти способы эквивалентны: ```bash yt set //home/project/path/table/@expiration_time '"2020-05-16 15:12:34.591+03:00"' yt set //home/project/path/table/@expiration_time '1589631154591' ``` Интервал времени указывается в миллисекундах: ```bash # Удалить узел, если его «не трогали» неделю. yt set //home/project/path/table/@expiration_timeout 604800000 ``` {% note warning "Внимание" %} Указывать `expiration_timeout` на директориях следует с чрезвычайной осторожностью. Время жизни директории продлевают только непосредственные обращения к ней, но не к ее поддереву. Так, например, чтение таблицы, содержащейся в директории с `expiration_timeout`, *не продлевает* ее время жизни. {% endnote %} ### Что важно знать про TTL {#important-to-know} Атрибуты TTL можно менять в транзакциях, однако эффект имеют только их закоммиченные значения. * Чтобы выставлять данные атрибуты для узла, необходимо иметь [право](https://ytsaurus.tech/docs/ru/user-guide/storage/access-control.md) `write` на сам узел, как и для многих других атрибутов, а также `remove` для данного узла и всего его поддерева, так как фактически заказывается удаление, хоть и отложенное. Чтобы удалить данные атрибуты, достаточно права `write`. * Система не дает никаких гарантий точности времени удаления. На практике удаление происходит в пределах единиц секунд после наступления указанного времени. Автоматическое удаление узла не наступает, если в момент наступления указанного времени на узле есть блокировки, отличные от `snapshot`. Система удалит узел, как только все блокировки будут сняты. Этим свойством можно пользоваться для искусственного продления времени жизни узла. * При копировании и перемещении узла атрибуты `expiration_time` и `expiration_timeout` по умолчанию сбрасываются, так что копия не будет автоматически удалена. У команд есть опции `preserve-expiration-time` и `preserve-expiration-timeout`, позволяющие поменять поведение. {% note warning "Внимание" %} Ряд вызовов API, создающих временные таблицы, устанавливают на них `expiration_time`/`expiration_timeout`, чтобы таблицы самоочищались. Следует иметь это в виду и не хранить в таких таблицах важные данные. {% endnote %} Удаление может произойти раньше, если узел находится в поддереве с меньшим значением `expiration_time`/`expiration_timeout` в корне. Чтобы получить фактическое время удаления узла, можно воспользоваться атрибутом `effective_expiration`: ```bash $ yt get //home/project/path/table/@effective_expiration { "time": {"value": 42, "path": //testator/path} "timeout": {"value": 42, "path": //testator/path} } ``` При отсутствии, например, `expiration_time` на пути от корня до узла, в поле `"time"` будет записано YSON entity.