<commit_before>---
layout: guide
doc_stub: false
search: true
title: Connections
section: Relay
desc: Build and customize Relay-style connection types
index: 1
---

Relay expresses [one-to-many relationships with _connections_](https://facebook.github.io/relay/graphql/connections.htm). Connections support pagination, filtering and metadata in a robust way.

`graphql-ruby` includes built-in connection support for `Array`, `ActiveRecord::Relation`s, `Sequel::Dataset`s, and `Mongoid::Criteria`s. You can define custom connection classes to expose other collections with GraphQL.

## Connection fields

To define a connection field, use the `field` method. For a return type, get a type's `.connection_type`.  The field's method or `resolver:` should return a collection (eg, `Array` or `ActiveRecord::Relation`) _without_ pagination. (The connection will paginate the collection).

For example:

```ruby
class PostType < GraphQL::Schema::Object
  # `Post#comments` returns an ActiveRecord::Relation
  # The GraphQL field returns a Connection
  field :comments, CommentType.connection_type, null: false
  # `Post#similar_posts` returns an Array
  field :similar_posts, PostType.connection_type, null: false

  # ...
end
```

(GraphQL-Ruby applies connection logic because the return type's name ends in `Connection`. You can manually override this with `connection: true` or `connection: false`.)

You can also define custom arguments and a custom resolve function for connections, just like other fields:

```ruby
field :featured_comments, CommentType.connection_type do
  # Add an argument:
  argument :since, String, required: false
end

def featured_comments(since: nil)
  comments = object.comments.featured
  if since
    comments = comments.where("created_at >= ?", since)
  end
  # Return an Array or ActiveRecord::Relation
  comments
end
```

### Maximum Page Size

You can limit the number of results with `max_page_size:`:

```ruby
field :featured_comments, CommentType.connection_type, null: false, max_page_size: 50
```

In addition, you can set a global default for all connection that do not specify a `max_page_size`:

```ruby
class MySchema < GraphQL::Schema
  default_max_page_size 100
end
```

## Connection types

You can customize connection and edge types by using the class-based API:

```ruby
# Make an edge class for use in the connection below:
class PostEdgeType < GraphQL::Types::Relay::BaseEdge
  node_type(PostType)
end

# Make a customized connection type
class PostConnectionWithTotalCountType < GraphQL::Types::Relay::BaseConnection
  edge_type(PostEdgeType)

  field :total_count, Integer, null: false
  def total_count
    # - `object` is the Connection
    # - `object.nodes` is the collection of Posts
    object.nodes.size
  end
end

```

Now, you can use `PostConnectionWithTotalCountType` to define a connection with the "totalCount" field:

```ruby
class AuthorType < GraphQL::Schema::Object<commit_msg>Add note about conflicts<commit_after>---
layout: guide
doc_stub: false
search: true
title: Connections
section: Relay
desc: Build and customize Relay-style connection types
index: 1
---

Relay expresses [one-to-many relationships with _connections_](https://facebook.github.io/relay/graphql/connections.htm). Connections support pagination, filtering and metadata in a robust way.

`graphql-ruby` includes built-in connection support for `Array`, `ActiveRecord::Relation`s, `Sequel::Dataset`s, and `Mongoid::Criteria`s. You can define custom connection classes to expose other collections with GraphQL.

## Connection fields

To define a connection field, use the `field` method. For a return type, get a type's `.connection_type`.  The field's method or `resolver:` should return a collection (eg, `Array` or `ActiveRecord::Relation`) _without_ pagination. (The connection will paginate the collection).

For example:

```ruby
class PostType < GraphQL::Schema::Object
  # `Post#comments` returns an ActiveRecord::Relation
  # The GraphQL field returns a Connection
  field :comments, CommentType.connection_type, null: false
  # `Post#similar_posts` returns an Array
  field :similar_posts, PostType.connection_type, null: false

  # ...
end
```

(GraphQL-Ruby applies connection logic because the return type's name ends in `Connection`. You can manually override this with `connection: true` or `connection: false`.)

You can also define custom arguments and a custom resolve function for connections, just like other fields:

```ruby
field :featured_comments, CommentType.connection_type do
  # Add an argument:
  argument :since, String, required: false
end

def featured_comments(since: nil)
  comments = object.comments.featured
  if since
    comments = comments.where("created_at >= ?", since)
  end
  # Return an Array or ActiveRecord::Relation
  comments
end
```

### Maximum Page Size

You can limit the number of results with `max_page_size:`:

```ruby
field :featured_comments, CommentType.connection_type, null: false, max_page_size: 50
```

In addition, you can set a global default for all connection that do not specify a `max_page_size`:

```ruby
class MySchema < GraphQL::Schema
  default_max_page_size 100
end
```

## Connection types

You can customize connection and edge types by using the class-based API:

```ruby
# Make an edge class for use in the connection below:
class PostEdgeType < GraphQL::Types::Relay::BaseEdge
  node_type(PostType)
end

# Make a customized connection type
class PostConnectionWithTotalCountType < GraphQL::Types::Relay::BaseConnection
  edge_type(PostEdgeType)

  field :total_count, Integer, null: false
  def total_count
    # - `object` is the Connection
    # - `object.nodes` is the collection of Posts
    object.nodes.size
  end
end
```

__Note:__  If you use _classes_ for an object's connection or edge types, then all of that object's connection and edge types should be classes. Otherwise, the auto-generated types from the `.edge_type` or `.connection_type` helpers will conflict with the class-based types.

Now, you can use `PostConnectionWithTotalCountType` to define a connection with the "totalCount" field:

```ruby
class AuthorType < GraphQL::Schema::Object
{'fraction_non_alphanumeric': 0.08889248704663212, 'fraction_numerical': 0.0019430051813471502, 'mean_word_length': 5.134061569016882, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 5, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4901669', 'n_tokens_mistral': 1784, 'n_tokens_neox': 1697, 'n_words': 686}