jmespath.js Documentation

The following examples demonstrate different capabilities of the JMESPath query language using jmespath.search:

• Object Projection: Selecting a sub-object.
• List Projection: Using [*] to extract specific fields from every object in an array.
• Filtering: Using [? ...] to filter array elements based on a condition (note that literal values in expressions often use backticks, e.g., `30`).

// Object Projection
jmespath.search({foo: {bar: {baz: [0, 1, 2, 3, 4]}}}, "foo.bar")
// returns { baz: [ 0, 1, 2, 3, 4 ] }

// List Projection
jmespath.search({"foo": [{"first": "a", "last": "b"}, {"first": "c", "last": "d"}]}, "foo[*].first")
// returns [ 'a', 'c' ]

// Filtering
jmespath.search({"foo": [{"age": 20}, {"age": 25}, {"age": 30}, {"age": 35}, {"age": 40}]}, "foo[?age > `30`]")
// returns [ { age: 35 }, { age: 40 } ]

The primary way to use jmespath.js is through the jmespath.search function. This function takes a JSON document (as a JavaScript object) and a JMESPath expression string, then returns the transformed JSON document or value resulting from the query.

Basic usage pattern:

1. Import the jmespath module.
2. Call jmespath.search(data, expression) where data is your JSON object and expression is your JMESPath query string.

var jmespath = require('jmespath');

// Example: Selecting a specific element from an array
var result = jmespath.search({foo: {bar: {baz: [0, 1, 2, 3, 4]}}}, "foo.bar.baz[2]");
// result is 2

Use tokenize(stream) to break a JMESPath expression string into a stream of tokens. This is a lower-level operation typically used for lexical analysis.

const jmespath = require('jmespath');

const expression = 'foo[0].bar';
const tokens = jmespath.tokenize(expression);

Use compile(stream) to transform a JMESPath expression string into an Abstract Syntax Tree (AST). This is useful if you intend to reuse the parsed expression multiple times against different data sets, avoiding the overhead of re-parsing.

const jmespath = require('jmespath');

const expression = 'foo[0].bar';
const ast = jmespath.compile(expression);

The primary way to use jmespath.js is via the search(data, expression) function. It takes a JSON-compatible data object and a JMESPath expression string, returning the result of the evaluation.

const jmespath = require('jmespath');

const data = { 
  "foo": [ 
    { "bar": 1 }, 
    { "bar": 2 } 
  ] 
};
const expression = 'foo[0].bar';

const result = jmespath.search(data, expression);
// result is 1

The jmespath.js runtime supports the following built-in functions. Note that many functions have specific type requirements (e.g., sum requires an array of numbers).

// Supported functions include:
// abs(number)
// avg(array_number)
// ceil(number)
// contains(string|array, any)
// ends_with(string, string)
// floor(number)
// length(string|array|object)
// map(expref, array)
// max(array_number|array_string)
// merge(object, [variadic object])
// max_by(array, expref)
// sum(array_number)
// starts_with(string, string)
// min(array_number|array_string)
// min_by(array, expref)
// type(any)
// keys(object)
// values(object)
// sort(array_string|array_number)
// sort_by(array, expref)
// join(string, array_string)
// reverse(string|array)
// to_array(any)
// to_string(any)
// to_number(any)
// not_null([variadic any])