Group mutation inputs
A mutation needs several related values, such as rating and commentary, as one argument.
GraphQL · Class
GraphQLInputObjectType
GraphQL Input Object types group related values into a reusable, structured input for field arguments or variables. They use input in SDL and can contain only input-compatible types.
How it works
An input object is a named, structured input type for field arguments and variables. Its fields use scalar, enum, or other input-object types, and unlike output objects, it cannot be returned by a field or have arguments on its own fields.
Syntax
input ReviewInput {
stars: Int!
commentary: String
}Parameters
| Name | Type | Description |
|---|---|---|
input object value | Input Object | A named set of input fields, such as stars and commentary, supplied as one structured argument or variable value. |
Returns
An input object is not a field result; it is accepted as input by arguments and variables.
Key points
- Use an input object when a field argument needs a coordinated group of values rather than isolated scalar arguments.
- Input Object is one of GraphQL’s six named type categories, alongside object, scalar, enum, interface, and union.
- The declaration resembles an object definition, but its keyword identifies the type as input-only.
- Write
inputin SDL to define the structured argument type. - Nested input objects let arguments represent multi-level structures.
- Input-object fields are value definitions, not resolver fields with their own argument lists.
Common mistakes
- Do not use an output object type as a field inside an input object; input and output types are separate categories.
- Input-object fields accept values directly and cannot declare field arguments.
Example: Structured mutation input
const ReviewInput = `input ReviewInput {
stars: Int!
commentary: String
}`;
const mutation = `mutation CreateReview($review: ReviewInput!) {
createReview(review: $review) {
stars
commentary
}
}`;The schema declaration groups related mutation input fields, while the operation supplies one variable whose declared type is the input object.
When to use it
Model nested arguments
A nested configuration or filter has multiple levels of related criteria.
Reuse an input contract
Several operations share the same argument shape.
Interview questions
QWhat problem does an input object solve?
Input Object types package several related argument values into one structured value. They are useful when a field, especially a mutation, needs more than individual scalar arguments.
Follow-up: Can an input object be used as a field result? No. It is input-only; a separate output object type is needed for returned data.
QWhat types may appear inside an input object?
Its fields may refer to scalars, enums, or other input objects, including wrapped forms such as lists and non-null types. This permits nested structured arguments while preserving a schema-defined shape.
Follow-up: Can an input object field reference an output object? No; the referenced type must itself be valid as an input type.
QHow is an input object declared?
In SDL, an input object is declared with the input keyword rather than type. For example, input ReviewInput { stars: Int!, commentary: String } defines a reusable structured argument type.
Follow-up: Why not reuse an object type? Output objects can contain output-oriented fields and arguments, so GraphQL keeps input and output type definitions distinct.
Related
Object typesScalar typesEnum typesInterface typesUnion typesArgumentsVariablesMutations