Что представляет собой JSONPath?

В данном разделе рассмотрим, как работает JSONPath на этапе предварительной обработки значений элементов. JSONPath состоит из частей, разделённых точками. Эти части могут быть простыми словами, которые представляют имена значений в формате JSON, подстановочными знаками (*), или более сложными конструкциями, заключёнными в квадратные скобки. Перед такой конструкцией, заключённой в квадратные скобки, может стоять точка, но это необязательно.

Пример JSONPath	Описание
$.object.name	Возвращает object.name содержимое.
$.object['name']	Возвращает object.name содержимое.
$.object.['name']	Возвращает object.name содержимое.
$["object"]['name']	Возвращает object.name содержимое.
$.['object'].["name"]	Возвращает object.name содержимое.
$.object.history.length()	Возвращает количество object.history элементов массива.
$[?(@.name == 'Object')].price.first()	Возвращает значение price свойства из первого объекта с именем "Object".
$[?(@.name == 'Object')].history.first().length()	Возвращает количество элементов массива истории из первого объекта с именем "Object".
$[?(@.price > 10)].length()	Возвращает количество объектов с ценой больше 10.

Используемые сегменты

Сегмент	Описание
< name>	Сопоставьте свойство объекта по имени.
*	Соответствует всем свойствам объекта.
['']	Сопоставьте свойство объекта по имени.
['', '', ...]	Сопоставьте свойство объекта с любым из перечисленных имен.
[]	Сопоставьте элемент массива по индексу.
[, , ...]	Сопоставьте элемент массива по любому из перечисленных индексов.
[*]	Соответствует всем свойствам объекта или элементам массива.
[:]	Сопоставлять элементы массива по определенному диапазону: ▶ < start> - первый соответствующий индекс (включая); если не указан, соответствует всем элементам массива с начала; если отрицательный, указывает начальное смещение от конца массива; ▶ < end> - последний соответствующий индекс (исключая); если не указан, соответствует всем элементам массива до конца; если отрицательный, указывает начальное смещение от конца массива.
[?()]	Сопоставляйте объекты / элементы массива, применяя выражение фильтра.

Чтобы найти нужный сегмент, игнорируя его происхождение (то есть отдельный сегмент), перед ним нужно поставить две точки (…). Например, $…name или $…[‘name’] вернёт значения всех свойств name.

Можно извлечь совпадающие имена элементов, добавив суффикс в виде тильды (~) к JSONPath. Он вернёт имя совпадающего объекта или индекс в строковом формате соответствующего элемента массива.

Формат вывода соответствует тем же правилам, что и в других запросах JSONPath:

Результаты определённого пути возвращаются «как есть»;
Результаты неопределённого пути возвращаются в виде массива.

Однако извлечение имени элемента, соответствующего определённому пути, имеет минимальное значение.

Выражение фильтрации

Выражение фильтра — это арифметическое выражение, записанное в инфиксной форме.

Поддерживаемые выражения:

Выражение	Описание
"< text>", '< text>'	Текстовая константа.
< number>	Числовая константа, поддерживающая научную нотацию.
< jsonpath starting with $>	Значение, на которое ссылается JSONPath из корневого узла входного документа; поддерживаются только определенные пути.
< jsonpath starting with @>	Значение, на которое ссылается JSONPath из текущего объекта / элемента; поддерживаются только определенные пути.

Поддерживаемые операторы:

Оператор	Тип	Описание	Результат
-	Двоичный файл	Вычитание	Количество
+	Двоичный файл	Добавление	Количество
/	Двоичный файл	Разделение	Количество
*	Двоичный файл	Умножение	Количество
==	Двоичный файл	Равенство	Логическое значение (1/0)
!=	Двоичный файл	Неравенство	Логическое значение (1/0)
<	Двоичный файл	Меньше, чем	Логическое значение (1/0)
<=	Двоичный файл	Меньше или равно	Логическое значение (1/0)
>	Двоичный файл	Больше, чем	Логическое значение (1/0)
>=	Двоичный файл	Больше или равно	Логическое значение (1/0)
=~	Двоичный файл	Соответствует регулярному выражению	Логическое значение (1/0)
!	Унарный	Логическое ЗНАЧЕНИЕ NOT	Логическое значение (1/0)
\|\|	Двоичный файл	Логическое значение ИЛИ	Логическое значение (1/0)
&&	Двоичный файл	Логическое значение И	Логическое значение (1/0)

Функции

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

Поддерживаемые функции:

Функция	Описание	Ввод	Вывод
avg	Среднее значение чисел во входном массиве	Массив чисел	Количество
min	Минимальное значение чисел во входном массиве	Массив чисел	Количество
max	Максимальное значение чисел во входном массиве	Массив чисел	Количество
sum	Сумма чисел во входном массиве	Массив чисел	Количество
length	Количество элементов во входном массиве	Массив	Количество
first	Первый элемент массива	Массив	Конструкция JSON в зависимости от содержимого входного массива

Агрегатные функции в JSONPath работают с числовыми значениями, которые заключены в кавычки. При необходимости агрегации эти значения автоматически преобразуются из строк в числа. Если входные данные несовместимы, функция выдаст ошибку.

Результат

В JSONPath есть два типа путей: определённые и неопределённые.

Определённый путь может вернуть либо null, либо единственный результат совпадения. Неопределённый путь может вернуть несколько результатов совпадений: JSONPaths с разделёнными, несколькими списками имён/индексов, фрагментами массива или сегментами выражения.

Если в JSONPath используется функция, путь становится определённым, так как функции всегда возвращают одно значение.

Определённый путь возвращает объект, массив или значение, на которое он указывает. В отличие от него, неопределённый путь возвращает массив соответствующих объектов, массивов или значений.

Форматирование

В сегментах, обозначенных скобками, и в выражениях можно использовать пробелы (пробел, символ табуляции). Например:

$[ 'a' ][ 0 ][ ?( $.b == 'c' ) ][ : -1 ].first()

Строки необходимо заключать в одинарные (') или двойные (") кавычки. Если внутри строки используются такие же кавычки, как и для её заключения, их нужно экранировать с помощью символа обратной косой черты (). То же самое касается и обратной косой черты (), которая также должна экранироваться символом обратной косой черты ().

Пример кода

{
  "books": [
    {
      "title": "The Hobbit",
      "author": "J. R. R. Tolkien",
      "genre": "fantasy",
      "published": "1937",
      "pages": 304,
      "rating": 4.5
    },
    {
      "title": "The Lord of the Rings",
      "author": "J. R. R. Tolkien",
      "genre": "fantasy",
      "published": "1954-1955",
      "pages": 1200,
      "rating": 4.8
    },
    {
      "title": "The Fellowship of the Ring",
      "author": "J. R. R. Tolkien",
      "genre": "fantasy",
      "published": "1954",
      "pages": 432,
      "rating": 4.7
    },
    {
      "title": "The Two Towers",
      "author": "J. R. R. Tolkien",
      "genre": "fantasy",
      "published": "1954",
      "pages": 400,
      "rating": 4.6
    },
    {
      "title": "The Return of the King",
      "author": "J. R. R. Tolkien",
      "genre": "fantasy",
      "published": "1955",
      "pages": 464,
      "rating": 4.9
    }
  ],
  "authors": [
    {
      "name": "J. R. R. Tolkien",
      "nationality": "British",
      "birthdate": "1892-01-03",
      "deathdate": "1973-09-02"
    }
  ],
  "genres": [
    "fantasy"
  ],
  "ratings": [
    4.5,
    4.8,
    4.7,
    4.6,
    4.9
  ]
}