Relay specification compliance in GraphQL - Step-by-Step Execution

Concept Flow - Relay specification compliance

Client sends Relay-compliant query

↓

Server parses query

↓

Server resolves nodes with global IDs

↓

Server applies pagination and connections

↓

Server returns data with edges and pageInfo

↓

Client receives Relay-compliant response

This flow shows how a Relay-compliant GraphQL query is processed from client request to server response following Relay specs.

Execution Sample

GraphQL

query {
  user(id: "VXNlcjox") {
    id
    name
    friends(first: 2) {
      edges {
        node { id name }
      }
      pageInfo { hasNextPage }
    }
  }
}

This query fetches a user by global ID and requests the first 2 friends with Relay-style edges and pageInfo.

Execution Table

Step	Action	Evaluation	Result
1	Receive query with global ID 'VXNlcjox'	Parse user(id: "VXNlcjox")	User node identified with local ID 1
2	Resolve user fields	Fetch id and name	id: 'VXNlcjox', name: 'Alice'
3	Resolve friends connection with first: 2	Fetch first 2 friends edges	Edges with nodes: Bob(id: 'VXNlcjoz'), Carol(id: 'VXNlcjo0')
4	Resolve pageInfo	Check if more friends exist beyond first 2	hasNextPage: true
5	Construct response	Include edges and pageInfo	Response ready with Relay-compliant structure
6	Send response to client	Client receives data	Query complete

💡 All requested fields resolved and Relay connection structure returned

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
user	null	{id: 'VXNlcjox', name: 'Alice'}	{id: 'VXNlcjox', name: 'Alice', friends: {edges: [...]}}	{id: 'VXNlcjox', name: 'Alice', friends: {edges: [...], pageInfo: {hasNextPage: true}}}	{id: 'VXNlcjox', name: 'Alice', friends: {edges: [...], pageInfo: {hasNextPage: true}}}
friends.edges	null	null	[{node: {id: 'VXNlcjoz', name: 'Bob'}}, {node: {id: 'VXNlcjo0', name: 'Carol'}}]	[{node: {id: 'VXNlcjoz', name: 'Bob'}}, {node: {id: 'VXNlcjo0', name: 'Carol'}}]	[{node: {id: 'VXNlcjoz', name: 'Bob'}}, {node: {id: 'VXNlcjo0', name: 'Carol'}}]
friends.pageInfo	null	null	null	{hasNextPage: true}	{hasNextPage: true}

Key Moments - 3 Insights

Why does the user ID look like a strange string (e.g., 'VXNlcjox') instead of a simple number?

Relay uses global IDs encoded in base64 to uniquely identify nodes across the schema. This is why the ID looks encoded, as shown in execution_table step 1.

What is the purpose of the 'edges' and 'pageInfo' fields in the friends connection?

'edges' contain the actual friend nodes with cursors, and 'pageInfo' tells if more data is available for pagination. This structure is required by Relay, as seen in steps 3 and 4.

How does the server know how many friends to return?

The 'first: 2' argument tells the server to return only the first two friends, which is applied during resolution in step 3.

Visual Quiz - 3 Questions

Look at the execution_table, what is the value of 'hasNextPage' at step 4?

A true

B false

C null

D undefined

💡 Hint

Check the 'Result' column in execution_table row for step 4.

At which step does the server resolve the user's friends edges?

A Step 2

B Step 3

C Step 4

D Step 5

💡 Hint

Look at the 'Action' column in execution_table to find when friends edges are fetched.

If the query requested 'first: 3' friends instead of 2, how would the variable_tracker change?

A pageInfo would be removed

B user variable would change to null

C friends.edges would include 3 nodes instead of 2

D No change in friends.edges

💡 Hint

Refer to variable_tracker row for friends.edges and how it tracks nodes count.

Concept Snapshot

Relay specification compliance in GraphQL:
- Use global IDs encoded in base64 for node identification.
- Connections use 'edges' (with nodes) and 'pageInfo' for pagination.
- Arguments like 'first' control pagination size.
- Server resolves nodes and returns data in Relay-compliant structure.
- Client expects data with edges and pageInfo for smooth pagination.

Full Transcript

This visual execution trace shows how a Relay-compliant GraphQL query is processed. The client sends a query with a global ID to fetch a user and their friends with pagination. The server parses the query, decodes the global ID to find the user, fetches requested fields including the first two friends as edges, and determines if more friends exist via pageInfo. The response is constructed with edges and pageInfo fields as Relay requires. Variables like user and friends.edges update step-by-step. Key moments clarify why IDs are encoded, the role of edges and pageInfo, and how pagination arguments affect results. The quiz tests understanding of these steps and variable states. This helps beginners see how Relay compliance shapes query structure and server response.

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