YSON-документ

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

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

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

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

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

Поддерживаются запросы и модификации внутри самого YSON-документа. Это означает, что документ можно запросить целиком, а можно только какие-то его отдельные части. Аналогично при модификации документа (команда set) — можно изменить весь документ целиком, а можно только его отдельные поля. Примеры см. в разделе Использование.

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

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

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

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

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

Прочитать YSON-документ:

$ yt get //tmp/my_test_doc

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

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

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

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

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

$ 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:

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

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

$ yt set //tmp/my_test_doc/key1 newvalue1

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

$ yt remove //tmp/my_test_doc

Ограничения

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

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

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

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