Start to Play

This chapter is for people who want to understand TeaQL by using it first, before reading the modeling and customization internals.

The goal is simple:

• open a TeaQL-powered starter project,
• run a few meaningful queries,
• inspect the generated API shape,
• and build intuition for why TeaQL reads more like business language than infrastructure code.

What you should expect

When you start playing with TeaQL, you are not learning a large ORM framework API surface first. You are learning a model-shaped API.

That means the first useful actions are usually:

1. Open a starter domain model.
2. Inspect the generated request objects.
3. Try basic list queries and filters.
4. Load related objects.
5. Save or update a small object graph.
6. Observe how Q, E, and UserContext work together.

The fastest way to get value

The most productive first session is usually:

1. Pick a starter model that resembles your business domain.
2. Read a few generated request methods instead of reading all framework docs.
3. Run small query cases:
   • list data,
   • filter by one field,
   • add pagination,
   • load child objects,
   • try one aggregate query.
4. Compare the code with what you would normally write in JPA, QueryDSL, or MyBatis-style code.

TeaQL becomes much easier once you see that the generated API is the primary interface.

What you should look for

When evaluating a starter model, pay attention to:

• whether entity and field names match your business language,
• whether generated request methods already read like your use cases,
• whether multi-level loading stays readable,
• whether statistics and filtering remain composable,
• whether the resulting code is easy for business-oriented developers to review.

A minimal mental model

TeaQL usage is usually centered on three ideas:

• Q for request construction and querying,
• E for safe expressions and calculated conditions,
• UserContext for infrastructure, runtime behavior, permissions, localization, and customization.

For example:

SmartList<Order> orders =
    Q.orders()
        .filterByStatus(OrderStatus.CONFIRMED)
        .orderByCreateTimeDescending()
        .top(20)
        .executeForList(ctx);

Once that feels natural, you can move to richer scenarios:

• nested loads,
• request reuse,
• JSON-driven search,
• aggregation,
• graph save,
• server-driven UI,
• UserContext customization.

Suggested reading order

If you are new to TeaQL, this order works well:

1. This chapter: understand how to approach TeaQL by usage.
2. Service Behind the Scenes: understand what runtime pieces make the demo work.
3. Start from Example: build your own model when you are ready.
4. KSML Quick Guide: understand the model language.

What success looks like

After finishing the first two chapters, you should be able to answer:

• What does a TeaQL-generated API feel like in real code?
• How do request objects map to a business model?
• Where do runtime services stop and generated business APIs begin?
• Which starter shape is the best starting point for your team?

That is enough to start serious evaluation without getting buried in framework details too early.