Python Business Scenarios

Use model-aware Assist for the exact Q, Request, Entity, and E API. The generator uses centralized snake_case plural names—for example order_statuses(), never a guessed order_statuss().

Shared query capability

Python 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.

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

Filter and paginate asynchronously

result = await (
    Q.customer_orders()
    .comment("Find matching orders")
    .with_order_number_containing("WEB-")
    .order_by_id_ascending()
    .offset(0)
    .limit(20)
    .purpose("Prepare the authorized order review page")
    .execute_for_list(context)
)

purpose() returns an executable wrapper. The wrapper, not the ordinary Request, exposes execute_for_list(context), execute_for_one(context), and execute_for_rows(context). Entity terminals return generated entities; the rows terminal preserves analytic records. Every execution method accepts exactly one runtime argument: context.

Select children

request = (
    Q.customer_orders()
    .comment("Load orders and their first lines")
    .select_order_line_list_with(
        Q.order_lines().order_by_id_ascending().limit(3)
    )
)
orders = await request.purpose(
    "Display the authorized order summary"
).execute_for_list(context)

The child Request is still a builder and does not execute independently. The SQL runtime implements per-parent Top-N with a partition/window plan.

Native statistics

groups = await (
    Q.schools()
    .with_name_containing("School")
    .group_by_school_type()
    .count_as("schoolCount")
    .sum_student_capacity_as("capacityTotal")
    .avg_student_capacity_as("capacityAverage")
    .min_student_capacity_as("capacityMinimum")
    .max_student_capacity_as("capacityMaximum")
    .comment("Aggregate schools by type")
    .purpose("Build the capacity dashboard")
    .execute_for_rows(context)
)
first_count = groups[0]["schoolCount"]

execute_for_rows preserves group keys and aliases as dictionaries. Aliases are not writable entity properties. Relation statistics decorate parent rows without loading all children:

types = await (
    Q.school_types_minimal()
    .select_code()
    .count_schools_as("schoolCount")
    .sum_student_capacity_of_schools_as("capacityTotal", Q.schools())
    .comment("Calculate statistics for every school type")
    .purpose("Render type summary cards")
    .execute_for_list(context)
)

COUNT, SUM, AVG, MIN, MAX, and GROUP BY remain database-native.

Include-all and matched-only facets

rows = await (
    Q.schools()
    .with_name_containing("Primary")
    .facet_by_school_type_as(
        "schoolTypes",
        Q.school_types_minimal()
        .select_code()
        .select_name()
        .count_schools_as("schoolCount"),
        include_all_facets=True,
    )
    .comment("Search schools and calculate type buckets")
    .purpose("Render the school search page")
    .execute_for_list(context)
)

buckets = rows.facet("schoolTypes")
first_count = buckets[0]["schoolCount"]

True keeps allowed zero-count values; use False for matched-only buckets. Restrict the allowed bucket domain on the child Request with Q.school_types_minimal().with_code_in("PRIMARY", "SECONDARY"). Several filter panels can share one outer query:

rows = await (
    Q.schools()
    .facet_by_school_type_as(
        "schoolTypes",
        Q.school_types_minimal().select_code().count_schools_as("count"),
        include_all_facets=True,
    )
    .facet_by_platform_as(
        "platforms",
        Q.platforms_minimal().select_name().count_schools_as("count"),
        include_all_facets=False,
    )
    .comment("Calculate school type and platform facets")
    .purpose("Render two authorized filter panels")
    .execute_for_list(context)
)

The main rows still contains Schools. rows.facet(name) reads a named Facet sidecar. Keep the same normalized filter on rows, counts, totals, and Facets when they describe the same screen.

Create and save

order = (
    Q.customer_orders()
    .comment("Create a validated order")
    .purpose("Persist an authorized checkout")
    .new_entity(context)
)
order.update_order_number("WEB-10001")
order = await order.audit_as("Create validated checkout order").save(context)

order.update_order_number("WEB-10001-R1")
order = await order.audit_as("Approve revised order number").save(context)

order.mark_for_deletion()
await order.audit_as("Cancel duplicate checkout order").save(context)

Loaded entities retain their optimistic version. A stale update is rejected rather than silently overwriting the current row. Query the complete current entity before a normal update. mark_for_deletion() marks a generated entity for audited deletion.

Expressions and loaded state

The generated E facade distinguishes loaded null from not loaded. Use it for safe expression evaluation, fallback, list size and traversal rather than reading a partial projection as though all fields were fetched.

Failure checklist

• A second execution argument is always wrong and should raise TypeError.
• Missing dataService in UserContext fails closed.
• Unknown JSON fields and unsupported operators must be rejected before Request construction.
• Save requires audit_as.
• Regenerate stale archives before investigating a missing or misspelled API.
• Run compileall/pytest and the selected async provider integration after regeneration.

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