Skip to content

Path expressions

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

This page describes path expressions functionality.

Each operation’s Example shows the code in nine tabs: Aerospike Expression Language (AEL) text on the Java SDK and Python SDK tabs, and the Exp builder on the other seven. See the AEL reference for AEL grammar.

Overview

A path expression is a programmatic, type-safe mechanism used to traverse and manipulate collection data types (CDTs). Expressions are used by Path expression operations (selectByPath and modifyByPath) to navigate and interact with nested Map and List elements.

Path expressions enhance Aerospike’s capability to retrieve and manipulate data from JSON-like documents. For a tutorial that builds on path expressions with other CDT techniques, see Working with nested collection data types.

The Developer SDK also exposes equivalent path navigation as Aerospike Expression Language (AEL) text (for example "$.bookstore.store.book.*[?(@.price < 10.0)]") and as builder-style allChildrenWithFilter calls.

How path expressions relate to other CDT APIs

Aerospike provides three complementary ways to work with nested collection data. CDT operations (ListOperation, MapOperation) act in-place on the record, reading or modifying a single element at a known position. CDT expressions (list and map) evaluate to a typed value and can be composed with other expressions for filtering and computed reads. Path expressions extend both models by selecting or modifying multiple elements at once using expression-based contexts such as allChildren() and allChildrenWithFilter(). For a tutorial that builds on all three techniques, see Working with nested collection data types.

Operations

Path expressions use two server-side operations to interact with nested CDTs. Both execute directly on database nodes, minimizing data transfer between client and server.

  • selectByPath: reads and selects multiple nested elements matching the developer-defined paths in a single operation. Returns specific subtrees or values rather than the entire record, reducing network traffic and latency. See the bookstore examples below.

  • modifyByPath: removes or updates the value of matched elements, directly on the server.

Navigation through hierarchical CDT structures is managed through a context list (CTX). The list defines element selection and filtering logic at each level of the document.

Path selectors

Paths are defined by progressively applying a list of element selectors from the root bin down to the target element(s). Every step must be contiguous.

  • Index, Key, Rank, Value: standard single-element selectors that navigate to a specific address within a List or Map.

  • allChildren(): matches all elements in a List or Map, enabling multi-element selection and retrieval. See the bookstore examples and advanced usage for worked examples.

  • allChildrenWithFilter(exp): matches elements that satisfy a filter expression. See filtering books by price for an example.

Loop variables

During path resolution with allChildrenWithFilter, a typed loop variable acts as a contextual placeholder that is filled with an aspect of the current CDT element being evaluated:

  • MAP_KEY: when the current element is a Map, assign its key to the loop var.
  • VALUE: assign the value of the current (Map or List) element to the loop var.
  • LIST_INDEX: when the current element is a List, assign its index position to the loop var.

For worked examples using loop variables, see the advanced usage page.

Return modes

The selectFlags parameter determines the format and content of the elements matched by a selectByPath operation.

  • MATCHING_TREE: Returns a hierarchical tree starting from the root down to the target nodes, preserving parent-child relationships. Only branches that satisfied the filter criteria are included. This provides the highest level of structural control.

  • VALUE / VALUES: Returns a flat list of values from the final context level.

  • MAP_KEY / MAP_KEYS: Returns only the keys of the selected map elements.

  • NO_FAIL: Ignores elements with incompatible types rather than failing the entire operation. Useful when matching across heterogeneous collections where not every element has the expected data type.

Indexing and constraints

  • Nesting depth: Lists and Maps support up to 64 levels of nesting (Database 8.2.0 and later). Path expressions can address elements at any of those levels. See Nesting depth limit for how depth is counted.

  • Expression indexes: Path expressions can be combined with expression indexes to support high-speed querying into nested documents. See the expression index example for a walkthrough.

  • Batch inlining: For in-memory namespaces with records exceeding about 1KiB, consider setting allowInline to false. See performance considerations for details.

Language support

Path expressions are supported in the Java and Python Developer SDKs and in the Java, Python, C#, C, Go, Node.js, and Rust clients. See the client feature compatibility matrix for version details.

Bookstore example

The examples below use the classic JSONPath bookstore dataset to demonstrate path expression queries. The data is stored as a single map bin named "bookstore".

Data structure

{
  "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
      },
      { "category": "fiction",
        "author": "J. R. R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99
      }
    ],
    "bicycle": {
      "color": "red",
      "price": 19.95
    }
  },
  "expensive": 10
}

Filtering dimensions

bin "bookstore" (map)
 ├── store (map)
 │    ├── book (list of 4 maps)
 │    │    ├── {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}
 │    │    └── {category:"fiction", author:"J. R. R. Tolkien", title:"The Lord of the Rings", isbn:"0-395-19395-8", price:22.99}
 │    └── bicycle (map)
 │         ├── color: "red"
 │         └── price: 19.95
 └── expensive: 10
  • Store level: select book vs bicycle (map key navigation)
  • Book level: filter on category, author, title, price, presence of isbn
  • Cross-level: compare book price against the top-level expensive threshold (10)

The authors of all books in the store

JSONPath equivalent: $.store.book[*].author

Navigate to the book list, match all children, and select just the "author" key from each book map.

Record record = session.query(key)
    .bin("authors").selectFrom("$.bookstore.store.book.*.author")
    .execute()
    .getFirstRecord();

Output:

["Nigel Rees", "Evelyn Waugh", "Herman Melville", "J. R. R. Tolkien"]

Filter all books with an ISBN number

JSONPath equivalent: $.store.book[?(@.isbn)]

Filter books where the isbn key exists using MapReturnType.EXISTS.

Record record = session.query(key)
    .bin("books").selectFrom("$.bookstore.store.book.*[?(@.isbn.exists())]")
    .execute()
    .getFirstRecord();

Output:

[
  {"category":"fiction", "author":"Herman Melville", "title":"Moby Dick", "isbn":"0-553-21311-3", "price":8.99},
  {"category":"fiction", "author":"J. R. R. Tolkien", "title":"The Lord of the Rings", "isbn":"0-395-19395-8", "price":22.99}
]

Filter all books cheaper than 10

JSONPath equivalent: $.store.book[?(@.price < 10)]

Record record = session.query(key)
    .bin("books").selectFrom("$.bookstore.store.book.*[?(@.price < 10.0)]")
    .execute()
    .getFirstRecord();

Output:

[
  {"category":"reference", "author":"Nigel Rees", "title":"Sayings of the Century", "price":8.95},
  {"category":"fiction", "author":"Herman Melville", "title":"Moby Dick", "isbn":"0-553-21311-3", "price":8.99}
]

Filter all fiction books costing less than 10

JSONPath equivalent: $.store.book[?(@.category=='fiction' && @.price < 10)]

Compound filter combining two conditions with and().

Record record = session.query(key)
    .bin("books").selectFrom("$.bookstore.store.book.*[?(@.category == 'fiction' and @.price < 10.0)]")
    .execute()
    .getFirstRecord();

Output:

[
  {"category":"fiction", "author":"Herman Melville", "title":"Moby Dick", "isbn":"0-553-21311-3", "price":8.99}
]

Next steps