graphql-relay

Gem Version Build Status Code Climate Test Coverage

Helpers for using graphql with Relay.

Installation

gem "graphql-relay"

bundle install

Usage

Global Ids

Global Ids provide refetching & global identification for Relay.

You should create GraphQL::Relay::GlobalNodeIdentification helper by defining object_from_id(global_id) & type_from_object(object). The resulting object provides ID resultion methods, a find-by-global-id field and a node interface. Example

ObjectTypes should implement that interface with the global_id_field helper: Example

You should attach the field to your query type: Example

Connections

Connections will provide arguments, pagination and pageInfo for Arrays or ActiveRecord::Relations. You can use the connection definition helper.

Then, implement the field. It's different than a normal field:

  • use the connection helper to define it, instead of field
  • Call #connection_type on an ObjectType for the field's return type (eg, ShipType.connection_type)

Examples:

You can also add custom fields to connection objects: Example

At runtime, graphql-relay chooses a connection implementation to expose a collection. graphql-relay provides ArrayConnection and RelationConnection, but you can also provide your own with BaseConnection.register_connection_implementation.

Mutations

Mutations allow Relay to mutate your system. When you define a mutation, you'll be defining:

  • A field for your schema's mutation root
  • A derived InputObjectType for input values
  • A derived ObjectType for return values

You don't define anything having to do with clientMutationId. That's automatically created.

To define a mutation, use GraphQL::Relay::Mutation.define. Inside the block, you should configure:

  • name, which will name the mutation field & derived types
  • input_fields, which will be applied to the derived InputObjectType
  • return_fields, which will be applied to the derived ObjectType
  • resolve(-> (inputs, ctx)), the mutation which will actually happen

The resolve proc:

  • Takes inputs, which is a hash whose keys are the ones defined by input_field
  • Takes ctx, which is the query context you passed with the context: keyword
  • Must return a hash with keys matching your defined return_fields

Examples:

Todo

  • Show how to wrap a simple field in a connection field with ConnectionField.create
  • Add a max_page_size config for connections?
  • Refactor some RelationConnection issues:

More Resources