Документация / GraphQL
Пагинация
Частая задача в GraphQL — обход связи между наборами объектов. Такие связи можно открыть в GraphQL по-разному, и разработчик клиента получает разные возможности. На этой странице разобрано, как делать пагинацию полей по модели соединений с курсорами.
Списки
Проще всего открыть связь между объектами полем, которое возвращает список. Например, чтобы получить друзей R2-D2, можно просто запросить их всех:
query {
hero {
name
friends {
name
}
}
}
Ответ:
{
"data": {
"hero": {
"name": "R2-D2",
"friends": [
{
"name": "Luke Skywalker"
},
{
"name": "Han Solo"
},
{
"name": "Leia Organa"
}
]
}
}
}
Срезы
Но быстро выясняется, что клиенту нужно больше. Клиент может захотеть указать, сколько друзей получить, — например, только первых двух. Тогда нужно что-то вроде:
query {
hero {
name
friends(first: 2) {
name
}
}
}
Получив первых двух, клиент может захотеть листать дальше: вторым запросом получить следующих двух друзей. Как это обеспечить?
Пагинация и рёбра
Сделать пагинацию можно по-разному:
friends(first:2 offset:2)— следующие два в списке;friends(first:2 after:$friendId)— следующие два после последнего полученного друга;friends(first:2 after:$friendCursor)— берём курсор последнего элемента и листаем от него.
Первый способ — классическая пагинация смещением (offset). У неё бывают недостатки в производительности и безопасности, особенно на больших наборах данных. Кроме того, если после запроса страницы в базу добавились новые записи, смещения следующих страниц становятся неоднозначными.
В целом самой мощной из перечисленных оказалась пагинация курсорами. Особенно если курсоры непрозрачные: через курсоры можно реализовать и пагинацию смещением, и пагинацию по идентификатору (сделав курсором смещение или идентификатор), а если модель пагинации потом изменится, курсоры дадут свободу манёвра. Чтобы напомнить, что курсоры непрозрачны и на их формат нельзя полагаться, рекомендуем кодировать их в base64.
Но тут возникает вопрос: как получить курсор объекта? Курсору не место в типе User — это свойство связи, а не
объекта. Поэтому вводим ещё один уровень: поле friends возвращает список рёбер (edges), а у ребра есть и
курсор, и сам объект — узел (node):
query {
hero {
name
friends(first: 2) {
edges {
node {
name
}
cursor
}
}
}
}
Ребро полезно и для сведений, относящихся к связи, а не к объектам. Например, если API должен сообщать «время дружбы», ребро — естественное место для этого поля.
Конец списка, количество и соединения
Теперь соединение можно листать курсорами, но как узнать, что достигнут конец? Пришлось бы запрашивать, пока не вернётся пустой список, а хочется, чтобы соединение само сообщало о конце и лишний запрос был не нужен. И что если нужны сведения о самом соединении — например, сколько всего друзей у R2-D2?
Чтобы решить обе задачи, поле friends может возвращать объект соединения (connection). Это объектный тип с
полем для рёбер и другими сведениями — общим количеством, признаком наличия следующей страницы. Итоговый запрос
может выглядеть так:
query {
hero {
name
friends(first: 2) {
totalCount
edges {
node {
name
}
cursor
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
В объект PageInfo можно добавить и endCursor и startCursor. Тогда, если дополнительные сведения рёбер не
нужны, рёбра можно не запрашивать вовсе — курсоры для пагинации есть в pageInfo. Отсюда возможное улучшение
соединений: кроме списка edges дать отдельный список одних узлов, чтобы обойтись без промежуточного уровня.
Полная модель соединения
Это явно сложнее исходного варианта с простым списком! Но такая модель даёт клиенту несколько возможностей:
- листать список;
- запрашивать сведения о самом соединении, например
totalCountилиpageInfo; - запрашивать сведения о ребре, например
cursorилиfriendshipTime; - менять способ пагинации на backend, ведь клиент работает только с непрозрачными курсорами.
Всё это есть в схеме примеров — в поле friendsConnection:
interface Character {
id: ID!
name: String!
friends: [Character]
friendsConnection(first: Int, after: ID): FriendsConnection!
appearsIn: [Episode]!
}
type FriendsConnection {
totalCount: Int
edges: [FriendsEdge]
friends: [Character]
pageInfo: PageInfo!
}
type FriendsEdge {
cursor: ID!
node: Character
}
type PageInfo {
startCursor: ID
endCursor: ID
hasNextPage: Boolean!
}
Пример запроса — два друга после первого: курсор Y3Vyc29yMQ== указывает на первого друга. Без аргумента
after пагинация начнётся с начала списка. А вместо поля edges можно запросить вспомогательное поле friends
соединения — тогда список друзей придёт сразу, без промежуточного уровня рёбер, если клиенту так удобнее:
query {
hero {
name
friendsConnection(first: 2, after: "Y3Vyc29yMQ==") {
totalCount
edges {
node {
name
}
cursor
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
Ответ:
{
"data": {
"hero": {
"name": "R2-D2",
"friendsConnection": {
"totalCount": 3,
"edges": [
{
"node": {
"name": "Han Solo"
},
"cursor": "Y3Vyc29yMg=="
},
{
"node": {
"name": "Leia Organa"
},
"cursor": "Y3Vyc29yMw=="
}
],
"pageInfo": {
"endCursor": "Y3Vyc29yMw==",
"hasNextPage": false
}
}
}
}
}
Спецификация соединений
Чтобы этот шаблон реализовывали единообразно, у проекта Relay есть формальная
спецификация соединений с курсорами: ей можно следовать при
проектировании API GraphQL с курсорной пагинацией, даже если вы не используете Relay. По ней аргументы
first/after листают вперёд, last/before — назад, а типы называют XConnection и XEdge:
type Product {
id: ID!
title: String!
}
type ProductEdge {
"Курсор позиции — передаётся в after, чтобы получить следующую страницу"
cursor: String!
node: Product!
}
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
type ProductConnection {
edges: [ProductEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type Query {
products(first: Int = 20, after: String, last: Int, before: String): ProductConnection!
}
Обёртки
Connection,EdgeиPageInfoзагромождают карту схемы, поэтому редактор по умолчанию их сворачивает: полеproductsпоказано как список[Product]с пометкой Relay. Галочка «Свернуть Relay» в панели «Описание» возвращает обёртки на карту.
Итоги
Подведём итоги рекомендаций по пагинации полей схемы GraphQL:
- поля-списки, которые могут вернуть много данных, должны поддерживать пагинацию;
- пагинация курсорами даёт полям схемы GraphQL устойчивую модель пагинации;
- спецификация соединений с курсорами проекта Relay задаёт единообразный шаблон пагинации полей схемы GraphQL.
Похожие инструменты
Обновлено: 17 октября 2026 г.
