Inputs

type UserInput {
  name
  email
}

Inputs allow you to organize fields to receive data. Besides scalars and enums, inputs are the other type accepted by arguments. You should use them when you have several attributes to receive from your front end.

Creating an Input

You can define inputs on a file or using the shortcut on the schema.

# app/graphql/inputs/user_input.rb
module GraphQL
  class UserInput < GraphQL::Input
    field :name
    field :email
  end
end

# OR

# app/graphql/app_schema.rb
input 'UserInput' do
  field :name
  field :email
end

Read more about field lists.

Description

Allows documenting inputs. This value can be retrieved using introspection or during a to_gql output. Within the class, desc works as a syntax sugar for self.description = ''. It also supports descriptions from I18n.

# app/graphql/inputs/user_input.rb
module GraphQL
  class UserInput < GraphQL::Input
    desc 'This is awesome!'
  end
end

Using Inputs

Once they are defined, you can set them as the type of any field’s arguments. Then, in your execution document, you can pass the values directly or through variables.

field(:create_user, 'User', null: false) do
  argument :user, 'UserInput', null: false
end

# Directly
mutation {
  createUser(user: { name: "John Doe", email: "[email protected]" }) { id }
}

# Using variables
mutation($user: UserInput!) {
  createUser(user: $user) { id }
}

The Instance

The inputs’ instances have several methods to facilitate handling them. For example, all the fields will be automatically converted from camel case to snake case. You can think of inputs as StrongParameters, because the combination of fields and their respective types have the same purpose of protecting attributes from end-user assignment.

# app/graphql/app_schema.rb
input 'UserInput' do
  field :first_name
  field :last_name
  field :email
end

add_mutation_field(:create_user, :bool, null: false) do
  argument :user, 'UserInput', null: false
end

def create_user(user:)
  puts user.args.first_name
end

mutation {
  createUser(user: {
    firstName: "John",
    lastName: "Doe",
    email: "[email protected]"
  })
}

Params

You can collect a sanitized Hash by calling the params method.

# app/graphql/app_schema.rb
def create_user(user:)
  puts user.params.inspect
  # { first_name: "John", last_name: "Doe", email: "[email protected]" }
end

Type Assignment

Inputs are one of the several types that allow being assigned to a specific class. When inputs are assigned, you can take advantage of the resource method, which will instantiate the assignment with the parameters. You can also provide extra parameters to this method to extend the instance.

# app/graphql/app_schema.rb
input 'UserInput' do
  # Assigned to ::User model
  self.assigned_to = 'User'
  # ...
end

def create_user(user:)
  puts user.resource(id: 1)
  # #<User id: 1, first_name: "John", ...>
end

The resource is the method delegated to receive any method that the input doesn’t have. This is a syntax sugar for dealing with the inputs as Models.

def create_user(user:)
  user.save! # Same as user.resource.save!
end

Read more about type assignment and sources.