JSONPath Queries

JSONPath queries integrate directly with Loro documents so you can traverse complex data without writing ad hoc tree walkers. This guide outlines the query surface, highlights supported syntax, and walks through examples that you can adapt to your own application.

JSONPath functions such as count(), length(), value(), match(), and search() are parsed but not evaluated at runtime. Each currently returns JsonPathError::EvaluationError::Unimplemented.

Preparing Sample Data

The snippets below use the WASM bindings, but the same structure works with the Rust API. We create a bookstore dataset inside a LoroDoc so we can run queries against it.

⚠️ Illustration only: This approach stuffs plain JavaScript objects into a document for convenience. In production code prefer composing LoroMap and LoroList instances explicitly so you can control how data enters the CRDT and benefit from fine-grained updates.

import { LoroDoc } from "loro-crdt";
 
const doc = new LoroDoc();
const testData = {
  books: [
    { title: "1984", author: "George Orwell", price: 10, available: true, isbn: "978-0451524935" },
    { title: "Animal Farm", author: "George Orwell", price: 8, available: true },
    { title: "Brave New World", author: "Aldous Huxley", price: 12, available: false },
    { title: "Fahrenheit 451", author: "Ray Bradbury", price: 9, available: true, isbn: "978-1451673318" },
    { title: "The Great Gatsby", author: "F. Scott Fitzgerald", price: null, available: true },
    { title: "To Kill a Mockingbird", author: "Harper Lee", price: 11, available: true },
    { title: "The Catcher in the Rye", author: "J.D. Salinger", price: 10, available: false },
    { title: "Lord of the Flies", author: "William Golding", price: 9, available: true },
    { title: "Pride and Prejudice", author: "Jane Austen", price: 7, available: true },
    { title: "The Hobbit", author: "J.R.R. Tolkien", price: 14, available: true }
  ],
  featured_author: "George Orwell",
  min_price: 10,
  featured_authors: ["George Orwell", "Jane Austen"],
};
 
const store = doc.getMap("store");
Object.entries(testData).forEach(([key, value]) => store.set(key, value));
doc.commit();

Executing JSONPath Queries

Run a query with the JSONPath method on WASM or jsonpath on Rust. The API returns a list of values for any matches. Container results currently surface as handlers internally, but that interface is still evolving and treated as opaque in this guide.

const doc = new LoroDoc();
// setup omitted for brevity
const results = doc.JSONPath("$.store.books[*].title");
console.log(results);
// => ["1984", "Animal Farm", ...]

use loro::prelude::*;
 
let doc = LoroDoc::new();
// setup omitted for brevity
let titles = doc.jsonpath("$.store.books[*].title")?;
for title in titles {
    if let ValueOrHandler::Value(value) = title {
        println!("{value}");
    }
}

Supported Selectors and Filters

RFC 9535 syntax works end-to-end, including:

• Selectors – names, indices (positive/negative), slices, unions, wildcards, and recursive descent (..).
• Filters – logical operators (&&, ||, !), comparisons, membership via in, substring checks with contains, property existence, and nested subqueries through $ (root) or @ (current node).
• Functions – count(), length(), and value() are parsed, while match() and search() are reserved for expansion. All functions currently return an unimplemented evaluation error at runtime.

Cookbook Examples

Once the document is populated you can combine selectors and filters to extract precisely what you need.

JSONPath always returns values in document order. When a filter references another query (such as $.store.featured_authors), the subquery is evaluated for each candidate element.