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.

Shared query capability

Go implements the complete seven-runtime native query profile: typed scalar and relation predicates including nested child queries, typed relation selection, projection and ordering, grouping and portable aggregates, relation statistics, facets, ordinary/continuous/ID-set pagination, and exact per-parent Top-N. See the cross-language query contract for the capability catalog and audited source revision.

Start with the common data-operations guide for the distinction between row results, grouped analytics, relation metrics, and Facet sidecars.

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

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

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

groups, err := lib.Q.Schools().
    WithNameContaining("School").
    GroupBySchoolType().
    CountAs("schoolCount").
    SumStudentCapacityAs("capacityTotal").
    AvgStudentCapacityAs("capacityAverage").
    MinStudentCapacityAs("capacityMinimum").
    MaxStudentCapacityAs("capacityMaximum").
    Comment("Aggregate schools by type").
    Purpose("Build the capacity dashboard").
    ExecuteRecords(context)

Aliases are analytic result keys rather than writable entity fields. Relation statistics decorate each parent without loading every child:

types, err := lib.Q.SchoolTypesMinimal().
    SelectCode().
    CountSchoolsAs("schoolCount").
    SumStudentCapacityOfSchoolsAs("capacityTotal", lib.Q.Schools()).
    Comment("Calculate statistics for every school type").
    Purpose("Render type summary cards").
    ExecuteForList(context)

Aggregates are executed by the provider as SQL COUNT/SUM/AVG/MIN/MAX/GROUP BY.

Include-all and matched-only facets

rows, err := lib.Q.Schools().
    WithNameContaining("Primary").
    FacetBySchoolTypeAs(
        "schoolTypes",
        lib.Q.SchoolTypesMinimal().
            SelectCode().
            SelectName().
            CountSchoolsAs("schoolCount"),
        true,
    ).
    Comment("Search schools and calculate type buckets").
    Purpose("Render the school search page").
    ExecuteForList(context)

buckets, _ := rows.Facet("schoolTypes")
firstCount, _ := buckets.Data[0]["schoolCount"].TryU64()

Omitting the optional Boolean, or passing true, preserves allowed zero-count buckets. Pass false for matched-only values. Restrict the allowed bucket domain on the child Request with lib.Q.SchoolTypesMinimal().WithCodeIn([]string{"PRIMARY", "SECONDARY"}). Multiple Facets can be chained:

rows, err := lib.Q.Schools().
    FacetBySchoolTypeAs(
        "schoolTypes",
        lib.Q.SchoolTypesMinimal().SelectCode().CountSchoolsAs("count"),
        true,
    ).
    FacetByPlatformAs(
        "platforms",
        lib.Q.PlatformsMinimal().SelectName().CountSchoolsAs("count"),
        false,
    ).
    Comment("Calculate school type and platform facets").
    Purpose("Render two authorized filter panels").
    ExecuteForList(context)

The main rows.Data and rows.Facet(name) sidecars are separate. Clone or rebuild the same active filter for page rows, record count, totals, and Facets; do not let those outputs silently describe broader populations.

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

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

saved.UpdateOrderNumber("WEB-10001-R1")
saved, err = saved.AuditAs("Approve revised order number").Save(context)

saved.MarkForDeletion()
_, err = saved.AuditAs("Cancel duplicate checkout order").Save(context)

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.
• Execution without both non-empty comment and purpose fails; either order is valid.
• 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 use model-aware Assist for Request and Entity APIs. 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.

Continue with Go advanced data operations for a composed search, relation graph, analytics, Facet, and audited update workflow.