Connection pattern (edges, nodes, pageInfo) in GraphQL - Deep Dive

Overview - Connection pattern (edges, nodes, pageInfo)

What is it?

The connection pattern is a way to organize lists of data in GraphQL. It breaks down a list into smaller parts called edges and nodes, and includes pageInfo to help with navigation. This pattern helps clients get data in chunks and know if more data is available.

Why it matters

Without this pattern, clients would struggle to load large lists efficiently or know if there is more data to fetch. It solves the problem of handling big data sets smoothly, improving user experience by loading data page by page instead of all at once.

Where it fits

Before learning this, you should understand basic GraphQL queries and types. After this, you can learn about cursor-based pagination and how to implement efficient data fetching in APIs.

Mental Model

Core Idea

The connection pattern organizes lists into edges and nodes with pageInfo to enable smooth, cursor-based pagination in GraphQL.

Think of it like...

Imagine a book's table of contents where each chapter (node) is listed with page numbers (edges), and the pageInfo tells you if there are more chapters ahead or behind.

Connection
├─ edges
│  ├─ cursor
│  └─ node (actual data item)
└─ pageInfo
   ├─ hasNextPage
   ├─ hasPreviousPage
   ├─ startCursor
   └─ endCursor

Build-Up - 7 Steps

1

Foundation

Basic list fetching in GraphQL

Concept: How to request a simple list of items in GraphQL.

In GraphQL, you can ask for a list of items by querying a field that returns an array of objects. For example, querying all users might return a list of user objects with their names and IDs.

Result

You get all items in one response, like a list of users with their details.

Understanding simple list queries is the base for learning how to handle larger lists efficiently.

2

Foundation

Problems with large lists

Concept: Why fetching all items at once can be inefficient or slow.

When a list is very large, sending all items in one response can be slow and use a lot of resources. It can also make the client slow or unresponsive because it has to process too much data at once.

Result

You realize that fetching all data at once is not practical for big lists.

Knowing the limits of simple list fetching motivates the need for better patterns like pagination.

3

Intermediate

Introduction to the connection pattern

Concept: How the connection pattern structures list data with edges and nodes.

The connection pattern wraps list items inside edges, where each edge contains a cursor and a node. The node is the actual data item, and the cursor is a unique identifier for that position in the list. This helps in fetching data in parts.

Result

You get a list where each item is inside an edge with a cursor, ready for pagination.

Understanding edges and nodes is key to grasping how GraphQL handles pagination smoothly.

4

Intermediate

Role of pageInfo in pagination

Concept: How pageInfo provides navigation details for the list.

pageInfo is an object that tells if there are more items before or after the current list chunk. It includes booleans like hasNextPage and hasPreviousPage, and cursors for the start and end of the current list slice.

Result

You can tell if more data is available and where to fetch next.

Knowing pageInfo helps clients decide when and how to load more data.

5

Intermediate

Cursor-based pagination explained

🤔Before reading on: Do you think cursor-based pagination uses page numbers or unique positions? Commit to your answer.

Concept: How cursors mark positions in the list for fetching next or previous items.

Instead of page numbers, cursor-based pagination uses unique strings (cursors) that point to specific items. When fetching the next page, the client sends the cursor of the last item received to get the following items.

Result

Pagination becomes more reliable and efficient, especially when data changes between requests.

Understanding cursors prevents common bugs with offset pagination and improves data consistency.

6

Advanced

Implementing connection pattern in GraphQL schema

🤔Before reading on: Do you think edges and pageInfo are mandatory in the schema or optional? Commit to your answer.

Concept: How to define types for edges, nodes, and pageInfo in a GraphQL schema.

You define an Edge type with a cursor and node field, a Connection type with edges and pageInfo fields, and a PageInfo type with navigation booleans and cursors. Your query returns the Connection type for lists.

Result

Your API supports the connection pattern, enabling clients to paginate data properly.

Knowing the schema structure is essential for building APIs that follow best practices for pagination.

7

Expert

Handling real-world challenges with connections

🤔Before reading on: Do you think connection pattern handles data changes during pagination perfectly? Commit to your answer.

Concept: How to deal with data changes, caching, and performance when using the connection pattern.

In real systems, data can change between paginated requests, causing missing or duplicated items. Using stable cursors, consistent sorting, and careful cache invalidation helps maintain correct pagination. Also, limiting page size and optimizing database queries improves performance.

Result

Pagination remains reliable and efficient even with data updates and heavy load.

Understanding these challenges prepares you to build robust, production-ready pagination systems.

Under the Hood

The connection pattern works by wrapping each list item in an edge object that includes a cursor, which uniquely identifies the item's position. The server uses these cursors to fetch slices of data efficiently. pageInfo provides metadata about the current slice, enabling clients to navigate forward or backward. This design supports cursor-based pagination, which is more stable than offset-based pagination because it relies on unique positions rather than numeric offsets.

Why designed this way?

The pattern was designed to solve problems with traditional pagination like offset-based methods, which can break when data changes or when items are inserted or deleted. By using cursors, the connection pattern ensures consistent and reliable pagination. It also standardizes pagination in GraphQL, making it easier for clients and servers to communicate about list navigation.

Client Request
   │
   ▼
Server
 ┌─────────────────────────────┐
 │  Fetch data slice using      │
 │  cursor from edges           │
 └─────────────┬───────────────┘
               │
               ▼
       Data slice with
       edges and pageInfo
               │
               ▼
           Client
   Uses pageInfo to
   request next slice

Myth Busters - 4 Common Misconceptions

Quick: Does the connection pattern always return all items in one response? Commit yes or no.

Common Belief: The connection pattern returns the entire list of items at once.

Reality: It returns only a slice of the list with edges and pageInfo to support pagination, not the full list.

Why it matters: Assuming it returns all data can lead to inefficient queries and slow applications.

Quick: Is the cursor in edges just a number like a page number? Commit yes or no.

Common Belief: Cursors are simple page numbers used to fetch pages.

Reality: Cursors are opaque strings that uniquely identify an item's position, not simple numbers.

Why it matters: Misunderstanding cursors can cause broken pagination and data inconsistency.

Quick: Does pageInfo guarantee that data won't change between pages? Commit yes or no.

Common Belief: pageInfo ensures data stays the same during pagination.

Reality: pageInfo only informs about navigation; data can still change between requests.

Why it matters: Expecting static data can cause bugs like missing or duplicated items in paginated lists.

Quick: Can you skip edges and just return nodes directly in the connection? Commit yes or no.

Common Belief: Edges are optional; you can return nodes directly without edges.

Reality: Edges are part of the standard connection pattern and include cursors needed for pagination.

Why it matters: Skipping edges breaks cursor-based pagination and client navigation.

Expert Zone

1

Cursors should be stable and opaque to clients to prevent misuse and ensure consistent pagination.

2

The order of items must be deterministic and consistent across requests to avoid pagination errors.

3

Combining connection pattern with filtering and sorting requires careful cursor design to maintain correctness.

When NOT to use

Avoid the connection pattern for very small or fixed-size lists where pagination is unnecessary. For simple offset-based pagination needs, traditional limit-offset queries may suffice. Also, if your data source does not support stable cursors, alternative pagination methods might be better.

Production Patterns

In production, APIs use the connection pattern with Relay-compliant schemas for frontend frameworks. They implement cursor encoding strategies, cache invalidation, and limit maximum page sizes. Some systems combine connections with subscriptions to update paginated lists in real time.

Connections

Cursor-based pagination

The connection pattern builds on cursor-based pagination principles.

Understanding cursor-based pagination clarifies why connections use cursors instead of page numbers.

REST API pagination

Connection pattern offers a more reliable alternative to REST offset-limit pagination.

Comparing these helps appreciate the stability and efficiency improvements in GraphQL pagination.

Linked data structures

Edges and nodes resemble linked list elements with pointers (cursors).

Recognizing this helps understand how pagination moves through data step-by-step.

Common Pitfalls

#1 Returning all items without pagination causes slow responses.

Wrong approach:

query { users { id name } }

Correct approach:

query { usersConnection(first: 10) { edges { cursor node { id name } } pageInfo { hasNextPage endCursor } } }

Root cause:

Not using the connection pattern or pagination arguments leads to fetching too much data at once.

#2 Using numeric offsets as cursors breaks pagination consistency.

Wrong approach:

edges { cursor: 1, node: {...} }, cursor is just a number

Correct approach:

edges { cursor: "opaqueString", node: {...} }, cursor is a unique encoded string

Root cause:

Misunderstanding cursor purpose causes unstable pagination when data changes.

#3 Omitting pageInfo makes it impossible to know if more data exists.

Wrong approach:

returning only edges without pageInfo

Correct approach:

returning edges plus pageInfo with hasNextPage and cursors

Root cause:

Ignoring pageInfo removes essential navigation info for clients.

Key Takeaways

The connection pattern organizes list data into edges and nodes with pageInfo to enable efficient cursor-based pagination.

Cursors uniquely identify positions in the list, making pagination stable even when data changes.

pageInfo provides navigation details like whether more pages exist and the cursors for the current slice.

Implementing the connection pattern correctly requires defining schema types for edges, nodes, and pageInfo.

Understanding this pattern helps build scalable APIs that deliver data smoothly and reliably to clients.