# Como usar paginação na API GraphQL

Saiba como percorrer conjuntos de dados usando a paginação baseada em cursor com a API GraphQL.

## Sobre paginação

A API GraphQL do GitHub limita o número de itens em que você pode efetuar fetch em uma única solicitação, para proteger contra solicitações excessivas ou abusivas aos servidores do GitHub. Ao usar a API GraphQL, você deve fornecer um argumento `first` ou `last` em todas as conexões. O valor desses argumentos deve ficar entre 1 e 100. A API GraphQL retornará o número de conexões especificado pelo argumento `first` ou `last`.

Se os dados que você está acessando tiverem mais conexões do que o número de itens especificado pelo argumento `first` ou `last`, a resposta será dividida em "páginas" menores do tamanho especificado. É possível efetuar fetch em uma dessas páginas por vez, até que todo o conjunto de dados tenha sido recuperado. Cada página contém o número de itens especificado pelo argumento `first` ou `last`, a menos que seja a última página, que talvez contenha um número menor de itens.

Este guia demonstra como solicitar páginas adicionais de resultados para respostas paginadas, como alterar o número de resultados retornados em cada página e como escrever um script para buscar várias páginas de resultados.

## Como solicitar um `cursor` em sua consulta

Ao usar a API GraphQL, você usa cursores para percorrer um conjunto de dados paginado. O cursor representa uma posição específica no conjunto de dados. Você pode obter o primeiro e o último cursor em uma página consultando o objeto `pageInfo`. Por exemplo:

```graphql
query($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    pullRequests(first: 100, after: null) {
      nodes {
        createdAt
        number
        title
      }
      pageInfo {
        endCursor
        startCursor
        hasNextPage
        hasPreviousPage
      }
    }
  }
}
```

Neste exemplo, `pageInfo.startCursor` fornece o cursor para o primeiro item na página.
`pageInfo.endCursor` fornece o cursor para o último item na página.
`pageInfo.hasNextPage` e `pageInfo.hasPreviousPage` indicam se há uma página antes e depois da que foi retornada.

## Como alterar o número de itens por página

Os argumentos `first` e `last` controlam quantos itens são retornados. O número máximo de itens em que você pode efetuar fetch usando o argumento `first` ou `last` é 100. Talvez seja necessário solicitar menos de 100 itens se a consulta resultar em muitos dados, para evitar atingir um limite de uma taxa ou nó. Para saber mais, confira [Limites de taxas e limites de consultas para a API GraphQL](/pt/enterprise-server@3.22/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api).

## Como percorrer o conjunto de dados usando paginação

Depois de um cursor ser retornado de uma consulta, você pode usá-lo para solicitar a próxima página de resultados. Para fazer isso, você usará o argumento `after` ou `before` e o cursor.

Por exemplo, supondo que o valor `pageInfo.endCursor` do exemplo anterior era `Y3Vyc29yOnYyOpHOUH8B7g==`, você pode usar essa consulta para solicitar a próxima página de resultados:

```graphql
query($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    pullRequests(first: 1, after: "Y3Vyc29yOnYyOpHOUH8B7g==") {
      nodes {
        createdAt
        number
        title
      }
      pageInfo {
        endCursor
        hasNextPage
        hasPreviousPage
      }
    }
  }
}
```

Você pode continuar a enviar consultas com o novo valor `pageInfo.endCursor` retornado na resposta até que não haja mais páginas para percorrer, indicado por `pageInfo.hasNextPage` retornando `false`.

Se você especificou o argumento `last` em vez do `first`, a última página de resultados será retornada primeiro. Nesse caso, você usará o valor o `pageInfo.startCursor` e o argumento `before` para obter a página anterior de resultados. Quando `pageInfo.hasPreviousPage` tiver retornado `false`, você terá chegado à última página. Por exemplo:

```graphql
query($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    pullRequests(last: 1, before: "R3Vyc29yOnYyOpHOHcfoOg==") {
      nodes {
        createdAt
        number
        title
      }
      pageInfo {
        startCursor
        hasPreviousPage
      }
    }
  }
}
```

## Próximas etapas

Você pode usar o SDK Octokit do GitHub e o plugin `octokit/plugin-paginate-graphql` para dar suporte à paginação em seus scripts. Para obter mais informações, consulte [plugin-paginate-graphql.js](https://github.com/octokit/plugin-paginate-graphql.js).