> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/build/work-with-data/handle-special-data-types/query-json-data.md). # Query JSON data [JMESPath](https://jmespath.org/) is a query language for JSON that you can use to extract and transform elements from a JSON document. For full details of how to use JMESPath, refer to the [JMESPath documentation](https://jmespath.org/tutorial.html). ## The `jmespath()` method n8n provides a custom method, `jmespath()`. Use this method to perform a search on a JSON object using the JMESPath query language. The basic syntax is: {% tabs %} {% tab title="JavaScript" %} ```js $jmespath(object, searchString) ``` {% endtab %} {% tab title="Python" %} ```python _jmespath(object, searchString) ``` {% endtab %} {% endtabs %} To help understand what the method does, here is the equivalent longer JavaScript: ```js var jmespath = require('jmespath'); jmespath.search(object, searchString); ``` {% hint style="info" %} **Expressions must be single-line** The longer code example doesn't work in Expressions, as they must be single-line. {% endhint %} `object` is a JSON object, such as the output of a previous node. `searchString` is an expression written in the JMESPath query language. The [JMESPath Specification](https://jmespath.org/specification.html#jmespath-specification) provides a list of supported expressions, while their [Tutorial](https://jmespath.org/tutorial.html) and [Examples](https://jmespath.org/examples.html) provide interactive examples. {% hint style="warning" %} **Search parameter order** The examples in the [JMESPath Specification](https://jmespath.org/specification.html#jmespath-specification) follow the pattern `search(searchString, object)`. The [JMESPath JavaScript library](https://github.com/jmespath/jmespath.js/), which n8n uses, supports `search(object, searchString)` instead. This means that when using examples from the JMESPath documentation, you may need to change the order of the search function parameters. {% endhint %} ## Common tasks This section provides examples for some common operations. More examples, and detailed guidance, are available in [JMESPath's own documentation](https://jmespath.org/tutorial.html). When trying out these examples, you need to set the Code node **Mode** to **Run Once for Each Item**. ### Apply a JMESPath expression to a collection of elements with projections From the [JMESPath projections documentation](https://jmespath.org/tutorial.html#projections): > Projections are one of the key features of JMESPath. Use it to apply an expression to a collection of elements. JMESPath supports five kinds of projections: > > * List Projections > * Slice Projections > * Object Projections > * Flatten Projections > * Filter Projections The following example shows basic usage of list, slice, and object projections. Refer to the [JMESPath projections documentation](https://jmespath.org/tutorial.html#projections) for detailed explanations of each projection type, and more examples. Given this JSON from a webhook node: ```js [ { "headers": { "host": "n8n.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 } } } } ] ``` Retrieve a [list](https://jmespath.org/tutorial.html#list-and-slice-projections) of all the people's first names: {% tabs %} {% tab title="Expressions (JavaScript)" %} ```js {{$jmespath($json.body.people, "[*].first" )}} // Returns ["James", "Jacob", "Jayden"] ``` {% endtab %} {% tab title="Code node (JavaScript)" %} ```js let firstNames = $jmespath($json.body.people, "[*].first" ) return {firstNames}; /* Returns: [ { "firstNames": [ "James", "Jacob", "Jayden" ] } ] */ ``` {% endtab %} {% tab title="Code node (Python)" %} ```python firstNames = _jmespath(_json.body.people, "[*].first" ) return {"firstNames":firstNames} """ Returns: [ { "firstNames": [ "James", "Jacob", "Jayden" ] } ] """ ``` {% endtab %} {% endtabs %} Get a [slice](https://jmespath.org/tutorial.html#list-and-slice-projections) of the first names: {% tabs %} {% tab title="Expressions (JavaScript)" %} ```js {{$jmespath($json.body.people, "[:2].first")}} // Returns ["James", "Jacob"] ``` {% endtab %} {% tab title="Code node (JavaScript)" %} ```js let firstTwoNames = $jmespath($json.body.people, "[:2].first"); return {firstTwoNames}; /* Returns: [ { "firstNames": [ "James", "Jacob", "Jayden" ] } ] */ ``` {% endtab %} {% tab title="Code node (Python)" %} ```python firstTwoNames = _jmespath(_json.body.people, "[:2].first" ) return {"firstTwoNames":firstTwoNames} """ Returns: [ { "firstTwoNames": [ "James", "Jacob" ] } ] """ ``` {% endtab %} {% endtabs %} Get a list of the dogs' ages using [object projections](https://jmespath.org/tutorial.html#object-projections): {% tabs %} {% tab title="Expressions (JavaScript)" %} ```js {{$jmespath($json.body.dogs, "*.age")}} // Returns [7,5] ``` {% endtab %} {% tab title="Code node (JavaScript)" %} ```js let dogsAges = $jmespath($json.body.dogs, "*.age"); return {dogsAges}; /* Returns: [ { "dogsAges": [ 7, 5 ] } ] */ ``` {% endtab %} {% tab title="Code node (Python)" %} ```python dogsAges = _jmespath(_json.body.dogs, "*.age") return {"dogsAges": dogsAges} """ Returns: [ { "dogsAges": [ 7, 5 ] } ] """ ``` {% endtab %} {% endtabs %} ### Select multiple elements and create a new list or object Use [Multiselect](https://jmespath.org/tutorial.html#multiselect) to select elements from a JSON object and combine them into a new list or object. Given this JSON from a webhook node: ```js [ { "headers": { "host": "n8n.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 } } } } ] ``` Use multiselect list to get the first and last names and create new lists containing both names: {% tabs %} {% tab title="Expressions (JavaScript)" %} ```js {{$jmespath($json.body.people, "[].[first, last]")}} // Returns [["James","Green"],["Jacob","Jones"],["Jayden","Smith"]] ``` {% endtab %} {% tab title="Code node (JavaScript)" %} ```js let newList = $jmespath($json.body.people, "[].[first, last]"); return {newList}; /* Returns: [ { "newList": [ [ "James", "Green" ], [ "Jacob", "Jones" ], [ "Jayden", "Smith" ] ] } ] */ ``` {% endtab %} {% tab title="Code node (Python)" %} ```python newList = _jmespath(_json.body.people, "[].[first, last]") return {"newList":newList} """ Returns: [ { "newList": [ [ "James", "Green" ], [ "Jacob", "Jones" ], [ "Jayden", "Smith" ] ] } ] """ ``` {% endtab %} {% endtabs %} ### An alternative to arrow functions in expressions For example, generate some input data by returning the below code from the Code node: ```js 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." ```js {{ $jmespath($("Code").all(), "[?json.name=='Lenovo'].json.category_id") }} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.n8n.io/build/work-with-data/handle-special-data-types/query-json-data.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.