How-to: Batch lookups

Every @lookupKey shape compiles to the same generator pattern: a VALUES(idx, key1, key2, …​) derived table joined against the target table on the key columns, ordered by idx. The output list is the same length as the input key list; unmatched keys produce null at their input position. Sorts do not apply: the order is the input order, full stop. Adding @asConnection on top of a @lookupKey field is rejected by the classifier (@asConnection on @lookupKey fields is invalid); pagination would shift positions and break the positional contract.

The Sakila example schema’s root lookups exercise the common shapes. The simplest is a single-scalar key:

A request filmById(film_id: ["1", "999999", "2"]) { title } returns three positions in input order: { "ACADEMY DINOSAUR" }, null, { "ACE GOLDFINGER" }. The empty-list case short-circuits before touching SQL: filmById(film_id: []) returns [] without dispatching a query.

Two @lookupKey arguments at the same call site correlate by index. customerById(customer_id: [ID] @lookupKey, store_id: ID @lookupKey) matches (customer_id[i], store_id[i]) per row; a scalar key broadcasts to every position, while two list keys must have the same length. The generator builds VALUES(idx, customer_id, store_id) JOIN customer USING (customer_id, store_id).

A request customerById(customer_id: ["1", "2", "4", "3"], store_id: "1") joins each customer id against store_id = "1" (broadcast) and returns four positions, null where a (customer_id, store_id) pair has no match. Two list arguments of unequal length are a runtime contract violation; wrap them in a @table input to get framework-level enforcement.

The argument-level @lookupKey shape is right when the keys are scalar lists at the call site and the caller can be trusted to supply correlated lists. When the pairing matters and you want the schema to enforce it, the input-type shape is preferable.

A @table-bound input type with @lookupKey on each leaf scalar lets the schema enforce that the keys travel together as one record. Each input element is one row of the lookup; the generator materialises VALUES(idx, film_id, actor_id) and joins on the full composite key.

The contract: each FilmActorKey is one row of the VALUES table, the join is on the full key set, and the output preserves input order. @lookupKey on the argument itself (key: [FilmActorKey!]! @lookupKey) is the carrier marker; the per-leaf @lookupKey annotations are what bind individual fields into the key tuple. A leaf without @lookupKey is excluded from the key set and resolves like any other @table-bound input field.

The same shape works for the @mutation directive’s UPDATE/DELETE/UPSERT row identification, but that is a distinct use of @lookupKey on INPUT_FIELD_DEFINITION covered in @mutation.

Two flavors of NodeId-driven lookup exist and they differ in failure mode:

Synthesised lookup-key path (@lookupKey on an [ID] arg whose target type carries @node). Each opaque base64 id decodes once per row at the arg layer to a Record<N> of the target’s primary-key columns; the generator emits VALUES(idx, pk_col1, pk_col2, …​) keyed on the decoded composite. Decode failure (a wrong-typename or malformed id) is a contract violation: it surfaces as GraphqlErrorException via CallSiteExtraction.NodeIdDecodeKeys.ThrowOnMismatch.

The output list is one element per opaque id, ordered by input position; the FilmActor type’s two-column primary key (actor_id, film_id) is encoded into each id and decoded into the VALUES row.

Same-table @nodeId arg path (@nodeId(typeName: T) on an [ID] arg whose T matches the field’s return type). Same lookup-by-id semantics, but with filter-style failure handling: a malformed id silently drops to "no row matches" via CallSiteExtraction.NodeIdDecodeKeys.SkipMismatchedElement. The classifier synthesises isLookupKey: true for this arm, so an explicit @lookupKey on the same arg is rejected (@nodeId already implies @lookupKey for same-table; the explicit directive is redundant).

filmsByNodeIdArg(ids: [<film_2>, "garbage", <film_4>]) returns two films at positions 0 and 2 and skips position 1 entirely; the malformed id never reaches the SQL pass. This contrasts with the @lookupKey + @nodeId(typeName:) case the generator rejects up front: pick one. For decode-side guidance on stable IDs, How-to: Global object IDs covers the encoder/decoder layout.

When a @lookupKey field hangs off a list parent and you want each parent to receive only its own filtered child list, combine @splitQuery with @lookupKey. The fetcher emits a flat SELECT joined against two VALUES tables: one for the per-parent dispatch keys (driven by the DataLoader), one for the caller-provided lookup keys.

Per request, the framework gathers every parent Film’s film_id, dispatches one batched query that joins film_actor against the per-parent key set and the caller’s actor_id list, then scatters rows back to their parents by idx. Each Film receives a list filtered by the caller’s actor keys; absence of an actor in a film yields no row (not null) at the child position, since this is a list output, not a positional one.

Without @splitQuery, the same [Actor!]! field with @lookupKey paginates across all parents in one wide SELECT: the lookup keys narrow the union of all parents' actors, not per-parent slices. That is rarely the right shape at the child level. The actors(actor_id: [Int!] @lookupKey) field on Film shows the inline (non-split) variant: it ships an inline correlated subquery per parent, useful when parent fan-out is small but wasteful at scale.

The same composition applies at deeper nesting depths through plain-object NestingField parents. Film.info.castByKey(actor_id: [Int!] @lookupKey) (info: FilmInfo, FilmInfo plain-object) treats the nested arm as just another SplitLookupTableField: same DataLoader shape, deeper path.

@splitQuery + @lookupKey + @asConnection is not a valid composition. The @asConnection rejection mentioned above applies to any @lookupKey field, including @splitQuery ones; combine @splitQuery + @asConnection (covered in connections) for per-parent paginated children, or @splitQuery + @lookupKey for per-parent narrowed batches, but not all three at once.

A @record parent reachable from @service is implicitly DataLoader-batched on its @table-typed children (classifyChildFieldOnResultType never inspects @splitQuery on record-parent table-bound fields). That same pattern admits @lookupKey: a RecordLookupTableField batches keyed by the parent record’s PK and narrowed by the caller-provided lookup keys. Explicit @splitQuery is redundant on these fields, not rejected.

The same VALUES-pair join applies; the difference is purely on the parent side, where the key extraction reads from the jOOQ record’s accessor rather than from a @table parent’s projected idx column. @sourceRow is the analogous escape hatch when the @record parent is a plain Java record (no FK metadata), but the lookup-key plumbing on the child side is the same.

← How-to index