A lightweight, high-performance java path util that queries and extracts data from JSON documents with XPath-style path expressions.
🌐 JQuick Website · 📖 GitHub · 📦 Maven Central
🔗 jquick-curl · 📂 jquick-path · 📊 jquick-excel · 📄 jquick-pdf · ☕ jquick-java · 🗄️ jquick-sql
English | 简体中文
- Project Introduction
- Features
- Environment Requirements
- Quick Start
- Usage Examples
- Core API Reference
- Compatibility & Scenarios
- Build & Compile
- Related Ecosystem
- Contributing
- License
- Donation & Support
JQuick Path is a query language and runtime for extracting data from JSON documents, playing the same role for JSON that XPath plays for XML. A concise cross-platform path expression is all you need to locate any node inside a nested JSON structure.
The library is written in pure Java and driven by an ANTLR4 grammar, so it has no native dependencies and behaves identically on every operating system. Under the hood it provides a fluent, type-safe builder (JSONPathQueryBuilder) together with a full expression engine: root and current node selectors, child properties, wildcards, recursive descent, array subscripts, slices, filters, arithmetic and logical expressions, plus result mapping into Java beans.
Whether you are reading configuration files, post-processing API responses, transforming data pipelines, or validating untrusted payloads, JQuick Path gives you a java path util that stays small, predictable and dependency-free.
JQuick Path is a query language used to extract data from JSON documents, similar to the role of XPath in XML. It provides a concise way to locate and extract specific parts of JSON structures through path expressions.
- Fluent query builder — compose a query with
JSONPathQueryBuilder.from(...).document(...).limit(...).execute(). - Programmatic path construction — build paths with
JPath,JSegmentsandJSubscriptsinstead of hand-written strings. - String path expressions — pass expressions such as
$.store.books..[2]straight topath(String). - Root and current node selectors —
$(JRoot.ROOT) and@(JRoot.CURRENT). - Segment selectors — property access, wildcard
*, recursive descent.., subscript segments and recursive subscripts. - Subscript selectors — numeric index, negative index, wildcard, object property
['title'], slice[start:end:step], filter[?(...)]and arithmetic expression subscripts. - Rich predicate library —
eq,ne,gt,ge,lt,le,like,regex,startsWith,endsWith,contains,in,exists,notExists,and,or,notand rawcustomexpressions. - Full filter expression engine — comparison, logical, arithmetic,
in, negation, regex and nested function calls such as@.length(). - Multiple input sources — JSON string,
Map, POJO orJSONObject. - Result handling —
JSONPathResultexposesgetRawData(),getAsList()andisList();as()/asList()map results to Java beans. - Sorting and pagination —
JSortBuilder.asc()/desc()for ordering,limit()/skip()for paging. - Grammar-driven parser — ANTLR4 grammar with a dedicated error listener for readable syntax diagnostics.
- Cross-platform and domestic OS compatible — pure Java bytecode, no JNI, tested on Windows, Linux and macOS as well as domestic OS compatible environments (Kylin, UOS, openEuler) with mainstream domestic JDKs.
- Bounded traversal — recursive descent over untrusted JSON is capped by
limit()/skip(), a lightweight path traversal defense against unbounded result expansion and resource exhaustion. - Declarative annotations —
@JSONPath,@JSONObject,@JSONArray,@JSONFilter,@JSONSortand@JSONFormatfor path-based field and result binding. - Extensible utilities —
JValueContextFactoryfor context-based value access andJTemplateEnginefor template evaluation. - Apache-2.0 licensed — free for commercial and personal use.
| Item | Requirement |
|---|---|
| JDK | 8 or later (JDK 17 recommended) |
| Build tool | Maven 3.6+ or Gradle 7+ |
| Operating system | Windows / Linux / macOS / domestic OS (信创) |
| Dependencies | ANTLR4 runtime, Hutool, Javelin core, JQuick JSON — all pure Java, no native libraries |
<dependency>
<groupId>io.github.paohaijiao</groupId>
<artifactId>jquick-path</artifactId>
<version>${latest.version}</version>
</dependency>implementation 'io.github.paohaijiao:jquick-path:${latest.version}'| Expression | Description |
|---|---|
| $ | Root object |
| . or [ ] | Child operator, used to access object properties |
| ... | Recursive descent, searches all child elements |
| * | Wildcard, matches all objects or array elements |
| [ ] | Subscript operator, used for array indexing or filtering |
| [start:end:step] | Array slice operation |
| ?() | Filter expression |
| @ | Current node, used in filter expressions |
All examples below share the same reference data unless stated otherwise.
- Reference Data
{
"store": {
"books": [
{
"title": "Book 1",
"author": "Author 1",
"price": 10
},
{
"title": "Book 2",
"author": "Author 2",
"price": 15
},
{
"title": "Book 3",
"author": "Author 3",
"price": 20
}
]
}
}
- Input Data: Contains a
storeobject, under which there is abooksarray, and the array contains book objects withtitle,author, andpriceattributes. - Path Expression Logic: Starting from the root node, access the
storeattribute andbooksattribute in sequence. - Java Code Logic: Use
JSONPathQueryBuilderto build a path from the root node, specify thestoreandbooksattributes, set thelimitto 10, and then execute the query.
JSONPathQueryBuilder.from(jsonObject)
.document(JPath.fromRoot(JRoot.ROOT)
.property("store").property("books"))
.limit(10).execute();
- Equivalent Path Expression: $.store.books
- Output Result: All book objects in the
booksarray
- Input Data: Same as the input data of the Root Node Expression
- Path Expression Logic: Starting from the current node, access the
storeattribute andbooksattribute in sequence. - Java Code Logic: Similar to the Root Node Expression, the difference is that the path is built starting from the current node (
JRoot.CURRENT).
JSONPathQueryBuilder.from(jsonObject)
.document(JPath.fromRoot(JRoot.CURRENT)
.property("store").property("books"))
.limit(10).execute();
- Equivalent Path Expression: @.store.books
- Output Result: Same as the output result of the Root Node Expression, both are all book objects in the
booksarray
- Input Data: JSON data containing a
storeobject with abooksarray underneath it - Path Expression Logic: Starting from the root node, use the wildcard
*to get all attributes under the root node - Java Code Logic: Build a path starting from the root node, use
property("*")to get all attributes, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT)
.property("*")).limit(10).execute();
- Equivalent Path Expression: $.*
- Output Result: The
booksarray in thestoreobject under the root node
- Input Data: Same as the input data of the Property Accessor
- Path Expression Logic: Starting from the root node, access the
storeandbooksattributes in sequence, then use the wildcard*to get all elements of thebooksarray - Java Code Logic: Build a path to specify the
storeandbooksattributes in sequence, then get all elements of the array throughproperty("*"), and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT)
.property("store").property("books").property("*"))
.limit(10)
.execute();
- Equivalent Path Expression: $.store.books.*
- Output Result: All book objects in the
booksarray
- Input Data: JSON data containing a
storeobject and abooksarray - Path Expression Logic: Access the
booksarray understoreand get the element with index 2 - Java Code Logic: After building the path to the
booksarray, specify the element with subscript 2 through thesegmentmethod, and execute the query
- JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT)
.property("store").property("books")
.segment(JSegments.subscript(JIndexSubscript.of(2))))
.limit(10)
.execute();
- Equivalent Path Expression: $.store.books[2]
- Output Result: The book object with index 2 in the
booksarray (Book 3)
- Input Data: Same as the input data of the Numeric Subscript Accessor
- Path Expression Logic: Get the
priceproperty value of the element with index 2 in thebooksarray - Java Code Logic: After getting the element with index 2, continue to specify
property("price")to get the price attribute, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT)
.property("store").property("books")
.segment(JSegments.subscript(JIndexSubscript.of(2))).property("price"))
.limit(10)
.execute();
- Equivalent Path Expression: $.store.books[2].price
- Output Result: The price of the book with index 2 (20)
- Input Data: JSON data containing a
storeobject and abooksarray - Path Expression Logic: Recursively search for all
priceproperty values under thebooksarray - Java Code Logic: After building the path to the
booksarray, usesegment(JSegments.recursiveId("price"))to recursively get thepriceattribute, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT)
.property("store").property("books")
.segment(JSegments.recursiveId("price")))
.limit(10)
.execute();
- Equivalent Path Expression: $.store.books..price
- Output Result: An array composed of the prices of all books ([10, 15, 20])
- Input Data: Same as the input data of the Subproperty Extractor
- Path Expression Logic: Recursively search for the element with index 2 under the
booksarray - Java Code Logic: After building the path to the
booksarray, get the element with the specified subscript throughsegment(JSegments.recursiveSubscript(JIndexSubscript.of(2))), and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT)
.property("store").property("books")
.segment(JSegments.recursiveSubscript(JIndexSubscript.of(2)))
).limit(10)
.execute();
- Equivalent Path Expression: $.store.books..[2]
- Output Result: The book object with index 2 in the
booksarray (Book 3)
- Reference JSON
{
"books": [
{
"title": "Book 1",
"author": "Author 1",
"price": 10
},
{
"title": "Book 2",
"author": "Author 2",
"price": 15
},
{
"title": "Book 3",
"author": "Author 3",
"price": 20
}
],
"extract": {
"title": "Book 3",
"author": "Author 3",
"price": 20
}
}
- Input Data: JSON data containing a
booksarray and anextractobject, with thebooksarray having information for three books - Path Expression Logic: Get the element with index 0 in the
booksarray - Java Code Logic: After building the path to the
booksarray, useJSubscripts.index(0)to specify the subscript, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.index(0))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[0]
- Output Result: The book object with index 0 in the
booksarray (Book 1)
- Input Data: Same as the input data of the Numeric Subscript
- Path Expression Logic: Get all elements of the
booksarray - Java Code Logic: After building the path to the
booksarray, useJSubscripts.wildcard()to get all elements, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books").segment(JSubscriptSegment.of(JSubscripts.wildcard())))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[*]
- Output Result: All book objects in the
booksarray
- Input Data: JSON data containing a
booksarray and anextractobject - Path Expression Logic: Get the
titleproperty value of theextractobject - Java Code Logic: After building the path to the
extractobject, useJSubscripts.property("title")to get thetitleattribute, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("extract")
.segment(JSubscriptSegment.of(JSubscripts.property("title"))))
.limit(10)
.execute();
- Equivalent Path Expression: $.extract['title']
- Output Result: The
titleproperty value of theextractobject (Book 3)
- Input Data: Same as the input data of the Property Extraction
- Path Expression Logic: Slice the
booksarray, starting from index 0, ending at index 1, with a step size of 2 - Java Code Logic: After building the path to the
booksarray, useJSubscripts.slice(0,1,2)to perform slicing, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books").segment(JSubscriptSegment.of(JSubscripts.slice(0,1,2))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[0:1:2]
- Output Result: The sliced array containing the book object with index 0 (Book 1)
- Input Data: JSON data containing a
booksarray and anextractobject - Path Expression Logic: Filter out the elements in the
booksarray where thetitleis 'Book 1' - Java Code Logic: After building the path to the
booksarray, useJSubscripts.filter(JPredicate.eq("title", "Book 1"))to perform filtering, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.filter(JPredicate.eq("title", "Book 1")))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[?(@.title == 'Book 1')]
- Output Result: The book object that meets the criteria (Book 1)
- Input Data: Same as the input data of the List Filtering
- Path Expression Logic: Calculate the index through the expression
0*1, and get the element of thebooksarray at the corresponding index - Java Code Logic: After building the path to the
booksarray, useJSubscripts.expr("0*1")to specify the index expression, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.expr("0*1"))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[0*1]
- Output Result: The book object with index 0 in the
booksarray (Book 1)
- Reference JSON
{
"books": [
{
"title": "Book 1",
"author": "Author 1",
"price": 10,
"isbn": true
},
{
"title": "Book 2",
"author": "Author 2",
"price": 15,
"isbn": false
},
{
"title": "Book 3",
"author": "Author 3",
"price": 20,
"isbn": true
}
],
"extract": {
"title": "Book 3",
"author": "Author 3",
"price": 20
}
}
- Input Data: JSON data containing a
booksarray and anextractobject, with thebooksarray having three books including theisbnattribute - Path Expression Logic: Get the element with index -2 in the
booksarray - Java Code Logic: After building the path to the
booksarray, useJSubscripts.expr("-2")to specify the negative index, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.expr("-2"))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[-2]
- Output Result: The book object with index -2 in the
booksarray (Book 1)
- Input Data: Same as the input data of the Negative Number Expression
- Path Expression Logic: Get the element with index 2 in the
booksarray - Java Code Logic: After building the path to the
booksarray, useJSubscripts.expr("2")to specify the index, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.expr("2"))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[2]
- Output Result: The book object with index 2 in the
booksarray (Book 3)
- Input Data: Same as the input data of the Negative Number Expression
- Path Expression Logic: Calculate the index through the expression
1+1, and get the element of thebooksarray at the corresponding index - Java Code Logic: After building the path to the
booksarray, useJSubscripts.expr("1+1")to specify the addition expression, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.expr("1+1"))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[1+1]
- Output Result: The book object with index 2 in the
booksarray (Book 3)
- Input Data: Same as the input data of the Negative Number Expression
- Path Expression Logic: Calculate the index through the expression
1-1, and get the element of thebooksarray at the corresponding index - Java Code Logic: After building the path to the
booksarray, useJSubscripts.expr("1-1")to specify the subtraction expression, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.expr("1-1"))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[1-1]
- Output Result: The book object with index 0 in the
booksarray (Book 1)
- Input Data: Same as the input data of the Negative Number Expression
- Path Expression Logic: Get the length of the
booksarray through the function@.length(), then subtract 1 to get the index and retrieve the corresponding element - Java Code Logic: After building the path to the
booksarray, useJSubscripts.expr("(@.length())-1")to specify the expression containing the function, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.expr("(@.length())-1"))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[(@.length())-1]
- Output Result: The last element of the
booksarray (Book 3)
- Input Data: Same as the input data of the Negative Number Expression
- Path Expression Logic: Filter out the elements in the
booksarray where theisbnis false - Java Code Logic: After building the path to the
booksarray, useJSubscripts.filter(JPredicate.custom("!@.isbn"))to perform NOT logic filtering, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.filter(JPredicate.custom("!@.isbn")))))
.limit(10);
- Equivalent Path Expression: $.books[?(!@.isbn)]
- Output Result: The book object where
isbnis false (Book 2)
- Input Data: Same as the input data of the Negative Number Expression
- Path Expression Logic: Calculate the index through the expression
1*1, and get the element of thebooksarray at the corresponding index - Java Code Logic: After building the path to the
booksarray, useJSubscripts.expr("1*1")to specify the multiplication expression, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.expr("1*1"))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[1*1]
- Output Result: The book object with index 1 in the
booksarray (Book 2)
- Input Data: Same as the input data of the Negative Number Expression
- Path Expression Logic: Calculate the index through the expression
1/1, and get the element of thebooksarray at the corresponding index - Java Code Logic: After building the path to the
booksarray, useJSubscripts.expr("1/1")to specify the division expression, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.expr("1/1"))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[1/1]
- Output Result: The book object with index 1 in the
booksarray (Book 2)
- Input Data: Same as the input data of the Negative Number Expression
- Path Expression Logic: Calculate the index through the expression
1%1, and get the element of thebooksarray at the corresponding index - Java Code Logic: After building the path to the
booksarray, useJSubscripts.expr("1%1")to specify the modulo expression, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.expr("1%1"))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[1%1]
- Output Result: The book object with index 0 in the
booksarray (Book 1)
- Input Data: Same as the input data of the Negative Number Expression
- Path Expression Logic: Filter out the elements in the
booksarray where thepriceis greater than 15 - Java Code Logic: After building the path to the
booksarray, useJSubscripts.filter(JPredicate.custom("@.price>15"))to perform greater than comparison filtering, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.filter(JPredicate.custom("@.price>15")))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[?(@.price>15)]
- Output Result: The book object where
priceis greater than 15 (Book 3)
- Input Data: Same as the input data of the Negative Number Expression
- Path Expression Logic: Filter out the elements in the
booksarray where thepriceis greater than or equal to 15 - Java Code Logic: After building the path to the
booksarray, useJSubscripts.filter(JPredicate.custom("@.price>=15"))to perform greater than or equal to comparison filtering, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.filter(JPredicate.custom("@.price>=15")))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[?(@.price>=15)]
- Output Result: The book objects where
priceis greater than or equal to 15 (Book 2, Book 3)
- Input Data: Same as the input data of the Negative Number Expression
- Path Expression Logic: Filter out the elements in the
booksarray where thepriceis less than 15 - Java Code Logic: After building the path to the
booksarray, useJSubscripts.filter(JPredicate.custom("@.price<15"))to perform less than comparison filtering, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.filter(JPredicate.custom("@.price<15")))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[?(@.price<15)]
- Output Result: The book object where
priceis less than 15 (Book 1)
- Input Data: Same as the input data of the Negative Number Expression
- Path Expression Logic: Filter out the elements in the
booksarray where thepriceis less than or equal to 15 - Java Code Logic: After building the path to the
booksarray, useJSubscripts.filter(JPredicate.custom("@.price<=15"))to perform less than or equal to comparison filtering, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.filter(JPredicate.custom("@.price<=15")))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[?(@.price<=15)]
- Output Result: The book objects where
priceis less than or equal to 15 (Book 1, Book 2)
- Input Data: Same as the input data of the Negative Number Expression
- Path Expression Logic: Filter out the elements in the
booksarray where thepriceis equal to 15 - Java Code Logic: After building the path to the
booksarray, useJSubscripts.filter(JPredicate.custom("@.price==15"))to perform equality comparison filtering, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.filter(JPredicate.custom("@.price==15")))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[?(@.price==15)]
- Output Result: The book object where
priceis equal to 15 (Book 2)
- Input Data: Same as the input data of the Negative Number Expression
- Path Expression Logic: Filter out the elements in the
booksarray where thepriceis not equal to 15 - Java Code Logic: After building the path to the
booksarray, useJSubscripts.filter(JPredicate.custom("@.price!=15"))to perform inequality comparison filtering, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.filter(JPredicate.custom("@.price!=15")))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[?(@.price!=15)]
- Output Result: The book objects where
priceis not equal to 15 (Book 1, Book 3)
- Input Data: Same as the input data of the Negative Number Expression
- Path Expression Logic: Filter out the elements in the
booksarray where thetitleis in ('Book 3','Book 2') - Java Code Logic: After building the path to the
booksarray, useJSubscripts.filter(JPredicate.custom("@.title in ('Book 3','Book 2')"))to perform IN logic filtering, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.filter(JPredicate.custom("@.title in ('Book 3','Book 2')")))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[?(@.title in ('Book 3','Book 2'))]
- Output Result: The book objects where
titleis in the specified range (Book 2, Book 3)
- Input Data: Same as the input data of the Negative Number Expression
- Path Expression Logic: Filter out the elements in the
booksarray where thetitleis in ('Book 3','Book 2') andisbnis true - Java Code Logic: After building the path to the
booksarray, useJSubscripts.filter(JPredicate.custom("@.title in ('Book 3','Book 2') &&@.isbn"))to perform AND logic filtering, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.filter(JPredicate.custom("@.title in ('Book 3','Book 2') &&@.isbn")))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[?(@.title in ('Book 3','Book 2') &&@.isbn)]
- Output Result: The book object that meets the AND logic criteria (Book 3)
- Input Data: Same as the input data of the Negative Number Expression
- Path Expression Logic: Filter out the elements in the
booksarray where thetitleis in ('Book 3','Book 2') orisbnis true - Java Code Logic: After building the path to the
booksarray, useJSubscripts.filter(JPredicate.custom("@.title in ('Book 3','Book 2') ||@.isbn"))to perform OR logic filtering, and execute the query
JSONPathQueryBuilder.from(jsonData)
.document(JPath.fromRoot(JRoot.ROOT).property("books")
.segment(JSubscriptSegment.of(JSubscripts.filter(JPredicate.custom("@.title in ('Book 3','Book 2') ||@.isbn")))))
.limit(10)
.execute();
- Equivalent Path Expression: $.books[?(@.title in ('Book 3','Book 2') ||@.isbn)]
- Output Result: The book objects that meet the OR logic criteria (Book 1, Book 2, Book 3)
- Input Data: JSON data containing a
storeobject and abooksarray - Path Expression Logic: Directly use the path expression
"$.store.books..[2]"to retrieve the corresponding element - Java Code Logic: Use the
pathmethod ofJSONPathQueryBuilderto directly pass in the path expression and execute the query
JSONPathQueryBuilder.from(jsonData).path("$.store.books..[2]").limit(10).execute();
- Output Result: The book object with index 2 in the
booksarray (Book 3)
| Method | Description |
|---|---|
from(Object) |
Create a query from a POJO (serialized then parsed) |
from(String) |
Create a query from a JSON string |
from(Map) |
Create a query from a Map |
from(JSONObject) |
Create a query from a JSONObject |
root(JSubscripts) |
Create a query starting from a root subscript |
filter(Class<T>) |
Create a typed JFilterBuilder<T> |
of(JPredicate<T>) / of(String) |
Build a JFilterExpression from a predicate or raw expression |
select(Class<T>) |
Create a typed JProjectionBuilder<T> |
| Method | Description |
|---|---|
document(JPath) |
Set the programmatically built path |
path(String) |
Set the path from a string expression |
limit(int) |
Limit the number of returned elements |
skip(int) |
Skip the first N elements (works together with limit) |
sort(JSortBuilder<T>) |
Sort list results (requires asList) |
as(Class<T>) |
Map a single result to a Java bean |
asList(Class<T>) |
Map list results to Java beans |
execute() |
Execute the query and return a JSONPathResult |
| Method | Description |
|---|---|
JPath.fromRoot(JRoot) |
Build a path from the root ($) or current (@) node |
JPath.documentRoot() / JPaths.documentPath() |
Build a path from the root node |
JPath.currentRoot() / JPaths.currentPath() |
Build a path from the current node |
segment(JSegment) / segments(JSegment...) |
Append one or more segments |
property(String) |
Append a property identifier segment |
wildcard() |
Append a wildcard segment |
index(int) |
Append an index subscript segment |
filter(JPredicate<?>) |
Append a filter subscript segment |
recursiveProperty(String) |
Append a recursive identifier segment |
recursiveWildcard() |
Append a recursive wildcard segment |
toJSONPathExpression() |
Render the path as a JSONPath string |
| Method | Description |
|---|---|
id(String) |
Identifier segment (.property) |
wildcard() |
Wildcard identifier segment (.*) |
subscript(JSubscript) |
Subscript segment ([...]) |
recursiveId(String) |
Recursive identifier segment (..property) |
recursiveWildcard() |
Recursive wildcard segment (..*) |
recursiveSubscript(JSubscript) |
Recursive subscript segment (..[...]) |
| Method | Description |
|---|---|
index(int) |
Numeric index, negative values count from the end |
wildcard() |
All elements ([*]) |
property(String) |
Object property (['title']) |
slice(Integer, Integer) |
Slice with start and end ([0:1]) |
slice(Integer, Integer, Integer) |
Slice with start, end and step ([0:1:2]) |
filter(JPredicate<T>) |
Filter expression ([?(...)]) |
expr(String) |
Raw arithmetic/function expression subscript ([0*1]) |
| Method | Description |
|---|---|
eq / ne |
Equal / not equal |
gt / ge / lt / le |
Greater than / greater or equal / less than / less or equal |
like(prop, pattern) |
Wildcard match (*, ?) |
regex(prop, regex) |
Regular expression match |
startsWith / endsWith / contains |
Common string matches built on regex |
in(prop, values...) |
Membership test |
exists / notExists |
Property presence test |
and / or / not |
Logical composition |
custom(String) |
Raw JSONPath filter expression |
of(prop, operator, value) |
Generic predicate with an explicit operator |
| Method | Description |
|---|---|
getRawData() |
The raw result object |
getAsList() |
The result as a List (single values are wrapped) |
isList() |
Whether the result is a list |
| Constant | Symbol | Description |
|---|---|---|
JRoot.ROOT |
$ |
Root document |
JRoot.CURRENT |
@ |
Current node |
JQuick Path is compiled to pure Java bytecode and contains no JNI or platform-specific code, so the same artifact runs unchanged on:
| Platform | Status |
|---|---|
| Windows (x86_64 / ARM64) | Supported |
| Linux (x86_64 / ARM64 / LoongArch) | Supported |
| macOS (Intel / Apple Silicon) | Supported |
| Domestic OS compatible (Kylin, UOS, openEuler, Anolis) | Supported |
The ANTLR4 runtime, Javelin core and JQuick JSON dependencies are all pure Java, which means the library is domestic OS compatible without any recompilation and can be deployed in 信创 environments alongside mainstream domestic JDKs.
- Configuration reading — pull nested values out of JSON/YAML-derived configuration documents.
- API response processing — extract and reshape fields from third-party responses.
- Data conversion — map JSON fragments straight into Java beans with
as()/asList(). - Batch and pipeline jobs — filter, slice, sort and paginate large JSON collections before downstream processing.
- Untrusted payload inspection — recursive descent is bounded by
limit()/skip(), so a path expression cannot expand without limit over attacker-controlled JSON (a lightweight path traversal defense against resource exhaustion).
# Clone the repository
git clone https://github.com/paohaijiao/jquick-path.git
cd jquick-path
# Compile and install into the local repository
mvn clean install
# Package without running tests
mvn clean package -DskipTests
# Generate Javadoc
mvn javadoc:javadocThe ANTLR4 grammar is located in src/main/java/com/github/paohaijiao/parser (JQuickJSONPath.interp / generated lexer, parser and visitor sources).
JQuick Path is part of the JQuick open-source ecosystem:
| Project | Description |
|---|---|
| JQuick hub | Lightweight, configuration-driven API gateway |
| JQuick SQL | Declarative SQL query toolkit |
| JQuick JSON | Lightweight, high-performance JSON library for Java |
| Javelin | Expression evaluation engine and shared core |
| JQuick Banner | Console banner component used by the executor |
Contributions of all kinds are welcome — bug reports, feature requests, documentation improvements and pull requests.
- Fork the repository and create your branch from
master. - Keep the existing code style and add tests for new behaviour.
- Make sure
mvn clean installpasses before opening a pull request. - Describe your change clearly and reference the related issue.
Please open an issue first for large changes so we can align on the design.
JQuick Path is released under the Apache License, Version 2.0.
Copyright (c) [2025-2099] Martin (goudingcheng@gmail.com)
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.