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()
    .comment("Query orders")
    .purpose("Load data")
    .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()
    .comment("Query orders")
    .purpose("Load data")
    .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)
    .comment("Query orders").purpose("Load data")
    .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()
    )
    .comment("Query orders").purpose("Load data")
    .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)
    .comment("Query orders")
    .purpose("Load orders in a date range")
    .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()
    .comment("Query employees").purpose("Load data")
    .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)
    .comment("Query orders").purpose("Load data")
    .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
  -> comment and purpose
  -> 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.