Skip to main content

Swift Advanced Data Operations

The generated Swift API supports the shared data-operation profile, while each loaded relation plan is deliberately bounded to one level. Compose deeper screens in explicit stages so loaded-state and query cost stay visible.

Search page with rows and two facets​

let rows = try await Q.schools()
  .withNameContaining("Primary")
  .selectSchoolTypeWith(
    Q.schoolTypesWithMinimalFields().selectCode().selectName())
  .selectPlatformWith(Q.platformsWithMinimalFields().selectName())
  .facetBySchoolTypeAs(
    "schoolTypes",
    Q.schoolTypesWithMinimalFields()
      .withCodeIn(["PRIMARY", "SECONDARY"])
      .selectCode().selectName().countSchoolsAs("schoolCount"),
    includeAllFacets: true)
  .facetByPlatformAs(
    "platforms",
    Q.platformsWithMinimalFields().selectName().countSchoolsAs("schoolCount"),
    includeAllFacets: false)
  .orderByIdDescending()
  .limit(50)
  .comment("Search schools with dashboard facets")
  .purpose("Render the authorized operations dashboard")
  .executeForList(context)

let typeBuckets = rows.facet("schoolTypes")
let platformBuckets = rows.facet("platforms")

The SchoolType Facet retains allowed zero-count buckets. The Platform Facet is matched-only; both remain sidecars to the primary School list.

Staged graph and per-parent Top-N​

The first stage loads each Platform's three largest Schools. This is one bounded relation level and the child limit applies per Platform:

let platforms = try await Q.platforms()
  .selectName()
  .selectSchoolListWith(
    Q.schools()
      .selectName()
      .selectStudentCapacity()
      .orderByStudentCapacityDescending()
      .limit(3))
  .comment("Load each platform and its three largest schools")
  .purpose("Render the authorized platform capacity review")
  .executeForList(context)

If the screen also needs SchoolType details, collect the loaded SchoolType IDs and issue a second typed Request:

let types = try await Q.schoolTypesWithMinimalFields()
  .withIdIn(schoolTypeIDs)
  .selectCode()
  .selectName()
  .comment("Load types referenced by the selected schools")
  .purpose("Complete the authorized platform capacity review")
  .executeForList(context)

This is intentional staged hydration, not a claim that one Swift relation plan recursively loads an arbitrary-depth graph.

Grouped and relation analytics​

let distribution = try await Q.schools()
  .groupBySchoolType()
  .countAs("schoolCount")
  .sumStudentCapacityAs("capacityTotal")
  .avgStudentCapacityAs("capacityAverage")
  .comment("Aggregate school capacity by type")
  .purpose("Build the authorized capacity report")
  .executeForRows(context)

let cards = try await Q.schoolTypesWithMinimalFields()
  .selectCode().selectName()
  .countSchoolsAs("schoolCount")
  .sumStudentCapacityOfSchoolsAs("capacityTotal", Q.schools())
  .comment("Calculate type-level school metrics")
  .purpose("Render the authorized type cards")
  .executeForList(context)

The first result contains TeaQLRecord analytic rows. The second retains typed SchoolTypes and adds named, read-only relation metrics.

Audited read-modify-save​

guard var school = try await Q.schools()
  .withIdIs(schoolID)
  .selectPlatformWith(Q.platformsWithMinimalFields().selectName())
  .selectSchoolTypeWith(Q.schoolTypesWithMinimalFields().selectCode())
  .comment("Load the complete school for capacity approval")
  .purpose("Apply an authorized capacity revision")
  .executeForOne(context)
else { throw AppError.schoolNotFound }

school.updateStudentCapacity(newCapacity)
school = try await school
  .auditAs("Approve revised student capacity")
  .save(context)

Load all Checker/Fix inputs and retain the returned entity so subsequent saves use the authoritative optimistic version.