Skip to main content

​
Overview

Input objects define a set of input fields. Input fields can be scalars, enums, or other input objects. Input types are used for complex argument structures. Inherits from: Rails::GraphQL::Type Specification: GraphQL Input Object Type Definition

​
Class Attributes

​
field_type
Class
default:"Field::InputField"
The type of field class used for input fields
​
valid_field_types
Array<Class>
Valid types that can be used in input fields:
  • Type::Enum
  • Type::Input
  • Type::Scalar

​
Class Methods

​
gql_name

Get the GraphQL name of the input type, with optional auto-suffix.
​
return
String
The GraphQL name, with suffix applied based on auto_suffix_input_objects config
class UserInput < GraphQL::InputType
end

# With auto_suffix_input_objects = "Input"
UserInput.gql_name # => "UserInput"

​
valid_input?(value)

Check if a value is valid input for this input type.
​
value
Hash | Object
required
The value to validate
​
return
Boolean
Returns true if the value is valid

​
deserialize(value = nil, **value_as_hash)

Turn input into an instance of the input object.
​
value
Hash
The input value as a hash
​
value_as_hash
Hash
Alternative: provide value as keyword arguments
​
return
Input
An input object instance
user_input = UserInput.deserialize(
  name: "Alice",
  email: "[email protected]"
)

user_input.name # => "Alice"

​
build(value = nil, **value_as_hash)

Alias for deserialize.

​
build_defaults

Build a hash with default values for all fields.
​
return
Hash
Hash mapping field names to their default values
class FilterInput < GraphQL::InputType
  field :limit, :int, default: 10
  field :offset, :int, default: 0
end

FilterInput.build_defaults
# => { "limit" => 10, "offset" => 0 }

​
as_json(value)

Transform value to its JSON hash representation.
​
value
Hash | Input
required
The value to serialize
​
return
Hash
Hash with GraphQL field names as keys

​
to_json(value)

Transform value to a JSON string.
​
value
Hash | Input
required
The value to serialize
​
return
String
JSON string representation

​
Instance Methods

​
initialize(args = nil, **xargs)

Create a new input instance.
​
args
OpenStruct
The deserialized arguments
​
xargs
Hash
Arguments as keyword parameters
input = UserInput.new(name: "Alice", email: "[email protected]")

​
args

Access the underlying arguments as an OpenStruct.
​
return
OpenStruct
Frozen OpenStruct containing all field values

​
params

Get arguments as a parameter hash.
​
return
Hash
Hash with Ruby-style (underscored) keys, with nested inputs converted to params
input = UserInput.new(first_name: "Alice")
input.params # => { first_name: "Alice" }

​
resource(*args, **xargs, &block)

Get or create an instance of the assigned class.
​
args
Array
Additional arguments for the assigned class constructor
​
xargs
Hash
Additional keyword arguments merged with params
​
return
Object | nil
Instance of the assigned class, or nil if no class assigned
class UserInput < GraphQL::InputType
  self.assigned_to = User
  
  field :name, :string
  field :email, :string
end

input = UserInput.new(name: "Alice", email: "[email protected]")
user = input.resource # => User.new(name: "Alice", email: "[email protected]")

​
args_as_json

Convert all arguments to their JSON representation.
​
return
Hash
Hash with all values serialized via as_json

​
args_to_json

Convert all arguments to a JSON string.
​
return
String
JSON string of all arguments

​
validate!(*)

Validate all field values in the input instance. 
input = UserInput.new(name: "Alice")
input.validate! # May raise InvalidValueError

​
to_h

Delegate to args.to_h.

​
[]

Access field values by key (delegates to args).

​
to_global_id / to_gid / to_gid_param

Convert the input to a GlobalID representation.
​
return
GlobalID
GlobalID instance for this input

​
Instance Attributes

​
assignment_error
Exception
Stores any error that occurred when loading the assigned class
​
resource
Object
Cached instance of the assigned class

​
Included Modules

​
Helpers::WithAssignment
Allows assignment to Ruby classes via assigned_to
​
Helpers::WithFields
Provides field definition and management methods

​
Configuration

class CreateUserInput < GraphQL::InputType
  description "Input for creating a new user"
  
  # Assign to a Ruby class
  self.assigned_to = User
  
  field :name, :string, null: false
  field :email, :string, null: false
  field :role, UserRoleEnum, default: "viewer"
  field :metadata, :json
end

​
Usage Examples

​
Basic Input

class FilterInput < GraphQL::InputType
  field :search, :string
  field :limit, :int, default: 20
  field :offset, :int, default: 0
end

field :users, [UserType] do
  argument :filter, FilterInput
  
  resolve ->(obj, args, ctx) {
    filter = args.filter
    User.where("name LIKE ?", "%#{filter.search}%")
        .limit(filter.limit)
        .offset(filter.offset)
  }
end

​
Nested Input Objects

class AddressInput < GraphQL::InputType
  field :street, :string
  field :city, :string
  field :country, :string
end

class CreateUserInput < GraphQL::InputType
  field :name, :string, null: false
  field :email, :string, null: false
  field :address, AddressInput
end

​
With Resource Mapping

class UpdateUserInput < GraphQL::InputType
  self.assigned_to = User
  
  field :name, :string
  field :email, :string
end

mutation :update_user do
  argument :id, :id, null: false
  argument :input, UpdateUserInput, null: false
  
  type UserType
  
  resolve ->(obj, args, ctx) {
    user = User.find(args.id)
    # Get params hash for update
    user.update!(args.input.params)
    user
  }
end

​
Accessing Values

input = CreateUserInput.new(
  name: "Alice",
  email: "[email protected]",
  role: "admin"
)

# Access via method
input.name # => "Alice" (via delegate_missing_to)

# Access via args
input.args.email # => "[email protected]"

# Access via hash
input[:role] # => "admin"

# Get as params
input.params # => { name: "Alice", email: "[email protected]", role: "admin" }

​
Special Features

​
Automatic Name Suffixing

Based on the auto_suffix_input_objects configuration, input type names are automatically suffixed: 
# With config.auto_suffix_input_objects = "Input"
class User < GraphQL::InputType
end

User.gql_name # => "UserInput"

​
Default Values

Fields can specify default values that are automatically merged during deserialization: 
class PaginationInput < GraphQL::InputType
  field :page, :int, default: 1
  field :per_page, :int, default: 25
end

input = PaginationInput.deserialize({}) # No values provided
input.page # => 1
input.per_page # => 25

​
Delegate Missing

Input instances delegate unknown methods to the resource object, allowing seamless integration with assigned classes.
  • Scalar - Use as input field types
  • Enum - Use as input field types
  • Arguments - Alternative for simple field arguments

Build docs developers (and LLMs) love

Get started for freeTalk to us