Computed shape fields — AQL

Computed shape fields

A shape field can be assigned an inline expression using :=. A common use is a sub-select that pulls related data without defining a link in the schema.

A sub-select follows the same cardinality rule as a top-level query: plain select returns a single object (or null), and multi select returns a JSON array.

1
select User {
2
  id,
3
  email,
4
  posts := (multi select Post { id, title } filter .author.id = User.id),  # array
5
  primary_org := (select Organization { id, name } filter .owner = User.id) # single object or null
6
}

A multi select compiles to a correlated json_agg subquery (empty array — never null — when nothing matches); a plain select compiles to row_to_json over a LIMIT 1 inner query (null when nothing matches). The outer type name (User.id) is a qualified reference — it resolves to the outer query’s alias.

1
  (SELECT COALESCE(json_agg(row_to_json(p_posts_sub)), '[]')
2
   FROM (SELECT p.id AS id, p.title AS title FROM "post" p WHERE p.author = u.id) p_posts_sub) AS posts,
3
  (SELECT row_to_json(o_primary_org_sub)
4
   FROM (SELECT o.id AS id, o.name AS name FROM "organization" o WHERE o.owner = u.id LIMIT 1) o_primary_org_sub) AS primary_org

Computed shape fields with no sub-select compile as scalar expressions (including arithmetic and null coalescing):

1
select OrderItem {
2
  id,
3
  unit_price,
4
  quantity,
5
  discount,
6
  subtotal := .unit_price * .quantity,
7
  total := (.unit_price * .quantity) - .discount,
8
  label := .name ?? .sku
9
}

Projecting a field from a subquery

A subquery normally resolves to a row’s id. Append .field to project a single column instead — the subquery then behaves as a scalar and can be combined with other operators. This works anywhere an expression is allowed, including insert / update assignment values:

1
update Repo filter .id = $id<uuid> set {
2
  installation_id :=
3
    (select GithubInstallation filter .id = $installation_id<uuid>?).installation_id
4
      ?? .installation_id
5
}

1
UPDATE "repo" r SET
2
  installation_id = COALESCE(
3
    (SELECT g.installation_id FROM "github_installation" g
4
     WHERE ($1::UUID IS NULL OR g.id = $1) LIMIT 1),
5
    r.installation_id)
6
WHERE r.id = $2

The projected field must be a scalar property or a link on the subquery’s type; an unknown field is a compile error.

An optional <Type> after the projection casts the result (see Casts & types — the cast works on any operand):

1
installation_id := (select GithubInstallation filter .id = $id<uuid>).installation_id<str> ?? .installation_id

1
installation_id = COALESCE(((SELECT g.installation_id FROM ... LIMIT 1))::TEXT, r.installation_id)

Note: field projection is available in generated queries (both Go and TypeScript output, which share the compiler). The TypeScript runtime aql tagged-template — for queries assembled dynamically at runtime — does not yet parse projections or ?? in assignment values.