findByJson / findWithJsonExpr Dynamic Query Guide
Evidence boundary: these Java API and parser rules are based on generated request/runtime source review. The current Java Golden Path remains blocked before runtime execution, so provider behavior, tenant isolation, resource limits, and chain-field cases require application integration tests. Start with the bounded Dynamic JSON Query recipe before exposing this mechanism to untrusted input.
Overview
TeaQL supports dynamic query construction from a JSON expression.
In generated request code this is commonly exposed as:
Q.orders().findWithJsonExpr(params)
In the core runtime, the JSON string is parsed and merged into the request through:
BaseRequest.internalFindWithJsonExpr(String jsonNodeExpr)
The dynamic JSON expression can add:
- Field filters
- Chain-field filters such as
customer.name - Ordering
- Offset/limit
- Page/page-size
This is useful when a frontend or generic admin API needs flexible search without writing one Java method for every possible filter combination.
Runtime Flow
The runtime flow is:
JSON string
-> DynamicSearchHelper.jsonFromString(...)
-> DynamicSearchHelper.mergeClauses(...)
-> addJsonFilter(...)
-> addJsonOrderBy(...)
-> addJsonLimiter(...)
-> addJsonPager(...)
-> request.comment("Query orders").purpose("Load data").executeForList(userContext)
In BaseService, dynamic search actions also use this mechanism:
if (ObjectUtil.isNotEmpty(parameter)) {
baseRequest.internalFindWithJsonExpr(parameter);
}
That means generated service endpoints can accept JSON search parameters and merge them into the generated request.
Basic Usage
Java
public WebResponse searchOrder(UserContext context, String params) {
SmartList<Order> orders = Q.orders().selectAll()
.findWithJsonExpr(params)
.orderByIdDescending()
.comment("Query orders").purpose("Load data")
.executeForList(context);
return WebResponse.of(orders);
}
This example assumes trusted tenant, actor, permissions, and request policy
were installed while UserContext was initialized. Runtime policy—not an
optional builder call in this method—must apply the tenant boundary before
provider execution.
JSON
{
"status": "SHIPPED",
"code": "ORD-2026",
"_orderBy": {
"field": "id",
"useAsc": false
},
"_page": 1,
"_pageSize": 20
}
Resulting Intent
status = SHIPPED
code contains ORD-2026
order by id desc
page 1, page size 20
JSON Filter Rules
findWithJsonExpr only applies a JSON field as a filter when the field is known to the current request.
Example:
{
"code": "ORD",
"status": "NEW"
}
Java request:
Q.orders().findWithJsonExpr(params)
.comment("Query orders").purpose("Load data")
.executeForList(userContext);
The dynamic helper checks whether code and status are fields of Order. Unknown fields are ignored for self-field filtering.
Value Type to Operator Rules
TeaQL infers the operator from the JSON value type.
| JSON Value | Inferred Operator | Example |
|---|---|---|
| String | CONTAIN by default | "code": "ORD" |
| Number | EQUAL | "id": 1001 |
| Boolean | EQUAL | "finished": false |
| Array of strings | IN | "status": ["NEW", "SHIPPED"] |
Array of objects with id | IN | "customer": [{"id": 1}, {"id": 2}] |
| Array with 2 values | BETWEEN for range-style values | "createTime": [1714521600000, 1717200000000] |
"__is_null__" | IS_NULL | "shipTime": "__is_null__" |
"__is_not_null__" | IS_NOT_NULL | "shipTime": "__is_not_null__" |
Important detail:
- Normal string values are treated as
CONTAIN. - A single-value string array such as
"name": ["product name"]is treated asINwith one value. In practice, this behaves like exact equality for that value. __is_null__and__is_not_null__are special string values.- Date/time fields convert array values into
Dateobjects when the target field is a date/time field.
String Contains
JSON
{
"code": "ORD-2026"
}
Meaning
Q.orders().withCode(Operator.CONTAIN, "ORD-2026")
Use this for fuzzy search boxes.
Exact Numeric and Boolean Filters
JSON
{
"id": 1001,
"finished": false
}
Meaning
Q.orders()
.filterByFinished(false)
.filterById(1001L)
.comment("Query orders")
.purpose("Explain JSON exact matches")
Numbers and booleans are treated as exact matches.
IN Filters
JSON
{
"status": ["NEW", "SHIPPED", "DELIVERED"]
}
Meaning
Q.orders()
.withStatus(Operator.IN, List.of("NEW", "SHIPPED", "DELIVERED"))
.comment("Query orders")
.purpose("Explain JSON IN filters")
This is useful for multi-select filters.
For exact matching with one string value, pass a single-value array:
{
"name": ["product name"]
}
This is parsed as IN with one value:
Q.products().withName(Operator.IN, "product name").comment("Query products").purpose("Load data")
For normal data, this is equivalent to:
name = product name
Object Reference Filters
If the field is an object reference, JSON objects can provide id.
JSON
{
"customer": {
"id": 10001
}
}
Meaning
The JSON value is unwrapped to the id:
Q.orders()
.filterByCustomer(Customer.refer(10001L))
.comment("Query orders")
.purpose("Explain reference filters")
For multiple references:
{
"customer": [
{"id": 10001},
{"id": 10002}
]
}
This is treated as an IN filter.
Null Checks
Is Null
{
"shipTime": "__is_null__"
}
Is Not Null
{
"shipTime": "__is_not_null__"
}
These values map to TeaQL Operator.IS_NULL and Operator.IS_NOT_NULL.
Range and Date/Time Filters
For date/time fields, a two-value array can be used as a range.
JSON
{
"createTime": [1714521600000, 1717200000000]
}
Meaning
Q.orders().withCreateTime(Operator.BETWEEN, startDate, endDate).comment("Query orders").purpose("Load data")
The helper unwraps date/time values into Date objects when the target field is a date/time field.
Use millisecond timestamps when passing date/time values through JSON.
Ordering
Use _orderBy.
Single Text Field
{
"_orderBy": "id"
}
This means:
order by id desc
The single text form defaults to descending because the helper calls:
addOrderBy(baseRequest, fieldValue.asText(), false)
Object Form
{
"_orderBy": {
"field": "createTime",
"useAsc": false
}
}
Multiple Order Rules
{
"_orderBy": [
{
"field": "status",
"useAsc": true
},
{
"field": "createTime",
"useAsc": false
}
]
}
Ordering only applies when the field is one of the current request's self fields.
Offset and Size
Use _start and _size for low-level offset/limit control.
JSON
{
"_start": 40,
"_size": 20
}
Meaning
offset 40
limit 20
This is useful for admin grids or infinite scrolling.
Page and Page Size
Use _page and _pageSize for page-based pagination.
JSON
{
"_page": 3,
"_pageSize": 20
}
Meaning
page 3, page size 20
offset = (3 - 1) * 20
The runtime calculates offset using the page number and request size.
Chain Field Filters
Dynamic JSON supports chain fields such as:
{
"customer.name": "Alice"
}
This means the filter is applied to the child request for customer.
Important Rule
The parent request must already contain the child sub-request.
Correct:
SmartList<Order> orders = Q.orders()
.selectCustomer()
.findWithJsonExpr("""
{
"customer.name": "Alice"
}
""").comment("Query orders").purpose("Load data")
.executeForList(userContext);
Better when customizing selected customer fields:
SmartList<Order> orders = Q.orders().selectCustomer(Q.customers().selectName())
.findWithJsonExpr(params)
.comment("Query orders").purpose("Load data")
.executeForList(userContext);
If the request has no customer sub-request, a chain-field filter cannot be attached safely.
Chain Field on Nested Collections
Example model:
Order
-> orderLineList
-> product
JSON:
{
"orderLineList.product.name": "Nitrogen"
}
Java:
SmartList<Order> orders = Q.orders().selectOrderLineList(
Q.orderLines()
.selectProduct(Q.products().selectName()))
.findWithJsonExpr(params)
.comment("Query orders").purpose("Load data")
.executeForList(userContext);
The chain path must match the selected request path:
orderLineList -> product -> name