Attaches a developer-supplied predicate to a field, an argument, or an input field. The reflected static method takes the surrounding table and the relevant scalar values, and returns a jOOQ Condition. The rewrite folds that Condition into the generated WHERE clause: by default in addition to the implicit column = ? predicates the rewrite would otherwise emit, or replacing them when override: true.

@condition is the escape hatch for predicates Graphitron can’t infer from the catalog: regex matches, range filters, date arithmetic, joins through correlated subqueries, vendor-specific predicates, multi-column boolean shapes. It also drives the dynamic enclosingOverride cascade at field level: an outer field-level @condition(override: true) suppresses the implicit-column predicates from a @table-typed input, but inner argument-level @condition annotations still fire. (The rewrite preserves inner explicit conditions, the legacy generator dropped them, see filmsOuterOverrideTableInput in the example schema for the test that pins this divergence.)

SDL signature

directive @condition(
    condition:        ExternalCodeReference
    override:         Boolean = false
    contextArguments: [String!]
) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION

Parameters

Name Type Default Description

condition

ExternalCodeReference

(required in practice)

Points at the static Java method that returns the Condition. className: and method: are both required, the rewrite reflects the method’s parameter list against (in order) the surrounding table, the input or scalar parameters, and any contextArguments. argMapping: rebinds GraphQL argument names to differently-named Java parameters when the conventions diverge.

override

Boolean

false

When true, suppresses the rewrite’s automatic equality predicates for the affected element only: at argument level, the implicit column = ? for that one argument; at field level, the implicit predicates for every direct argument and the column-equality predicates inside @table inputs. Inner explicit @condition annotations are preserved on either axis.

contextArguments

[String!]

[]

Names of values to pull from the GraphQL GraphQLContext at runtime. Each named context value becomes a Java parameter the reflected method receives, alongside the table and the input arguments. Wire the values into GraphQLContext in your servlet bootstrap.

Canonical examples

Argument-level, no override (the explicit predicate is AND-ed with the implicit column IN (…​)):

type Query {
    citiesByName(
        cityNames: [String!] @field(name: "CITY")
            @condition(condition: {className: "com.example.CityConditions", method: "cityMethod"})
    ): [City]
}

Field-level, no override (the explicit predicate is AND-ed with the implicit predicates for every argument):

type Query {
    cities(
        countryId: String! @field(name: "COUNTRY_ID"),
        cityNames: [String!] @field(name: "CITY")
    ): [City] @condition(condition: {className: "com.example.CityConditions", method: "cityMethod"})
}

Field-level, override: true on a @table input. The outer @condition runs, the implicit column-equality predicates from FilmConditionInput are suppressed, but an inner @condition on FilmConditionInput.filmId still fires:

type Query {
    filmsOuterOverrideTableInput(filter: FilmConditionInput): [Film!]!
        @condition(
            condition: {
                className: "com.example.conditions.InputFieldConditionFixtures",
                method:    "outerOverrideMethod"
            },
            override: true
        )
}

input FilmConditionInput @table(name: "film") {
    filmId: Int @field(name: "FILM_ID")
        @condition(condition: {
            className: "com.example.conditions.InputFieldConditionFixtures",
            method:    "filmIdCondition"
        })
}

Net effect: (film_id >= 2) AND (film_id = 1) — both the outer override and the inner explicit @condition are honoured, even though the outer override is true.

Multi-segment input path with a plain (non-@table) input. The two-level nested input lets a leaf-level @condition reference its enclosing-input field by path:

input NestedFilmInput {
    inner: InnerFilmInput
}

input InnerFilmInput {
    filmId: Int @condition(condition: {
        className: "com.example.conditions.PlainFilmIdConditions",
        method:    "filmIdCondition"
    })
}

The rewrite extracts inner.filmId from the outer argument map and passes it to filmIdCondition as the bound parameter.

Context-argument flow. The reflected method receives the table, any explicit input parameters, and the named context values:

type Query {
    citiesForCurrentUser: [City]
        @condition(
            condition:        {className: "com.example.CityConditions", method: "tenantScoped"},
            contextArguments: ["tenantId"]
        )
}

tenantScoped(City table, UUID tenantId) runs at request time with tenantId pulled from GraphQLContext.

FK-target @nodeId filter. When an input field carries both @nodeId(typeName: "X") and @condition, the field decodes an opaque id for a foreign-key-linked table X (reached from the input’s own table through a catalog foreign key). The reflected method’s table parameter is then X, not the input’s own table:

input SoknadsmangeltypeFilterInput @table(name: "soknadsmangeltype") {
    regelverksamlingId: ID! @nodeId(typeName: "Regelverksamling")
        @condition(condition: {
            className: "com.example.conditions.SoknadsmangeltypeConditions",
            method:    "iRegelverksamling"
        }, override: true)
}

The method signature is iRegelverksamling(Regelverksamling rs, String regelverksamligId): it receives an alias for the FK-target Regelverksamling, and the rewrite wraps the returned Condition in a correlated subquery, EXISTS (SELECT 1 FROM regelverksamling rs WHERE soknadsmangeltype.<fk> = rs.<pk> AND <your predicate>), so the predicate runs against X while the outer row set is preserved. The developer method is identical to any other @condition method; it neither knows nor cares that its Condition lands inside an EXISTS rather than the top-level WHERE. Composite-key NodeType targets are supported: the correlation ANDs every foreign-key column pair (EXISTS (SELECT 1 FROM project p WHERE p.org_id = project_note.org_id AND p.project_id = project_note.project_id AND <your predicate>)). The same EXISTS is emitted wherever the predicate lands, including inline child-field fetchers and @splitQuery batched fetchers, not only top-level query conditions.

Constraints

  • Applies on FIELD_DEFINITION, ARGUMENT_DEFINITION, and INPUT_FIELD_DEFINITION. The element type fixes the predicate’s scope: argument-level conditions can only see their own argument and any context arguments, field-level conditions see all of the field’s arguments, input-field-level conditions see the input’s enclosing argument map (the rewrite extracts the leaf value via the path from the outer argument).

  • condition.className: and condition.method: are both required for a meaningful directive. A @condition whose reference resolves to no method (missing className: or method:) surfaces as field '<name>' @condition: …​ or argument '<name>' @condition: …​.

  • argMapping: is supported on @condition (unlike on @externalField, @enum, @sourceRow). Use it to rebind a GraphQL argument name to a differently-named Java parameter, the rewrite carries the mapping into the reflected method’s parameter list.

  • contextArguments: values must already be wired into the runtime GraphQLContext map, the rewrite passes the listed keys through unmodified. A typo here surfaces as a null parameter at request time, not as a build error.

  • Field-level override: true suppresses the implicit predicates from the field’s direct arguments and from any @table-bound input nested under those arguments. Inner explicit @condition annotations on the input’s fields are preserved, override does not cascade through them. (Divergence from the legacy generator: legacy semantics dropped them. The rewrite’s behaviour is the intended one and filmsOuterOverrideTableInput pins it as a regression-fence.)

  • Argument-level override: true is local: it suppresses the implicit column = ? for that one argument, nothing else.

  • An input field carrying both @nodeId(typeName: "X") and @condition binds the condition method’s table parameter to the FK-target table X (the table the decoded id identifies), reached through the catalog foreign key from the input’s own table. The predicate is emitted as a correlated EXISTS over that foreign key, so the method receives an alias for X rather than the input’s own table. Single-column and composite-key NodeType targets are both supported (the composite correlation ANDs every foreign-key column pair). This holds at every emission site: top-level query conditions, inline child-field fetchers, and @splitQuery batched fetchers.

  • Nested input types must be carrier-mapped to flow through @condition. A @table input maps to a jOOQ record (only at the leaf, jOOQ records can not contain other records); a class-backed input maps to its Java record (and any input above it must also be a Java record). An input is class-backed when the Java parameter it flows into is that record type; leaving it without a carrier routes through the PojoInputType path, which still works for plain scalar paths.

  • Listed nested input types ([InnerInput] inside an outer record) require a Java record carrier on the outer input, the rewrite needs a stable Java type for the list element.

See also

  • @reference supplies catalog-driven joins that @condition can layer additional filtering on.

  • @field(name: …​) is the column-binding axis, @condition and @field coexist on the same slot, @field drives the implicit predicate, @condition adds (or replaces) the explicit one.

  • An input type’s backing class determines the carrier the condition method reads from: @table supplies a jOOQ record, otherwise the carrier is the Java record the method parameter is typed as (inferred, not declared).

  • @service is the alternative when a whole fetcher is custom code, @condition is for adjusting a single predicate inside an otherwise generated query.

  • How-to: Stacking and overriding conditions covers the override cascade rules, nested-input record conventions, and the divergence from legacy semantics.

← Reference index