Перейти к основному содержимому
Версия: 2.0 (WIP)

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

Чтобы извлекать значения из 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]