How-to: Handle services

When a field takes an input-type argument, the framework passes the input through as a single Java parameter, not flattened into per-field parameters. A field declared as

binds to

where FilmCreateInput is a Java class whose components correspond to the input-type’s fields. The backing class is reflected from the createFilm method’s parameter type; graphql-java does the input deserialisation; the framework just hands the resulting object to the method. The Java side reads in.title(), in.languageId(), etc.

When the input type’s producer (the service method parameter) is a typed Java class, the backing class is the canonical home for the input shape. When the input flows into no typed parameter, the framework’s input projection produces an ImmutableMap<String, Object> that the Java method must read by key; the typed-class shape is strongly preferred, so declare the service method’s parameter as the typed input class.

argMapping: works for input arguments the same way it works for scalars: argMapping: "input: in" rebinds the Java parameter name.

It can also reach inside the input: the right-hand side of an entry may walk into nested input fields with dot-separated segments, so a method that wants two scalars out of a wrapper input can have them without the wrapper.

Binding a parameter to a nested input field is the canonical description of the path form. What stays outside @service’s surface is renaming the fields of the input type as seen by its backing class; that is the input type’s own concern (see @field` on input fields).

Note the axis argMapping: works on: it rebinds method parameters, scattering one input’s fields across several of them. Grouping input fields under a nested type, below, works on the input’s members instead: one bean parameter, whose fields are reached through the nesting. The two do not overlap.

An input type’s fields can be clustered under nested input objects for the client’s benefit while the backing Java class stays flat. A nested input field with no matching member on the backing class is treated as a grouping: its own fields bind against the backing class as if they had been declared at the top level of the enclosing input.

The client sends duration: { length: 120 }; the method receives length = 120. The grouping is wire-format ergonomics only and has no effect on the Java side.

A nested input field whose name does match a member of the backing class keeps binding to that member as a nested object, so adding a matching member is how you opt a group back out of flattening. A group that is absent or null leaves every field under it null, the same as omitting those fields would.

Rejected shapes, each named at build time: a grouping input that reaches itself; a list-shaped grouping input (there is nothing for a list of groups to flatten onto); two fields that bind to the same member, whether or not a group is involved; and a nested input field carrying @field(name:) or @nodeId whose named member does not exist, which is reported as the missing member rather than silently flattened.

When the service method’s parameter is a jOOQ-generated TableRecord rather than a hand-written class, the input binds on the column axis instead of the Java-member axis: each plain input field names a column with @field(name:), and a @nodeId field decodes an identity into the record’s key columns. The framework builds the record for you and hands it to the method already populated.

Each field loads independently and only when the client actually sent it, so jOOQ’s per-column changed flag stays honest: an omitted field leaves its column untouched (and out of the INSERT / UPDATE your service runs), an explicitly-sent null writes SQL NULL.

contextArguments: is for values that aren’t GraphQL arguments but live on the per-request GraphQLContext: tenant IDs, authenticated principals, feature-flag snapshots. Declaring contextArguments: ["tenantId"] in the directive means the framework looks up env.getGraphQlContext().get("tenantId") and threads the result as an additional Java parameter named tenantId:

The runtime contract is "your servlet or webfilter must place each named value on the request context before the resolver runs". The framework does not validate context arguments at startup; a missing context value yields null at call time, which most code will then throw on. The classifier does check that the parameter exists on the Java method’s signature.

When the return type is bound to a @table GraphQL type, the framework treats the returned records as key carriers: it lifts each record’s primary key and re-selects the fields the query asked for from the table, in one batched query on the request’s connection, ordered back to the order your method returned. Populate the key columns; everything else comes from the table. This is the same contract for every table-returning service shape (plain, interface, union), and it is the outbound mirror of the inbound rule above: records crossing the service boundary carry the key columns and nothing else, in both directions.

So the example selects FILM_ID alone and is a complete answer for any selection set over Film. Selecting more columns is harmless, and existing services that select every column keep returning the same rows; they just pay one keyed SELECT they no longer need. Rewriting them to select keys only removes that cost.

Two consequences worth knowing before you rely on this:

When the return type is a non-table GraphQL scalar (or list of scalars), the Java return must be a value graphql-java can coerce. The framework wraps the result in a DataFetcherResult and lets graphql-java apply scalar coercion (e.g. Integer → Int!, BigDecimal → Float). No projection or batching is involved.

When the return type is a class-backed type (a custom payload whose backing class is reflected from this @service method’s return type), each row in the service’s result has children that the framework still resolves. Two paths drive the child-fetch dispatch:

The recentlyCreatedFilms example exercises the lifter path:

The service hand-rolls three payloads with languageId`s `(1, 2, 1). The framework’s lifter-driven DataLoader dispatches one batched language lookup with the deduplicated key set {1, 2}, not three. The full decision tree for which path applies (and the four backing-class variants) lives in How-to: Result-type variants.

For @service on a child field (under @splitQuery, see next section), the return shape is a Map<Key, Value> indexed by the parent-key shape the classifier expects. The example schema’s FilmService.titleUppercase exercises the Record1<Integer> arm:

The Set<Record1<Integer>> parameter is the framework’s batch: one entry per distinct parent the request touched. The returned Map’s keys must be the same instances (or value-equal substitutes) the framework supplied; the framework reads each parent’s value out of the map by lookup. Missing keys yield `null for the field on that parent.

The accepted source shapes are Set<Row<N>>, Set<Record<N>>, and Set<X extends TableRecord>. ServiceCatalog.classifySourcesType picks the matching batch shape from the parameter’s reflected element type. Row<N> works (use DSL.row(value) to construct keys back); Record<N> lets you call .value1()/.value2() to extract column values directly; the typed-record arm hands you a typed record carrying the key columns, which is often the most convenient key to write SQL against, and is also what names the key on a class-backed parent.

A child @service batches against a key its parent can produce, and the Sources parameter’s element type names that key. When the parent type carries @table, the element is the parent’s own record and the key is its primary key, so there is nothing to think about. When the parent is class-backed (a DTO a service returned, or a Java type an accessor chain reached), the element names whichever table the batch keys on, and the parent has to be able to produce it.

AktivitetRecord names the key: the framework resolves it to the aktivitet table and keys the batch on that table’s primary key. For the parent to supply it, one of three things must hold:

Reach for the third when the parent class is not yours to edit, or when more than one accessor returns the declared record and the build asks you to break the tie:

The declared producer wins over accessor inference wherever both would apply: writing it is how you say which record is the key, and inference does not run under it.

As everywhere else on the @service path, the records the framework hands you carry the key columns and nothing else, even when the accessor or producer it read them from returned a fully populated record. Fetch the rest through the injected DSLContext, in one query for the batch.

If none of the three holds, the build fails:

Two shapes are rejected by name rather than guessed at: more than one accessor returning the declared record (which of them produces the key is not determined by the element type alone, so declare the producer to break the tie), and an accessor or producer returning many of them (a child @service batches one key per parent, which is what its Map<Key, Value> return means).

The dispatch is DataLoader-batched: one invocation of the service method per request per field, regardless of how many parents the request touches. The cache key is path-scoped, request-scoped, and tenant-prefixed (see How-to: When to split queries for the full key shape and the consequences for aliased uses).

The performance shape: one Set<Key>-input call, one Map<Key, Value>-output result, regardless of fan-out. A request that touches 200 films sees one titleUppercase invocation with a 200-element Set, not 200 calls; missing keys in the returned Map yield null for that parent’s field.