Skip to main content

Swift Scenarios

Shared query capability​

Swift implements the complete seven-runtime native query profile: typed scalar and nested relation predicates, typed relation selection through explicit child Requests, projection and ordering, grouping and portable aggregates, relation statistics, facets, ordinary/continuous/ID-set pagination, and exact per-parent Top-N. Loaded relation plans remain explicit and bounded one level at a time. 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. The examples use the generated School Management fixture.

Query rows and relations​

An executable query carries non-empty comment and purpose before the terminal, then receives the single context argument:

let schools = try await Q.schools()
  .withNameContaining("Primary")
  .selectSchoolTypeWith(
    Q.schoolTypesWithMinimalFields().selectCode().selectName())
  .orderByIdDescending()
  .limit(20)
  .comment("Find primary schools with their type")
  .purpose("Render the authorized school directory")
  .executeForList(context)

schools is a SmartList<School>: it has normal Swift collection behavior and preserves TeaQL totals, aggregations, summaries, facets, and loaded state for compatible queries.

Aggregate and group​

let groups = try await 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")
  .executeForRows(context)

let firstCount = groups[0]["schoolCount"]

executeForRows preserves group keys and aliases as TeaQLRecord values. Aliases are not writable model fields. Relation statistics decorate each parent:

let types = try await Q.schoolTypesWithMinimalFields()
  .selectCode()
  .countSchoolsAs("schoolCount")
  .sumStudentCapacityOfSchoolsAs("capacityTotal", Q.schools())
  .comment("Calculate statistics for every school type")
  .purpose("Render type summary cards")
  .executeForList(context)

Include-all and matched-only facets​

let rows = try await Q.schools()
  .withNameContaining("Primary")
  .facetBySchoolTypeAs(
    "schoolTypes",
    Q.schoolTypesWithMinimalFields()
      .selectCode()
      .selectName()
      .countSchoolsAs("schoolCount"),
    includeAllFacets: true)
  .comment("Search schools and calculate type buckets")
  .purpose("Render the school search page")
  .executeForList(context)

let buckets = rows.facet("schoolTypes")
let firstCount = buckets?[0]["schoolCount"]

true retains allowed zero-count buckets; use false for matched-only values. Restrict the allowed bucket domain on the child Request with Q.schoolTypesWithMinimalFields().withCodeIn(["PRIMARY", "SECONDARY"]). Multiple named Facets can be attached to the same outer Request:

let rows = try await Q.schools()
  .facetBySchoolTypeAs(
    "schoolTypes",
    Q.schoolTypesWithMinimalFields().selectCode().countSchoolsAs("count"),
    includeAllFacets: true)
  .facetByPlatformAs(
    "platforms",
    Q.platformsWithMinimalFields().selectName().countSchoolsAs("count"),
    includeAllFacets: false)
  .comment("Calculate school type and platform facets")
  .purpose("Render two authorized filter panels")
  .executeForList(context)

The main list and its Facet sidecars are separate. Loaded relation plans remain explicit and bounded one level at a time in the current Swift runtime.

Create, update, and delete​

A mutation starts from a purpose-bearing generated request and saves with a non-blank audit reason. Keep the returned entity because it contains persistence results such as generated identity and the new version while preserving loaded/null/not-loaded state:

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

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

school.markForDeletion()
_ = try await school.auditAs("Retire the duplicate school record").save(context)

Query the complete current entity before a normal update so its optimistic version and Checker inputs are loaded.

Use generated constants and predicates rather than hard-coded identifiers. The exact generated method names remain the source of truth for the selected model.

Continue with Swift advanced data operations for composed Facets, analytics, per-parent Top-N, staged relation loading, and an audited update workflow.