Skip to main content

How to Choose a Model

Choosing a starting model is a design decision, not just a convenience choice.

The wrong model can still generate code, but the generated API will feel unnatural and your team will spend too much time compensating in services, wrappers, and custom workflow logic. The right model makes the generated API feel like it belongs to your business.

Choose by business shape, not by table similarity​

The first rule is simple:

  • do not choose a model only because it has similar tables,
  • choose a model because it has a similar business shape.

Business shape includes:

  • workflow complexity,
  • aggregate relationships,
  • status transitions,
  • reporting style,
  • external integration needs,
  • server-driven UI needs,
  • permission and localization requirements.

The main selection criteria​

Evaluate candidate models against these dimensions:

1. Domain vocabulary match​

The closer the business nouns are, the less translation work your team will do later.

Look for:

  • similar entity names,
  • similar actor names,
  • similar transaction names,
  • similar lifecycle states.

2. Workflow similarity​

This matters more than many teams expect.

If your product has:

  • multi-step approvals,
  • operational checklists,
  • pre/post processing,
  • field-level confirmation,
  • dynamic page transitions,

then a model with similar workflow objects is a better fit than one with similar tables but much simpler flows.

3. Aggregate complexity​

Compare:

  • number of child collections,
  • depth of nested loading,
  • number of cross-entity validations,
  • save/update graph complexity,
  • statistics and reporting needs.

If your system is graph-heavy, choose a graph-heavy reference model.

4. Query style​

Check whether the reference model naturally demonstrates the kinds of queries you need:

  • simple list queries,
  • search filters,
  • deep object loading,
  • aggregations,
  • reusable request fragments,
  • JSON-driven dynamic search.

5. Technical customization pressure​

Some systems need very little runtime customization. Others depend heavily on:

  • multi-tenant routing,
  • i18n,
  • access control,
  • audit rules,
  • read/write splitting,
  • external lock coordination,
  • infrastructure-specific integration.

If your project will rely heavily on these features, choose a model whose surrounding architecture already assumes strong UserContext customization.

A simple scoring method​

You can score candidate models from 1 to 5 on:

  • domain vocabulary,
  • workflow fit,
  • aggregate fit,
  • query fit,
  • reporting fit,
  • customization fit.

The best candidate is usually not the one with the highest table overlap. It is the one with the highest total business fit.

When to start from a smaller model​

Sometimes the right choice is not the closest large model. Start from a smaller model when:

  • your team is new to TeaQL,
  • the domain is still changing quickly,
  • your workflow is not settled yet,
  • you want to validate naming and aggregate structure first,
  • you need a low-risk prototype before full modeling.

This is often the better engineering choice than importing a very rich model too early.

When to start from a richer model​

Start from a richer model when:

  • your domain already has complex workflows,
  • you know you need service-request forms,
  • you know you need deep graph loading,
  • you know you need statistics and operational reporting,
  • you expect heavy runtime customization through UserContext.

In those cases, starting from an undersized model usually creates rework.

Red flags​

Do not choose a starting model if:

  • the entity names already feel wrong,
  • key workflows are missing,
  • most statuses would need to be replaced,
  • query patterns look unlike your real use cases,
  • the model is too CRUD-oriented for a workflow-heavy product,
  • the model is too workflow-heavy for a simple CRUD system.

If you see several of these, keep looking or start a fresh model from example.

For most teams, the most reliable path is:

  1. inspect a few existing models,
  2. choose one with the closest workflow and aggregate shape,
  3. rename it into your business language early,
  4. validate the generated API readability with real query cases,
  5. then move to your own KSML modeling.

Next step​

Once you know what a good starting model looks like, move on to:

That is the point where your team should stop evaluating and start modeling deliberately.