Типы данных
В данном разделе описаны типы данных, которые поддерживаются в 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"]] |