Skip to main content

TeaQL is not just an ORM

· 2 min read
TeaQL Code Gen
TeaQL Code Gen
Core Contributor

It is tempting to describe TeaQL as an ORM because TeaQL knows about entities, relations, repositories, and databases.

That description is incomplete.

TeaQL is a generated business API layer. Persistence is one part of the system, but the main value is the generated domain language that sits above persistence.

What an ORM Usually Optimizes​

Most ORM discussions focus on mapping:

  • classes to tables;
  • fields to columns;
  • relations to joins;
  • objects to rows;
  • transactions to persistence sessions.

Those are real problems. TeaQL also needs to solve them. But large business systems have another repeated problem: the same business request is rebuilt again and again in controllers, repositories, DTOs, SQL, validators, and frontend response logic.

What TeaQL Optimizes​

TeaQL optimizes the business API surface.

It generates request APIs that can express:

  • selection;
  • nested relation loading;
  • filters;
  • list-existence queries;
  • pagination;
  • grouped statistics;
  • relation aggregates;
  • graph writes;
  • validation hooks;
  • runtime customization.

The generated API is meant to be read by backend engineers, domain engineers, reviewers, and AI coding tools.

Generated Business APIs​

An ORM might make it easy to load an Order.

TeaQL aims to make it clear how a complete order page is assembled:

Q.orders()
    .filterByMerchant(ctx.getMerchant())
    .selectCustomer(Q.customers().selectName())
    .selectLineItemList(Q.lineItems().selectSku().selectQuantity())
    .countLineItems()
    .orderByCreateTimeDescending()
    .page(1, 20)
    .executeForList(ctx);

The key is not whether this compiles to SQL. It does. The key is that the API names the business shape before the runtime turns it into storage operations.

Runtime Boundary​

TeaQL also treats runtime behavior as part of the model:

  • user context;
  • tenant and permission policy;
  • cache behavior;
  • distributed locks;
  • logging and metrics;
  • validation;
  • event dispatch;
  • database provider selection.

That is why TeaQL has a runtime layer instead of only a mapper layer.

Why This Helps AI​

AI tools should not need to guess SQL, join rules, table names, tenant filters, and response shapes from scattered code.

Generated APIs give AI tools a deterministic vocabulary:

  • call this field selector;
  • use this relation loader;
  • compose this query fragment;
  • execute through this runtime context;
  • do not bypass the provider.

That is a different goal from a traditional ORM.

The Short Version​

TeaQL uses persistence mapping, but it is not defined by persistence mapping.

It is a generated business API platform that keeps domain intent visible while allowing the runtime provider to change underneath.