Skip to content

description: Embrace JMESPath, a gateway to seamless data transformation and extraction

The JSON Query Language

JMESPath is a powerful query language designed specifically for JSON data. It allows you to transform and extract information from JSON documents in a concise and flexible manner. In this chapter, we'll explore key features of JMESPath, covering array searches, the contains function, the join function, and array flattening.

Alumio supports many JMESPath functions, allowing you to easily query and transform JSON data. For example, you can use JMESPath to extract specific fields from API responses, filter data, and transform JSON documents.

Alumio supports:

  • Using the [] syntax to search within arrays
  • Using the | operator to 'project' the results of a query.
  • Using the || operator (OR) to handle cases where a field may be missing.

To use JMESPath in Alumio, either use &{} (your query goes between the {}) or use ?{}. The ? operator is useful when the field might be missng, and you want to return null if it is (instead of an error).

Alumio does NOT support:

  • Projecting to objects in JMESPath using the . operator. For example array[].{ Name: name }

For more info, see: https://jmespath.org/specification.html)

Searching Within Arrays

{
  "students": [
    {
      "name": "John Doe",
      "grades": [85, 92, 78],
      "isStudent": true
    },
    {
      "name": "Alice Smith",
      "grades": [92, 88, 95],
      "isStudent": true
    },
    {
      "name": "Bob Johnson",
      "grades": [78, 85, 80],
      "isStudent": false
    }
  ]
}

JMESPath provides a convenient syntax for searching within arrays. To extract all names from an array of objects, you can use the [] syntax:

students[].name

This query retrieves an array of all names from the "students" array.

To search within the array for only those names of those who are students (isStudent == true), you can use the following query:

students[?isStudent == `true`].name

You can use several operators, such as >, <, >=, <=, ==, !=, contains, starts_with, and ends_with.

Using the Contains Function

The contains function in JMESPath allows you to check if an array contains a specific value. For example, to check if the "grades" array contains the value 90:

students[?grades.contains(@, `90`)]

This query returns the entire student object where the "grades" array contains the value 90.

Using the Join Function

JMESPath's join function is handy for combining the values of an array into a single string. Let's say you want to join the names of all students with a comma:

join(',',students[].name)

This query produces a string with all student names joined by commas.

Flattening & merging Arrays

JMESPath supports flattening arrays, which can be useful when dealing with nested structures.

students[].grades[]

This query flattens the two nested arrays into one single array of all grades.

Conditional Operators

JMESPath supports conditional operators. The || operator acts as an OR operator, allowing you to handle cases where the query might return an error, null, an empty string, or false. For example:

students[].certifications || `false`

This query will return false, because the there is no certifications node.

You can return using this method:

  • Strings, or an empty string, by utilizing single quotes: || '' or || 'default'
  • Integers, or 0, by utilizing backticks: || `0`
  • Booleans, or false, by utilizing backticks: || `false`
  • Null, by utilizing backticks: || `null`
  • Arrays, by utilizing backticks: || `[]`

The | operator can be used for projection. For instance, to pick the first item from an array:

students[*].grades | [0]

This query selects the first grade from each student's "grades" array.

Real-world Applications

JMESPath's expressive syntax makes it a valuable tool for working with JSON data in various scenarios. Whether you're querying API responses, filtering data, or transforming JSON structures, JMESPath provides a concise and effective way to interact with your JSON documents.