Простые запросы

Чтобы извлекать значения из JSON-структуры, JSONata определяет синтаксис пути расположения. Как и XPath, он выбирает все возможные значения документа, соответствующие указанному пути. Два структурных элемента JSON — объекты и массивы.

Навигация по объектам JSON

Объект JSON — это ассоциативный массив (также map или hash). Путь через JSON-объекты произвольной глубины состоит из имён полей, разделённых точками .. Выражение возвращает JSON-значение, на которое указывает последний шаг пути. Если на пути поле не найдено, выражение ничего не возвращает (в JavaScript это undefined). Отсутствующие во входном документе данные не вызывают ошибок.

В примерах этого руководства, если не оговорено иное, используется следующий JSON-документ:

{
  "FirstName": "Fred",
  "Surname": "Smith",
  "Age": 28,
  "Address": {
    "Street": "Hursley Park",
    "City": "Winchester",
    "Postcode": "SO21 2JN"
  },
  "Phone": [
    { "type": "home", "number": "0203 544 1234" },
    { "type": "office", "number": "01962 001234" },
    { "type": "office", "number": "01962 001235" },
    { "type": "mobile", "number": "077 7700 1234" }
  ],
  "Email": [
    { "type": "work", "address": ["fred.smith@my-work.com", "fsmith@my-work.com"] },
    { "type": "home", "address": ["freddy@my-social.com", "frederic.smith@very-serious.com"] }
  ],
  "Other": {
    "Over 18 ?": true,
    "Misc": null,
    "Alternative.Address": { "Street": "Brick Lane", "City": "London", "Postcode": "E1 6RF" }
  }
}

Примеры

Ниже приведены выражения и их результаты для этого документа.

• Возвращает строку JSON (в двойных кавычках).

  Surname => "Smith"

• Возвращает число JSON.

  Age => 28

• Ссылки на поля разделяются точкой ..

  Address.City => "Winchester"

• Путь найден и возвращает значение null.

  Other.Misc => null

• Путь не найден; ничего не возвращается (JavaScript undefined).

  Other.Nothing => (ничего не возвращается)

• Ссылку на поле с пробелами или зарезервированными токенами можно заключить в обратные кавычки.

  Other.`Over 18 ?` => true

Навигация по массивам JSON

Массивы JSON используют, когда нужна упорядоченная коллекция значений. Каждому значению соответствует индекс (позиция), а не имя, поэтому для обращения к отдельному значению нужен дополнительный синтаксис — квадратные скобки после имени поля массива. Если в скобках указано число либо выражение, дающее число, оно обозначает выбираемый индекс. Индексы начинаются с нуля: первый элемент arr — arr[0]. Нецелое число округляется вниз. Если выражение в скобках нечисловое или не вычисляется в число, оно трактуется как предикат.

Отрицательные индексы считаются от конца: arr[-1] выбирает последний элемент, arr[-2] — предпоследний и т. д. Если индекс превышает размер массива, ничего не выбирается.

Если индекс не задан (после ссылки на поле нет квадратных скобок), выбирается весь массив. Если массив содержит объекты и путь выбирает поля в этих объектах, выборка выполняется для каждого объекта массива.

Примеры

• Первый элемент (объект):

  Phone[0] => { "type": "home", "number": "0203 544 1234" }

• Второй элемент:

  Phone[1] => { "type": "office", "number": "01962 001234" }

• Последний элемент:

  Phone[-1] => { "type": "mobile", "number": "077 7700 1234" }

• Отрицательные индексы считаются от конца:

  Phone[-2] => { "type": "office", "number": "01962 001235" }

• Элемента нет — результат пустой:

  Phone[8] => (ничего не возвращается)

• Выбирает поле number первого элемента:

  Phone[0].number => "0203 544 1234"

• У Phone нет индекса, поэтому выбираются все элементы (весь массив), затем у каждого — поле number:

  Phone.number => [ "0203 544 1234", "01962 001234", "01962 001235", "077 7700 1234" ]

• Можно ожидать только первый номер, но возвращается первый номер каждого элемента, выбранного Phone:

  Phone.number[0] => [ "0203 544 1234", "01962 001234", "01962 001235", "077 7700 1234" ]

• Индекс применяется к массиву, который возвращает Phone.number; это одно из применений скобок:

  (Phone.number)[0] => "0203 544 1234"

• Возвращает диапазон элементов, создавая массив индексов:

  Phone[[0..1]] => [ { "type": "home", "number": "0203 544 1234" }, { "type": "office", "number": "01962 001234" } ]

Результирующие последовательности

Разворачивание последовательностей

Пустые и одноэлементные последовательности

Массивы верхнего уровня, вложенные массивы и разворачивание

Рассмотрим JSON-документ:

[
  { "ref": [1, 2] },
  { "ref": [3, 4] }
]

На верхнем уровне здесь массив, а не объект. Чтобы выбрать его первый объект, не к чему присоединить [0] как имя поля. Самостоятельное [0] тоже нельзя использовать: оно конфликтует с синтаксисом конструктора массива. Вместо этого используйте ссылку на контекст $, обозначающую начало документа.

• $ в начале выражения обозначает весь входной документ:

  $[0] => { "ref": [1, 2] }

• Здесь .ref возвращает весь внутренний массив:

  $[0].ref => [1, 2]

• Возвращает элемент в первой позиции внутреннего массива:

  $[0].ref[0] => 1

• Несмотря на вложенную структуру, результат разворачивается в один плоский массив; исходная вложенная структура теряется. О том, как сохранить её в результате, см. конструкторы массивов:

  $.ref => [1, 2, 3, 4]