GraphQL::Connections

Additional implementations of cursor-based paginations for GraphQL Ruby.

Add this line to your application's Gemfile:

gem "graphql-connections"

Implements Relay specification for serving stable connections based on column values. If objects are created or destroyed during pagination, the list of items won’t be disrupted.

You can use a stable connection wrapper on a specific field:

field :messages, Types::Message.connection_type, null: false

def messages
  GraphQL::Connections::Stable.new(Message.all)
end

Records are sorted by model's primary key by default. You can change this behaviour by providing primary_key param:

GraphQL::Connections::Stable.new(Message.all, primary_key: :created_at)

In case when you want records to be sorted by more than one field (i.e., keyset pagination), you can use keys param:

GraphQL::Connections::Stable.new(Message.all, keys: %w[name id])

When you pass only one key, a primary key will be added as a second one:

GraphQL::Connections::Stable.new(Message.all, keys: [:name])

NOTE: Currently we support maximum two keys in the keyset.

Also, you can pass the :desc option to reverse the relation:

GraphQL::Connections::Stable.new(Message.all, keys: %w[name id], desc: true)

GraphQL::Connections::Stable.new(Message.all, primary_key: :created_at, desc: true)

Also, you can disable opaque cursors by setting opaque_cursor param:

GraphQL::Connections::Stable.new(Message.all, opaque_cursor: false)

Or you can apply a stable connection to all Active Record relations returning by any field:

class ApplicationSchema < GraphQL::Schema
  connections.add(ActiveRecord::Relation, GraphQL::Connections::Stable)
end

NOTE: Don't use stable connections for relations whose ordering is too complicated for cursor generation.

Register connection for all Chewy requests:

class ApplicationSchema < GraphQL::Schema
  connections.add(Chewy::Search::Request, GraphQL::Connections::ChewyConnection)
end

And define field like below:

field :messages, Types::Message.connection_type, null: false

def messages
  CitiesIndex.query(match: {name: "Moscow"})
end

NOTE: Using first and lastarguments simultaneously is not supported yet.

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/bibendi/graphql-connections.

The gem is available as open source under the terms of the MIT License.