第 4 回 kintone コマンドラインツール(cli-kintone v0)でクエリ指定して絞り込み・並び順変更をしてみよう
このチュートリアルは ver. 0.x.x の cli-kintone の使い方を紹介しています。
ver.1.0.0 以降の cli-kintone の使い方を紹介するチュートリアルは次のページを参照してください。
はじめよう cli-kintone
はじめに
前回までで、cli-kintone を使ったレコード操作は、ほぼできるようになったのではないでしょうか。
今回は、クエリを使ったレコードの絞り込みや並び替えの方法を紹介します。
詳細は
クエリの書き方の記事 で確認していただくとして、ここではクエリの基本的な書き方をおぼえていきましょう。
クエリの書き方
基本的な式の書き方
フィールドの値または関数で扱うレコードを絞り込む場合、「フィールドコード(またはシステム識別子)」「演算子」「値(または関数)」で構成される式を使います。
式の基本書式
|
|
たとえば 数値_0
フィールドの値が 10
以上のレコードを抽出する場合、式は以下のようになります。
|
|
フィールドコード 数値_0
、演算子 >=
、条件の境界になる値 10
、これらを、フィールドコード、演算子、値の順に組み合わたものを 1 セットとして記述します。
in, not in を使用する場合
式の書き方は多くの場合上の書式で対応できますが、一部の演算子を使用する場合は若干異なります。
演算子に in
, not in
を使用する場合、以下の書式になります。
in, not in 演算子を使用する場合の書式
|
|
値の記述
クエリ内部では、関数を除いたすべての値をダブルクオート "
で囲って表記します。
値の記述例
|
|
式のグループ化
単独の式で条件を指定できるケースもありますが、より詳細な条件を指定したい場合も多いと思います。
式は丸括弧 ()
でくくるとグループ化できます。
また and
, or
を用いて、「かつ」「または」を含む条件を表現できます。
これらの演算子で複数の式を結合すると、より詳細な条件を指定できます。
グループ化された式の例
|
|
この例の場合、下記 2 つのどちらかの条件に当てはまるレコードが抽出されます。
数値
フィールドの値が100
以上で、かつ、文字列一行
フィールドに文字列テスト
を含む値をもつレコード更新日時
フィールドの値を、前月 1 日
に設定しているレコード
and, or の優先順位
式がグループ化されていない場合、論理積の演算子 and
が優先されます。
前項の例の場合、or
よりも and
が優先的に処理されるので、括弧を外した場合も同じ条件となります。
関連レコードに含まれるフィールドの指定
関連レコードに含まれるフィールドを指定する場合、下記いずれかの書式で式を書くことができます。
関連レコードを指定する場合の基本書式
|
|
in, not in 演算子を使用する場合の書式
|
|
cli-kintone のログインユーザー
cli-kintone では、API トークン認証の場合は Administrator、パスワード認証の場合はそのユーザーがログインユーザーとなります。
したがって LOGINUSER()
または PRIMARY_ORGANIZATION()
の関数を利用する場合、そのログインユーザーを基準に関数が処理されます。
演算子および関数と利用可能なフィールドの一覧
基本的なクエリの書き方がわかったところで、各演算子・関数に対して使えるフィールドの種類を確認してみましょう。
演算子と利用可能なフィールド
演算子 | フィールドまたはシステム識別子 |
---|---|
= |
レコード番号、$id、作成日時、更新日時、文字列(1 行)、リンク、数値、日付、時刻、日時、ステータス |
!= |
レコード番号、$id、作成日時、更新日時、文字列(1 行)、リンク、数値、日付、時刻、日時、ステータス |
> |
レコード番号、$id、作成日時、更新日時、数値、日付、時刻、日時 |
< |
レコード番号、$id、作成日時、更新日時、数値、日付、時刻、日時 |
>= |
レコード番号、$id、作成日時、更新日時、数値、日付、時刻、日時 |
<= |
レコード番号、$id、作成日時、更新日時、数値、日付、時刻、日時 |
in |
レコード番号、$id、作成者、更新者、文字列(1 行)、リンク、数値、チェックボックス、ラジオボタン、ドロップダウン、複数選択、ユーザー選択、組織選択、グループ選択 |
not in |
レコード番号、$id、作成者、更新者、文字列(1 行)、リンク、数値、チェックボックス、ラジオボタン、ドロップダウン、複数選択、ユーザー選択、組織選択、グループ選択 |
like |
文字列(1 行)、リンク、文字列(複数行)、リッチエディター、添付ファイル |
not like |
文字列(1 行)、リンク、文字列(複数行)、リッチエディター、添付ファイル |
テーブル化されたフィールドは =
, !=
の代わりに in
, not in
を利用する必要があります。
関数と利用可能なフィールド
関数 | フィールドまたはシステム識別子 |
---|---|
LOGINUSER() |
作成者、更新者、ユーザー選択 |
PRIMARY_ORGANIZATION() |
組織選択 |
NOW() |
作成日時、更新日時、日時 |
TODAY() |
作成日時、更新日時、日付、日時 |
YESTERDAY() |
作成日時、更新日時、日付、日時 |
TOMORROW() |
作成日時、更新日時、日付、日時 |
FROM_TODAY() |
作成日時、更新日時、日付、日時 |
THIS_WEEK() |
作成日時、更新日時、日付、日時 |
LAST_WEEK() |
作成日時、更新日時、日付、日時 |
NEXT_WEEK() |
作成日時、更新日時、日付、日時 |
THIS_MONTH() |
作成日時、更新日時、日付、日時 |
LAST_MONTH() |
作成日時、更新日時、日付、日時 |
NEXT_MONTH() |
作成日時、更新日時、日付、日時 |
THIS_YEAR() |
作成日時、更新日時、日付、日時 |
LAST_YEAR() |
作成日時、更新日時、日付、日時 |
NEXT_YEAR() |
作成日時、更新日時、日付、日時 |
クエリで使えるオプション
並び順の指定
フィールドコードまたはシステム識別子を指定して、その値でレコードを並び替えることができます。
昇順で並び替える場合の書式
|
|
降順で並び替える場合の書式
|
|
エクスポート対象レコードの件数指定
エクスポートするレコード数を limit
の後に指定した数で制限します。
エクスポート対象レコード件数を指定する場合の書式
|
|
エクスポート対象レコードを一定数スキップさせる
エクスポート対象レコードから任意の件数分をスキップしてエクスポートできます。
このとき、スキップするレコードは order by <フィールドコードまたはシステム識別子> <asc または desc>
によって指定した順で数えられます。
エクスポート対象レコードを一定数スキップする場合の書式
|
|
cli-kintone でクエリを利用しレコードを絞り込む
それではクエリを使って cli-kintone でレコードをエクスポートする具体例を見ていきましょう。
今回もこれまで使ってきた
交通費申請アプリ
で試してみましょう。
クエリ作成のコツ
cli-kintone でクエリによる絞り込みが必要な場合、式をひとつずつ個別に試してエクスポートしていき、そのあと and
や or
でつなげた条件で試すようにします。
このようにしてエクスポートが想定どおりに動くことを確認してから、保存や削除することで意図しないデータ操作を減らすことができます。
通常のフィールドで絞り込み・並び順を指定する
今回は、次の条件でレコードを抽出し、並び順は「合計金額」の降順を指定します。
- 条件 1:「ステータス」が「承認」
- 条件 2:「所属部署」が「営業部」または「経理部」
- 条件 3:「合計金額」が「10000 円以上」
条件 1, 2, 3 それぞれの関係は、「条件 1」かつ「条件 2」または「条件 3」です。
「ステータス」が「承認」の式
|
|
「所属部署」が「営業部」または「経理部」の式
|
|
「合計金額」が「10000 円以上」の式
|
|
「合計金額」の降順指定
|
|
式の組み合わせでできたクエリの例
これらの式を条件とおりに組み合わせると、次のようなクエリができあがります。
|
|
次はこれを cli-kintone 上で試してみましょう。
|
|
エクスポートするレコード件数を絞り込みたい場合、limit <数>
を、スキップする件数を指定したい場合は offset <数>
を、それぞれクエリに追加してみてください。
前回まででは触れていませんでしたが、クエリには必ず空白が含まれるので全体のクエリはダブルクオート "
で囲う必要があります
そのため、クエリ内部のダブルクオート "
はバックスラッシュ \
を利用してエスケープする必要があります。
PowerShell や Bash などのシェルでは '
でくくった文字列もコマンドの引数として渡せるので、その場合はバックスラッシュ \
によるダブルクオート "
のエスケープは必要ありません。
テーブル内のフィールドで絞り込む
最後に、テーブル内のフィールドを使ってレコードを絞り込んでみましょう。
クエリ内でテーブル内のフィールドを指定する場合、 =
, !=
の代わりに in
, not in
を使う必要があります。
また、クエリの指定条件に当てはまる要素を含んだテーブルをもつレコードすべてが選択されます。
これらを踏まえて、下記いずれかの条件に当てはまるレコードを絞り込んでみましょう。
絞り込み条件
- 「金額」が「500 円以上」
- 「交通手段」が「電車(片道)」「電車(往復)」ではない。
- 「訪問先」が「サイボウズ株式会社」
以下、これらの条件に基づいた式です。
「金額」が「500 円以上」
|
|
「交通手段」が「電車(片道)」「電車(往復)」ではない
|
|
「訪問先」が「サイボウズ株式会社」
「訪問先」が「サイボウズ株式会社」は、基本の指定方法の場合 Place = "サイボウズ株式会社"
となりますが、今回はテーブル内の指定なので以下のようになります。
|
|
これらの式を組み合わせて cli-kintone 上で実行する場合、以下のようになります。
|
|
まとめ
第 4 回は以上になります。
kintone でのクエリについておわかりいただけたでしょうか?
cli-kintone の機能もあと少しで完璧にできそうですね!
次回は添付ファイルの操作について紹介します。
お楽しみに。
この Tips は、cli-kintone ver 0.10.2 と 2020 年 3 月版 kintone で動作を確認しています。