kintone API のクエリの書き方の基本

目次

はじめに

今回は、クエリの書き方の基本について紹介したいと思います。
クエリを使用すると、ある条件で絞り込んだ特定のレコードを取得できます。
クエリの書き方がよりわかりやすいように、アプリを用いながら紹介してきたいと思います。
もちろんアプリを使用しなくても、クエリの書き方のみ参考にしていただいてかまいません。
ぜひ開発に役立ていただければと思います。

アプリの準備

アプリストアから「問い合わせ管理」を追加します。
参考: サンプルアプリを追加する (External link)
アプリを作成する際には「サンプルデータを含める」にチェックを入れてください。
また、アプリの設定画面から以下のようにフィールドコードを変更してください。

フィールド名 フィールドコード
対応日時 ResponseDate
対応内容 Correspondence

クエリの書き方

式の形式について

クエリは、主に以下の形式に沿って式を書いていきます。

1
<フィールドコード> <演算子> <値 または 関数>

より詳しいクエリの仕様や、フィールドごとに使える演算子・関数については クエリの書き方 を確認してください。
では、実際にレコードを取得してみましょう。
JavaScript でクエリを指定してレコードを取得するサンプルは、本記事の クエリに変数を代入する で紹介しています。

文字列(1行)の値を指定する

以下の条件を指定して、実際にレコードを取得してみましょう。

完全一致:「顧客名」フィールドの値が「山田商事株式会社」

文字列を完全一致で指定する際は、以下のように = 演算子を使用します。

1
Customer = "山田商事株式会社"
部分一致:「顧客名」フィールドの値に「株式会社」を含む

文字列を部分一致で指定する際は、以下のように like 演算子を使用します。

1
Customer like "株式会社"

ドロップダウンの値を指定する

以下の条件を指定して、実際にレコードを取得してみましょう。
ドロップダウンフィールドの値を指定する際は、以下のように innot in 演算子を使用します。
innot in 演算子を使用する際には、値を () で囲う必要があります。

「対応状況」フィールドの値に「対応中」または「未対応」を含む
1
Status in ("対応中","未対応")
「対応状況」フィールドの値に「完了」を含まない
1
Status not in("完了")

また、以下のフィールドは、ドロップダウンと同じように、innot in 演算子を使用してレコードを取得できます。

  • チェックボックス
  • ラジオボタン
  • 複数選択

日付フィールドの値を指定する

以下の条件を指定して、実際にレコードを取得してみましょう。

「期限」フィールドの値が「2018-02-01」
1
LimitDay = "2018-02-01"

日付フィールドでは、一致するもの以外にも範囲を指定して絞り込みを行うことができます。
以下の条件を指定して、実際にレコードを取得してみましょう。

「期限」フィールドの値が「2018-02-01」から「2018-03-01」まで
1
LimitDay >= "2018-02-01" and LimitDay <= "2018-03-01"

このように、複数の条件を指定する際には and 演算子を使って式をつなげていきます。

テーブル内のフィールドの値を取得する

テーブル内のフィールドを取得する際には =!= 演算子が使えません。
その代わりに in もしくは not in 演算子を使う必要があります。
実際に、以下の条件でフィールドを取得してみましょう。

「対応日時」フィールドの値が「2018-01-05 14:00」
1
ResponseDate in("2018-01-05T05:00:00Z")

「日付フィールドの値を指定する」で紹介したように、通常は日付フィールドや日時フィールドに対しては =!= 演算子を使用します。
しかし、テーブル内では使用できなくなってしまうので注意が必要です。

ここまでは、フィールド単体を指定したクエリを紹介しました。
次は、複数のフィールドを指定する方法について紹介します。

複数のフィールドや条件の指定

「日付フィールドの値を指定する」の最後にも指定しましたが、andor 演算子を使って複数の条件を指定できます。
まずは、and 演算子を使用して複数のフィールドの条件をクエリで指定してみましょう。

「and」を使用した条件の指定
  • 「期限」フィールドの値が「今日」より前
  • 「対応状況」フィールドの値に「完了」を含まない。
1
LimitDay < TODAY () and Status not in ("完了")

「期限」フィールドの条件に TODAY() 関数を指定しました。
TODAY() 関数というのは、クエリで使える関数のひとつです。
関数を使用すれば、いちいち日付を指定しなくても「今日」「先週」や「来週」といった条件を簡単に指定できます。
他の関数は クエリの書き方 > 関数 を参照ください。

「order by」を使用した条件の指定

続いて、先ほどの条件にもうひとつ条件を追加してみましょう。

  • 「期限」フィールドの値が「今日」より前
  • 「対応状況」フィールドの値に「完了」が含まれない。
  • 「期限」フィールドの値の「昇順」で取得する。
1
LimitDay < TODAY() and Status not in ("完了")order by LimitDay asc

このように、order by オプションを使うことでレコードの出力される順番をソートできます。

式のグループ化

複数のフィールドに対して複数の条件を指定する際には、式をグループしましょう。
式を丸括弧 () で囲うことでグループ化できます。
グループ化を行うことでより詳細な条件を指定できます。

式をグループ化した場合の条件の指定

「問い合わせ種別」フィールドの値が「その他」、または「期限」フィールドの値が「2018-02-01」から「2018-03-01」まで。

1
(QType in ("その他")) or (LimitDay >= "2018-02-01" and LimitDay <= "2018-03-01")

クエリに変数を代入する

最後に変数を代入する方法について紹介したいと思います。
実際に JavaScript を使用してクエリを書く際には、クエリ内に変数を含めるケースがあるかと思います。
たとえば、レコードから取得した値をクエリに代入したりするケースです。
こういった動的な値を使用してクエリを書くためには文字列を変数を分けて考える必要があります。

レコードを開いたときに、「期限日」の値が同じ他のレコードを取得したいケースを想定して考えてみましょう。
上記の条件を実装するには、以下の順番で処理が必要です。

  1. 開いているレコードの値を取得する。
  2. 取得した値をクエリに代入する。

実際に、コードをみていきましょう。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
/*
 * kintone API のクエリの書き方のサンプルコード
 * Copyright (c) 2020 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
 */
(() => {
  'use strict';

  kintone.events.on('app.record.detail.show', (event) => {
    const record = event.record;
    const limitDay = record.LimitDay.value;
    const query = 'LimitDay = "' + limitDay + '"';

    const body = {
      app: kintone.app.getId(),
      query: query
    };

    kintone.api(kintone.api.url('/k/v1/records', true), 'GET', body, (resp) => {
      // success
      console.log(resp);
    }, (error) => {
      // error
      console.log(error);
    });
    return event;
  });
})();

ポイント

上のコードの 7 行目がポイントです。

1
const query = 'LimitDay = "' + limitDay + '"';

レコード取得の条件となるクエリには、レコード内の「期限」フィールドの値を代入しています。
このように、JavsScript 内の変数をクエリに代入するためには、文字列として結合する必要があります。

おわりに

クエリの書き方は、一度コツをつかめたら簡単に書くことができます。
今回は書き方についての紹介をしましたが、簡単にクエリを作ることができる便利な方法もあります。
その他のクエリ作成方法については レコード一括取得APIのクエリを簡単に作りたい を参照してください。

クエリは、組み合わせることによってさまざまなデータを取得でき、実際の開発で利用することも多いです。
クエリを活用して、これからも kintone をより便利にカスタマイズしていただければと思います。