Типы данных Yandex Database

В YDB используются типы данных YQL. Некоторые из типов YQL поддерживаются с ограничениями — они применяются только в вычислениях и не могут быть типом столбца или частью первичного ключа. Все столбцы, включая ключевые, могут содержать специальное значение NULL.

Числовые типы

Строковые типы

В отличие от типа данных Json, который хранит исходное текстовое представление, переданное пользователем, JsonDocument использует бинарное индексированное представление. Важное отличие с точки зрения семантики состоит в том, что JsonDocument не сохраняет форматирование, порядок ключей в объектах и их дубликаты.

За счет индексированного представления JsonDocument позволяет обходить документную модель с использованием JsonPath без необходимости парсинга всего содержимого. Это позволяет эффективно выполнять операции из JSON API, уменьшая задержки и стоимость пользовательских запросов. Выполнение запросов над JsonDocument может быть до нескольких раз эффективнее в зависимости от типа нагрузки.

Из-за добавленной избыточности JsonDocument менее эффективен в хранении. Дополнительные накладные расходы на хранение зависят от конкретного содержимого и в среднем составляют 20–30% от исходного объема. Сохранение данных в формате JsonDocument требует дополнительной конвертации из текстового представления, что делает его запись менее эффективной. Тем не менее, для большинства read-intensive сценариев, подразумевающих обработку данных из JSON, этот тип данных является предпочтительным и рекомендуется к использованию.

Дата и время

Опциональные типы

Данные в YQL могут как гарантированно иметь значение, так и быть пустыми. Пустые значения обозначаются как NULL. Типы данных, которые могут содержать значения NULL, называются опциональными или, в терминах SQL, — nullable.

Опциональные типы данных в текстовом виде обозначаются вопросительным знаком в конце (например, String?) или как Optional<...>.

Наиболее часто на опциональных типах данных выполняются следующие операции:

• UNWRAP
  — извлечь значение оригинального типа из опционального, T? преобразуется в T.

  Пример записи:

  UNWRAP(x)
  

  Важно

  Операция UNWRAP вернет ошибку времени выполнения, если значение x есть NULL.

• COALESCE
  — проверить значение на NULL, если да, то заменить NULL значением value.

  Примеры записи:

  COALESCE(x, "value")
  

  x ?? "value"
  

  IF(x is not null,UNWRAP(x),"value")
  

  Приведенные примеры записи эквивалентны.

• IF
  — вычислить выражение, если значение x не является NULL.

  Пример записи:

  IF(x is not null,f(UNWRAP(x)))
  

  В этом примере можно вызвать функцию f на оригинальном значении, так как в предикате IF уже проверено, что x не NULL.

• JUST
  — изменить тип данных на опциональный текущего, T преобразуется в T?.

  Пример записи:

  JUST(x)
  

• NOTHING
  — создать пустое значение с указанным типом.

  Пример записи:

  NOTHING(String?)
  

Опциональные типы данных — это один из видов контейнеров, которые могут быть произвольным образом вложены друг в друга или в другие контейнеры.

При поиске в словаре (Dict(k,v)) со значением типа Optional<T> результатом поиска будет Optional<Optional<T>>.

Пример запроса:

$dict = {"a":1, "b":null};
$found = $dict["b"];
select if($found is not null, unwrap($found), -1);

Результат:

# column0
0 null

Контейнеры

При необходимости контейнеры можно вкладывать друг в друга в произвольных комбинациях. Например, List<Tuple<Int32, Int32>> — список, содержащий в качестве элементов кортежи.

Опциональные значения в некоторых контекстах также могут рассматриваться как один из видов контейнеров (Optional<Type>), который ведёт себя как список длины 0 или 1.

Для представления множеств следует использовать словарь с значениями типа Void — Dict<T, Void>.

Для обращения к элементам контейнера используется точка или фигурные скобки
, в зависимости от его типа.

Специальные типы данных

Представление данных YDB в формате JSON

Bool

Логическое значение.

• Тип в JSON — bool.
• Пример значения YDB — true.
• Пример значения JSON — true.

Int8, Int16, Int32, Int64

Целочисленные знаковые типы.

• Тип в JSON — number.
• Пример значения YDB — 123456, -123456.
• Пример значения JSON — 123456, -123456.

Uint8, Uint16, Uint32, Uint64

Целочисленные беззнаковые типы.

• Тип в JSON — number.
• Пример значения YDB — 123456.
• Пример значения JSON — 123456.

Float

Вещественное 4-байтное число.

• Тип в JSON — number.
• Пример значения YDB — 0.12345679.
• Пример значения JSON — 0.12345679.

Double

Вещественное 8-байтное число.

• Тип в JSON — number.
• Пример значения YDB — 0.12345678901234568.
• Пример значения JSON — 0.12345678901234568.

Decimal

Число с фиксированной точностью. Поддерживается только Decimal(22, 9).

• Тип в JSON — string.
• Пример значения YDB — -320.789.
• Пример значения JSON — "-320.789".

String

Бинарные строки. Алгоритм кодирования в зависимости от значения байта:

• [0-31] — \u00XX (6 символов, обозначающих код символа юникода);
• [32-126] — as is. Это читаемые однобайтовые символы, не требующие эскейпинга;
• [127-255] — \u00XX.

При декодировании происходит обратный процесс. Коды символов в \u00XX более 255 не допускаются.

• Тип в JSON — string.
• Пример значения YDB — последовательность из 4 байт:
  • 5 0x05 - управляющий символ;
  • 10 0x0a - перенос строки \n;
  • 107 0x6b - символ k;
  • 255 0xff - символ юникода ÿ.
• Пример значения JSON — "\u0005\nk\u00FF".

Utf8, Json, Uuid

Строковые типы в utf-8. Такие строки представляются в JSON строками с escaping'ом JSON-символов: \\, \", \n, \r, \t, \f.

• Тип в JSON — string.

• Пример значения YDB — код на С++:

  "Escaped characters: "
  "\\ \" \f \b \t \r\n"
  "Non-escaped characters: "
  "/ ' < > & []() ".
  

• Пример значения JSON — "Escaped characters: \\ \" \f \b \t \r\nNon-escaped characters: / ' < > & []() ".

Date

Дата. Uint64, количество дней unix time.

• Тип в JSON — string.
• Пример значения YDB — 18367.
• Пример значения JSON — "2020-04-15".

Datetime

Дата и время. Uint64, количество секунд unix time.

• Тип в JSON — string.
• Пример значения YDB — 1586966302.
• Пример значения JSON — "2020-04-15T15:58:22Z".

Timestamp

Дата и время. Uint64, количество микросекунд unix time.

• Тип в JSON — string.
• Пример значения YDB — 1586966302504185.
• Пример значения JSON — "2020-04-15T15:58:22.504185Z".

Interval

Временной интервал. Int64, точность до микросекунд, допустимы значения интервалов - не более 24 часов.

• Тип в JSON — number.
• Пример значения YDB — 123456, -123456.
• Пример значения JSON — 123456, -123456.

Optional

Означает, что значение может быть null. Если значение null, то в JSON также будет null. Если значение не null, то в JSON значение запишется так же, как если бы тип был не Optional.

• Тип в JSON — отсутствует.
• Пример значения YDB — null.
• Пример значения JSON — null.

List

Список. Упорядоченный набор значений заданного типа.

• Тип в JSON — array.
• Пример значения YDB:
  • тип — List<Int32>;
  • значение — 1, 10, 100.
• Пример значения JSON — [1,10,100].

Stream

Поток. Однопроходной итератор по значениям одного типа.

• Тип в JSON — array.
• Пример значения YDB:
  • тип — Stream<Int32>;
  • значение — 1, 10, 100.
• Пример значения JSON — [1,10,100].

Struct

Структура. Неупорядоченный набор значений с заданными именами и типом.

• Тип в JSON — object.
• Пример значения YDB:
  • тип — Struct<'Id':Uint32,'Name':String,'Value':Int32,'Description':Utf8?>;
  • значение — "Id":1,"Name":"Anna","Value":-100,"Description":null.
• Пример значения JSON — {"Id":1,"Name":"Anna","Value":-100,"Description":null}.

Tuple

Кортеж. Упорядоченный набор значений заданных типов.

• Тип в JSON — array.
• Пример значения YDB:
  • тип — Tuple<Int32??,Int64???,String??,Utf8???>;
  • значение — 10,-1,null,"Some string".
• Пример значения JSON — [10,-1,null,"Some string"].

Dict

Словарь. Неупорядоченный набор пар ключ-значение. И для ключа, и для значения задан тип. В json записывается в массив массивов, состоящих из двух элементов.

• Тип в JSON — array.
• Пример значения YDB:
  • тип — Dict<Int64,String>;
  • значение — 1:"Value1",2:"Value2".
• Пример значения JSON — [[1,"Value1"],[2,"Value2"]].