QueryBuilder API

The QueryBuilder provides a fluent API for building and executing JSONPath queries with JavaScript-based transformations.

Creating a Builder

Create a builder instance with your data:

import { JSONPath } from '@jsonpathx/jsonpathx';

const data = { /* your data */ };
const builder = JSONPath.create(data);

Basic Query

Start with a JSONPath expression:

const result = await builder
  .query('$.products[*]')
  .execute();

Chainable Methods

All chainable methods return this for method chaining.

query()

Set the JSONPath query expression.

builder.query('$.store.book[*]')

filter()

Filter results using a JavaScript function.

const result = await JSONPath.create(data)
  .query('$.products[*]')
  .filter(product => product.price < 100)
  .filter(product => product.inStock)
  .execute();

Multiple filters are applied in sequence (AND logic).

map()

Transform each result.

const names = await JSONPath.create(data)
  .query('$.products[*]')
  .map(product => product.name)
  .execute();

sort()

Sort results using a comparator function.

const sorted = await JSONPath.create(data)
  .query('$.products[*]')
  .sort((a, b) => a.price - b.price)
  .execute();

take()

Take the first N results.

const top5 = await JSONPath.create(data)
  .query('$.products[*]')
  .sort((a, b) => b.rating - a.rating)
  .take(5)
  .execute();

skip()

Skip the first N results.

const page2 = await JSONPath.create(data)
  .query('$.products[*]')
  .skip(10)
  .take(10)
  .execute();

deduplicate()

Remove duplicate results.

const unique = await JSONPath.create(data)
  .query('$..category')
  .deduplicate()
  .execute();

Terminal Methods

These methods execute the query and return a result.

execute()

Execute the query and return all results.

const results = await builder
  .query('$.items[*]')
  .execute();

first()

Get the first result.

const first = await JSONPath.create(data)
  .query('$.products[*]')
  .sort((a, b) => b.price - a.price)
  .first();

last()

Get the last result.

const last = await JSONPath.create(data)
  .query('$.products[*]')
  .last();

count()

Count the results.

const count = await JSONPath.create(data)
  .query('$.products[?(@.inStock)]')
  .count();

exists()

Check if any results exist.

const hasExpensive = await JSONPath.create(data)
  .query('$.products[?(@.price > 1000)]')
  .exists();

Complete Example

const products = await JSONPath.create(catalog)
  .query('$.products[*]')
  .filter(p => p.category === 'electronics')
  .filter(p => p.price >= 50 && p.price <= 500)
  .filter(p => p.rating >= 4.0)
  .filter(p => p.inStock)
  .sort((a, b) => b.rating - a.rating)
  .take(10)
  .map(p => ({
    name: p.name,
    price: p.price,
    rating: p.rating
  }))
  .execute();

Next Steps

• Examples - Advanced QueryBuilder examples
• Performance - Optimization techniques
• API Reference - Complete API documentation