Skip to main content

Statistics Query

Evidence status: API and intent-order review only. No current provider-backed result records totals, grouping/null behavior, numeric types, or an execution plan for this recipe.

Problem​

Produce a dashboard count or distribution without loading rows and aggregating them in application memory.

Java Path​

The examples explicitly narrow to one merchant for dashboard semantics. Tenant and permission isolation must already be enforced by the runtime policy in UserContext, including for aggregate and grouped queries; these filters are not the security boundary.

For a simple count:

Q.orders()
    .filterByMerchant(ctx.getMerchant())
    .count()
    .comment("Count merchant orders")
    .purpose("Display the order total on the dashboard")
    .executeForList(ctx);

For a grouped distribution, use the group method generated for the field:

Q.orders()
    .filterByMerchant(ctx.getMerchant())
    .count()
    .groupByOrderStatus()
    .comment("Count merchant orders by status")
    .purpose("Display the order status distribution")
    .executeForList(ctx);

Verify exact count/group methods in generated source.

Verification​

  • Seed a small dataset whose expected totals can be calculated by hand.
  • Confirm tenant, permission, date, and soft-delete constraints match the list page being summarized.
  • Test null or missing group values.
  • Confirm numeric types and rounding for sum/average operations.
  • Compare the generated statistic with a trusted database result during test.
  • Check execution plan and indexes for production-sized datasets.

When Not to Use This Shape​

Use a reporting-specific path when the query requires database-specific features, large analytical scans, or a separately governed warehouse. Keep its scope, parameters, audit intent, and verification explicit.

References​