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().comment("Query users").purpose("Load data").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().comment("Query users").purpose("Load data").executeForList(userContext)

Select a related object with custom fields:

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

Filter list fields during selection:

Q.users().comment("Query users").purpose("Load data").selectOrderList(
    Q.orders().comment("Query orders").purpose("Load data").withAmountGreaterThan(100)
)

3.4 Unselect (Exclude Fields)​

Exclude specific fields from the selection:

Q.articles().comment("Query articles").purpose("Load data").unselectContent().comment("Query orders").purpose("Load data").executeForList(userContext)

Useful for excluding large text or blob fields.

4. Filtering​

4.1 Exact Filtering (filterBy)​

Q.users().comment("Query users").purpose("Load data").filterByStatus("ACTIVE")

Filter by object reference:

Q.orders().comment("Query orders").purpose("Load data").filterByUser(
    Q.users().comment("Query users").purpose("Load data").withUserGenderIsFemale()
)

4.2 Conditional Filtering (which)​

Generated based on field type:

Q.users().comment("Query users").purpose("Load data").withNameIsNull()
Q.users().comment("Query users").purpose("Load data").withAgeGreaterThan(18)

Generic operator form:

Q.users().comment("Query users").purpose("Load data").withName(Operator.contains, "admin")

4.3 List Existence (has<List>)​

Q.users().comment("Query users").purpose("Load data").hasOrders()

Find users who have at least one order.

5. Aggregation & Statistics​

5.1 Count​

Q.orders().comment("Query orders").purpose("Load data").count()

Conditional count with alias:

Q.orders().comment("Query orders").purpose("Load data").count(
  "shippedCount",
  Q.orders().comment("Query orders").purpose("Load data").withStatusAreShipped()
)

5.2 Other Aggregates​

Supported functions:

  • sum
  • max
  • min
  • avg

Example:

Q.orders().comment("Query orders").purpose("Load data").sumTotalAmount()

5.3 Group By​

Q.orders().comment("Query orders").purpose("Load data").count().groupByOrderStatus()

6. Sorting​

Sorting methods are generated per field.

Q.orders().comment("Query orders").purpose("Load data").orderByCreateTimeAscending()

Locale-aware sorting:

Q.users().comment("Query users").purpose("Load data").orderByNameAscendingUsingGBK()

7. Pagination​

7.1 Top N​

Q.orders().comment("Query orders").purpose("Load data").top(10)

7.2 Offset​

Q.orders().comment("Query orders").purpose("Load data").offset(20, 10)
  • Start from index 20
  • Fetch 10 records
  • Index starts from 0

7.3 Page​

Q.orders().comment("Query orders").purpose("Load data").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