Skip to main content

Technical FAQ

What is TeaQL?​

TeaQL is a domain-model-driven Java data access and runtime framework. It generates readable APIs such as Q.orders() and executes them through UserContext.

Start with Introduction.

What are Q expressions?​

Q expressions are generated query builders. Use them for filtering, selection, sorting, pagination, aggregation, and execution.

See TeaQL Quick Guide Query.

What are E expressions?​

E expressions are NULL-safe chained expressions for reading values from loaded object graphs.

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?​

Yes. Use nested select...(...) and select...List(...) calls.

Q.orders()
    .selectCustomer()
    .selectOrderLineList(Q.orderLines().selectProduct())
    .execute(userContext)

See TeaQL Quick Guide Query.

Can TeaQL customize nested child queries?​

Yes. Child list selection accepts another request, so you can filter, select, sort, and limit children inline.

Q.orders().selectOrderLineList(
    Q.orderLines()
        .withQuantityGreaterThan(0)
        .orderByDisplayOrderAscending()
)

See Code-Level Comparison.

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

enhanceChild(...) is used to enrich polymorphic child data, for example loading different fields for check reports and analysis reports under one base report list.

See Code-Level Comparison.

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

Use entity update methods and save(userContext). For deletion, mark the object for removal and save it.

order.updateStatus(OrderStatus.SHIPPED).save(userContext);

See Creating, Updating, Deleting Objects.

What is UserContext?​

UserContext is TeaQL's runtime execution boundary. It carries user, tenant, request, permission, cache, audit, i18n, logging, routing, and infrastructure behavior.

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.

Yes. Use findWithJsonExpr(params) to merge JSON filters, sorting, offset/limit, and page/page-size into a generated request.

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\"}")

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())

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?​

Yes. TeaQL includes built-in natural language translators and projects can customize language selection, fallback, labels, and messages.

See i18n Customization.

Which natural languages are supported?​

TeaQL includes translator classes for English, Chinese, Traditional Chinese, German, French, Spanish, Portuguese, Japanese, Korean, Arabic, Thai, Indonesian, Filipino, and Ukrainian. Projects can add custom translators.

See i18n Customization.

How do I debug SQL generated by TeaQL?​

Enable dynamic log markers such as SQL_SELECT or SQL_UPDATE.

See Debugging - Dynamic Log Controll and Logging Customization.

Can TeaQL use distributed locks?​

Yes. Expose distributed lock behavior through CustomUserContext and use it around critical business operations.

See Distributed Locking.

Can TeaQL split read and write requests?​

Yes. Route reads and writes through policies attached to CustomUserContext.

See Split Read & Write Requests.

Can TeaQL generate audit records?​

Yes. Audit identity and request metadata should come from CustomUserContext, and audit events can be recorded around saves or business operations.

See Custom Audit Trail.

Which databases can TeaQL work with?​

TeaQL targets multiple relational and analytical databases, including PostgreSQL, MySQL, Oracle, MS SQL Server, IBM Db2, SAP HANA, SQLite, DuckDB, and Snowflake.

See Data Service Supported.

Can TeaQL ensure schema and indexes?​

Yes. TeaQL can support model-driven schema and index preparation depending on the target database and project configuration.

See Data Service Supported.

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 Onshore/Offshore Mode.

Is TeaQL suitable for compliance-heavy systems?​

Yes. TeaQL's audit, access control, query consistency, and centralized UserContext customization help with compliance-oriented designs.

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