Передача параметров и данных в формате JSON
YQL позволяет задавать параметры используя DECLARE выражение. Сами параметры передаются с помощью restricted JSON формата.
Ниже дано описание формата передачи различных типов данных.
Этот формат также используется для ответов из API.
Числовые типы
Bool
Логическое значение.
- Тип в JSON —
bool
. - Пример значения JSON —
true
.
Int, Uint, Float, Double, Decimal
- Тип в JSON —
string
. - Числа передаются в строковом представлении.
- Пример значения JSON —
"123456"
,"-42"
,"0.12345679"
,"-320.789"
.
Строковые типы
String
Бинарные строки.
- при наличии невалидных utf-8 символов, например,
\xFF
, строка кодируется в base64 и оборачивается в массив с одним элементом - если нет специальных символов, то передается как есть
- Тип в JSON -
string
илиarray
- Пример значения JSON -
"AB"
,["qw6="]
(для строки\xAB\xAC
)
Utf8
Строковые типы в utf-8. Такие строки представляются в JSON строками с escaping'ом JSON-символов: \\
, \"
, \n
, \r
, \t
, \f
.
- Тип в JSON —
string
. - Пример значения JSON —
"Escaped characters: \\ \" \f \b \t \r\nNon-escaped characters: / ' < > & []() "
.
Uuid
Универсальный идентификатор UUID.
- бинарный формат UUID кодируется с помощью base64 и оборачивается в лист
- Тип в JSON -
array
- Пример значения JSON -
["AIQOVZvi1EGnFkRmVUQAAA=="]
для550e8400-e29b-41d4-a716-446655440000
Yson
- Тип в JSON -
object
. - YSON более богатый язык, чем JSON, поэтому есть необходимость предоставлять дополнительные атрибуты, поэтому задаются поля
$value
,$type
,$attributes
. - Строки, числа и логические значения заменяются на объект с двумя ключами:
$value
и$type
. Типы могут быть:boolean
,int64
,uint64
,double
,string
. - Каждый байт бинарной строки переводится в юникодный символ с соответствующим номером и кодируется в UTF-8 (такой же механизм использует YT при преобразовании Yson в Json).
- Yson атрибуты добавляются в виде отдельного объекта c ключом
$attributes
и значениями атрибутов. - если какое имя начинается с
$
, то он экранируется с помощью удваивания$$
. - Пример YSON:
{ "$a" = 2;
b = {
c = <attr1=val1;attr2=5>12.5;
d = [ "el"; # ]
}
}
- Пример значения JSON:
{
"$$a" : { "$value": "2", "$type": "int64" },
"b" : {
"c": {
"$value" : "12.5",
"$type" : "double",
"$attributes" :
{
"attr1": { "$value": "b", "$type": "string" },
"attr2": { "$value": "5", "$type": "int64" }
}
},
"d": [ { "$value": "el", "$type": "string" }, null ]
}
}
Json
- Тип в JSON -
object
. - Пример значения JSON -
{ "a" : 12.5, "c" : 25 }
.
Дата и время
Date
Дата, внутреннее представление - Uint16, количество дней c unix epoch.
- Тип в JSON —
string
. - Пример значения JSON —
"19509"
для даты2023-06-01
.
Datetime
Дата и время, внутреннее представление - Uint32, количество секунд c unix epoch.
- Тип в JSON —
string
. - Пример значения JSON —
"1686966302"
для даты"2023-06-17T01:45:02Z"
.
Timestamp
Дата и время, внутреннее представление - Uint64, количество микросекунд c unix epoch.
- Тип в JSON —
string
. - Пример значения JSON —
"1685577600000000"
для2023-06-01T00:00:00.000000Z
.
Interval
Временной интервал, внутреннее представление - Int64, точность до микросекунд.
- Тип в JSON —
string
. - Пример значения JSON —
"12345678910"
.
TzDate, TzDateTime, TzTimestamp
Временные типы с меткой временной зоны.
- Тип в JSON -
string
. - Значение представляется как строковое представление времени и временная зона через запятую.
- Пример значения JSON -
"2023-06-29,Europe/Moscow"
,""2023-06-29T17:14:11,Europe/Moscow""
,""2023-06-29T17:15:36.645735,Europe/Moscow""
для TzDate, TzDateTime и TzTimestamp соответственно.
Контейнеры
В контейнерах все элементы кодируются согласно их типу.
List
Список. Упорядоченный набор значений заданного типа, значения передаются как строки.
- Тип в JSON —
array
. - Пример значения JSON для
List<Int32>
—["1","10","100"]
.
Struct
Структура. Неупорядоченный набор значений с заданными именами и типом.
- Тип в JSON —
object
илиarray
. - Может передоваться как объект или как массив, где порядок элементов должен совпадать с соответствующими полями структуры.
- Пример значения JSON
{"a": "-100", "b": "foo"}
,{"a": "-100", "b": "foo", "c": null}
или["-100", "foo", null]
дляStruct<a:Int32, b:String, c:Optional<String>>
.
Tuple
Кортеж. Упорядоченный набор значений заданных типов.
- Тип в JSON —
array
. - Пример значения JSON для типа Tuple<Int32, String, Float?> —
[-1,"Some string",null]
.
Dict
Словарь. Неупорядоченный набор пар ключ-значение.
- Тип в JSON —
object
илиarray
. - для ключей типа
String
иUtf8
можно передавать объект, для остальных типов надо передавать массив массивов, состоящих из двух элементов (ключа и значения). - Пример значения JSON —
[["1","123"],["2","456"]]
дляDict<Int32, Interval>
,{ "foo": "123", "bar": "456" }
дляDict<String, Int32>
.
Enum
Перечисление.
- Тип в JSON -
string
. - Пример значения JSON -
"b"
дляEnum<a,b>
.
Variant
Кортеж или структура, про которые известно, что заполнен ровно один элемент.
- Тип в JSON -
array
. - Первый способ передачи - массив из поля структуры, обернутый в массив, и значения. Способ подходит только для варианта над структурами.
- Второй способ передачи - массив из индекса поля структуры/кортежа и само значение.
- Пример значения JSON -
[["foo"], false]
,[["bar"], "6"]
или["0", false]
,["1", "6"]
дляVariant<foo: Int32, bar: Bool>
.
Специальные типы
Optional
Означает, что значение может быть null
.
- Тип в JSON —
array
илиnull
. - Значения обертываются в массив,
null
значение представляется пустым массивом илиnull
. - Пример значения JSON -
[["1"], ["2"], ["3"], []]
или[["1"], ["2"], ["3"], null]
дляList<Optional<Int32>>
.
Void
Сингулярный тип данных с единственным возможным значением null
.
- Тип в JSON -
string
. - Значение JSON -
"Void"
.