diff --git a/.github/workflows/remove-from-fr-board.yaml b/.github/workflows/remove-from-fr-board.yaml index d1e48ca3f61d..8ecef7069961 100644 --- a/.github/workflows/remove-from-fr-board.yaml +++ b/.github/workflows/remove-from-fr-board.yaml @@ -29,12 +29,3 @@ jobs: env: GITHUB_TOKEN: ${{secrets.DOCS_BOT_PAT_WORKFLOW_READORG}} PR_URL: https://github.com/${{ github.event.client_payload.command.repository.full_name }}/pull/${{ github.event.client_payload.command.resource.number }} - - - name: Check out repo - if: ${{ failure() }} - uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4.0.0 - - uses: ./.github/actions/slack-alert - if: ${{ failure() }} - with: - slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }} - slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }} diff --git a/content/graphql/guides/forming-calls-with-graphql.md b/content/graphql/guides/forming-calls-with-graphql.md index 1305db75581b..2659ddd8ff67 100644 --- a/content/graphql/guides/forming-calls-with-graphql.md +++ b/content/graphql/guides/forming-calls-with-graphql.md @@ -407,7 +407,7 @@ For more information on the difference between enums and strings, see the [offic There is a _lot_ more you can do when forming GraphQL calls. Here are some places to look next: -- [Pagination](https://graphql.org/learn/pagination/) +- [AUTOTITLE](/graphql/guides/using-pagination-in-the-graphql-api) - [Fragments](https://graphql.org/learn/queries/#fragments) - [Inline fragments](https://graphql.org/learn/queries/#inline-fragments) - [Directives](https://graphql.org/learn/queries/#directives) diff --git a/content/graphql/guides/index.md b/content/graphql/guides/index.md index 7311e5cf39d3..d745f87d6f6c 100644 --- a/content/graphql/guides/index.md +++ b/content/graphql/guides/index.md @@ -16,8 +16,8 @@ children: - /using-global-node-ids - /migrating-from-rest-to-graphql - /using-the-explorer + - /using-pagination-in-the-graphql-api - /managing-enterprise-accounts - /using-the-graphql-api-for-discussions - /migrating-graphql-global-node-ids --- - diff --git a/content/graphql/guides/introduction-to-graphql.md b/content/graphql/guides/introduction-to-graphql.md index 14b05bdf9c0a..661ff5d5fb0e 100644 --- a/content/graphql/guides/introduction-to-graphql.md +++ b/content/graphql/guides/introduction-to-graphql.md @@ -71,7 +71,7 @@ It's helpful to picture a graph: dots connected by lines. The dots are nodes, th ## Edge -Edges represent connections between nodes. When you query a connection, you traverse its edges to get to its nodes. Every `edges` field has a `node` field and a `cursor` field. Cursors are used for [pagination](https://graphql.github.io/learn/pagination/). +Edges represent connections between nodes. When you query a connection, you traverse its edges to get to its nodes. Every `edges` field has a `node` field and a `cursor` field. Cursors are used for pagination. For more information, see "[AUTOTITLE](/graphql/guides/using-pagination-in-the-graphql-api)." ## Node diff --git a/content/graphql/guides/using-pagination-in-the-graphql-api.md b/content/graphql/guides/using-pagination-in-the-graphql-api.md new file mode 100644 index 000000000000..896cc7dfe741 --- /dev/null +++ b/content/graphql/guides/using-pagination-in-the-graphql-api.md @@ -0,0 +1,101 @@ +--- +title: Using pagination in the GraphQL API +intro: Learn how to traverse data sets using cursor based pagination with the GraphQL API. +versions: + fpt: '*' + ghes: '*' + ghae: '*' + ghec: '*' +topics: + - API +shortTitle: Pagination +--- + +## About pagination + +{% data variables.product.company_short %}'s GraphQL API limits the number of items that you can fetch in a single request in order to protect against excessive or abusive requests to GitHub's servers. When you use the GraphQL API, you must supply a `first` or `last` argument on any connection. The value of these arguments must be between 1 and 100. The GraphQL API will return the number of connections specified by the `first` or `last` argument. + +If the data that you are accessing has more connections than the number of items specified by the `first` or `last` argument, the response is divided into smaller "pages" of the specified size. These pages can be fetched one at a time until the entire data set has been retrieved. Each page contains the number of items specified by the `first` or `last` argument, unless it is the last page, which may contain a lower number of items. + +This guide demonstrates how to request additional pages of results for paginated responses, how to change the number of results returned on each page, and how to write a script to fetch multiple pages of results. + +## Requesting a `cursor` in your query + +When using the GraphQL API, you use cursors to traverse through a paginated data set. The cursor represents a specific position in the data set. You can get the first and last cursor on a page by querying the `pageInfo` object. For example: + +```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 + } + } + } +} +``` + +In this example, `pageInfo.startCursor` gives the cursor for the first item on the page. `pageInfo.endCursor` gives the cursor for the last item on the page. `pageInfo.hasNextPage` and `pageInfo.hasPreviousPage` indicate whether there is a page before and after the page that was returned. + +## Changing the number of items per page + +The `first` and `last` arguments control how many items are returned. The maximum number of items you can fetch using the `first` or `last` argument is 100. You may need to request fewer than 100 items if your query touches a lot of data in order to avoid hitting a rate or node limit. For more information, see "[AUTOTITLE](/graphql/overview/rate-limits-and-node-limits-for-the-graphql-api)." + +## Traversing the data set using pagination + +Once you return a cursor from a query, you can use the cursor to request the next page of results. To do so, you will use the `after` or `before` argument and the cursor. + +For example, assuming the `pageInfo.endCursor` value from the previous example was `Y3Vyc29yOnYyOpHOUH8B7g==`, you can use this query to request the next page of results: + +```graphql +query($owner: String!, $name: String!) { + repository(owner: $owner, name: $name) { + pullRequests(first: 1, after: "Y3Vyc29yOnYyOpHOUH8B7g==") { + nodes { + createdAt + number + title + } + pageInfo { + endCursor + hasNextPage + hasPreviousPage + } + } + } +} +``` + +You can continue to send queries with the new `pageInfo.endCursor` value returned in the response until there are no pages left to traverse, indicated by `pageInfo.hasNextPage` returning `false`. + +If you specified the `last` instead of the `first` argument, the last page of results will be returned first. In this case, you will use the `pageInfo.startCursor` value and the `before` argument to get the previous page of results. Once `pageInfo.hasPreviousPage` returns `false`, you have reached the last page. For example: + +```graphql +query($owner: String!, $name: String!) { + repository(owner: $owner, name: $name) { + pullRequests(last: 1, before: "R3Vyc29yOnYyOpHOHcfoOg==") { + nodes { + createdAt + number + title + } + pageInfo { + startCursor + hasPreviousPage + } + } + } +} +``` + +## Next steps + +You can use {% data variables.product.company_short %}'s Octokit SDK and the `octokit/plugin-paginate-graphql` plugin to support pagination in your scripts. For more information, see "[plugin-paginate-graphql.js](https://github.com/octokit/plugin-paginate-graphql.js)." diff --git a/content/graphql/index.md b/content/graphql/index.md index 73d31225efd7..4502d00d5ccb 100644 --- a/content/graphql/index.md +++ b/content/graphql/index.md @@ -13,7 +13,7 @@ featuredLinks: - /graphql/overview/explorer - /graphql/overview/public-schema - /graphql/overview/schema-previews - - /graphql/guides/using-the-graphql-api-for-discussions + - /graphql/guides/using-pagination-in-the-graphql-api guideCards: - /graphql/guides/migrating-from-rest-to-graphql - /graphql/guides/managing-enterprise-accounts @@ -33,4 +33,3 @@ children: - /reference - /guides --- -