Relay specification compliance in GraphQL

Introduction

Relay specification compliance helps organize data fetching in GraphQL so apps can load data efficiently and smoothly.

When building a React app that needs to fetch data in small chunks for faster loading.

When you want to handle large lists of items with smooth scrolling or pagination.

When you want to keep track of data changes and update the UI automatically.

When you want to standardize how your GraphQL server handles pagination and connections.

When you want to make your GraphQL API compatible with Relay clients.

Syntax

GraphQL

type Query {
  items(first: Int, after: String): ItemConnection
}

type ItemConnection {
  edges: [ItemEdge]
  pageInfo: PageInfo
}

type ItemEdge {
  node: Item
  cursor: String
}

type PageInfo {
  hasNextPage: Boolean
  endCursor: String
}

Relay uses a special pattern called 'connections' to handle lists and pagination.

The 'edges' hold the actual items and cursors to track position in the list.

Examples

Fetches the first 5 items after the position marked by 'cursor123', including info if more items exist.

GraphQL

query {
  items(first: 5, after: "cursor123") {
    edges {
      node {
        id
        name
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Defines a connection type for users following Relay's structure.

GraphQL

type UserConnection {
  edges: [UserEdge]
  pageInfo: PageInfo
}

type UserEdge {
  node: User
  cursor: String
}

Sample Program

This query fetches the first 3 books with their ids and titles, plus pagination info.

GraphQL

query {
  books(first: 3) {
    edges {
      node {
        id
        title
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Important Notes

Relay's cursor-based pagination helps avoid problems with changing data during paging.

Always include 'pageInfo' to know if more data can be fetched.

Cursors are opaque strings that mark positions in the list.

Summary

Relay specification organizes data fetching with connections and edges.

It uses cursors to paginate smoothly through lists.

Following Relay makes your GraphQL API compatible with Relay clients.

Practice

1. What is the main purpose of the edges field in a Relay-compliant GraphQL connection?

easy

A. To store metadata about the entire list

B. To hold the list of items along with their cursors for pagination

C. To define the total count of items in the list

D. To specify the GraphQL schema version

Solution

1. Step 1: Understand Relay connection structure

   Relay connections use edges to represent each item with its cursor for pagination.

2. Step 2: Identify the role of edges

   The edges field contains nodes (items) and cursors, enabling smooth pagination.

3. Final Answer:

   To hold the list of items along with their cursors for pagination -> Option B

4. Quick Check:

   edges = items + cursors [OK]

Hint: Edges always pair items with cursors for pagination [OK]

Common Mistakes:

• Confusing edges with pageInfo
• Thinking edges store only items without cursors
• Mixing edges with totalCount field

2. Which of the following is the correct syntax to request the first 5 items in a Relay connection named users?

easy

A. { users(first: 5) { edges { node { id } } } }

B. { users(limit: 5) { edges { node { id } } } }

C. { users(count: 5) { edges { node { id } } } }

D. { users(take: 5) { edges { node { id } } } }

Solution

1. Step 1: Recall Relay pagination argument

   Relay uses first to specify how many items to fetch from the start.

2. Step 2: Check syntax correctness

   Only first: 5 is valid; limit, count, and take are not Relay standard arguments.

3. Final Answer:

   { users(first: 5) { edges { node { id } } } } -> Option A

4. Quick Check:

   Use first for Relay pagination [OK]

Hint: Use 'first' to fetch initial items in Relay queries [OK]

Common Mistakes:

• Using non-Relay arguments like limit or count
• Omitting edges or node fields
• Confusing Relay with REST query parameters

3. Given this GraphQL query on a Relay connection:

{ posts(first: 2) { edges { cursor node { title } } pageInfo { hasNextPage } } }

And the server returns:

{ "data": { "posts": { "edges": [ { "cursor": "cursor1", "node": { "title": "Post A" } }, { "cursor": "cursor2", "node": { "title": "Post B" } } ], "pageInfo": { "hasNextPage": true } } } }

What does hasNextPage indicate?

medium

A. The query failed to fetch posts

B. There are no more posts after the current 2

C. The current page is the last page

D. There are more posts available after the current 2

Solution

1. Step 1: Understand pageInfo.hasNextPage

   This field tells if more items exist beyond the current page.

2. Step 2: Interpret the returned value

   The value true means more posts exist after the fetched two.

3. Final Answer:

   There are more posts available after the current 2 -> Option D

4. Quick Check:

   hasNextPage = true means more data [OK]

Hint: True hasNextPage means more items exist [OK]

Common Mistakes:

• Assuming true means no more data
• Confusing hasNextPage with hasPreviousPage
• Ignoring pageInfo in Relay connections

4. You wrote this Relay connection query:

{ comments(last: 3) { edges { node { text } } } }

But the server returns an error:

"Field 'last' is not supported on this connection"

What is the likely cause?

medium

A. The connection does not support backward pagination with 'last'

B. The 'last' argument must be replaced with 'first'

C. The query is missing the 'before' cursor argument

D. The 'edges' field is misspelled

Solution

1. Step 1: Understand Relay pagination directions

   Relay supports forward pagination with first and backward with last.

2. Step 2: Identify server limitation

   Some connections only support forward pagination; thus, last is unsupported.

3. Final Answer:

   The connection does not support backward pagination with 'last' -> Option A

4. Quick Check:

   Unsupported 'last' means no backward pagination [OK]

Hint: Check if connection supports 'last' for backward pagination [OK]

Common Mistakes:

• Replacing 'last' with 'first' without cursor
• Assuming 'edges' spelling causes error
• Ignoring need for 'before' cursor with 'last'

5. You want to fetch a paginated list of products using Relay spec. You need to get the first 3 products, then fetch the next 3 after the last cursor. Which sequence of queries correctly follows Relay pagination?

hard

A. { products(last: 3) { edges { cursor node { name } } pageInfo { startCursor } } }{ products(first: 3, after: "startCursor") { edges { node { name } } } }

B. { products(first: 3) { edges { cursor node { name } } pageInfo { endCursor } } }{ products(last: 3, before: "endCursor") { edges { node { name } } } }

C. { products(first: 3) { edges { cursor node { name } } pageInfo { endCursor } } }{ products(first: 3, after: "endCursor") { edges { node { name } } } }

D. { products(first: 3) { edges { cursor node { name } } pageInfo { endCursor } } }{ products(first: 3, after: "cursor") { edges { node { name } } } }

Solution

1. Step 1: Fetch first 3 products with 'first' and get endCursor

   The first query correctly fetches 3 products and retrieves endCursor for next page.

2. Step 2: Use 'after' with endCursor to fetch next 3 products

   The second query uses after: "endCursor" to continue pagination forward.

3. Final Answer:

   Correct sequence uses 'first' and 'after' with endCursor -> Option C

4. Quick Check:

   Use endCursor with after for next page [OK]

Hint: Use endCursor with after to paginate forward [OK]

Common Mistakes:

• Using last with before for forward pagination
• Passing literal 'cursor' instead of actual endCursor value
• Mixing startCursor with after argument