# GraphQL API におけるページネーションの使用

GraphQL API でカーソルベースのページネーションを使用してデータセットを走査する方法を学びます。

## ページネーションについて

GitHub の GraphQL API は、GitHub のサーバーへの過剰な要求や不正な要求から保護するために 1 つの要求でフェッチできる項目数を制限します。 GraphQL API を使用する場合は、任意の接続に対して `first` または `last` 引数を指定する必要があります。 これらの引数の値は 1～100 で指定してください。 GraphQL API は、`first` または `last` 引数で指定された接続の数を返します。

アクセスするデータの接続数が、`first` または `last` 引数で指定された項目の数よりも多い場合、応答は指定したサイズの小さい "ページ" に分割されます。 これらのページは、データ セット全体が取得されるまで、1 つずつ順番に取得できます。 各ページには、`first` または `last` 引数で指定された項目の数が含まれます。そのページが最後のページである場合は、含まれる項目の数が少なくなる場合があります。

このガイドでは、ページ分割された応答に結果の追加ページを要求する方法、各ページで返される結果の数を変更する方法、および複数の結果ページをフェッチするスクリプトを記述する方法を示します。

## クエリで `cursor` を要求する

GraphQL API を使用する際は、カーソルを使用して、ページネーションされたデータセットを移動します。 カーソルは、データ セット内の特定の位置を表します。
`pageInfo` オブジェクトに対してクエリを実行すると、ページの最初と最後のカーソルを取得できます。 次に例を示します。

```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
      }
    }
  }
}
```

この例では、 `pageInfo.startCursor` はページの最初の項目のカーソルを指定します。
`pageInfo.endCursor` は、ページの最後の項目のカーソルを指定します。
`pageInfo.hasNextPage` と `pageInfo.hasPreviousPage` は 、返されたページの前後にページがあるかどうかを示します。

## ページごとのアイテム数の変更

`first` および `last` 引数は、返される項目の数を制御します。
`first` または `last` 引数を使用してフェッチできる項目の最大数は 100 個です。 レートまたはノードの制限に達しないように、クエリが大量のデータにタッチする場合は、100 個未満の項目を要求する必要がある場合があります。 詳しくは、「[GraphQL API のレート制限とクエリ制限](/ja/enterprise-server@3.22/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api)」をご覧ください。

## ページネーションを使用したデータセットの巡回

クエリからカーソルを返したら、カーソルを使用して結果の次のページを要求できます。 そのためには、`after` または `before` の引数とカーソルを使用します。

たとえば、前の例の `pageInfo.endCursor` 値が `Y3Vyc29yOnYyOpHOUH8B7g==` であったと仮定すると、このクエリを使用して結果の次のページを要求できます。

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

走査するページがなくなるまで、応答で返された新しい `pageInfo.endCursor` 値を使用してクエリを送信し続けることができ、それは `pageInfo.hasNextPage` が `false` を返すことによって示されます。

`last` 引数の代わりに `first` を指定した場合、結果の最後のページが最初に返されます。 この場合は、`pageInfo.startCursor` 値と `before` 引数を使用して、結果の前のページを取得します。
`pageInfo.hasPreviousPage` が `false` を返したら、最後のページに到達していることになります。 次に例を示します。

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

## 次のステップ

GitHub の Octokit SDK と `octokit/plugin-paginate-graphql` プラグインを使用して、スクリプトでのページネーションをサポートすることができます。 詳細については、「[plugin-paginate-graphql.js](https://github.com/octokit/plugin-paginate-graphql.js)を参照してください。