YSON-документ

В данном разделе содержится информация о YSON-документах.

Общие сведения

YSON-документ — это узел Кипариса, имеющий тип document и предназначенный для хранения произвольных YSON-структур.

Помимо YSON-документа, создавать и хранить иерархические структуры данных можно в виде узлов типа map_node, list_node, string_node и других.
По сравнению с этим способом, YSON-документы имеют следующие отличия:

  • Хранение данных в виде документа более компактно с точки зрения потребляемой памяти, так как узел документа не является полноценным узлом Кипариса.
  • Документ ведет себя как единое целое с точки зрения специфичных для Кипариса возможностей: блокировок, владельцев, атрибутов revision, creation_time, modification_time, expiration_time и других.

Работать с документами можно с помощью стандартных команд: get, list, exists, set, remove, как и с другими объектами в Кипарисе.

Поддерживаются запросы и модификации внутри самого документа. Адресация внутри документа осуществляется с помощью языка YPath.

Подробнее про формат YSON.

Использование

Создать YSON-документ:

CLI

yt create document //tmp/my_test_doc
3f08-5b920c-3fe01a5-e0c12642

По умолчанию при создании в документе хранится YSON-entity. Прочитать YSON-документ:

CLI

yt get //tmp/my_test_doc

Указать начальное значение YSON-документа при создании:

CLI

yt create document //tmp/my_test_doc --attributes '{value=hello}'
3f08-6c0ee0-3fe01a5-2c4f6104
yt get //tmp/my_test_doc
"hello"

Записать в YSON-документ число и прочитать его:

CLI

yt set //tmp/my_test_doc 123
#
yt get //tmp/my_test_doc
123

Записать в YSON-документ сложную структуру и прочитать ее полностью или частично:

CLI

yt set //tmp/my_test_doc '{key1=value1;key2={subkey=456}}'
#
yt get //tmp/my_test_doc
{
    "key1" = "value1";
    "key2" = {
        "subkey" = 456;
    };
}
yt get //tmp/my_test_doc/key2
{
    "subkey" = 456;
}

При этом узел будет иметь тип document:

CLI

yt get //tmp/my_test_doc/@type
"document"

Частично изменить YSON-документ:

CLI

yt set //tmp/my_test_doc/key1 newvalue1

Удалить YSON-документ полностью:

CLI

yt remove //tmp/my_test_doc

Ограничения

В Кипарисе существует еще одна возможность создавать и хранить иерархические структуры данных: в виде узлов типа map_node, list_node, string_node и другие.

Чтение и запись YSON-документов происходит через мастер-сервер Кипариса, поэтому их нельзя применять в качестве высоконагруженной объектной базы данных. Разумный лимит — единицы RPS. Поскольку эти данные хранятся в памяти мастер-сервера в виде дерева, следует с осторожностью выбирать объем данных.

Разумным лимитом на отдельный документ можно считать килобайты. Суммарный объем всех документов пользователя не должен превышать единицы мегабайт. Обычно такие узлы используются для хранения небольших кусочков структурированных метаданных, конфигурации и т.д.

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

Помимо атрибутов, присущих всем узлам Кипариса, документы имеют следующие дополнительные атрибуты:

Атрибут Тип Описание
value any Полное содержимое документа. Атрибут позволяет задать содержимое документа при создании. Атрибут является opaque, то есть при чтении всех атрибутов узла без фильтра он будет отображаться как entity.