offset の制限値を考慮した kintone のレコード一括取得について
はじめに
kintone のレコードを一括で取得する方法は 3 つあります。
本記事では、これらの取得方法について使い分けの判断基準を紹介します。
複数のレコードを取得する API の制限値
複数のレコードを取得する API の offset に指定可能な上限は、1 万までです。
1 万件を超えるレコードを取得する場合は、
カーソル API を利用する必要があります。
2020 年 7 月 12 日の定期メンテナンス以前から kintone をご利用の方は offset 制限値の詳細 も確認してください。
基本的な考え方
レコードを一括取得する方法には、次の 3 つの選択肢があります。
-
方法 1:レコード ID を利用する方法
レコードのソート条件を必要としない、つまりレコード ID 順で問題ない場合に有効です。 -
方法 2:カーソル API を利用する方法
レコードのソート条件を必要とする場合のうち、取得するレコードが 1 万件を超えると見込まれる場合に有効です。 -
方法 3:offset を利用する方法
将来的にも取得するレコードが 1 万件を超えないと見込まれる場合に有効です。
方法 1:レコード ID を利用する方法
特徴
複数のレコードを取得する API で、レコード ID(レコード番号)の昇順でソートを行い、ID 順にレコードを取得する方法です。
ID を利用する方法のポイントは、次の 2 点です。
- 「前回取得したレコードのうち一番最後のレコードのレコード ID < レコード ID」となるように絞り込みます。
order by $id asc
というレコード ID 順に並び替えます。
この方法は、kintone に限らず RDBMS 一般で知られており「シーク法」とも呼ばれています。
高速になる理由は、
こちらのページ
に詳しく紹介されています。
適しているシナリオ
この方法は、次のようなシナリオに適しています。
- レコードのソート条件を必要としない場合(レコード ID 順で問題ない場合)
- レコード ID 順にレコードを取得した後、プログラムのロジックで別のソートができる場合
理由
- レコード ID を利用する方法では、レコード取得にかかる時間がレコード数に対して線形比例するため、高速にレコードを取得できます。
- ただし、複数のフィールドでソートした結果を利用したい場合には、複雑なクエリが必要となります。
後述のコーディング例では、複数のフィールドでソートする場合も考慮しています。
実装に関連する情報
方法 2:カーソル API を利用する方法
特徴
カーソル API を使ってレコードを取得する方法です。
カーソル(cursor)とは、DB における用語で、データの検索結果に対する「いまどのデータを処理しているか?」という位置を保持するデータです。
DB 上にカーソルを作成し、作成したカーソルの位置情報からレコードを取得できます。
kintone のカーソル API を使ってレコードを一括で取得する流れは、次のとおりです。
- カーソルの作成 API を使って、カーソルを作成します。
- カーソルからレコードを取得する API を使って、レコードを取得します。
- カーソルの削除 API を使って、作成したカーソルを削除します。
カーソル API を利用する方法と、「方法 3:offset を利用する方法」とのデータ取得にかかる時間の比較は、 こちらの記事 を参照してください。
適しているシナリオ
この方法は、次のようなシナリオに適しています。
- バッチ処理など、必要なカーソル数を見積もりできる場合
理由
- 「方法 3:の offset を利用する方法」と比べ、ソート条件やレコードの件数によらず、レコード取得時間が安定しています。
- 「カーソル 1 ドメインにつき同時に作成できるカーソルは 10 個まで」という制約があります。
そのため、必要なカーソル数を見積もりできる、または制御できるような処理に向いています。
同時に複数のユーザーからのリクエストが想定される kintone JavaScript カスタマイズには向いていません。
実装に関連する情報
方法 3:offset を利用する方法
特徴
複数のレコードを取得する API を使い、リクエストパラメーターの offset を指定して順次レコードを取得する方法です。
offset はレコードの先頭からの距離を表す情報です。
offset と取得件数を表すリクエストパラメーター limit を指定して
複数のレコードを取得する API を実行すると、「offset 番目のレコードから limit 件」のレコードを取得します。
offset を利用する方法では、offset を少しずつ大きくしていくことで、取得するレコードの位置を指定しながら順次レコードを取得します。
適しているシナリオ
この方法は、次のようなシナリオに適しています。
- 取得するレコード件数が 1 万件を超えない場合
- レコード取得で 1 万件の制限を設けることができる場合
理由
- offset と limit を指定するのみでレコードを順次取得できるため、実装がシンプルになります。
実装に関連する情報
おわりに
レコードを一括で取得するための API の使い分けを紹介しました。 レコード数やソート条件の有無に応じて適切な方法を選択してください。
offset 制限値の詳細
2020 年 7 月 12 日の定期メンテナンスで
複数のレコードを取得する API の offset の上限値を 1 万に設定しました。
詳細は「
kintone API レコード一括取得 API の OFFSET の上限値制限について(2019 年 8 月 2 日)
」を確認してください。
レコード一括取得 API で offset 上限値 1 万を超える処理を行った場合、警告メッセージが表示されます。
対象は、超過後に該当のアプリを開いた kintone システム管理者(cybozu.com 共通管理者含む)、および該当のアプリ管理者です。
該当のアプリのレコード一覧画面の上部に、超過した日時と警告メッセージが表示されます。
超過すると、 7 月 12 日の定期メンテナンス以降から検知されます。表示の頻度は 30 日に 1 度です。
前回の表示から超過した場合、前回の表示から 30 日後に再表示されます。
例)9 月 1 日に表示。9 月 5 日に制限超過。10 月 1 日に再表示。(9 月 30 日までにプログラムを改修した場合も、9 月 5 日分の超過として表示されます)