Skip to content

Query JSON with JMESPath#

JMESPath is a query language for JSON, that allows elements within a JSON document to be extracted and transformed.

jmespath() is a custom method that allows searches on JSON objects using the JMESPath query language.

Before you begin#

Syntax#

Javascript method:

1
$jmespath(object, searchString)

Python method:

1
_jmespath(object, searchString)

Example#

To help understand what the method does, here is the equivalent longer JavaScript:

1
2
var jmespath = require('jmespath');
jmespath.search(object, searchString);

Note

Expressions must be single-line

Arguments#

Argument Description
object A JSON object, such as the output of a previous node.
searchString An expression written in the JMESPath query language.

Additional information#

Search parameter order#

Ensemble supports the JMESPath JavaScript library which puts search parameters in order search(object, searchString) which differs to those explained on official JMESPath pages: * JMESPath Tutorial * JMESPath Examples

Examples#

Note

The code node Mode must be set to Run once for each item to test these examples.

JMESPath projections#

JMESPath supports five kinds of projections:

Example JSON from a webhook node#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
[
  {
    "headers": {
      "host": "Ensemble.instance.address",
      ...
    },
    "params": {},
    "query": {},
    "body": {
      "people": [
        {
          "first": "James",
          "last": "Green"
        },
        {
          "first": "Jacob",
          "last": "Jones"
        },
        {
          "first": "Jayden",
          "last": "Smith"
        }
      ],
      "dogs": {
        "Fido": {
          "color": "brown",
          "age": 7
        },
        "Spot": {
          "color": "black and white",
          "age": 5
        }
      }
    }
  }
]

JMESPath projection#

Retrieve a list of first names from the JSON

The following JavaScript expressions return the following names: * James * Jacob * Jayden

JavaScript

1
  {{$jmespath($json.body.people, "[*].first" )}}

JavaScript for Code node:

1
2
  let firstNames = $jmespath($json.body.people, "[*].first" )
  return {firstNames};

Python for Code node:

1
2
firstNames = _jmespath(_json.body.people, "[*].first" )
return {"firstNames":firstNames}

Slice projections#

The following projections return the following names: * James * Jacob * Jadyen

1
  {{$jmespath($json.body.people, "[:2].first")}}

JavaScript for code node:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
  let firstTwoNames = $jmespath($json.body.people, "[:2].first");
  return {firstTwoNames};
	/* Returns:
	[
		{
			"firstNames": [
				"James",
				"Jacob",
				"Jayden"
			]
		}
	]
	*/

Python code to return two first names: * James * Jacob

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
firstTwoNames = _jmespath(_json.body.people, "[:2].first" )
return {"firstTwoNames":firstTwoNames}
"""
	Returns:
	[
  		{
			"firstTwoNames": [
			"James",
			"Jacob"
			]
		}
	]
"""

Object projections#

Return a list of dog ages: * 7 * 5

JavaScript expression

1
  {{$jmespath($json.body.dogs, "*.age")}}

Javascript for the Code node

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
let dogsAges = $jmespath($json.body.dogs, "*.age");
return {dogsAges};
/* Returns:
	[
		{
			"dogsAges": [
				7,
				5
			]
		}
	]
*/

Python for the Code node

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
  dogsAges = _jmespath(_json.body.dogs, "*.age")
  return {"dogsAges": dogsAges}
"""
	Returns:
	[
		{
			"dogsAges": [
				7,
				5
			]
		}
	]
	"""

Multiselect elements#

Use multiselect list to get the first and last names and create new lists containing both names: * ["James","Green"] * ["Jacob","Jones"] * ["Jayden","Smith"]

JavaScript expression

[[% raw %]] 

1
  {{$jmespath($json.body.people, "[].[first, last]")}}
[[% endraw %]]

JavaScript for the Code node

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
  let newList = $jmespath($json.body.people, "[].[first, last]");
  return {newList};
/* Returns:
	[
		{
			"newList": [
				[
					"James",
					"Green"
				],
				[
					"Jacob",
					"Jones"
				],
				[
					"Jayden",
					"Smith"
				]
			]
		}
	]
*/

Python for the Code node

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
  newList = _jmespath(_json.body.people, "[].[first, last]")
  return {"newList":newList}
"""
	Returns:
	[
		{
			"newList": [
				[
					"James",
					"Green"
				],
				[
					"Jacob",
					"Jones"
				],
				[
					"Jayden",
					"Smith"
				]
			]
		}
	]
"""

An alternative to arrow functions in expressions#

For example, generate some input data by returning the below code from the Code node:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
return[
  {
    "json": {      
      "num_categories": "0",
      "num_products": "45",
      "category_id": 5529735,
      "parent_id": 1407340,
      "pos_enabled": 1,
      "pos_favorite": 0,
      "name": "HP",
      "description": "",
      "image": ""
    }
  },
  {
    "json": {
      "num_categories": "0",
      "num_products": "86",
      "category_id": 5529740,
      "parent_id": 1407340,
      "pos_enabled": 1,
      "pos_favorite": 0,
      "name": "Lenovo",
      "description": "",
      "image": ""
    }
  }  
]

You could do a search like "find the item with the name Lenovo and tell me their category ID."

1
{{ $jmespath($("Code").all(), "[?json.name=='Lenovo'].json.category_id") }}