JSONata is a JSON query and transformation language. JSONata can do a lot, which can make it intimidating to start with. This guide aims to make JSONata easier to use by providing concrete examples of the language in action.
This guide’s examples all take the same input JSON (shown below), and use JSONata to query or transform that input in interesting ways.
All screenshots in this guide come from JSONata Exerciser—a handy site for testing JSONata in your web browser. To use the JSONata Exerciser you must place your input JSON in the left pane and your JSONata in the top-right pane. The Exerciser automatically applies the JSONata to the input JSON, and displays the result in the bottom-right pane.
1) Grab one piece of data
Let’s start simple. Sometimes all you want to do is grab one piece of data out of a JSON object. With JSONata you can do that by referencing the appropriate property name.
device
You can use the . operator to access nested properties.
body.temp
2) Create a smaller JSON object
JSONata allows you to take a large JSON input, and output a separate JSON object that only contains the properties you need. For example, the following JSONata returns a JSON object that only contains the device property (and its value).
{
"device": device
}
3) Add new fields
Building on the previous example, sometimes you want to create your own JSON structure that includes a mix of data from your input JSON, and completely new properties. The following JSONata outputs a device property from the input JSON, and a newly created property and value.
{
"device": device,
"a_new_property": "a value"
}
4) Create a new JSON structure altogether
You can use JSONata to create a JSON object that uses a completely different structure than your input JSON. This can be useful if, for instance, you need send JSON to a system that expects JSON data in a completely different format.
The JSONata below creates a JSON object with a new data property that includes two properties from the input JSON.
{
"data": {
"device": device,
"when": when
}
}
5) Using built-in functions
JSONata has several built-in functions that can help you parse data. The example below uses JSONata’s $split function to break "tower_id": "310,410,25878,88213007" into four properties in a new JSON object.
There are dozens of other built-in functions you might want to experiment with, including $trim() and $substring() for working with strings, or $round(), $floor(), and $ceil() for working with numbers.
You might also find $fromMillis() useful, as it allows you to convert a millisecond-based time to a formatted string representation.
{
"time": $fromMillis(when * 1000)
}
You can control the format of the $fromMillis() output with its optional picture argument. See the $fromMillis() documentation for more information.
7) Adding conditional logic
JSONata allows you to perform conditional checks using the ternary operator. For example, the JSONata below selects either tri_location or tower_location depending on the value of best_location_type.
Functions have a few additional rules to follow, such as needing to introduce a scope using parenthesis. This is a bit easier to understand with an example, so check out the code below, which defines a custom $localizeTemperature function, and uses it to convert temperature values to Fahrenheit or Celsius depending on the country.
JSONata provides an order-by operator that allows you to sort an array of JSON data. For example, the code below sorts the settings array by its name property.
{
"settings": settings^(name)
}
The filter operator allows you to select items in an array that match a provided condition. For example, the code below selects all objects in settings that have a name of "power_saving".
{
"settings": settings[name = 'power_saving']
}
10) Blues extensions to JSONata
In case all of these examples weren’t enough, JSONata also includes a series of extension APIs. Here at Blues we use JSONata a lot, as we find it a handy way to manipulate JSON before routing data to cloud services, so we’ve extended the language with a few new features.
For instance, we allow our users to refer to environment variables using the $ operator. As an example, the JSONata code below uses $interval to read an environment variable named interval.
{
"interval": $interval
}
We also offer a custom function named $doNotRoute() that allows you to conditionally route your data to a service. For example, the code below only routes data if a location exists.
Do you have an ambitious roadmap with plans to scale to 1,000 devices and beyond? Then, the Enterprise plan is for you.
The Enterprise plan includes custom pricing, centralized billing, and direct data center connectivity, giving companies complete control over their projects.
Each Enterprise plan is tailor-made with custom per-device pricing that includes attractive discounts based on device count and event volume.
Who is Enterprise Designed For?
Companies that place a premium on end-to-end data security, from Notecard’s encrypted communications to Notehub’s private data routing to your cloud application.
Those with internal controls that require centralized billing and admin-managed permissions.
Drive cost savings and data accessibility with Notehub’s 90-day event history retention and seamless integration with Amazon’s S3 Archive service.
Analyze and Scale
Actionable Intelligence for Projects at Scale
Go from insight to action with Analyze & Scale’s advanced analytics capabilities.
Projects operating at scale generate troves of valuable data, but to make sense of it, you need powerful tools at your fingertips. That’s where Analyze & Scale comes in.
Who is Analyze & Scale Designed For?
Companies looking to visualize their deployment and device locations with pinpoint accuracy while leveraging event-driven alerts to reduce downtime and promptly address fleet developments.
Drive cost savings and data accessibility with Notehub’s 90-day event history retention and seamless integration with Amazon’s S3 Archive service.
Those looking to perform in-depth project and device analysis to drive innovation and product improvement.
Develop
For Scaling Projects Looking for Enhanced Automation & Control
Notehub’s Development plan is purpose-built to accelerate your project’s journey from pilot to scale.
It’s packed with features that will make it easier to efficiently grow your project from 10s of devices to 100s.
Who is Development Designed For?
Companies looking to visualize their deployment and device locations with pinpoint accuracy while leveraging event-driven alerts to reduce downtime and promptly address fleet developments.
Drive cost savings and data accessibility with Notehub’s 90-day event history retention and seamless integration with Amazon’s
S3 Archive service.
Essentials
Only Pay for What You Use
Through Essentials, our subscription-free tier, you pay only for the data you export from Notehub to your cloud application, making it perfect for developing PoCs, piloting projects or early-stage deployments.
While Essentials provides essential data routing from device to cloud, upgrading to Development unlocks a suite of premium features designed to optimize and accelerate your deployment.
Who is Essentials Designed For?
Projects that are looking to use Notehub exclusively as a device-to-cloud data pump, and do not want to use the advanced features to optimize their deployment.
Companies who are not currently focused on using Development’s features to optimize their deployment or gain deeper insight into their devices.
Projects that are prototyping or experimenting with Blues.
Companies that at the current stage of their business are comfortable with unpredictable monthly Notehub costs.
What are Consumption Credits?
Instead of paying a monthly subscription fee to use Notehub, users of Essentials are charged based on the amount of messages they export from Notehub to their cloud applications.
Users on the Essentials plan pay to export this data by pre-purchasing Consumption Credits. A Consumption Credit is a single event of either routing a data message from Notehub to the user application or reading a data message using Nothub API. As messages are routed/read, Consumption Credits are deducted, offering a flexible pricing model based on actual usage.
What Events Consume Consumption Credits?
Here’s a breakdown of the specific events and requests that consume Consumption Credits:
Service
CC Cost
Routed Event
1 CC
Event API Retrieval Request
1 CC
Other Notehub API Requests
.001 CC
Real-time Device Messaging*
1 CC
Notecard web request*
1 CC
What is the Pricing for Consumption Credits?
Companies on the Essentials plan will receive a monthly allocation of up to 5,000CCs for free. Beyond this 5,000CC top-up, Consumption Credits can be purchased on a sliding scale based on volume: