Документация / 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 г.