Skip to main content

​
Overview

The Rails::GraphQL::Field class represents fields in GraphQL types. Fields can be input fields (arguments) or output fields (on objects, interfaces, queries, mutations, subscriptions). Namespace: Rails::GraphQL Includes:
  • Helpers::WithDirectives
  • Helpers::WithDescription
Subclasses:
  • InputField - Fields on input objects
  • OutputField - Fields on output types
  • MutationField - Fields for mutations
  • SubscriptionField - Fields for subscriptions

​
Constructor

​
initialize

​
name
String | Symbol
required
The name of the field
​
owner
Type
required
The type that owns this field
​
null
Boolean
default:"true"
Whether the field value can be null
​
array
Boolean
default:"false"
Whether the field returns an array
​
nullable
Boolean
default:"true"
Whether array items can be null (only applies if array: true)
​
full
Boolean
default:"false"
Shortcut for null: false, nullable: false, array: true
​
enabled
Boolean
default:"true"
Whether the field is enabled
​
disabled
Boolean
default:"false"
Opposite of enabled (overrides enabled if true)
​
directives
Array
List of directives to apply to the field
​
desc
String
Field description
​
description
String
Field description (alias for desc)
​
method_name
Symbol
Name of the method to call on the object
​
block
Block
Configuration block
field = Field.new(:email, owner: User, null: false, desc: 'User email address')

​
Instance Attributes

​
name
Symbol
The Ruby-style name of the field (underscore_case)
​
gql_name
String
The GraphQL-style name of the field (camelCase)
​
owner
Type
The type that owns this field
Aliases:
  • to_sym → name
  • gid_base_class → owner
  • proxied_owner → owner

​
Class Methods

​
input_type?

Check if this field class is valid as an input type. Returns: Boolean 
InputField.input_type? # => true
OutputField.input_type? # => false

​
output_type?

Check if this field class is valid as an output type. Returns: Boolean 
OutputField.output_type? # => true
InputField.output_type? # => false

​
leaf_type?

Check if this field is considered a leaf output. Returns: Boolean

​
proxy?

Check if the field is a proxy kind of field. Returns: Boolean 
field.class.proxy? # => false

​
mutation?

Check if the field is associated with a mutation. Returns: Boolean 
MutationField.mutation? # => true

​
subscription?

Check if the field is associated with a subscription. Returns: Boolean 
SubscriptionField.subscription? # => true

​
Instance Methods

​
configure

Apply additional configurations using a block.
​
block
Block
required
Configuration block
Returns: self 
field.configure do
  desc 'Updated description'
end

​
apply_changes

Apply a controlled set of changes to the field.
​
nullable
Boolean
Update nullable setting
​
null
Boolean
Update null setting
​
disabled
Boolean
Disable the field
​
enabled
Boolean
Enable the field
​
desc
String
Update description
​
description
String
Update description
​
block
Block
Configuration block
field.apply_changes(null: false, desc: 'New description')

​
method_name

Get the name of the method used to retrieve field data. Returns: Symbol 
field.method_name # => :email

​
all_owners

Return all owners of the field (always returns single-item array). Returns: Array<Type> 
field.all_owners # => [User]

​
State Management Methods

​
enable!

Mark the field as enabled. 
field.enable!

​
disable!

Mark the field as disabled. 
field.disable!

​
required!

Mark the field as non-nullable (set null to false). 
field.required!

​
required_items!

Mark array items as non-nullable (set nullable to false). 
field.required_items!

​
Query Methods

​
null?

Check if the field value can be null. Returns: Boolean 
field.null? # => true

​
required?

Check if the field value cannot be null. Returns: Boolean 
field.required? # => true
# Equivalent to: !field.null?

​
array?

Check if the field returns an array. Returns: Boolean 
field.array? # => true

​
nullable?

Check if array items can be null. Returns: Boolean 
field.nullable? # => true

​
enabled?

Check if the field is enabled. Returns: Boolean 
field.enabled? # => true

​
disabled?

Check if the field is disabled. Returns: Boolean 
field.disabled? # => false

​
internal?

Check if the field is internal (name starts with __). Returns: Boolean 
field.internal? # => false

​
valid_input?

Check if the field is valid for input. Override in subclasses. Returns: Boolean 
field.valid_input?(value) # => true

​
valid_output?

Check if the field is valid for output. Override in subclasses. Returns: Boolean 
field.valid_output?(value) # => true

​
valid?

Check if the given value is valid (uses valid_input? or valid_output? based on field type).
​
value
Any
required
Value to validate
Returns: Boolean 
field.valid?("[email protected]") # => true

​
Serialization Methods

​
to_json

Transform the given value to its JSON string representation. Must be overridden by subclasses.
​
value
Any
required
Value to serialize
Returns: String Raises: NotImplementedError if not overridden

​
as_json

Turn the given value into a JSON-compatible object. Must be overridden by subclasses.
​
value
Any
required
Value to serialize
Returns: JSON-compatible object Raises: NotImplementedError if not overridden

​
deserialize

Convert user input into a Ruby object. Must be overridden by subclasses.
​
value
Any
required
Input value to deserialize
Returns: Ruby object Raises: NotImplementedError if not overridden

​
Validation

​
validate!

Validate the field definition. Raises: NameError if the field name is invalid (starts with __ but is not internal) 
field.validate!

​
Proxy and Comparison

​
to_proxy

Create a proxy of the current field.
​
args
Array
Arguments for proxy
​
xargs
Hash
Additional options
​
block
Block
Configuration block
Returns: Field with ProxiedField module 
proxy_field = field.to_proxy

​
=~

Check if another field is equivalent.
​
other
Field
required
Field to compare with
Returns: Boolean 
field1 =~ field2 # => true

​
Description

​
description

Get the description of the field.
​
namespace
Symbol
Namespace for the description
Returns: String 
field.description # => "User email address"

​
Example: Defining Fields

​
Output Fields on Object Type

class User < Rails::GraphQL::Type::Object
  # Simple field
  field :id, :id, null: false

  # Field with description
  field :name, :string, null: false, desc: 'Full name of the user'

  # Array field with non-nullable items
  field :tags, [:string], nullable: false

  # Shortcut for non-null array with non-null items
  field :permissions, [:string], full: true

  # Field with custom method name
  field :email_address, :string, method_name: :email

  # Field with directives
  field :legacy_field, :string, directives: DeprecatedDirective(reason: 'Use newField instead')

  # Field with arguments
  field :posts, [Post] do
    argument :limit, :int, default: 10
    argument :offset, :int, default: 0

    def resolve(limit:, offset:)
      object.posts.limit(limit).offset(offset)
    end
  end

  # Disabled field (not available in schema)
  field :internal_data, :string, disabled: true
end

​
Input Fields on Input Type

class CreateUserInput < Rails::GraphQL::Type::Input
  # Required field
  argument :name, :string, null: false

  # Optional field with description
  argument :email, :string, desc: 'User email address'

  # Field with default value
  argument :role, :string, default: 'user'

  # Array field
  argument :tags, [:string]

  # Nested input type
  argument :address, AddressInput
end

​
Mutation Fields

class CreateUser < Rails::GraphQL::Type::Mutation
  # Input arguments
  argument :name, :string, null: false
  argument :email, :string, null: false

  # Return type
  type :User, null: false

  # Resolver
  def resolve(name:, email:)
    User.create!(name: name, email: email)
  end
end

​
Field Options Summary

Build docs developers (and LLMs) love

Get started for freeTalk to us