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:
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 taxa e limites de nó para a API GraphQL.
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:
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:
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, confira plugin-paginate-graphql.js.