JMESPath Query

JMESPath (JSON Matching Expression paths) is a query language for JSON. It allows you to declaratively specify how to extract elements from JSON documents using a simple and intuitive syntax.

Basic Concept

JMESPath expressions work by traversing JSON data structures to extract and transform values. The query language is designed to be simple, lightweight, and expressive.

Syntax Overview

Basic Access

// Access root properties
name
settings.theme

// Access array elements
users[0]
users[0].name

// Access nested properties
users[0].address.city

Array Operations

// Get array length
users | length(@)

// Get all array elements
users[*]

// Array slicing
users[0:2]
users[:2]    // First 2 elements
users[2:]    // From index 2 to end

Sample JSON Data

{
  "store": {
    "book": [
      {
        "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
      },
      {
        "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99
      },
      {
        "category": "fiction",
        "author": "Herman Melville", 
        "title": "Moby Dick",
        "isbn": "0-553-21311-3",
        "price": 8.99
      }
    ],
    "bicycle": {
      "color": "red",
      "price": 19.95
    }
  },
  "users": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "[email protected]",
      "age": 30,
      "active": true,
      "address": {
        "street": "123 Main St",
        "city": "New York",
        "zipcode": "10001"
      }
    },
    {
      "id": 2,
      "name": "Jane Smith", 
      "email": "[email protected]",
      "age": 25,
      "active": false,
      "address": {
        "street": "456 Oak Ave",
        "city": "Los Angeles", 
        "zipcode": "90210"
      }
    }
  ]
}

Basic Queries

// Get all books
store.book

// Get first book
store.book[0]

// Get book title
store.book[0].title

// Get bicycle color
store.bicycle.color

// Get all users
users

// Get user address
users[0].address.city

Advanced Projections

Wildcard Projections

// Get all book titles
store.book[*].title

// Get all user names
users[*].name

// Get all user cities
users[*].address.city

// Get all authors
store.book[*].author

Object Projections

// Project over object values
store.*

// Get all values from store
store.* | [0]

// Flatten projections
store.book[*].{title: title, author: author}

Filtering

Filter Expressions

// Books under $10
store.book[?price < `10`]

// Fiction books
store.book[?category == 'fiction']

// Books that have ISBN
store.book[?isbn]

// Active users
users[?active]

// Users over 25
users[?age > `25`]

// Users in New York
users[?address.city == 'New York']

Comparison Operators

// Equal
users[?age == `30`]

// Not equal
users[?age != `30`]

// Less than
store.book[?price < `10`]

// Greater than
users[?age > `25`]

// Less than or equal
store.book[?price <= `10`]

// Greater than or equal
users[?age >= `25`]

Multi-select Hash

Create custom objects with selected fields:

// Select specific book fields
store.book[0].{title: title, author: author, price: price}

// Select user information
users[0].{name: name, email: email, city: address.city}

// Create summary for all books
store.book[*].{title: title, author: author}

// User summary with computed fields
users[*].{name: name, location: address.city, status: active}

Multi-select List

Create arrays with selected values:

// Get title and author as array
store.book[0].[title, author]

// Get user name and city
users[0].[name, address.city]

// Multiple values for all books
store.book[*].[title, price]

Functions

Built-in Functions

// Length function
users | length(@)
store.book | length(@)

// Sort function
store.book | sort_by(@, &price)
users | sort_by(@, &age)

// Reverse function
store.book | reverse(@)

// Maximum/Minimum
store.book | max_by(@, &price)
store.book | min_by(@, &price)
users | max_by(@, &age)

// Sum (for arrays of numbers)
store.book[*].price | sum(@)
users[*].age | sum(@)

String Functions

// Join arrays into strings
store.book[*].author | join(', ', @)

// String operations
users[*].name | join(' | ', @)

Pipes and Expressions

// Chain operations with pipes
store.book | sort_by(@, &price) | [0]

// Filter then project
store.book[?category == 'fiction'] | [*].title

// Complex pipeline
users[?active] | sort_by(@, &age) | [*].{name: name, age: age}

// Multiple filters
store.book[?price < `10` && category == 'fiction']

Slicing

// Array slicing
store.book[0:2]    // First 2 books
store.book[1:]     // All except first
store.book[:2]     // First 2 books
store.book[-1:]    // Last book
store.book[-2:]    // Last 2 books

// Step slicing
users[::2]         // Every other user

Complex Examples

Data Aggregation

// Total book prices
store.book[*].price | sum(@)

// Average book price
store.book[*].price | avg(@)

// Expensive books summary
store.book[?price > `10`].{title: title, price: price}

// Active users in descending age order
users[?active] | sort_by(@, &age) | reverse(@)

Data Transformation

// Book catalog
store.book[*].{
  title: title,
  author: author,
  category: category,
  price: price,
  hasIsbn: isbn && `true` || `false`
}

// User directory
users[*].{
  profile: {
    name: name,
    email: email
  },
  location: address.city,
  active: active
}

Conditional Logic

// Books with conditional pricing
store.book[*].{
  title: title,
  priceCategory: price < `10` && 'cheap' || 'expensive'
}

// User status
users[*].{
  name: name,
  status: active && 'Active' || 'Inactive',
  ageGroup: age >= `30` && 'Senior' || 'Junior'
}

Best Practices

1. Use meaningful projections: Select only the data you need
2. Filter early: Apply filters before projections for better performance
3. Use built-in functions: Leverage functions like sort_by, max_by, etc.
4. Chain operations: Use pipes to create readable query chains
5. Test incrementally: Build complex queries step by step
6. Use multi-select: Create structured output with hash and list selects

Common Patterns

Extract and Transform

// Extract specific fields
store.book[*].[title, author, price]

// Transform with calculations
store.book[*].{item: title, cost: price, expensive: price > `10`}

// Nested transformations
users[*].{
  user: name,
  contact: {email: email, city: address.city}
}

Finding Specific Items

// Find specific book
store.book[?title == 'Moby Dick']

// Find user by criteria
users[?age == `30` && active]

// Find and extract
store.book[?category == 'fiction'] | [0].title

JMESPath provides a powerful and intuitive way to query JSON data with its declarative syntax and rich set of built-in functions.