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

目次

はじめに

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

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

  • カーソル(Cursor)API の説明
  • 複数のレコードを取得する API(records.json)で offset を指定した場合の性能比較

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

カーソル API が追加された理由

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

  • レコード ID によるソートのみでよい場合: 方法 1:レコード ID を利用する方法
  • レコード ID 以外のソートが必要な場合:カーソル API によるレコード一括取得(この記事で紹介します)

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

カーソル(Cursor)とは

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

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

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

  1. カーソルを作成する API を使用し、カーソルを作成する。

  2. カーソルからレコードを取得する API を使用し、レコードを取得する。

  3. 検索対象のレコードがなくなるまで 2 を繰り返し、レコードを取得する。

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

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

条件 1

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

条件 2

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

条件 3

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

条件 4

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

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

まとめ

複数のレコードを取得する API(records.json のパラメーター offset に上限値が設定されます。
offset による方法でレコードの一括取得を行っている場合は、より高速で一括取得可能なカーソルによる方法に移行をしてください。

主な制限事項

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

information

この Tips は、2019 年 7 月版 kintone で動作を確認しています。