Skip to content

Connection

The @connection directive marks an object type as a Relay Connection type, enabling standardized cursor-based pagination in your GraphQL schema.

Purpose

Use @connection to identify types that represent paginated lists following the Relay Connection specification. This enables:

  • Build-time validation of connection type structure
  • Integration with Viaduct's pagination utilities
  • Clear schema documentation of pagination patterns

Schema definition

The directive is defined in Viaduct's default schema:

"Marks an object type as a Relay Connection type"
directive @connection on OBJECT

Usage

Apply @connection to object types that follow the Relay Connection pattern:

"""
A connection to a list of Characters with pagination support.
Follows the Relay Connection specification.
"""
type CharactersConnection @connection @scope(to: ["default"]) {
  "List of character edges"
  edges: [CharacterEdge]
  "Pagination information"
  pageInfo: PageInfo!
}

View full file on GitHub

Connection types can include additional fields beyond the Relay spec minimum. Here's an example with an optional totalCount field:

"""
A connection to a list of Films.
Demonstrates usage of @connection directive.
"""
type FilmsConnection @connection @scope(to: ["default"]) {
  "A list of edges."
  edges: [FilmEdge]
  "Information to aid in pagination."
  pageInfo: PageInfo!
  "Total number of films (optional extension field)."
  totalCount: Int
}

View full file on GitHub

Requirements

Types marked with @connection must:

  1. Have a name ending in Connection
  2. Have an edges field returning a list of edge types (marked with @edge)
  3. Have a pageInfo: PageInfo! field

Note

Full validation and builder utilities are under development. See the Pagination guide for more details.