第 4 回 kintone コマンドラインツール(cli-kintone v0)でクエリ指定して絞り込み・並び順変更をしてみよう

著者名: 瀧ヶ平 充 (External link)

目次

information

このチュートリアルは ver. 0.x.x の cli-kintone の使い方を紹介しています。
ver.1.0.0 以降の cli-kintone の使い方を紹介するチュートリアルは次のページを参照してください。
はじめよう cli-kintone

はじめに

前回までで、cli-kintone を使ったレコード操作は、ほぼできるようになったのではないでしょうか。

今回は、クエリを使ったレコードの絞り込みや並び替えの方法を紹介します。
詳細は クエリの書き方の記事 で確認していただくとして、ここではクエリの基本的な書き方をおぼえていきましょう。

クエリの書き方

基本的な式の書き方

フィールドの値または関数で扱うレコードを絞り込む場合、「フィールドコード(またはシステム識別子)」「演算子」「値(または関数)」で構成される式を使います。

式の基本書式
1
<フィールドコード または システム識別子> <演算子> <値 または 関数>

たとえば 数値_0 フィールドの値が 10 以上のレコードを抽出する場合、式は以下のようになります。

1
数値_0 >= 10

フィールドコード 数値_0、演算子 >=、条件の境界になる値 10、これらを、フィールドコード、演算子、値の順に組み合わたものを 1 セットとして記述します。

in, not in を使用する場合

式の書き方は多くの場合上の書式で対応できますが、一部の演算子を使用する場合は若干異なります。
演算子に in, not in を使用する場合、以下の書式になります。

in, not in 演算子を使用する場合の書式
1
<フィールドコード または システム識別子> <in または not in> (<「,」で区切った一つないし複数の関数または値>)

値の記述

クエリ内部では、関数を除いたすべての値をダブルクオート " で囲って表記します。

値の記述例
1
$id in ("1", "4", "5"), 作成者 in (LOGINUSER(), "login_name")

式のグループ化

単独の式で条件を指定できるケースもありますが、より詳細な条件を指定したい場合も多いと思います。
式は丸括弧 () でくくるとグループ化できます。
また and, or を用いて、「かつ」「または」を含む条件を表現できます。
これらの演算子で複数の式を結合すると、より詳細な条件を指定できます。

グループ化された式の例
1
(数値 >= "100" and 文字列一行 like "テスト") or 更新日時 >= LAST_MONTH(1)

この例の場合、下記 2 つのどちらかの条件に当てはまるレコードが抽出されます。

  • 数値 フィールドの値が 100 以上で、かつ、文字列一行 フィールドに文字列 テスト を含む値をもつレコード
  • 更新日時 フィールドの値を、前月 1 日 に設定しているレコード

and, or の優先順位

式がグループ化されていない場合、論理積の演算子 and が優先されます。
前項の例の場合、or よりも and が優先的に処理されるので、括弧を外した場合も同じ条件となります。

関連レコードに含まれるフィールドを指定する場合、下記いずれかの書式で式を書くことができます。

関連レコードを指定する場合の基本書式
1
<関連レコードのフィールドコード>.<関連レコード先のフィールドコード> <演算子> <関数または値>
in, not in 演算子を使用する場合の書式
1
<関連レコードのフィールドコード>.<関連レコード先のフィールドコード> <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() 作成日時、更新日時、日付、日時

クエリで使えるオプション

並び順の指定

フィールドコードまたはシステム識別子を指定して、その値でレコードを並び替えることができます。

昇順で並び替える場合の書式
1
order by <フィールドコード または システム識別子> asc
降順で並び替える場合の書式
1
order by <フィールドコード または システム識別子> desc

エクスポート対象レコードの件数指定

エクスポートするレコード数を limit の後に指定した数で制限します。

エクスポート対象レコード件数を指定する場合の書式
1
limit <エクスポート数>

エクスポート対象レコードを一定数スキップさせる

エクスポート対象レコードから任意の件数分をスキップしてエクスポートできます。
このとき、スキップするレコードは order by <フィールドコードまたはシステム識別子> <asc または desc> によって指定した順で数えられます。

エクスポート対象レコードを一定数スキップする場合の書式
1
offset <スキップするレコード数>

cli-kintone でクエリを利用しレコードを絞り込む

それではクエリを使って cli-kintone でレコードをエクスポートする具体例を見ていきましょう。
今回もこれまで使ってきた 交通費申請アプリ (External link) で試してみましょう。

クエリ作成のコツ

cli-kintone でクエリによる絞り込みが必要な場合、式をひとつずつ個別に試してエクスポートしていき、そのあと andor でつなげた条件で試すようにします。
このようにしてエクスポートが想定どおりに動くことを確認してから、保存や削除することで意図しないデータ操作を減らすことができます。

通常のフィールドで絞り込み・並び順を指定する

今回は、次の条件でレコードを抽出し、並び順は「合計金額」の降順を指定します。

  • 条件 1:「ステータス」が「承認」
  • 条件 2:「所属部署」が「営業部」または「経理部」
  • 条件 3:「合計金額」が「10000 円以上」

条件 1, 2, 3 それぞれの関係は、「条件 1」かつ「条件 2」または「条件 3」です。

「ステータス」が「承認」の式
1
ステータス = "承認"
「所属部署」が「営業部」または「経理部」の式
1
Department in ("営業部", "経理部")
「合計金額」が「10000 円以上」の式
1
Sum >= 10000
「合計金額」の降順指定
1
order by Sum desc
式の組み合わせでできたクエリの例

これらの式を条件とおりに組み合わせると、次のようなクエリができあがります。

1
ステータス = "承認" and Department in ("営業部", "経理部") or Sum >= \"10000\" order by Sum desc"

次はこれを cli-kintone 上で試してみましょう。

1
>cli-kintone.exe --export -a <アプリID> -d <ドメイン名> -t <APIトークン> -q "ステータス = \"承認\" and Department in (\"営業部\", \"経理部\") or Sum >= \"10000\" order by Sum desc"

エクスポートするレコード件数を絞り込みたい場合、limit <数> を、スキップする件数を指定したい場合は offset <数> を、それぞれクエリに追加してみてください。
前回まででは触れていませんでしたが、クエリには必ず空白が含まれるので全体のクエリはダブルクオート " で囲う必要があります
そのため、クエリ内部のダブルクオート " はバックスラッシュ \ を利用してエスケープする必要があります。
PowerShell や Bash などのシェルでは ' でくくった文字列もコマンドの引数として渡せるので、その場合はバックスラッシュ \ によるダブルクオート " のエスケープは必要ありません。

テーブル内のフィールドで絞り込む

最後に、テーブル内のフィールドを使ってレコードを絞り込んでみましょう。
クエリ内でテーブル内のフィールドを指定する場合、 =, != の代わりに in, not in を使う必要があります。
また、クエリの指定条件に当てはまる要素を含んだテーブルをもつレコードすべてが選択されます。

これらを踏まえて、下記いずれかの条件に当てはまるレコードを絞り込んでみましょう。

絞り込み条件

  • 「金額」が「500 円以上」
  • 「交通手段」が「電車(片道)」「電車(往復)」ではない。
  • 「訪問先」が「サイボウズ株式会社」

以下、これらの条件に基づいた式です。

「金額」が「500 円以上」
1
Price >= 500
「交通手段」が「電車(片道)」「電車(往復)」ではない
1
transportation not in ("電車(片道)", "電車(往復)")
「訪問先」が「サイボウズ株式会社」

「訪問先」が「サイボウズ株式会社」は、基本の指定方法の場合 Place = "サイボウズ株式会社" となりますが、今回はテーブル内の指定なので以下のようになります。

1
Place in ("サイボウズ株式会社")

これらの式を組み合わせて cli-kintone 上で実行する場合、以下のようになります。

1
>cli-kintone.exe --export -a <アプリID> -d <ドメイン名> -t <APIトークン> -q "Price >= 500 or Place in (\"サイボウズ株式会社\") or transportation not in (\"電車(片道)\", \"電車(往復)\")"

まとめ

第 4 回は以上になります。
kintone でのクエリについておわかりいただけたでしょうか?
cli-kintone の機能もあと少しで完璧にできそうですね!

次回は添付ファイルの操作について紹介します。
お楽しみに。

information

この Tips は、cli-kintone ver 0.10.2 と 2020 年 3 月版 kintone で動作を確認しています。