Пагинация

Пагинация используется практически во всех запросах, где возвращается список элементов. Она используется для ограничения количества одновременно запрашиваемых элементов. Количество элементов контролируется параметром first, который должен быть в пределах от 1 до 50. Некоторые узлы могут иметь другой верхний лимит для first. При превышении лимита параметр first будет равен максимально возможному значению. Этот аргумент опциональный, и при отсутствии будет так же использоваться верхний предел.

Получение курсора

В GraphQL API для навигации по страницам используется курсор. Курсор указывает на конкретный элемент в коллекции. В pageInfo содержится курсор, указывающий на последний элемент на странице:

graphql

query PaginationPersonsSimple {
  persons(first: 2) {
    pageInfo {
      first
      hasNextPage
      endCursor
    }
    items {
      id
      firstName
    }
  }
}

cURL

curl https://api.talantix.ru/graphql \
 -X POST \
-H "Content-Type: application/json" \
-H "User-Agent: api-doc-agent" \
-H "Authorization: Bearer <your access token>" \
-d "{\"query\":\"query PaginationPersonsSimple {\\n  persons(first: 2) {\\n    pageInfo {\\n      first\\n      hasNextPage\\n      endCursor\\n    }\\n    items {\\n      id\\n      firstName\\n    }\\n  }\\n}\"}"

Посмотреть в playground

примечание

Подробнее про query persons и объект persons

Во всех узлах с пагинацией имеется объект items, представляющий собой массив запрашиваемых элементов, и объект pageInfo, который содержит информацию о текущей странице.

• first - сколько элементов запрошено на странице
• hasNextPage - имеются ли элементы на следующей странице
• endCursor - курсор, указывающий на последний элемент на странице

Получение следующей страницы

Запрос первой страницы позволяет получить endCursor, допустим в этом случае равный 123456789|2. Чтобы получить страницу начиная со следующего элемента, необходимо указать его в параметре after:

graphql

query PaginationPersonsWithCursor {
  persons(first: 2, after: "123456789|2") {
    pageInfo {
      first
      endCursor
      hasNextPage
    }
    items {
      id
      firstName
    }
  }
}

cURL

curl https://api.talantix.ru/graphql \
 -X POST \
-H "Content-Type: application/json" \
-H "User-Agent: api-doc-agent" \
-H "Authorization: Bearer <your access token>" \
-d "{\"query\":\"query PaginationPersonsWithCursor {\\n  persons(first: 2, after: \\\"123456789|2\\\") {\\n    pageInfo {\\n      first\\n      endCursor\\n      hasNextPage\\n    }\\n    items {\\n      id\\n      firstName\\n    }\\n  }\\n}\"}"

Посмотреть в playground

Последующие страницы запрашиваются аналогичным образом, страница с pageInfo.hasNextPage = false является последней

Краткий флоу работы с пагинацией

1. Делаем первый запрос без after аргумента, при необходимости ограничиваем требуемым количеством элементов параметром first
2. В результате предыдущего запроса получаем курсор, указывающий на последний элемент - pageInfo.endCursor
3. Используем полученный курсор в следующем запросе в качестве аргумента after, получаем следующую страницу и повторяем процесс пока не получим pageInfo.hasNextPage = false.