--- metadata: - name: generator content: Diplodoc Platform v5.50.6 alternate: - https://ytsaurus.tech/docs/en/user-guide/storage/yson.md - https://ytsaurus.tech/docs/ru/user-guide/storage/yson.md --- > **Documentation Index:** Fetch the complete configuration index at https://ytsaurus.tech/docs/ru/llms.txt # YSON В данном разделе собрана информация про YSON — JSON-подобный формат данных. ## Основные отличия YSON от JSON { #main-differences } 1. Поддержка бинарного представления скалярных типов (чисел, строк и булевого типа); 2. [Атрибуты](#attributes): произвольный словарь, который можно установить дополнительно на литерал любого — даже скалярного — типа. ## Синтаксические отличия { #syntax-differeces } 1. Вместо запятой в качестве разделителя используется точка с запятой; 2. В словарях ключ от значения отделяется не двоеточием, а знаком равенства: `=`; 3. Строковые литералы не обязательно всегда заключать в кавычки — только если возникает неоднозначность при парсинге; Имеется следующий набор **скалярных** типов: 1. [Строки](#string) (`string`); 2. [Знаковые](#int) и [беззнаковые](#uint) 64-битные целые числа (`int64` и `uint64` ); 3. [Числа с плавающей точкой](#double) двойной точности (`double`); 4. [Булев](#boolean) (логический) тип (`boolean`); 5. [Специальный тип entity](#entity), имеющий всего один литерал (`#`). Скалярные типы обычно имеют как текстовое, так и бинарное представление. Есть два **композитных** типа: 1. [Список](#list) (`list`); 2. [Словарь](#map) (`map`). ## Скалярные типы { #scalar_types } ### Строки { #string } Токены строк бывают трёх видов: 1. **Идентификаторы** задаются регулярным выражением ` [A-Za-z_][A-Za-z0-9_.\-]*`, расширенные C-идентификаторы, отличие в символах `-`,`.`. Идентификатор задает строку с идентичным ему содержимым и используется в первую очередь для краткости (не нужно ставить кавычки). Примеры: - `abc123`; - `_`; - `a-b`. 2. **Текстовые строки** — [C-escaped](https://en.wikipedia.org/wiki/Escape_sequences_in_C) строки в двойных кавычках. Примеры - `"abc123"`; - `""`; - `"quotation-mark: \", backslash: \\, tab: \t, unicode: \xEA"`. 3. **Бинарные строки**: `\x01 + length (protobuf sint32 wire format) + data ( bytes)`. ### Знаковые 64-битные целые числа (`int64`) { #int } Два способа записи: 1. **Текстовый** (`0`, `123`, `-123`, `+123`); 2. **Бинарный**: `\x02 + value (protobuf sint64 wire format)`. ### Беззнаковые 64-битные целые числа (`uint64`) { #uint } Два способа записи: 1. **Текстовый** (`10000000000000`, `123u`); 2. **Бинарный**: `\x06 + value (protobuf uint64 wire format)`. ### Числа с плавающей точкой (`double`) { #double } Два способа записи: 1. **Текстовый**: `0.0`, `-1.0`, `1e-9`, `1.5E+9`, `32E1`; 2. **Бинарный**: `\x03 + protobuf double wire format`. {% note warning "Внимание" %} Текстовое представление чисел с плавающей точкой включает в себя округление, которое может привести к тому, что при обратном парсинге значение окажется иным. В случае, если вам важна точность, следует использовать бинарное представление. {% endnote %} ### Булевы литералы (`boolean`) { #boolean } Два способа записи: 1. **Текстовый** (`%false`, `%true`); 2. **Бинарный** (`\x04`, `\x05`). ### Entity (`entity`) { #entity } Entity представляет собой атомарное скалярное значение, не имеющее собственного содержимого. Сценарии, в которых данный тип может быть полезен, разнообразны. Например, часто entity обозначает null. Также при запросе `get` на поддерево [Кипариса](https://ytsaurus.tech/docs/ru/user-guide/storage/cypress.md) [файлы](https://ytsaurus.tech/docs/ru/user-guide/storage/objects.md#files) и [таблицы](https://ytsaurus.tech/docs/ru/user-guide/storage/objects.md#tables) возвращаются в виде entities (полезные данные при этом хранятся в [атрибутах](#attributes) данного узла). Лексически entity кодируется символом диеза: `#`. ### Выделенные литералы { #special_literals } Специальные токены: `;`, `=`, `#`, `[`, `]`, `{`, `}`, `<`, `>`, `)`, `/`, `@`, `!`, `+`, `^`, `:`, `,`, `~`. Не все эти символы используются в YSON, некоторые используются в [YPath](https://ytsaurus.tech/docs/ru/user-guide/storage/ypath.md). ## Композитные типы { #composite_types } ### Список (`list`) { #list } Задаётся следующим образом: `[value; ...; value]`, где `value` — литералы произвольных скалярных или композитных типов. Пример: `[1; "hello"; {a=1; b=2}]`. ### Словарь (`map`) { #map } Задаётся следующим образом: `{key = value; ...; key = value}`. Здесь `*key*` — литералы строкового типа, а `value` — литералы произвольных скалярных или композитных типов. Пример: `{a = "hello"; "38 parrots" = [38]}`. ### Атрибуты { #attributes } На любой литерал в YSON можно установить атрибуты. Формат записи: ` value`. Внутри угловых скобок синтаксис аналогичен словарю. Например, `"some-string"` или `<"44" = 44>44`. Но чаще всего атрибуты можно встретить на литералах типа `entity`, например, `#`. ## Грамматика {#grammar} YSON-данные бывают трех типов: 1. **Node** (одно дерево, в примере — ``) 2. **ListFragment** (значения, разделенные `;`, в примере — ``) 3. **MapFragment** (пары ключ-значение, разделенные `;`, в примере — ``) Грамматика (определяется с точностью до пробельных символов, которые могут быть в произвольном количестве добавлены и удалены между токенами): ```antlr = [ ], ; = | | | ; = | | | | ; = "[", , "]"; = "{", , "}"; = "#"; = "<", , ">"; = { , ";" }, [ ]; = ; = { , ";" }, [ ]; = , "=", ; % Key cannot be empty ``` Символ `;` после последнего элемента внутри `` и `` может быть опущен. Следующие конструкции следует считать валидными при чтении: #| || C `;` на конце | Сокращенная запись || || ```yson c {a=b;} 1;2;3; ``` | ```yson c {a=b} 1;2;3 ``` || |# ## Примеры {#examples} - Map (Node) ```yson { performance = 1 ; precision = 0.78 ; recall = 0.21 } ``` - Map (Node) ```yson { cv-precision = [ 0.85 ; 0.24 ; 0.71 ; 0.70 ] } ``` - List (Node) ```yson [ 1; 2; 3; 4; 5 ] ``` - String (Node) ```yson foobar ``` ```yson "hello world" ``` - Int64 (Node) `42` - Double (Node) `3.1415926` - ListFragment ```yson { key = a; value = 0 }; { key = b; value = 1 }; { key = c; value = 2; unknown_value = [] } ``` - MapFragment ```yson do = create; type = table; scheme = {} ``` - HomeDirectory (Node) ```yson { home = { sandello = { mytable = # ; anothertable = # } ; monster = { } } } ``` ## Работа с YSON из кода { #working_from_code } Обычно пользователям не приходится работать напрямую с YSON. При использовании одного из официальных YTsaurus-клиентов YSON-структуры будут выражаться в одном из перечисленных ниже видов: 1. **C++**:[ `TNode`](https://github.com/ytsaurus/ytsaurus/blob/main/library/cpp/yson/node/node.h) — класс, обеспечивающий динамическое DOM-подобное представление YSON-документа; 2. **Python**: [`YsonType`](https://github.com/ytsaurus/ytsaurus/blob/main/yt/python/yt/yson/yson_types.py) — YSON-типы мимикрируют под Python типы. YSON-атрибуты объекта `x` можно получить так: `x.attributes`, это Python словарь; 3. **Java**: [`YTreeNode`](https://github.com/ytsaurus/ytsaurus/blob/main/yt/java/yson-tree/src/main/java/tech/ytsaurus/ysontree/YTreeNode.java) — интерфейс, обеспечивающий динамическое DOM-подобное представление YSON-документа.