Skip to main content

First Query

TeaQL Java query APIs are generated from the domain model. The entry point is Q, and the usual execution boundary is UserContext.

The main idea is simple:

Q.orders()
    .executeForList(ctx);

This creates an order request, applies the generated default behavior, executes it through the runtime context, and returns a list result.

Load All Rows for an Entity​

Q.orders().executeForList(ctx);

Use this only for small datasets or controlled examples. Production queries should usually filter, page, or select only the fields needed by the page.

Filter by Owner or Business Scope​

Q.orders()
    .filterByOwner(owner)
    .executeForList(ctx);

Filters should express business scope. In real systems this often includes merchant, tenant, owner, department, or current user visibility.

Select Only What the Page Needs​

Q.orders()
    .filterByOwner(webUser)
    .selectLineItemList(
        Q.lineItemsWithIdField().selectSkuName()
    )
    .executeForList(ctx);

Generated selection methods help keep response shape close to the page requirement. If a page only needs SKU names, do not load the full child object graph.

Query a Date Range​

Q.ordersWithIdField()
    .selectTitle()
    .filterByOwner(owner)
    .withCreateDateBetween(start, end)
    .executeForList(ctx);

The generated API exposes field-aware helpers such as withCreateDateBetween(...). These methods are easier to review than string-based field names.

Order Results​

Q.employees()
    .filterByMerchant(merchantId)
    .orderByNameAscendingUsingGBK()
    .executeForList(ctx);

Sorting methods are generated from fields. Locale-aware variants can be generated where the model and runtime support them.

Page Results​

Q.orders()
    .filterByOwner(owner)
    .offset(0, 10)
    .executeForList(ctx);

Pagination should be applied at the level the UI actually pages. Do not load a large list and page it in application memory.

What to Remember​

For first use, remember this pattern:

Q.entity()
  -> filter
  -> select
  -> order
  -> page
  -> execute

TeaQL keeps the query close to the domain model so developers and AI coding tools can understand intent without reading SQL or mapper files first.