Skip to main content

Explore a Starter Application

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.

Open the Agent Task Builder to choose a scenario, or prepare the downloadable school model to work through the commands yourself. Tasks run in your own development environment.

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. Request model-aware Assist for the entity and query you want to use.
  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 focused Assist for a few request methods before writing application code.
  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)
.comment("Query orders").purpose("Load data")
.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.