第 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で動作を確認しています。