Skip to main content

Explore Models

Evidence boundary: the public Model Explorer is a set of design guides. Its Java/Rust snippets are documentation-contract checked, but the corresponding KSML source models and compiled generated workspaces are not committed here. See the Examples and Evidence Index before treating a catalog scenario as runnable.

One of the best ways to understand TeaQL is to start from an existing model instead of starting from a blank file.

TeaQL is model-centric. The generated API quality depends heavily on the quality of the domain model. Exploring existing models helps you learn both:

  • how TeaQL expects a domain to be described,
  • and what kind of API shape a good model produces.

Why start from an existing model​

A good reference model gives you immediate examples of:

  • entity naming,
  • relationship structure,
  • constants and enumerations,
  • request patterns,
  • aggregate boundaries,
  • server-driven view objects,
  • query and statistics design.

It also helps your team avoid a common mistake: designing a model that mirrors tables rather than business concepts.

What to inspect first​

When reading an existing model, inspect these areas in order:

  1. Core entities
    • What are the main business objects?
    • Are they named in business language?
  2. Relationships
    • Which entities are parent-child?
    • Which ones are references?
    • Which relations are likely aggregate boundaries?
  3. Constants and states
    • Are statuses and scenario types modeled explicitly?
  4. Generated requests
    • Do the generated request methods read clearly?
    • Can common business filters be expressed naturally?
  5. Write scenarios
    • Can common save/update flows be represented without large mapping layers?
  6. Workflow objects
    • Are there view objects or service-request forms for workflow-heavy use cases?

What a strong reference model looks like​

A strong TeaQL model usually has these qualities:

  • stable business terms,
  • explicit entity relationships,
  • meaningful types and state values,
  • reasonable aggregate size,
  • clear distinctions between master data, transactional data, and workflow data,
  • enough metadata to support readable generated APIs.

If the model is strong, the generated code often reads almost like business pseudocode.

Questions to ask while exploring​

Use this checklist when reviewing a model:

  • Can developers guess the purpose of an entity from its name alone?
  • Do request methods already match the most common query scenarios?
  • Can complex graph loading stay readable?
  • Are business states modeled as constants instead of string literals spread across code?
  • Are workflow entry points modeled clearly?
  • Does the model support future customization through UserContext?

A practical evaluation loop​

For each candidate model, try a small set of representative cases:

Q.orders().top(20).comment("Query orders").purpose("Load data").executeForList(ctx);

Q.orders().filterByStatus(OrderStatus.CONFIRMED)
    .selectOrderLineList()
    .comment("Query orders").purpose("Load data")
    .executeForList(ctx);

Q.orders().groupByStatus()
    .count()
    .comment("Query orders").purpose("Load data")
    .executeForList(ctx);

Then ask:

  • Is this more readable than what your team writes today?
  • Would business-oriented developers understand it?
  • Can technical developers customize it without rewriting the architecture?

Use reference models as design material​

Do not treat existing models as templates to copy blindly.

Use them as design material for:

  • naming conventions,
  • aggregate design,
  • state modeling,
  • service-request patterns,
  • API readability targets.

Usually the best path is:

  1. start from a close reference model,
  2. remove what does not fit,
  3. rename aggressively to your real domain terms,
  4. then add the missing parts.

Common mistake​

The most common mistake is choosing a model only because the database tables look similar.

That is too shallow.

A better match is one where:

  • the workflow shape is similar,
  • the aggregate complexity is similar,
  • the reporting and statistics needs are similar,
  • the team structure is similar,
  • the future customization points are similar.

Next step​

After exploring a few models, the next decision is which one is the right starting point.

Continue with How to Choose a Model.