Skip to main content

Technical FAQ

Evidence boundary: Answers distinguish generated API shapes from executed combinations. Rust 4.1.1 with SQLite has runtime evidence; the current Java 1.525-RELEASE generated workspace is still blocked before execution. Inspect generated source for exact model-specific methods.

What is TeaQL?​

TeaQL is a domain-model-driven generator and runtime approach for Java and Rust. It emits typed domain APIs such as Java Q.orders() and Rust Q::orders(), with execution coordinated through the stack's UserContext.

Start with Introduction.

What are Q expressions?​

Q expressions are generated query builders. Depending on the emitted stack and model, they provide filtering, selection, sorting, pagination, aggregation, and execution. Read the generated request before selecting an exact method.

See TeaQL Quick Guide Query.

What are E expressions?​

In the Java API, E expressions provide null-tolerant chained access to values from loaded object graphs. This is not currently documented as a Java/Rust parity claim.

Example:

E.order(order).getCustomer().getName().eval()

See TeaQL Quick Guide Query.

How is TeaQL different from QueryDSL, Spring Data JPA, or MyBatis tools?​

TeaQL focuses on generated domain-language APIs, nested graph loading, polymorphic enhancement, entity save semantics, and UserContext-driven runtime customization.

See Code-Level Comparison Across Java Data Access Tools.

Can TeaQL load multi-level object graphs?​

Generated Java requests can expose nested select...(...) and select...List(...) calls. Names depend on the model.

Q.orders()
    .selectCustomer()
    .selectOrderLineList(Q.orderLines().selectProduct())
    .comment("Query orders")
    .purpose("Load the order graph for the detail view")
    .executeForList(userContext);

See TeaQL Quick Guide Query.

Can TeaQL customize nested child queries?​

Where the generated relation selector accepts a child request, it can shape child filtering, selection, sorting, and limits inline. Confirm the emitted signature and provider behavior.

Q.orders().selectOrderLineList(
    Q.orderLines()
        .withQuantityGreaterThan(0)
        .orderByDisplayOrderAscending()
).comment("Query orders").purpose("Load data")

See Code-Level Comparison.

What is enhanceChild(...) used for?​

Some generated Java request APIs expose enhanceChild(...) for polymorphic child selection. Treat the linked example as model-specific and inspect the current generated signature before use.

See Code-Level Comparison.

How do I create, update, or delete objects?​

Use generated entity update methods and declare audit intent before saving. For deletion, mark the object for removal, declare the business action, and save it.

order.updateStatus(OrderStatus.SHIPPED)
    .auditAs("Ship customer order")
    .save(userContext);

See Creating, Updating, Deleting Objects.

What is UserContext?​

UserContext is TeaQL's runtime execution boundary. An application can resolve identity, tenant, request intent, policy, audit, localization, routing, and infrastructure services through it; those controls are not automatically correct merely because a context object exists.

See Understand UserContext.

Why should I customize CustomUserContext?​

Customize CustomUserContext when your project needs tenant isolation, permission checks, ID generation, cache policy, audit trail, distributed locking, read/write splitting, i18n, or logging behavior.

See Understand UserContext.

How do I implement tenant or permission rules?​

Put tenant and permission helpers in CustomUserContext, then use them from services and request wrappers. Do not scatter these checks across controllers.

See TeaQL Best Practices in Spring Boot / Spring Cloud.

The current Java request API documents findWithJsonExpr(params) for merging accepted dynamic JSON fields into a generated request. Validate size, fields, sorting, and pagination, then apply trusted server-side scope separately.

See findByJson / findWithJsonExpr Dynamic Query Guide.

No. A normal string is treated as CONTAIN.

For exact matching, use a single-value array:

{
  "name": ["product name"]
}

See findByJson / findWithJsonExpr Dynamic Query Guide.

Can dynamic JSON search filter nested fields?​

Yes, but the nested request must already be selected.

Q.orders()
    .selectCustomer(Q.customers().selectName())
    .findWithJsonExpr("{\"customer.name\":\"Alice\"}")
    .comment("Query orders")
    .purpose("Load orders for matching customer names")
    .executeForList(userContext);

See findByJson / findWithJsonExpr Dynamic Query Guide.

Should I trust frontend JSON filters for tenant or permission scope?​

No. Keep trusted filters in Java, usually through UserContext.

Q.orders()
    .findWithJsonExpr(params)
    .filterByMerchant(userContext.getMerchant())
    .comment("Query tenant orders")
    .purpose("Render the current merchant order list")
    .executeForList(userContext);

See findByJson / findWithJsonExpr Dynamic Query Guide.

How do I customize internal IDs?​

Implement an internal ID generator and expose it through CustomUserContext.

See Custom Internal Id Generator.

How do I customize business-facing IDs?​

Use a common ID generator for values such as order numbers, invoice numbers, or customer numbers.

See Custom Common Id Generator.

Can TeaQL integrate project-specific cache behavior?​

Yes. Put cache key generation, TTL rules, invalidation, and provider access behind CustomUserContext or a service resolved from it.

See Cache Customization.

Does TeaQL support internationalization?​

TeaQL Java documents translator extension points, and projects can customize language selection, fallback, labels, and messages. Verify the concrete translator set in the resolved runtime rather than treating it as a stable cross-stack list.

See i18n Customization.

Which natural languages are supported?​

The available languages depend on the resolved Java runtime and project extensions. Inspect the translator implementations in the pinned version and test locale selection and fallback. No Rust parity claim is made here.

See i18n Customization.

How do I debug SQL generated by TeaQL?​

For a Java application that deliberately registers the documented dynamic-log controls, enable scoped markers such as SQL_SELECT or SQL_UPDATE. Protect administrative log-control endpoints and avoid exposing sensitive parameters.

See Debugging - Dynamic Log Controll and Logging Customization.

Can TeaQL use distributed locks?​

TeaQL Java can integrate an application-provided distributed-lock service through CustomUserContext. The application remains responsible for lock ownership, timeout, fencing, failure, and provider testing.

See Distributed Locking.

Can TeaQL split read and write requests?​

TeaQL Java exposes read/write routing extension points through UserContext. Correct replica consistency, transaction routing, failover, and monitoring remain application/provider responsibilities.

See Split Read & Write Requests.

Can TeaQL generate audit records?​

TeaQL exposes mutation audit intent and runtime audit extension points. An application must still verify actor identity, event emission, sink durability, masking, access, retention, and failure behavior.

See Custom Audit Trail.

Which databases can TeaQL work with?​

Current source and architecture pages contain multiple Java database modules and Rust provider families. Only Rust SQLite 4.1.1 with rusqlite 0.32 has the maintained provider-backed execution evidence; a module or crate name is not a support commitment.

See Database Provider Compatibility.

Can TeaQL ensure schema and indexes?​

Schema preparation is provider- and version-specific. Java 1.525-RELEASE exposes SchemaExecutor.ensureSchema(...); it does not expose a verified universal teaql.ensureSchema property. The current generated Rust schema-mode branches also require verification before treating dry-run as a safety boundary.

See Configuration Properties and Database Provider Compatibility.

Use:

Controller -> Service -> Util

Controllers adapt protocols, services own transaction boundaries, and util classes hold reusable TeaQL query/business functions.

See TeaQL Best Practices in Spring Boot / Spring Cloud.

Should controllers contain TeaQL business logic?​

Usually no. Keep controllers thin and delegate to services or util methods.

See TeaQL Best Practices in Spring Boot / Spring Cloud.

How should a team divide TeaQL work?​

Product managers or architects can own modeling, technical developers customize UserContext, and business developers use Q and E to implement services and controllers.

See Internal Team Mode and Distributed Delivery Mode.

Is TeaQL suitable for compliance-heavy systems?​

TeaQL mechanisms can support a compliance-oriented design, but they do not certify an application or replace authorization, audit-sink, data-governance, operational, and independent compliance controls.

See GDPR Guide, PCI DSS Guide, and Global KYC/KYB Guide.