Java Business Scenarios

Shared query capability

Java implements the complete seven-runtime native query profile: typed scalar and nested relation predicates, typed relation selection through child Requests, 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; generated Assist remains the authority for model-specific Java method names.

The examples below use the generated School Management fixture. Start from the common data-operations guide for the difference between row queries, grouped analytics, relation statistics, and Facet sidecars.

Query rows and relations

SmartList<School> schools = Q.schools()
    .withNameContaining("Primary")
    .selectSchoolTypeWith(
        Q.schoolTypesWithMinimalFields().selectCode().selectName())
    .orderByIdDescending()
    .top(20)
    .comment("Find primary schools with their type")
    .purpose("Render the authorized school directory")
    .executeForList(context);

The child Request controls the relation projection. A reverse child list uses the generated select...With(childRequest) form in the same way; put its order and top(...) on the child Request to request per-parent Top-N.

Aggregate and group

Aggregate-only metrics describe the whole filtered population. Adding a group changes the result into one analytic row per group:

SmartList<School> groups = 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")
    .executeForList(context);

The aliases are analytic properties, not writable School fields. Java keeps grouped rows in groups.getAggregationResults(); for a single aggregate-only row, groups.aggregationProperties() provides an alias-to-value map. Relation statistics decorate parent rows without loading all children:

SmartList<SchoolType> types = Q.schoolTypesWithMinimalFields()
    .selectCode()
    .countSchoolsAs("schoolCount")
    .sumStudentCapacityOfSchoolsAs("capacityTotal")
    .comment("Calculate statistics for every school type")
    .purpose("Render type summary cards")
    .executeForList(context);

Facets

The outer Request defines the matching Schools. The nested SchoolTypeRequest defines each bucket's projection and metric:

SmartList<School> rows = Q.schools()
    .withNameContaining("Primary")
    .facetBySchoolTypeAs(
        "schoolTypes",
        Q.schoolTypesWithMinimalFields()
            .selectCode()
            .selectName()
            .countAs("schoolCount"),
        true)
    .comment("Search schools and calculate type buckets")
    .purpose("Render the school search page")
    .executeForList(context);

SmartList<SchoolType> buckets = rows.getFacet("schoolTypes");
Number count = buckets.get(0).getDynamicProperty("schoolCount");

The final Boolean controls bucket membership:

• true returns every allowed SchoolType, including zero-count buckets;
• false returns only SchoolTypes matched by the outer filter.

Restrict the allowed bucket domain on the child Request—for example, Q.schoolTypesWithMinimalFields().withCodeIn("PRIMARY", "SECONDARY")—without changing the outer School filter.

Multiple facets are independent named sidecars:

SmartList<School> rows = Q.schools()
    .withNameContaining("Primary")
    .facetBySchoolTypeAs(
        "schoolTypes", Q.schoolTypesWithMinimalFields().selectCode().countAs("count"), true)
    .facetByPlatformAs(
        "platforms", Q.platformsWithMinimalFields().selectName().countAs("count"), false)
    .comment("Calculate school type and platform facets")
    .purpose("Render two authorized filter panels")
    .executeForList(context);

Read the sidecars with rows.getFacet("schoolTypes") and rows.getFacet("platforms"). They do not replace rows; the main list still contains the matching Schools.

Create, update, and delete

School school = Q.schools()
    .comment("Construct a school")
    .purpose("Create the approved school record")
    .newEntity(context)
    .updateName("North School")
    .updateStudentCapacity(600)
    .updateActive(true)
    .auditAs("Create North School")
    .save(context);

school = school.updateStudentCapacity(640)
    .auditAs("Approve revised capacity")
    .save(context);

school.markForDeletion()
    .auditAs("Retire the duplicate school record")
    .save(context);

For a normal update, query the complete current entity first so its optimistic version and Checker inputs are loaded. Always retain the entity returned by save(context) when the call is used as an expression.

Use these maintained Java guides for concrete application work:

Need	Guide
Typed filters, ordering, paging, and execution	Query Quick Guide
Relation graph loading	Association Loading
Counts, grouping, and statistics	Statistics
Loaded/null/not-loaded traversal	Safe Expressions
Allowlisted dynamic input	Dynamic JSON Query
Audited create, update, and deletion	Create, Update, Delete
Server-driven view output	Server-driven UI

The seven-runtime contract defines the shared semantics. Generated model names remain application-specific; use Assist for exact methods.

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