Skip to main content

TeaQL Quick Guide(Query)

This guide introduces the TeaQL generated query library, focusing on the two core expression families: Q and E.

1. Overview​

After TeaQL generates the client library, developers can use:

  • Q: Query expressions for data access
  • E: NULL-safe chained expressions for safe navigation and evaluation

These APIs are designed to be:

  • Strongly typed
  • Fluent and readable
  • Safe for complex domain models

2. Q Expressions (Query API)​

2.1 Basic Query Structure​

Q.<pluralObjectName>
 .<select | filter | aggregate | order | pagination>
 .executeForList(userContext)

Return a single object:

Q.<pluralObjectName>
 .<select | filter | aggregate | order | pagination>
 .execute(userContext)
  • executeForList(...) → returns multiple results
  • execute(...) → returns a single result
  • executeForStream(...) → returns a stream to handling large amount objects

3. Selection (Select)​

3.1 Default Selection​

Q.users().executeForList(userContext)
  • Selects all fields by default

3.2 Minimal Fields​

Q.usersWithMinimalFields().executeForList(userContext)
  • Selects only id and version

3.3 Select Variants​

MethodDescription
selectSelf()Select only the object itself, no expanded references
selectAll()Select all scalar fields (no lists)
selectAny()Select all fields including lists
select<Field>()Select a single field
select<List>()Select a list field

Examples​

Q.users().selectName().executeForList(userContext)

Select a related object with custom fields:

Q.orders().selectUser(
    Q.usersWithIdField().selectName()
)

Filter list fields during selection:

Q.users().selectOrderList(
    Q.orders().whichAmountGreaterThan(100)
)

3.4 Unselect (Exclude Fields)​

Exclude specific fields from the selection:

Q.articles().unselectContent().executeForList(userContext)

Useful for excluding large text or blob fields.

4. Filtering​

4.1 Exact Filtering (filterBy)​

Q.users().filterByStatus("ACTIVE")

Filter by object reference:

Q.orders().filterByUser(
    Q.users().whichUserGenderIsFemale()
)

4.2 Conditional Filtering (which)​

Generated based on field type:

Q.users().whichNameIsNull()
Q.users().whichAgeGreaterThan(18)

Generic operator form:

Q.users().whichName(Operator.contains, "admin")

4.3 List Existence (has<List>)​

Q.users().hasOrders()

Find users who have at least one order.

5. Aggregation & Statistics​

5.1 Count​

Q.orders().count()

Conditional count with alias:

Q.orders().count(
  "shippedCount",
  Q.orders().whichStatusAreShipped()
)

5.2 Other Aggregates​

Supported functions:

  • sum
  • max
  • min
  • avg

Example:

Q.orders().sumTotalAmount()

5.3 Group By​

Q.orders().count().groupByOrderStatus()

6. Sorting​

Sorting methods are generated per field.

Q.orders().orderByCreateTimeAscending()

Locale-aware sorting:

Q.users().orderByNameAscendingUsingGBK()

7. Pagination​

7.1 Top N​

Q.orders().top(10)

7.2 Offset​

Q.orders().offset(20, 10)
  • Start from index 20
  • Fetch 10 records
  • Index starts from 0

7.3 Page​

Q.orders().page(2, 20)
  • Page number starts from 1
  • 20 records per page

8. E Expressions (NULL-Safe Chain API)​

E provides safe navigation for deep object graphs without explicit null checks.

8.1 Safe Null Checking​

CustomOrderItem item = null;

if (
  E.customerOrderItem(item)
   .getCustomOrder()
   .getCustomer()
   .getContactName()
   .isNull()
) {
  // your logic
}

8.2 Safe Value Evaluation​

String name =
  E.customerOrderItem(item)
   .getCustomOrder()
   .getCustomer()
   .getContactName()
   .eval();
  • Returns null safely if any link in the chain is null

8.3 Safe Lambda Execution​

Execute logic only when value is empty:

E.customOrderItem(item)
 .getCustomOrder()
 .getCustomer()
 .getContactName()
 .whenIsEmpty(() -> {
     // do something
 });

Enum-specific helpers:

E.user(user)
 .getGender()
 .whenUserGenderIsFemale(() -> {
     // do something
 });

9. Summary​

  • Q: expressive, composable, type-safe query DSL
  • E: NULL-safe navigation and conditional execution
  • Designed to work seamlessly with KSML domain models
  • Ideal for complex enterprise systems with deep object graphs