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

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

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

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

• 方法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日分の超過として表示されます）

「kintone JavaScript Client（@kintone/rest-api-client）」「cil-kintone」を利用することで、offset、limitを考慮せずにレコードの一括取得が可能です。
詳細は以下の内容を参照してください。

• kintone JavaScript Client
• kintoneコマンドラインツール（cli-kintone）

REST APIは制限値の範囲内で実行してください。
制限値の詳細は以下のヘルプを参照してください。

• 制限値一覧/REST API