Skip to main content

Go Business Scenarios

The examples use names verified in a generated Order Search domain. Your model produces its own methods; inspect q.go, the entity package's request.go, entity.go, and e.go before copying a name.

Filter, sort, and paginate​

orders, err := lib.Q.CustomerOrders().
    Comment("Find matching orders").
    WithOrderNumberContaining("WEB-").
    OrderByIdAsc().
    Offset(0).
    Limit(20).
    Purpose("Prepare the authorized order review page").
    ExecuteForList(ctx)

Purpose returns *ExecutableCustomerOrderRequest; execution is not available on the ordinary builder. Comment may be set earlier, with filters and projections between the two intent calls.

Generated scalar operators include equality, inequality, IN, range, contains, starts-with and ends-with where the field type supports them. Validate dynamic JSON against an explicit allowlist before choosing any generated method.

Load a relation​

orders, err := lib.Q.CustomerOrders().
    Comment("Load orders and their first lines").
    SelectOrderLineListWith(
        order_line.NewOrderLineRequest().OrderByIdAsc().Limit(3),
    ).
    Purpose("Display the authorized order summary").
    ExecuteForList(ctx)

Use the generated relation method rather than issuing application SQL. Per-parent limits use the runtime partition/window path when supported by the SQL provider.

Count, sum, and group​

rows, err := lib.Q.CustomerOrders().
    Comment("Group authorized order totals by status").
    GroupByStatus().
    CountAs("recordCount").
    SumTotalAmountAs("totalAmount").
    Purpose("Build the status facet").
    ExecuteRecords(ctx)

Aggregates are executed by the provider as SQL COUNT/SUM/GROUP BY. Clone or rebuild the same active filter for page rows, record count, totals and facets; do not let those outputs silently use broader filters.

Create, update, and delete​

Create through the executable Request so context and generated entity type stay explicit:

order := lib.Q.CustomerOrders().
    Comment("Create a validated order").
    Purpose("Persist an authorized checkout").
    NewEntity(ctx)

order.UpdateOrderNumber("WEB-10001")
err := order.AuditAs("Create validated checkout order").Save(ctx)

For updates, query the entity first so its original version is loaded. Save uses that expected version and rejects a stale copy. Use the generated delete marker or mutation API found in the entity source; do not guess its name.

Context and audit checks​

  • ExecuteForList receives only *runtime.UserContext.
  • A missing data service fails closed.
  • Purpose without an earlier non-empty comment fails before execution.
  • Save without AuditAs fails.
  • Tenant, actor, permissions and policy must be installed by trusted context initialization.
  • Runtime mutation audit and the masked application audit sink are separate paths.

Failure checklist​

Run go test ./..., then inspect generated Request and Entity source. Common failures are an old generated workspace, a stale runtime replacement, missing relation metadata, an unregistered dataService, or an application using a guessed plural name.