Skip to main content

Association Loading

TeaQL selection APIs can shape object graphs directly in the query. This avoids manual N+1 loops and keeps relation intent visible in application code.

Q.orders().selectUser(
        Q.usersWithIdField().selectName()
    )
    .comment("Query orders").purpose("Load data")
    .executeForList(ctx);

The parent request says which relation to load. The nested request says which fields are needed from the related object.

Select a Child List​

Q.users().selectOrderList(
        Q.ordersWithId()
            .selectOrderId()
            .selectDate()
    )
    .comment("Query users").purpose("Load data")
    .executeForList(ctx);

Child list selection is explicit. The caller can decide whether the child list should load minimal fields, all fields, or a nested graph.

Limit Child Rows​

Q.ordersWithId()
    .selectLineItemList(
        Q.lineItemsWithId()
            .selectImageURL()
            .limit(3)
    )
    .comment("Query order item previews")
    .purpose("Render order list preview images")
    .executeForList(ctx);

This is useful for preview UI, such as an order page that only needs the first few item images.

Count Child Rows​

Q.ordersWithId()
    .countLineItems()
    .comment("Count order line items")
    .purpose("Render order list item counts")
    .executeForList(ctx);

Counting child rows lets a list page show summary information without loading every child row.

have and haveNo​

Use generated list-existence helpers when the business condition is about whether children exist.

Q.assets()
    .haveCylinders(
        Q.cylinders().whereContainerIsNull()
    )
    .unlimited()
    .comment("Query assets")
    .purpose("Load assets with unassigned cylinders");
Q.assets()
    .haveNoCylinders(
        Q.cylinders().whereContainerIsNull()
    )
    .unlimited()
    .comment("Query assets")
    .purpose("Load assets without unassigned cylinders");

These helpers express domain intent more clearly than hand-written joins or manual post-filtering.

Practical Rule​

Load the relation shape the page needs:

  • use scalar selectors for list pages;
  • use nested selectors for detail pages;
  • use limit for previews;
  • use count for child summaries;
  • use have / haveNo for existence conditions.