カーソル API を使ってレコードを一括取得する

はじめに

2019年 7月版 kintone に カーソル API という新規 API が追加されます。

• カーソルの作成
• カーソルからレコードを取得
• カーソルの削除

この カーソル API はレコード全件取得のための API です。
本記事では、次の内容をご紹介します。

• カーソル（Cursor） API の説明
• レコードの一括取得API（records.json）で offset を指定した場合の性能比較

カーソルAPIを使ったレコード取得のコーディング例は、「レコード一括取得の JavaScript コーディング例：カーソル API を利用する方法」をご参照ください。

追加理由

2020年7月定期メンテナンスで、レコードの一括取得 API （records.json）のパラメータである offset に上限値1万件を設定することを予定しています。
offset に上限値が設定されるため、offset による方法でレコードの一括取得を行っていて、かつ取得レコード数が1万を超える可能性がある場合は、次の方法でレコードを取得してください。

• レコード ID によるソートのみでよい場合：レコードIDによるレコード一括取得
• レコード ID 以外のソートが必要な場合：カーソル API によるレコード一括取得（この記事で紹介します）

記事の後半で紹介しますが、カーソル API による方法では、offset に比べ複雑なソート条件下でもレスポンスが劣化しないことがメリットとして挙げられます。

カーソル（Cursor）とは

DB における用語の１つで DB 内の位置を保持するデータです。
DB 上にカーソルを作成し、作成したカーソルの位置情報からレコードを取得するということが可能になります。

今回 kintone に追加されたカーソルに関する API は以下の3つです。

カーソルを作成する
作成したカーソルからレコードを取得する
作成したカーソルを削除する

この API を使ってレコードを取得する一連の流れは以下のようになります。

１．カーソルを作成する API を使用し、カーソルを作成する

２．カーソルからレコードを取得する API を使用し、レコードを取得する

３．検索対象のレコードがなくなるまで２を繰り返し、レコードを取得する

offset による一括取得との比較

API のリクエストパラメータで、ソート条件とレコードの取得数を変更し、
様々な条件でレコード取得までにかかる時間を計測することで、offset と カーソル API の比較をしていきます。
各条件ごとのグラフは、カーソルの作成から取得対象のレコードを取得してくるまでの累積時間です。

条件①

• 10万レコード
• $id のソート

グラフ

条件②

• 10万レコード
• 文字列1行のソート

グラフ

条件③

• 50万レコード
• $id のソート

グラフ

条件④

• 50万レコード
• 文字列1行のソート

グラフ

グラフを見ていただくと一目瞭然ですが、カーソルによる一括取得の方が取得時間が安定して早いことがわかります。
逆に offset による方法はソート方法やレコード件数により、取得時間が左右されており、安定していないことがわかります。

まとめ

Get Records のパラメーターである offset に上限値が設定されるため、
offset による方法でレコードの一括取得を行っている場合は、より高速で一括取得可能なカーソルによる方法に移行をしてください。

主な制限事項

• カーソルは1ドメインにつき同時に10個まで作成できます。
• カーソルの作成にかけられる時間は5分間です。それ以降はタイムアウトします。
• カーソルの有効期限はカーソルの作成 または カーソルからレコードを取得 による最終リクエスト時刻から10分です。

その他の制限事項についてはドキュメントを参照してください。

このTipsは、2019年7月版 kintoneで確認したものになります。