kintoneのレコードを一括で取得する方法は3つあります。
本記事では、これらの取得方法について使い分けの判断基準を紹介します。

複数のレコードを取得する API のoffsetに指定可能な上限は、1万までです。
1万件を超えるレコードを取得する場合は、 カーソル APIを利用する必要があります。

2020年7月12日の定期メンテナンス以前からkintoneをご利用の方は offset 制限値の詳細も確認してください。

レコードを一括取得する方法には、次の3つの選択肢があります。

• 方法 1：レコード ID を利用する方法
  レコードのソート条件を必要としない、つまりレコードID順で問題ない場合に有効です。
• 方法 2：カーソル API を利用する方法
  レコードのソート条件を必要とする場合のうち、取得するレコードが1万件を超えると見込まれる場合に有効です。
• 方法 3：offset を利用する方法
  将来的にも取得するレコードが1万件を超えないと見込まれる場合に有効です。

  

複数のレコードを取得する APIで、レコードID（レコード番号）の昇順でソートを行い、ID順にレコードを取得する方法です。

IDを利用する方法のポイントは、次の2点です。

• 「前回取得したレコードのうち一番最後のレコードのレコードID < レコードID」となるように絞り込みます。
• order by $id ascというレコードID順に並び替えます。

この方法は、kintoneに限らずRDBMS一般で知られており「シーク法」とも呼ばれています。
高速になる理由は、 こちらのページ に詳しく紹介されています。

この方法は、次のようなシナリオに適しています。

• レコードのソート条件を必要としない場合（レコードID順で問題ない場合）
• レコードID順にレコードを取得した後、プログラムのロジックで別のソートができる場合

理由

• レコードIDを利用する方法では、レコード取得にかかる時間がレコード数に対して線形比例するため、高速にレコードを取得できます。
• ただし、複数のフィールドでソートした結果を利用したい場合には、複雑なクエリが必要となります。
  後述のコーディング例では、複数のフィールドでソートする場合も考慮しています。

• レコード一括取得の JavaScript コーディング例 - レコード ID を利用する方法

カーソル APIを使ってレコードを取得する方法です。

カーソル（cursor）とは、DBにおける用語で、データの検索結果に対する「いまどのデータを処理しているか？」という位置を保持するデータです。
DB上にカーソルを作成し、作成したカーソルの位置情報からレコードを取得できます。

kintoneのカーソルAPIを使ってレコードを一括で取得する流れは、次のとおりです。

1. カーソルの作成 APIを使って、カーソルを作成します。
2. カーソルからレコードを取得する APIを使って、レコードを取得します。
3. カーソルの削除 APIを使って、作成したカーソルを削除します。

カーソルAPIを利用する方法と、「方法3：offsetを利用する方法」とのデータ取得にかかる時間の比較は、 こちらの記事を参照してください。

この方法は、次のようなシナリオに適しています。

• バッチ処理など、必要なカーソル数を見積もりできる場合

理由

• 「方法3：のoffsetを利用する方法」と比べ、ソート条件やレコードの件数によらず、レコード取得時間が安定しています。
• 「カーソル1ドメインにつき同時に作成できるカーソルは10個まで」という制約があります。
  そのため、必要なカーソル数を見積もりできる、または制御できるような処理に向いています。
  同時に複数のユーザーからのリクエストが想定されるkintone JavaScriptカスタマイズには向いていません。

• レコード一括取得の JavaScript コーディング例 - カーソル API を利用する方法

複数のレコードを取得する APIを使い、リクエストパラメーターのoffsetを指定して順次レコードを取得する方法です。

offsetはレコードの先頭からの距離を表す情報です。
offsetと取得件数を表すリクエストパラメーター limitを指定して 複数のレコードを取得する APIを実行すると、「offset番目のレコードからlimit件」のレコードを取得します。

offsetを利用する方法では、offsetを少しずつ大きくしていくことで、取得するレコードの位置を指定しながら順次レコードを取得します。

この方法は、次のようなシナリオに適しています。

• 取得するレコード件数が1万件を超えない場合
• レコード取得で1万件の制限を設けることができる場合

理由

• offsetとlimitを指定するのみでレコードを順次取得できるため、実装がシンプルになります。

• レコード一括取得の JavaScript コーディング例 - offset を利用する方法

レコードを一括で取得するためのAPIの使い分けを紹介しました。 レコード数やソート条件の有無に応じて適切な方法を選択してください。

2020年7月12日の定期メンテナンスで 複数のレコードを取得する APIのoffsetの上限値を1万に設定しました。
詳細は「 kintone API レコード一括取得 API の OFFSET の上限値制限について（2019 年 8 月 2 日） 」を確認してください。

レコード一括取得APIでoffset上限値1万を超える処理を行った場合、警告メッセージが表示されます。
対象は、超過後に該当のアプリを開いたkintoneシステム管理者（cybozu.com共通管理者含む）、および該当のアプリ管理者です。
該当のアプリのレコード一覧画面の上部に、超過した日時と警告メッセージが表示されます。

超過すると、7月12日の定期メンテナンス以降から検知されます。表示の頻度は30日に一度です。
前回の表示から超過した場合、前回の表示から30日後に再表示されます。
例）9月1日に表示。9月5日に制限超過。10月1日に再表示。（9月30日までにプログラムを改修した場合も、9月5日分の超過として表示されます）