Schema - Rails GraphQL

Overview

The Rails::GraphQL::Schema class is the core representation of a GraphQL schema. Each schema is associated with a single namespace and manages QueryFields, Mutations, and Subscriptions. Inherits from: Rails::GraphQL::Type Includes:

ActiveSupport::Configurable
ActiveSupport::Rescuable
Helpers::Instantiable

Extends:

Helpers::WithSchemaFields
Helpers::WithDirectives
Helpers::WithGlobalID
Helpers::Registerable
GraphQL::Introspection

Class Methods

find

Find a schema associated with a namespace (soft mode).

namespace

Symbol

required

The namespace to search for

Returns: Schema or nil

schema = Rails::GraphQL::Schema.find(:api)

find!

Find a schema associated with a namespace. Raises an exception if not found.

namespace

Symbol

required

The namespace to search for

Returns: Schema Raises: NameError if schema not found

schema = Rails::GraphQL::Schema.find!(:api)

namespace

Get or set the namespace for the schema.

Symbol

The namespace to assign

mod

Module

Optional module to associate with the namespace

Returns: Symbol - The current namespace (defaults to :base)

class ApiSchema < Rails::GraphQL::Schema
  namespace :api
end

# Get the namespace
ApiSchema.namespace # => :api

types

Find all types available for the current schema.

base_class

Symbol

default:":Type"

The base class to filter types by

block

Block

Optional block to iterate over types

schema.types do |type|
  puts type.gql_name
end

find_type

Find a type associated with the schema.

type

Symbol | String

required

The type to find

xargs

Hash

Additional options (base_class, namespaces)

Returns: Type or nil

user_type = schema.find_type(:User)

find_type!

Find a type associated with the schema. Raises an exception if not found.

type

Symbol | String

required

The type to find

Returns: Type Raises: Exception if type not found

user_type = schema.find_type!(:User)

find_directive!

Find a directive associated with the schema.

directive

Symbol | String

required

The directive to find

Returns: Directive Raises: Exception if directive not found

directive = schema.find_directive!(:deprecated)

request

Create a new request instance for this schema. Returns: Rails::GraphQL::Request

request = schema.request

execute

Shortcut to execute a GraphQL request.

args

Array

Arguments passed to the request

xargs

Hash

Additional execution options

Returns: Execution result

result = schema.execute(document, variables: { id: 1 })

Alias: perform

validate

Validate the schema. Only runs if not already validated.

schema.validate

validate!

Force validation of the schema.

schema.validate!

valid?

Check if the schema has been validated. Returns: Boolean

schema.valid? # => true

Subscription Methods

subscription_provider

Return the subscription provider for the current schema. Returns: Subscription provider instance

provider = schema.subscription_provider

add_subscriptions

Add new subscriptions using provided request subscription objects.

subscriptions

Array

required

Request subscription objects to add

schema.add_subscriptions(subscription1, subscription2)

remove_subscriptions

Remove subscriptions by their subscription IDs.

sids

Array

required

Subscription IDs to remove

schema.remove_subscriptions('sub-123', 'sub-456')

accepts_subscription?

Check if the given operation can be subscribed to.

operation

Object

required

The operation to check

Returns: Boolean

schema.accepts_subscription?(operation) # => true

subscription_id_for

Generate a subscription ID. By default, produces a random UUID. Returns: String - UUID

id = schema.subscription_id_for(subscription) # => "550e8400-e29b-41d4-a716-446655440000"

Cache Methods

cached?

Check if a value exists in the schema cache.

name

String

required

Cache key name

options

Hash

Cache options

Returns: Boolean

schema.cached?('query-hash') # => true

read_from_cache

Read a value from the schema cache.

name

String

required

Cache key name

Returns: Cached value or nil

value = schema.read_from_cache('query-hash')

write_on_cache

Write a value to the schema cache.

name

String

required

Cache key name

value

Any

required

Value to cache

options

Hash

Cache options

schema.write_on_cache('query-hash', compiled_query)

fetch_from_cache

Fetch a value from cache, executing the block if not found.

name

String

required

Cache key name

value = schema.fetch_from_cache('key') { compute_value }

delete_from_cache

Delete a value from the schema cache.

name

String

required

Cache key name

schema.delete_from_cache('query-hash')

Type Creation Methods

create_type

Create a new type dynamically without defining a separate class.

name

String | Symbol

required

Name of the type

superclass

Symbol

Base type (e.g., :Object, :Interface)

xargs

Hash

Additional type options

block

Block

Configuration block

schema.create_type(:Address, :Object) do
  field :street, :string
  field :city, :string
end

source

Create a single source type.

object

Class

required

The source object/model

superclass

Class

Superclass for the source

build

Boolean

default:"true"

Whether to build immediately

schema.source(User, build: true)

sources

Create multiple source types of the same base type.

list

Array

required

List of source objects

of_type

Class

Base type for all sources

build

Boolean

default:"true"

Whether to build immediately

schema.sources(User, Post, Comment, of_type: ActiveRecordSource)

Loading Methods

load_directory

Load all files in a directory as dependencies.

dir

String

default:"."

Directory path

recursive

Boolean

default:"true"

Whether to load recursively

class ApiSchema < Rails::GraphQL::Schema
  load_directory '../types'
end

Alias: load_current_directory

load_dependencies

Load a list of known dependencies.

type

Symbol

required

Type of dependencies (:directive, :source, etc.)

list

Array

required

List of dependencies to load

schema.load_dependencies(:directive, :deprecated, :skip)

load_directives

Load directive dependencies.

list

Array

required

List of directives to load

schema.load_directives(:deprecated, :skip, :include)

load_sources

Load source dependencies.

list

Array

required

List of sources to load

build

Boolean

default:"false"

Whether to build sources immediately

schema.load_sources(:user, :post, build: true)

Configuration Options

Show Configuration Settings

The schema inherits configuration from Rails::GraphQL.config with the following keys:

enable_introspection

Boolean

Enable GraphQL introspection queries

request_strategies

Array

Available request execution strategies

enable_string_collector

Boolean

Enable optimized string collection for responses

default_response_format

Symbol

Default format for responses (:string, :hash, :json)

schema_type_names

Hash

Custom type name mappings

cache

ActiveSupport::Cache::Store

Cache store instance

default_subscription_provider

String | Class

Default subscription provider

default_subscription_broadcastable

Boolean

Enable subscription broadcasting by default

Introspection

gql_name

The GraphQL name for schemas is always __Schema. Returns: String

schema.gql_name # => "__Schema"

Alias: graphql_name

kind

The kind of object, always :schema. Returns: Symbol

schema.kind # => :schema

Alias: to_sym

to_gql

Describe the schema as a GraphQL SDL string.

xargs

Hash

Options for SDL generation

Returns: String - GraphQL SDL

sdl = schema.to_gql
puts sdl

Example Usage

class ApiSchema < Rails::GraphQL::Schema
  namespace :api

  # Load types from directory
  load_directory '../types'

  # Load directives
  load_directives :deprecated, :cached

  # Define a query field
  field :user, :User do
    argument :id, :id, null: false
  end

  # Define a mutation
  mutation :create_user, :User do
    argument :name, :string, null: false
    argument :email, :string, null: false
  end

  # Configure
  config.enable_introspection = true
  config.default_response_format = :json
end

# Execute a query
result = ApiSchema.execute(
  query,
  variables: { id: 1 },
  context: { current_user: user }
)

Core Classes

Type Classes

Sources

Execution

Configuration

​Overview

​Class Methods

​find

​find!

​namespace

​types

​find_type

​find_type!

​find_directive!

​request

​execute

​validate

​validate!

​valid?

​Subscription Methods

​subscription_provider

​add_subscriptions

​remove_subscriptions

​accepts_subscription?

​subscription_id_for

​Cache Methods

​cached?

​read_from_cache

​write_on_cache

​fetch_from_cache

​delete_from_cache

​Type Creation Methods

​create_type

​source

​sources

​Loading Methods

​load_directory

​load_dependencies

​load_directives

​load_sources

​Configuration Options

​Introspection

​gql_name

​kind

​to_gql

​Example Usage

Build docs developers (and LLMs) love

Overview

Class Methods

find

find!

namespace

types

find_type

find_type!

find_directive!

request

execute

validate

validate!

valid?

Subscription Methods

subscription_provider

add_subscriptions

remove_subscriptions

accepts_subscription?

subscription_id_for

Cache Methods

cached?

read_from_cache

write_on_cache

fetch_from_cache

delete_from_cache

Type Creation Methods

create_type

source

sources

Loading Methods

load_directory

load_dependencies

load_directives

load_sources

Configuration Options

Introspection

gql_name

kind

to_gql

Example Usage