offset の制限値を考慮した kintone のレコード一括取得について

目次

はじめに

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

複数のレコードを取得する API の制限値

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

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

基本的な考え方

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

方法 1:レコード ID を利用する方法

特徴

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

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

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

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

適しているシナリオ

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

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

実装に関連する情報

方法 2:カーソル API を利用する方法

特徴

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

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

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

  1. カーソルの作成 API を使って、カーソルを作成します。
  2. カーソルからレコードを取得する API を使って、レコードを取得します。
  3. カーソルの削除 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 日) (External link) 」を確認してください。

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

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