JSONata, query and transform

RESTED_DEV integrates in its READ endpoints JSONata, a library that allows you to query, filter, sort and transform your data! (and more!)

To check the oficial documentation please visit their website, https://docs.jsonata.org/overview.html.

On this page you will find a quick starting guide to use JSONata expressions for the most common usages.

JSONata version: 1.8.4

Usage

let jsonataExp = `$[createdAt="2021-01-03T21:58:31.000Z"]`;
jsonataExp = encodeURI(jsonataExp);

fetch('https://app.rested.dev/api/1/ce/examples/unsecure-endpoint' +
'?key=d59eb2859c284168ac48aef65046d5dd' +
'&jsonata=' + jsonataExp);

The JSONata expression is sent in the URL using the parameter jsonata, we recommend to encode the expression to ensure that special characters are sent properly in the request.

Please remember:

• Only READ endpoints accept JSONata expressions.
• The expression is evaluated using the result of the read operation. You need to take into account when using other parameters like dataOnly or uniqueId.

Common Expressions

JSONata helps us solve the most common cases when it comes to extracting data from JSON. Here you can find some basic expressions.

We will use the following JSON to test our expressions.

[
  {
    "uniqueId": "9157c740159e4ff18b4a42d4a0c39622",
    "data": {
      "name": "Eduardo",
      "phone": 999888727,
      "age": 30
    },
    "createdAt": "2021-02-03T21:54:37.000Z",
    "updatedAt": "2021-02-03T21:54:37.000Z"
  },
  {
    "uniqueId": "66a1212c55ce47f9bc055e6c331b7af3",
    "data": {
      "name": "Miguel",
      "age": 17,
      "phone": 999888777
    },
    "createdAt": "2021-02-03T21:56:54.000Z",
    "updatedAt": "2021-02-03T21:56:54.000Z"
  },
  {
    "uniqueId": "86011b52ebc640aeba53a6e09a9d9773",
    "data": {
      "name": "Marco",
      "age": 18
    },
    "createdAt": "2021-02-04T21:57:59.000Z",
    "updatedAt": "2021-02-04T21:57:59.000Z"
  },
  {
    "uniqueId": "0f6586aa7ccf4901a3f066eeeea69116",
    "data": {
      "name": "Sergio",
      "age": 28,
      "jobDetails": {
        "company": "RESTED_DEV"
      }
    },
    "createdAt": "2021-02-07T22:02:50.000Z",
    "updatedAt": "2021-02-07T22:02:50.000Z"
  }
]

You can try out these expressions at https://try.jsonata.org.

Simple queries

data.name

Gets an array of names.

Result

[
  "Eduardo",
  "Miguel",
  "Marco",
  "Sergio"
]

---

$[1]

Gets the second element.

Result

{
  "uniqueId": "66a1212c55ce47f9bc055e6c331b7af3",
  "data": {
    "name": "Miguel",
    "age": 17,
    "phone": 999888777
  },
  "createdAt": "2021-02-03T21:56:54.000Z",
  "updatedAt": "2021-02-03T21:56:54.000Z"
}

---

$[0]data.name

Gets the name of the first element.

Result

"Eduardo"

Filtering

$[data.name="Eduardo"]

Filters records in the array containing the path data.name and matching Eduardo.

Result

{
  "uniqueId": "9157c740159e4ff18b4a42d4a0c39622",
  "data": {
    "name": "Eduardo",
    "phone": 999888727,
    "age": 30
  },
  "createdAt": "2021-02-03T21:54:37.000Z",
  "updatedAt": "2021-02-03T21:54:37.000Z"
}

---

$[data.jobDetails]

Filters records in the array containing the path data.jobDetails.

Result

{
  "uniqueId": "0f6586aa7ccf4901a3f066eeeea69116",
  "data": {
    "name": "Sergio",
    "age": 28,
    "jobDetails": {
      "company": "RESTED_DEV"
    }
  },
  "createdAt": "2021-02-07T22:02:50.000Z",
  "updatedAt": "2021-02-07T22:02:50.000Z"
}

---

$[data.age > 16 and data.age < 20]

Filters records in the array with data.age between 16 and 20.

Result

[
  {
    "uniqueId": "66a1212c55ce47f9bc055e6c331b7af3",
    "data": {
      "name": "Miguel",
      "age": 17,
      "phone": 999888777
    },
    "createdAt": "2021-02-03T21:56:54.000Z",
    "updatedAt": "2021-02-03T21:56:54.000Z"
  },
  {
    "uniqueId": "86011b52ebc640aeba53a6e09a9d9773",
    "data": {
      "name": "Marco",
      "age": 18
    },
    "createdAt": "2021-02-04T21:57:59.000Z",
    "updatedAt": "2021-02-04T21:57:59.000Z"
  }
]

Pagination

$[[0..1]]

Gets the first 2 elements.

Result

[
  {
    "uniqueId": "9157c740159e4ff18b4a42d4a0c39622",
    "data": {
      "name": "Eduardo",
      "phone": 999888727,
      "age": 30
    },
    "createdAt": "2021-02-03T21:54:37.000Z",
    "updatedAt": "2021-02-03T21:54:37.000Z"
  },
  {
    "uniqueId": "66a1212c55ce47f9bc055e6c331b7af3",
    "data": {
      "name": "Miguel",
      "age": 17,
      "phone": 999888777
    },
    "createdAt": "2021-02-03T21:56:54.000Z",
    "updatedAt": "2021-02-03T21:56:54.000Z"
  }
]

---

$[[2..4]]

Gets the second 2 elements.

Result

[
  {
    "uniqueId": "86011b52ebc640aeba53a6e09a9d9773",
    "data": {
      "name": "Marco",
      "age": 18
    },
    "createdAt": "2021-02-04T21:57:59.000Z",
    "updatedAt": "2021-02-04T21:57:59.000Z"
  },
  {
    "uniqueId": "0f6586aa7ccf4901a3f066eeeea69116",
    "data": {
      "name": "Sergio",
      "age": 28,
      "jobDetails": {
        "company": "RESTED_DEV"
      }
    },
    "createdAt": "2021-02-07T22:02:50.000Z",
    "updatedAt": "2021-02-07T22:02:50.000Z"
  }
]

Sorting

$[] ~> $sort(function($a,$b){ $a.data.age > $b.data.age })

Sorts the results by ascending age. In this expression we use the $sort function to sort the results.

Result

[
  {
    "uniqueId": "66a1212c55ce47f9bc055e6c331b7af3",
    "data": {
      "name": "Miguel",
      "age": 17,
      "phone": 999888777
    },
    "createdAt": "2021-02-03T21:56:54.000Z",
    "updatedAt": "2021-02-03T21:56:54.000Z"
  },
  {
    "uniqueId": "86011b52ebc640aeba53a6e09a9d9773",
    "data": {
      "name": "Marco",
      "age": 18
    },
    "createdAt": "2021-02-04T21:57:59.000Z",
    "updatedAt": "2021-02-04T21:57:59.000Z"
  },
  {
    "uniqueId": "0f6586aa7ccf4901a3f066eeeea69116",
    "data": {
      "name": "Sergio",
      "age": 28,
      "jobDetails": {
        "company": "RESTED_DEV"
      }
    },
    "createdAt": "2021-02-07T22:02:50.000Z",
    "updatedAt": "2021-02-07T22:02:50.000Z"
  },
  {
    "uniqueId": "9157c740159e4ff18b4a42d4a0c39622",
    "data": {
      "name": "Eduardo",
      "phone": 999888727,
      "age": 30
    },
    "createdAt": "2021-02-03T21:54:37.000Z",
    "updatedAt": "2021-02-03T21:54:37.000Z"
  }
]

Working with dates

Combining $filter and $toMillis

$[] ~> $filter(function($value){
    $toMillis($value.createdAt)>$toMillis("2021-02-07T22:00:00.000Z")
})

$toMillis converts a ISO 8601 date to milliseconds. In this example we filter all the elements created after 2021-02-07 22:00:00.

Result

{
  "uniqueId": "0f6586aa7ccf4901a3f066eeeea69116",
  "data": {
    "name": "Sergio",
    "age": 28,
    "jobDetails": {
      "company": "RESTED_DEV"
    }
  },
  "createdAt": "2021-02-07T22:02:50.000Z",
  "updatedAt": "2021-02-07T22:02:50.000Z"
}