カテゴリー内の他の記事

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

フォローする

Index

はじめに

kintone API レコード一括取得 API の OFFSET の上限値制限について(2019年8月2日)」でお知らせしていますが、レコード一括取得 API のパラメータ offset の上限値 1 万件の設定を、2020 年 7 月頃に実施する予定です。
それに伴い、レコード一括取得時にその結果が 1 万を超える可能性がある場合には、運用・適用中のプログラムのご確認ならびに修正対応の検討をお願いいたします。

レコードを一括で取得する方法については、現在大きく3つの選択肢が考えられます。今回はこれらの方法の使い分けについて紹介します。

基本的な考え方

レコードを一括取得する方法には、「レコード ID を利用する方法」「カーソル API を利用する方法」「offset を利用する方法」の 3つの選択肢があります。

レコードのソート条件を必要としない場合(レコード ID 順で問題ない場合)場合、方法1: レコード ID を利用する方法を利用できます。

レコードのソート条件を必要とする場合のうち、取得するレコードが 1 万件を超えると見込まれる場合、方法2: カーソル API を利用する方法を利用してください。

一方、将来的にも取得するレコードが 1 万件を超えないと見込まれる場合、方法3: offset を利用する方法も利用可能です。

レコード一括取得の3つの方法

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

特徴 

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

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

  • 「レコード ID > 前回取得したレコードの中で一番最後のレコードのレコード ID」となるように絞り込みを行うこと
  • 「order by $id asc」というレコード ID 順に並び替えること

id.png

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

適しているシナリオ

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

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

理由

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

実装に関連する情報

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

特徴

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

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

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

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

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

適しているシナリオ

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

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

理由

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

実装に関連する情報

方法 3 offset を利用する方法

特徴

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

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

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

適しているシナリオ

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

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

理由

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

実装に関連する情報

SDK の対応状況

SDK 対応状況

kintone JavaScript SDK

  • カーソル API を利用する方法
  • offset を利用する方法
kintone Java SDK
  • カーソル API を利用する方法
  • offset を利用する方法

kintone iOS SDK

  • offset を利用する方法

記事に関するフィードバック

直接的に記事と関連がないご質問はcybozu developer コミュニティをご活用ください。

ログインしてコメントを残してください。