クエリの書き方

kintone の REST API でレコードを複数件取得する際、特定の条件に一致するレコードだけを取得したいケースは非常に多いです。

このような場合に使用するのがクエリ（query）パラメータです。クエリを適切に記述することで、必要なデータだけを効率的に取得できます。

この記事では、kintone のクエリの書き方を基礎から実践まで、豊富なサンプルコードと共に解説します。

クエリの基本構造

クエリは、演算子、関数、オプションを組み合わせて記述します。

const query = 'フィールドコード 演算子 "値" オプション';

例えば、「ステータス」フィールドが「対応中」のレコードを、更新日時の降順で 20 件取得する場合は以下のように記述します。

const query = 'ステータス in ("対応中") order by 更新日時 desc limit 20';

演算子一覧

演算子は「フィールドコード 演算子 値」の形式で記述します。

比較演算子

文字列演算子

論理演算子

フィールドタイプ別の演算子対応表

フィールドの種類によって使用できる演算子が異なります。

関数一覧

クエリでは、日付や現在のユーザーを動的に指定できる関数が用意されています。

ユーザー・組織関数

const query = '作成者 in (LOGINUSER())';

日付・日時関数

FROM_TODAY 関数の単位

FROM_TODAY 関数の第 2 引数には以下の単位を指定できます。

const query = '作成日時 >= FROM_TODAY(-7, DAYS)';

const query = '期限日 = THIS_MONTH(LAST)';

オプション

クエリの末尾にオプションを追加することで、取得するレコードの並び順や件数を制御できます。

order by（並び替え）

const query = 'ステータス in ("対応中") order by 更新日時 desc';

const query = 'order by 優先度 desc, 作成日時 asc';

• asc: 昇順（小さい順）
• desc: 降順（大きい順）
• 省略時はレコード ID の降順

limit（取得件数）

const query = 'ステータス in ("対応中") limit 20';

• 0〜500 の範囲で指定可能
• 省略時は 100 件

offset（スキップ件数）

const query = 'ステータス in ("対応中") offset 30';

• 0〜10,000 の範囲で指定可能
• 省略時は 0

実践的なサンプルクエリ

基本的な絞り込み

const query = '顧客名 = "サイボウズ株式会社"';

const query = '顧客名 like "株式会社"';

const query = 'ステータス in ("対応中", "確認中", "保留")';

日付による絞り込み

const query = '期限日 = TODAY()';

const query = '期限日 < TODAY() and ステータス not in ("完了")';

const query = '期限日 >= TODAY() and 期限日 <= THIS_WEEK(SUNDAY)';

const query = '作成日時 >= "2024-01-01" and 作成日時 <= "2024-12-31"';

複合条件

const query = '優先度 in ("高") and ステータス not in ("完了") order by 更新日時 desc';

// 「緊急」または「期限切れかつ未完了」のタスク
const query = '(優先度 in ("緊急")) or (期限日 < TODAY() and ステータス not in ("完了"))';

ユーザーによる絞り込み

const query = '担当者 in (LOGINUSER())';

const query = '作成者 in (LOGINUSER())';

空欄チェック

const query = 'コメント is empty';

const query = '添付ファイル is not empty';

JavaScript での実装例

基本的な使用方法

(() => {
  'use strict';

  /**
   * 条件に一致するレコードを取得する
   * @param {string} query - 検索条件
   * @returns {Promise<object[]>} レコードの配列
   */
  const fetchRecords = async (query) => {
    const appId = kintone.app.getId();
    const response = await kintone.api(kintone.api.url('/k/v1/records.json', true), 'GET', {
      app: appId,
      query,
    });
    return response.records;
  };

  kintone.events.on(['app.record.index.show'], async (event) => {
    // 今日が期限の未完了タスクを取得
    const query = '期限日 = TODAY() and ステータス not in ("完了") order by 優先度 desc';
    const records = await fetchRecords(query);

    console.log(`本日期限のタスク: ${records.length}件`);
    records.forEach((record) => {
      console.log(`- ${record['タスク名'].value}`);
    });

    return event;
  });
})();

動的なクエリの構築

(() => {
  'use strict';

  /**
   * 条件を動的に組み立ててクエリ文字列を生成する
   * @param {object} filters - フィルター条件
   * @returns {string} クエリ文字列
   */
  const buildQuery = (filters) => {
    const conditions = [];

    if (filters.status && filters.status.length > 0) {
      const statusList = filters.status.map((s) => `"${s}"`).join(', ');
      conditions.push(`ステータス in (${statusList})`);
    }

    if (filters.assignee) {
      conditions.push(`担当者 in ("${filters.assignee}")`);
    }

    if (filters.startDate) {
      conditions.push(`作成日時 >= "${filters.startDate}"`);
    }

    if (filters.endDate) {
      conditions.push(`作成日時 <= "${filters.endDate}"`);
    }

    let query = conditions.length > 0 ? conditions.join(' and ') : '';

    if (filters.orderBy) {
      query += ` order by ${filters.orderBy}`;
    }

    if (filters.limit) {
      query += ` limit ${filters.limit}`;
    }

    return query;
  };

  // 使用例
  const filters = {
    status: ['対応中', '確認中'],
    startDate: '2024-01-01',
    orderBy: '更新日時 desc',
    limit: 50,
  };

  const query = buildQuery(filters);
  console.log(query);
  // 出力: ステータス in ("対応中", "確認中") and 作成日時 >= "2024-01-01" order by 更新日時 desc limit 50
})();

エスケープ処理

クエリの値にダブルクォートやバックスラッシュが含まれる場合は、エスケープが必要です。

/**
 * クエリ値をエスケープする
 * @param {string} value - エスケープする値
 * @returns {string} エスケープ後の値
 */
const escapeQueryValue = (value) => {
  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
};

// 使用例
const customerName = 'サイボウズ "株式会社"';
const escapedName = escapeQueryValue(customerName);
const query = `顧客名 = "${escapedName}"`;
// 結果: 顧客名 = "サイボウズ \"株式会社\""

テーブル（サブテーブル）内フィールドの検索

テーブル内のフィールドを検索する場合、= や != 演算子は使用できません。代わりに in や not in を使用します。

// テーブル内の「対応日時」フィールドが特定の日時
const query = '対応日時 in ("2024-11-28T05:00:00Z")';

レコード番号（$id）での検索

レコード番号フィールドは、フィールドコードの代わりに $id システム識別子で指定できます。

const query = '$id >= 100 and $id <= 200';

const query = '$id not in (1, 2, 3)';

よくあるエラーと対処法

「不正なクエリです」エラー

よくある原因と対処法：

1. フィールドコードの誤り: フィールド名ではなくフィールドコードを使用しているか確認
2. 演算子の不一致: フィールドタイプに対応した演算子を使用しているか確認
3. 引用符の不足: 文字列値は必ずダブルクォートで囲む
4. エスケープ漏れ: 特殊文字が含まれる場合はエスケープ処理を行う

// ❌ 選択系フィールドに = を使用
const query = 'ステータス = "対応中"';

// ✅ 選択系フィールドには in を使用
const query = 'ステータス in ("対応中")';

// ❌ 文字列値を引用符で囲んでいない
const query = '顧客名 = サイボウズ';

// ✅ 文字列値はダブルクォートで囲む
const query = '顧客名 = "サイボウズ"';

まとめ

kintone のクエリを適切に使用することで、必要なデータだけを効率的に取得できます。

ポイントをまとめると：

• フィールドコードを正確に指定する
• フィールドタイプに応じた演算子を使用する
• 日付関数を活用して動的な条件を設定する
• 複雑な条件は括弧でグループ化する
• 特殊文字は適切にエスケープする

これらを押さえておくことで、kintone REST API をより効果的に活用できるようになります。

関連ページ

練習問題