Типы данных
В данном разделе описаны типы данных, которые поддерживаются в YDB.
Поддерживаемые типы данных
В YDB используются типы данных YQL. Некоторые из типов YQL поддерживаются с ограничениями — они могут использоваться только в вычислениях, но не могут быть типом столбца или использоваться в первичном ключе. Все столбцы, включая ключевые, могут содержать специальное значение NULL.
Значения NULL в ячейках первичного ключа
Несмотря на наличие возможности иметь значения составного первичного ключа, в которых в части полей сохранены значения NULL, мы настоятельно рекомендуем никогда так не делать и не хранить в первичном ключе NULL.
В таблицах 1, 2 и 3 приведены возможные варианты использования типов данных YQL в YDB.
Числовые типы данных
Таблица 1. Возможности использования числовых типов данных YQL в YDB
| Тип | Пояснение | Используется в запросах и вычислениях YQL |
Используется в качестве типа данных столбца |
Используется в первичных ключах |
Поддерживает возможность сравнения |
|---|---|---|---|---|---|
Bool |
cтандартный булев тип, true или false |
Да | Да | Да | Да |
Int8 |
целое число со знаком, от -27 до 27 − 1 | Да | Нет | Нет | Да |
Int16 |
целое число со знаком, от -215 до 215 − 1 | Да | Нет | Нет | Да |
Int32 |
целое число со знаком, от -231 до 231 − 1 | Да | Да | Да | Да |
Int64 |
целое число со знаком, от -263 до 263 − 1 | Да | Да | Да | Да |
Uint8 |
беззнаковое целое, от 0 до 28 − 1 | Да | Да | Да | Да |
Uint16 |
беззнаковое целое, от 0 до 216 − 1 | Да | Нет | Нет | Да |
Uint32 |
беззнаковое целое, от 0 до 232 − 1 | Да | Да | Да | Да |
Uint64 |
беззнаковое целое, от 0 до 264 − 1 | Да | Да | Да | Да |
Float |
вещественное 4-байтное число | Да | Да | Нет | Да |
Double |
вещественное 8-байтное число | Да | Да | Нет | Да |
Decimal |
число с фиксированной точностью, сейчас поддерживается Decimal(22, 9) — 13 знаков в целой части, 9 в дробной |
Да | Да | Нет | Да |
DyNumber |
бинарное представление числа с плавающей точкой, сохраняющее порядок | Да | Да | Да | Да |
Строковые типы данных
Таблица 2. Возможности использования строковых типов данных YQL в YDB
| Тип | Пояснение | Используется в запросах и вычислениях YQL |
Используется в качестве типа данных столбца |
Используется в первичных ключах |
Поддерживает возможность сравнения |
|---|---|---|---|---|---|
String |
произвольная последовательность байт | Да | Да | Да | Да |
Utf8 |
текст в кодировке UTF-8 | Да | Да | Да | Да |
Json |
валидный JSON в текстовом представлении | Да | Да | Нет | Нет |
JsonDocument |
валидный JSON в бинарном индексированном представлении | Да | Да | Нет | Нет |
Uuid |
универсальный идентификатор UUID | Да | Нет | Нет | Да |
Ограничения на размер
Максимальный размер значения в ячейке с любым строковым типом данных — около 4 МБ.
Отличия Json и JsonDocument
В отличии от типа данных Json, который хранит исходное текстовое представление, переданное пользователем, JsonDocument использует бинарное индексированное представление. Важное отличие с точки зрения семантики состоит в том, что JsonDocument не сохраняет форматирование, порядок ключей в объектах и их дубликаты.
За счет индексированного представления, JsonDocument позволяет обходить документную модель с использованием JsonPath без необходимости парсинга всего содержимого. Это позволяет эффективно выполнять операции из JSON API, уменьшая задержки и стоимость пользовательских запросов. Выполнение запросов над JsonDocument может быть до нескольких раз эффективнее в зависимости от типа нагрузки.
Из-за добавленной избыточности JsonDocument менее эффективен в хранении. Дополнительные накладные расходы на хранение зависят от конкретного содержимого, но в среднем составляют 20%–30% от исходного объема. Кроме того, сохранение данных в формате JsonDocument требует дополнительной конвертации из текстового представления, что делает его запись несколько менее эффективной. Тем не менее, для большинства read-intensive сценариев, подразумевающих обработку данных из JSON, новый тип данных является предпочтительным и рекомендуется к использованию.
Хранение чисел в JsonDocument
Для хранении чисел (JSON Number) в JsonDocument, а также для арифметических операций над ними в JSON API, используется тип double. Возможна потеря точности при использовании нестандартных представлений чисел в исходном JSON документе.
Дата и время
Таблица 3. Возможности использования типов данных даты и времени YQL в YDB
| Тип | Пояснение | Используется в запросах и вычислениях YQL |
Используется в качестве типа данных столбца |
Используется в первичных ключах |
Поддерживает возможность сравнения |
|---|---|---|---|---|---|
Date |
точность до дней | Да | Да | Да | Да |
Datetime |
точность до секунд | Да | Да | Да | Да |
Timestamp |
точность до микросекунд | Да | Да | Да | Да |
Interval |
точность до микросекунд, допустимые значения интервалов — не более 24 часов | Да | Да | Нет | Да |
Опциональные значения (типы, допускающие значение NULL)
Любые типизированные данные в YQL, включая столбцы таблиц, бывают как гарантированно имеющие значение, так и потенциально пустые (что обозначается как NULL). Такие значения называют «опциональными» или в терминах SQL «nullable».
Наиболее распространённой операцией для таких типов данных является COALESCE, позволяющий оставить заполненные значения без изменений, а NULL заменить на указанное следом значение по умолчанию.
При описании таких типов данных в текстовом виде, они обозначаются с вопросительным знаком на конце (например, String?) или как Optional<...>.
Контейнеры
Таблица 4. Составные типы данных YQL
| Название | Объявление типа | Пример типа | Пояснение |
|---|---|---|---|
| Список | List<Type> |
List<Int32> |
Последовательность переменной длины, состоящая из элементов одного типа. |
| Словарь | Dict<KeyType, ValueType> |
Dict<String, Int32> |
Набор пар ключ-значение с фиксированным типом ключей и значений. |
| Кортеж | Tuple<Type1, ..., TypeN> |
Tuple<Int32, Double> |
Набор безымянных элементов фиксированной длины с указанными типами всех элементов. |
| Структура | Struct<Name1:Type1, ..., NameN:TypeN> |
Struct<Name:String, Age:Int32> |
Набор именованных полей с указанными типами значений, фиксированный на момент начала запроса (то есть обязательно не зависящий от данных). |
| Поток | Stream<Type> |
Stream<Int32> |
Однопроходной итератор по значениям одного типа. Не является сериализуемым. |
| Вариант над кортежем | Variant<Type1, Type2> |
Variant<Int32, String> |
Кортеж, про который известно, что заполнен ровно один элемент. |
| Вариант над структурой | Variant<Name1:Type1, Name2:Type2> |
Variant<value:Int32, error:String> |
Структура, про которую известно, что заполнен ровно один элемент. |
При необходимости контейнеры можно вкладывать друг в друга в произвольных комбинациях, например List<Tuple<Int32, Int32>> (список, содержащий в качестве элементов кортежи).
Опциональные значения в некоторых контекстах также могут рассматриваться как один из видов контейнеров (Optional<Type>), который ведёт себя как список длины 0 или 1.
Для представления множеств следует использовать словарь с значениями типа Void - Dict<T, Void>.
Представление данных YDB в формате json
Таблица 5. Представление данных YDB в формате json
| Тип | Описание | Тип в json | Пример YDB Value | Пример эквивалента в json |
|---|---|---|---|---|
| Optional | Optional означает, что значение может быть null. Если значение null, то в json также будет null. Если значение не null, то в json будет записываться так же, как если бы тип был не Optional. |
null |
null |
|
| Bool | Булев, Логический тип данных | bool | true |
true |
| Int8, Int16, Int32, Int64 | Целочисленные знаковые типы | number | 123456-123456 |
123456-123456 |
| Uint8, Uint16, Uint32, Uint64 | Целочисленные беззнаковые типы | number | 123456 |
123456 |
| Float | Вещественное 4-байтное число | number | 0.12345679 |
0.12345679 |
| Double | Вещественное 8-байтное число | number | 0.12345678901234568 |
0.12345678901234568 |
| Decimal | Число с фиксированной точностью. Сейчас поддерживается только Decimal(22, 9) | string | -320.789 |
"-320.789" |
| Date | Дата. Uint64, количество дней unix time | string | 18367 |
"2020-04-15" |
| Datetime | Дата и время. Uint64, количество секунд unix time | string | 1586966302 |
"2020-04-15T15:58:22Z" |
| Timestamp | Дата и время. Uint64, количество микросекунд unix time | string | 1586966302504185 |
"2020-04-15T15:58:22.504185Z" |
| Interval | Временной интервал. Int64, точность до микросекунд, допустимы значения интервалов - не более 24 часов | number | 123456-123456 |
123456-123456 |
| TzDate | Дата. String, точность до дней, содержит метку временной зоны | string | "2020-01-01,GMT" |
"2020-01-01,GMT" |
| TzDatetime | Дата и время. String, точность до секунд, содержит метку временной зоны | string | "2020-01-01T01:02:03,Europe/Moscow" |
"2020-01-01T01:02:03,Europe\/Moscow" |
| TzTimestamp | Дата и время. String, точность до микросекунд, содержит метку временной зоны | string | "2020-01-01T01:02:03.456789,Europe/Moscow" |
"2020-01-01T01:02:03.456789,Europe\/Moscow" |
| String, Yson | Бинарные строки. Алгоритм кодирования в зависимости от значения байта: - [0-31]: \u00XX (6 символов, обозначающих код символа юникода) - [32-126]: as is. Это читаемые однобайтовые символы, не требующие эскейпинга - [127-255]: \u00XX При декодировании происходит обратный процесс. Коды символов в \u00XX более 255 не допускаются. |
string | Последовательность из 4 байт: - 5 0x05 - управляющий символ- 10 0x0a - перенос строки '\n'- 107 0x6b - символ 'k'- 255 0xff - символ юникода "ÿ" |
"\u0005\nk\u00FF" |
| Utf8, Json, Uuid | Строковые типы в utf-8. Такие строки представляются в json строками с escaping'ом json-символов: \\ \" \n \r \t \f |
string | С++ код: "Escaped characters: ""\\ \" \f \b \t \r\n""Non-escaped characters: ""/ ' < > & []() " |
"Escaped characters: \\ \" \f \b \t \r\nNon-escaped characters: / ' < > & []() " |
| List | Список. Упорядоченный набор значений заданного типа | array | Тип: List<Int32>Значения: 1, 10, 100 |
[1,10,100] |
| Struct | Структура. Неупорядоченный набор значений с заданными именами и типом | object | Тип: Struct<'Id':Uint32,'Name':String,'Value':Int32,'Description':Utf8?>Значения: "Id":1,"Name":"Anna","Value":-100,"Description":null |
{"Id":1,"Name":"Anna","Value":-100,"Description":null} |
| Tuple | Кортеж. Упорядоченный набор значений заданных типов | array | Тип: Tuple<Int32??,Int64???,String??,Utf8???>Значение: 10,-1,null,"Some string" |
[10,-1,null,"Some string"] |
| Dict | Словарь. Неупорядоченный набор пар ключ-значение. И для ключа, и для значения задан тип. В json записывается в массив массивов, состоящих из двух элементов |
array | Тип: Dict<Int64,String>Значение: 1:"Value1",2:"Value2" |
[[1,"Value1"],[2,"Value2"]] |