---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://ytsaurus.tech/docs/en/user-guide/storage/yson-docs.md
  - https://ytsaurus.tech/docs/ru/user-guide/storage/yson-docs.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ytsaurus.tech/docs/ru/llms.txt

<!-- source: ru/_includes/user-guide/storage/yson-docs.md -->
# YSON-документ

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

## Общие сведения { #common }

YSON-документ — это узел [Кипариса](https://ytsaurus.tech/docs/ru/user-guide/storage/cypress.md), имеющий тип  **document** и предназначенный для хранения произвольных YSON-структур.

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

Работать с документами можно с помощью стандартных [команд](https://ytsaurus.tech/docs/ru/api/commands.md):  `get`, `list`, `exists`, `set`, `remove`, как и с другими объектами в Кипарисе.

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

Адресация внутри документа осуществляется с помощью языка [YPath](https://ytsaurus.tech/docs/ru/user-guide/storage/ypath.md).


## Использование { #usage }

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

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

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

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

```bash
$ yt get //tmp/my_test_doc
```

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

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

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

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

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

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

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

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

```bash
$ yt set //tmp/my_test_doc/key1 newvalue1
```

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

```bash
$ yt remove //tmp/my_test_doc
```

## Ограничения { #limits }

Чтение и запись YSON-документов происходит через мастер-сервер Кипариса, поэтому их нельзя применять в качестве высоконагруженной объектной базы данных. Разумный лимит — единицы [RPS](https://en.wikipedia.org/wiki/Queries_per_second). Поскольку эти данные хранятся в памяти мастер-сервера в виде дерева, следует понимать, что объем данных, которые можно сохранить в YSON-документах, сильно ограничен.

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

## Системные атрибуты { #attributes }

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

| **Атрибут** | **Тип** | **Описание**                                                 |
| ----------- | ------- | ------------------------------------------------------------ |
| `value`     | `any`   | Полное содержимое документа. Атрибут позволяет задать содержимое документа при создании. Атрибут является [opaque](attributes.md#system_attr), то есть при чтении всех атрибутов узла без фильтра он будет отображаться как [entity](yson.md#entity). |
<!-- endsource: ru/_includes/user-guide/storage/yson-docs.md -->