class GraphQL::Schema

A GraphQL schema which may be queried with GraphQL::Query.

The Schema contains:

Schemas start with root types, Schema.query, Schema.mutation and Schema.subscription. The schema will traverse the tree of fields & types, using those as starting points. Any undiscoverable types may be provided with the types configuration.

Schemas can restrict large incoming queries with max_depth and max_complexity configurations. (These configurations can be overridden by specific calls to Schema.execute)

Schema configuration reference

The schema definition guide contains setup examples and links each contract above to its API method. Keep method-specific behavior in the comments for those methods so this page remains the source of truth.

Root Types

query, mutation, and subscription register the entry-point object types for a schema. Each may receive a type class or a block for lazy loading:

query Types::Query
mutation { Types::Mutation }
subscription { Types::Subscription }

Use Schema.orphan_types for object types which implement an interface but aren’t reachable from a field return type. Use Schema.extra_types when a type should be printed and included in introspection without being connected to the schema’s type graph.

Object Identification

Relay-style node(id:) fields, arguments configured with loads:, and the ObjectCache use Schema.object_from_id to fetch an application object. Return nil when the object does not exist or is not visible to the current operation. Implement Schema.id_from_object to produce a stable ID which can be passed back to object_from_id.

Schema.resolve_type maps an application object to its runtime GraphQL type when a field returns an interface or union.

Error Handling

Override Schema.type_error to handle mismatches between application values and the GraphQL type system. Register application exception handlers with Schema.rescue_from. Schema.parse_error handles invalid query strings, and Schema.query_stack_error is called when execution encounters a SystemStackError.

Default Limits

Schema.max_depth limits nested field selections and Schema.max_complexity limits the calculated cost of a query. Schema.default_max_page_size limits connection fields. Schema.validate_timeout, Schema.validate_max_errors, and Schema.max_query_string_tokens bound validation and parsing work. These limits can be configured on a schema and, where documented, overridden for an individual execution.

Introspection

Schema.extra_types adds otherwise unreachable types to printed SDL and introspection results. Pass a custom namespace to Schema.introspection to replace or extend the default introspection system.

Authorization

Schema.unauthorized_object and Schema.unauthorized_field run when an authorization hook returns false. Return a replacement value or raise GraphQL::ExecutionError to add a client-facing error.

Execution Configuration

Schema.trace_with installs tracing modules. Schema.query_analyzer and Schema.multiplex_analyzer register analysis hooks. Schema.default_logger configures runtime logging, while Schema.context_class and Schema.query_class select the classes used during execution. Schema.lazy_resolve registers promise-like values, and Schema.use installs schema plugins such as Dataloader and Visibility.

Examples

Example: defining a schema

class MySchema < GraphQL::Schema
  query QueryType
  # If types are only connected by way of interfaces, they must be added here
  orphan_types ImageType, AudioType
end

Constants

BUILT_IN_TYPES

Attributes