# Справка и примеры JMESPath

В этом документе содержатся описания новых функций JMESPath, которые не вошли в основную спецификацию этого языка, и некоторые примеры типичного использования этих запросов. Полную справку можно найти в Интернете на сайте https://jmespath.org/.

## Перечень новых функций

- to_lower
- to_upper
- or, or2, or3, or4, or5, or_a
- and, and2, and3, and4, and5, and_a
- plus, plus2, plus3, plus4, plus5, plus_a
- minus, minus2, minus3, minus4, minus5, minus_a
- multiple, multiple2, multiple3, multiple4, multiple5, multiple_a
- divide, divide2, divide3, divide4, divide5, divide_a
- average, average2, average3, average4,average5, average_a
- module
- round
- round_s
- in_array
- unique
- json_parse
- to_string2
- format_date

## to_lower

Преобразует строку в нижний регистр.

Пример

Данные | Запрос | Ответ
--- | --- | ---
    { "text": "JMESPath is a query language for JSON." }
    to_lower(text)
    "jmespath is a query language for json."

## to_upper

Преобразует строку в верхний регистр.

Пример

Данные | Запрос | Ответ
--- | --- | ---
    { "text": "JMESPath is a query language for JSON." }
    to_upper(text)
    "JMESPATH IS A QUERY LANGUAGE FOR JSON."

## or, or2, or3, or4, or5, or_a

Логическое ИЛИ для двух, трёх, четырёх, пяти, массива аргументов. (or и or2 — синонимы)

Примеры

Данные | Запрос | Ответ
--- | --- | ---
    { "bool": [true, false, false, false, false] }
    or(bool[0], bool[1])
    true
    or2(bool[0], bool[1])
    true
    or3(bool[0], bool[1], bool[2])
    true
    or4(bool[0], bool[1], bool[2], bool[3])
    true
    or5(bool[0], bool[1], bool[2], bool[3], bool[4])
    true
    or_a(bool)
    true
    { "bool": [] }
    or_a(bool)
    true
    { "bool": [false, false, false, false, false] }
    or_a(bool)
    false

## and, and2, and3, and4, and5, and_a

Логическое И для двух, трёх, четырёх, пяти, массива аргументов. (and и and2 — синонимы)

Примеры

Данные | Запрос | Ответ
--- | --- | ---
    { "bool": [true, true, true, true, true] }
    and(bool[0], bool[1])
    true
    and2(bool[0], bool[1])
    true
    and3(bool[0], bool[1], bool[2])
    true
    and4(bool[0], bool[1], bool[2], bool[3])
    true
    and5(bool[0], bool[1], bool[2], bool[3], bool[4])
    true
    and_a(bool)
    true
    { "bool": [] }
    and_a(bool)
    true
    { "bool": [false, true, true, true, true] }
    and_a(bool)
    false

## plus, plus2, plus3, plus4, plus5, plus_a

Сложение двух, трёх, четырёх, пяти, массива аргументов. (plus и plus2 — синонимы)

Примеры

Данные | Запрос | Ответ
--- | --- | ---
    [1, 2, 3, 4, 5]
    plus([0], [1])
    3
    plus2([0], [1])
    3
    plus3([0], [1], [2])
    6
    plus4([0], [1], [2], [3])
    10
    plus5([0], [1], [2], [3], [4])
    15
    plus_a(@)
    15

## minus, minus2, minus3, minus4, minus5, minus_a

Вычитание двух, трёх, четырёх, пяти, массива аргументов. Из каждого предыдущего элемента вычитается следующий. (minus и minus2 — синонимы)

Примеры

Данные | Запрос | Ответ
--- | --- | ---
    [100, 2, 3, 4, 5]
    minus([0], [1])
    98
    minus2([0], [1])
    98
    minus3([0], [1], [2])
    95
    minus4([0], [1], [2], [3])
    91
    minus5([0], [1], [2], [3], [4])
    86
    minus_a(@)
    86

## multiple, multiple2, multiple3, multiple4, multiple5, multiple_a

Умножение двух, трёх, четырёх, пяти, массива аргументов. (Multiple и multiple2 — синонимы)

Примеры

Данные | Запрос | Ответ
--- | --- | ---
    [1, 2, 3, 4, 5]
    multiple([0], [1])
    2
    multiple2([0], [1])
    2
    multiple3([0], [1], [2])
    6
    multiple4([0], [1], [2], [3])
    24
    multiple5([0], [1], [2], [3], [4])
    120
    multiple_a(@)
    120

## divide, divide2, divide3, divide4, divide5, divide_a

Деление двух, трёх, четырёх, пяти, массива аргументов. Результат деления делится последовательно на каждый следующий элемент. (Divide и divide2 — синонимы)

Примеры

Данные | Запрос | Ответ
--- | --- | ---
    [120, 2, 3, 4, 5]
    divide([0], [1])
    60
    divide2([0], [1])
    60
    divide3([0], [1], [2])
    20
    divide4([0], [1], [2], [3])
    5
    divide5([0], [1], [2], [3], [4])
    1
    divide_a(@)
    1

## average, average2, average3, average4, average5, average_a

Среднее арифметическое двух, трёх, четырёх, пяти, массива аргументов. (Average и average2 — синонимы)

Примеры

Данные | Запрос | Ответ
--- | --- | ---
    [2, 4, 6, 8, 10]
    average([0], [1])
    3
    average2([0], [1])
    3
    average3([0], [1], [2])
    4
    average4([0], [1], [2], [3])
    5
    average5([0], [1], [2], [3], [4])
    6
    average_a(@)
    6

## module

Возвращает абсолютное значение числа.

Примеры

Данные | Запрос | Ответ
--- | --- | ---
    120.55555
    module(@)
    120.55555
    -120.55555
    module(@)
    120.55555

## round

Округляет число, переданное в первом аргументе, до указанного количества знаков после запятой, переданного во втором аргументе.

Примеры

Данные | Запрос | Ответ
--- | --- | ---
    120.55555
    round(@, `2`)
    120.56
    -120.55555
    round(@, `2`)
    -120.56

## round_s

Округляет число, переданное в первом аргументе, до указанного количества знаков после запятой, переданного во втором аргументе. Разделяет неразрывным пробелом тысячи, миллионы, миллиарды.

Примеры

Данные | Запрос | Ответ
--- | --- | ---
    1200.55555
    round_s(@, `2`)
    1 200.56
    -1200.55555
    round_s(@, `2`)
    -1 200.56

## in_array

Проверяет, содержится ли значение, переданное в первом аргументе, в массиве значений, переданных во втором.

Примеры

Данные | Запрос | Ответ
--- | --- | ---
    in_array(`1`, [`1`, `2`])
    true
    1
    in_array(@, [`1`, `2`])
    true
    [{"tag": 1}, {"tag": 2}, {"tag": 3}]
    [?in_array(tag, [`1`, `2`])]
    [{"tag": 1},{"tag": 2}]

## unique

Оставляет в массиве данных примитивного типа только уникальные значения.

Примеры

Данные | Запрос | Ответ
--- | --- | ---
    [1, 1, 2, 3, 4, 4]
    unique(@)
    [1, 2, 3, 4]

## json_parse

Преобразует строку в формате JSON в объект. С этим объектом можно выполнять дальнейшие манипуляции.

Примеры

Данные | Запрос | Ответ
--- | --- | ---
    "[1, 2, 3]"
    json_parse(@)
    [1, 2, 3]
    "[1, 2, 3]"
    json_parse(@)[?in_array(@, [`1`, `2`])]
    [1, 2]

## to_string2

Преобразует элемент в строку. В отличие от to_string, лучше обрабатывает различные типы данных JavaScript.

Примеры

Данные | Запрос | Ответ
--- | --- | ---
    null
    to_string2(@)
    ""
    0
    to_string2(@)
    "0"
    {"key1": [1, 2, 3]}
    to_string2(key2)
    ""
    {"key1": [1, 2, 3]}
    to_string2(key1)
    "[1,2,3]"

## format_date

Форматирует дату. В первом аргументе принимает дату в одном из ISO-форматов и приводит её к формату, переданному во втором аргументе. В третьем аргументе можно передать формат исходной даты, если это не ISO.

Примеры

Данные | Запрос | Ответ
--- | --- | ---
    "2024-02-03T12:34:56.000Z"
    format_date(@)
    "03.02.2024 15:34:56"
    format_date(@, 'HH:mm')
    "15:34"
    "2024-02-03"
    format_date(@, '', 'YYYY-MM-DD')
    "03.02.2024 00:00:00"
    "12:34:56"
    format_date(@, 'mm:ss.SSS', 'HH:mm:ss')
    "34:56.000"

Примеры кодирования даты и времени.

| Токен | Результат
--- | --- | ---
Месяц | M | 1 2 ... 11 12
| Mo | 1st 2nd ... 11th 12th
| MM | 01 02 ... 11 12
| MMM | янв. февр. ... ноя. дек.
| MMMM | январь февраль ... ноябрь декабрь
Квартал | Q | 1 2 3 4
| Qo | 1 2 3 4
День месяца | D | 1 2 ... 30 31
| Do | 1-го 2-го ... 30-го 31-го
| DD | 01 02 ... 30 31
День года | DDD | 1 2 ... 364 365
| DDDo | 1-й 2-й ... 364-й 365-й
| DDDD | 001 002 ... 364 365
День недели | d | 0 1 ... 5 6
| do | 0-й 1-й ... 5-й 6-й
| dd | вс пн ... пт сб
| ddd | вс пн ... пт сб
| dddd | понедельник ... пятница, суббота, воскресенье
День недели (локальный) | e | 0 1 ... 5 6
День недели (ISO) | E | 1 2 ... 6 7
Неделя года | w | 1 2 ... 52 53
| wo | 1-я 2-я ... 52-я 53-я
| ww | 01 02 ... 52 53
Неделя года (ISO) | W | 1 2 ... 52 53
| Wo | 1-я 2-я ... 52-я 53-я
| WW | 01 02 ... 52 53
Год | YY | 70 71 ... 29 30
| YYYY | 1970 1971 ... 2029 2030
| YYYYYY | -001970 -001971 ... +001907 +001971 Примечание: Расширенные годы (охватывают полный диапазон значений времени приблизительно на 273 790 лет вперед или назад с 1 января 1970 года)
| Y | 1970 1971 ... 9999 +10000 +10001 Примечание: Это соответствует стандарту ISO 8601 для дат после 9999 года
Эра Год | y | 1 2 ... 2020 ...
Эра | N, NN, NNN | BC AD Примечание: Сокращённое название эпохи
| NNNN | Before Christ, Anno Domini Примечание: Полное название эпохи
| NNNNN | BC AD Примечание: Короткое название эпохи
Неделя Год | gg | 70 71 ... 29 30
| gggg | 1970 1971 ... 2029 2030
Неделя Год (ISO) | GG | 70 71 ... 29 30
| GGGG | 1970 1971 ... 2029 2030
AM/PM | A | AM PM
| a | am pm
Час | H | 0 1 ... 22 23
| HH | 00 01 ... 22 23
| h | 1 2 ... 11 12
| hh | 01 02 ... 11 12
| k | 1 2 ... 23 24
| kk | 01 02 ... 23 24
Минута | m | 0 1 ... 58 59
| mm | 00 01 ... 58 59
Секунда | s | 0 1 ... 58 59
| ss | 00 01 ... 58 59
Доля секунды | S | 0 1 ... 8 9
| SS | 00 01 ... 98 99
| SSS | 000 001 ... 998 999
| SSSS ... SSSSSSSSS | 000[0..] 001[0..] ... 998[0..] 999[0..]
Часовой пояс | z or zz | EST CST ... MST PST
| Z | -07:00 -06:00 ... +06:00 +07:00
| ZZ | -0700 -0600 ... +0600 +0700
Unix Timestamp | X | 1360013296
Unix Millisecond Timestamp | x | 1360013296123