複数のレコードを取得するAPIを利用する際、リクエストパラメーターの「totalCount」をどう設定していますか？
totalCountパラメーターの使い方によっては、複数のレコードを取得するAPIの処理が遅くなります。
後で詳細を記載しますが、totalCountパラメーターにtrueを指定すると、falseを指定した時よりも処理速度は遅くなる特性があります。
この記事では、totalCountパラメーターにtrueを指定した際の複数のレコードを取得するAPIの実行時の処理速度が、以下の条件が変わることで、どのように変化するのか検証します。

• 「クエリの絞り込みで使うフィールドの種類」
• 「クエリで絞り込んだ際、条件に合致するレコード数」

検証結果から、複数のレコードを取得するAPIを快適に実行してもらうために、totalCountパラメーターを指定する際の注意点を紹介します。

本記事では、フィールドの種類について以下のように記載します。

• 選択フィールド：ラジオボタン、ドロップダウン、チェックボックス、複数選択

• 単一選択フィールド：ラジオボタン、ドロップダウン

• 複数選択フィールド：チェックボックス、複数選択

警告

ご利用の環境内のデータ量等の要因により処理速度は変わります。

• 同様のリクエストパラメーターで複数のレコードを取得するAPIを実行した場合に同じ結果を保証するものではありません。
• 将来にわたっても同様の結果になることを保証するものではありません。

複数のレコードを取得するAPIのリクエストパラメーターの1つです。

queryで指定した条件に一致するレコードの件数を取得するかどうかを指定できます。

• true：件数を取得する。
• false：件数を取得しない。

APIの詳細は以下を確認してください。
複数のレコードを取得する - cybozu developer network

• 件数を取得する処理実行によって処理速度が遅くなります。
• 複数のレコードを取得するAPIのリクエストを繰り返し実行した場合、falseを指定した際と比較してリクエストが大幅に遅延するなど、kintoneを快適に使えなくなる場合があります。

• totalCountパラメーターにtrueとfalseを指定した際の処理速度の比較
• totalCountパラメーターにtrueを指定した場合において、以下の条件に基づき、処理速度の差を比較
  1. クエリの絞り込み条件で使うフィールドの種類
  2. クエリで絞り込んだ際、条件に合致するレコード数（以降「クエリで絞り込んだ際のヒットするレコード数」）
• クエリで絞り込んだ際、条件に合致するレコードを全件取得した際の処理速度の差を比較

以下検証A、検証Bの条件で確認します。
複数のレコードを取得するAPIを実行する時、指定するクエリ（ 検証時に実行したリクエストパラメーターの8行目 ）で、絞り込んだ際のヒットするレコード数の違いによる処理速度を比較します。

• 検証A: クエリで絞り込んだ結果、ヒットするレコード数が10,000件、20,000件、30,000件、40,000件の場合

• 検証B: クエリで絞り込んだ結果、ヒットするレコード数が1件、10件、100件、500件の場合

それに加えて、検証A・検証Bそれぞれにおいて、クエリで使用するフィールドの種類が処理速度に与える影響も比較します。

• 使用した検証環境：kintone 2024年11月版
• ブラウザー：Google Chrome

以下の画像のように、フィールドを配置したアプリを用意します。 アクセス権は設定しません。

• 選択フィールド：選択肢を4つ用意（sample1～sample4）
  • ラジオボタン2のみ選択肢を5つ用意（「---」、sample1～sample4）
• ユーザー選択フィールド：選択肢を4つ用意（ユーザー1～ユーザー4）

以下の表の記載内容で、アプリに100,000件のレコードを登録します。

検証Aで使用するフィールドのレコード登録内容

検証Bで使用するフィールドのレコード登録内容

4行目のフィールドコードin（"選択肢"）と6行目の「totalCount:true」の箇所を都度変更して実行します。

1
2
3
4
5
6
7

const body = {
  app: kintone.app.getId(),
  query:
    `フィールドコード in ("選択肢") order by レコード番号 asc limit 500 offset 0`,
  fields: ["レコード番号"],
  totalCount: true,
};

totalCountパラメーターにtrueを指定したときの処理速度が、falseを指定した時よりも遅くなることを確認しました。

検証Aにおいて、クエリで絞り込んだ際のヒットするレコード数が40,000件の条件の場合の処理速度は以下のようになりました。 （単位は「秒」です）

totalCountパラメーターにtrueを指定した場合において、以下の条件に基づき、処理速度の差を比較した結果を記載します。

1. クエリの絞り込み条件で使うフィールドの種類
2. クエリで絞り込んだ際のヒットするレコード数

単一選択フィールド・数値フィールドと比べて、複数選択フィールド・ユーザー選択フィールドは処理速度が遅かったです。

クエリで絞り込んだ際のヒットするレコード数が多い場合、処理速度は遅くなる傾向が見られました。
検証Bの、複数選択フィールド、ユーザー選択フィールドでは、その傾向が見られない場合もありました。

検証結果では、totalCountパラメーターにtrue / falseを指定した場合の差は数秒にとどまっています。

しかし、totalCountパラメーターにtrueを指定して複数のレコードを取得するAPIのリクエストを繰り返し実行した場合、リクエストが大幅に遅延する等、kintoneを快適に使えなくなる場合があります。

そこで、追加で以下の検証をしました。

複数のレコードを取得するAPIを以下の条件で指定し、offsetを利用して条件に合致するレコード10,000件を全件取得します。

• クエリの条件
  1. チェックボックスのsample1で、totalCountパラメーターにtrue / falseを指定
  2. ラジオボタンのsample1で、totalCountパラメーターにtrue / falseを指定

複数のレコードを取得するAPIを複数回実行する場合、totalCountパラメーターにtrue / falseを指定したときの処理速度の差がさらに開きました。

• totalCountパラメーターにtrueを指定したときの処理速度が、falseを指定した時よりも遅くなることを確認しました。

• totalCountパラメーターにtrueを指定した場合

  1. クエリの絞り込み条件で使うフィールドの種類に、単一選択フィールド・数値フィールドを使用したときに比べて、複数選択フィールド・ユーザー選択フィールドを使用したときは処理速度が遅くなりました。
  2. クエリで絞り込んだ際のヒットするレコード数が多い場合、処理速度は遅くなる傾向がありました。

• 複数のレコードを取得するAPIを複数回実行する場合、totalCountパラメーターにtrue / falseを指定したときの処理速度の差がさらに開きました。

• 複数のレコードを取得するAPIの絞り込みでヒットしたレコード数を数える必要がない場合は、totalCountパラメーターにfalseを指定する。

• 複数のレコードを取得するAPIでtotalCountパラメーターにtrueを指定する場合は、以下を推奨する。

  1. 複数選択フィールドやユーザー選択フィールドをクエリの絞り込みの条件に使わないこと（今回の検証の中では処理速度が速かった単一選択フィールドや数値フィールドを使うこと）
  2. クエリで絞り込んだ際のヒットするレコード数を少なくすること

• 上記の「2. クエリで絞り込んだ際のヒットするレコード数を少なくする」の他に、複数のレコードを取得するAPIの実行件数を最小限にできる方法を試す。
  例：レコードデータ取得対象のアプリに不要なレコードがある場合は削除・アーカイブする。

• totalCountパラメーターにtrueを指定して複数のレコードを取得するAPIのリクエストを繰り返し実行した場合、リクエストが大幅に遅延する等、kintoneを快適に使えなくなる場合があります。（ totalCountパラメーターとは？ に記載）

• 本記事を参考に、totalCountパラメーターの性質を理解し、使い所を見極めて、複数のレコードを取得しましょう。

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