Soracom

Users

ドキュメント
Home ドキュメント SORACOM Lagoon 3 Panel の共通機能

Query を加工して新しい Query を作成する (Expression)

Expression 機能は、既存の Query を加工して新しい Query を作成する機能です。

利用できる加工方法は以下のとおりです。なお、加工方法によって、データの個数が変わります。

加工方法説明データの個数
Math既存の Query に対して、四則演算 (+-*/) や関数 (abs()log() など) を利用して、新しい Query を作成します。利用できる関数については、[Show help] をクリックしてください。計算に利用した Query と同じ個数
Reduce既存の Query の Dashboard で表示する時間範囲 または Panel ごとに表示する時間範囲 における最小値などを、新しい Query として作成します。最小値、最大値、平均値、合計値、データ数、最終値を利用できます。1 個
Resample既存の Query を任意の時間間隔 (例: 10 分) で再集計して、新しい Query として作成します。再集計する方法は、最小値、最大値、平均、合計から選択できます。値が存在しない場合に補うこともできます。指定した時間によって個数が異なる
Classic condition条件を満たす場合に 1 になり、条件を満たさない場合に 0 になる新しい Query を作成します。1 個
Threshold値が指定した値、または範囲に含まれる場合に 1 になり、そうでない場合に 0 になる新しい Query を作成します。計算に利用した Query と同じ個数
データが表示されない場合は

データの個数が 1 個になる加工方法を選択した場合、Time seriesBar chart など、複数のデータの表示に適した Panel の種類 を選択しているときは、データが表示されません。StatGauge など、1 個のデータを表示できる Panel の種類を選択してください。

Harvest Data に保存する前に Orbit で加工できます

Harvest Data に保存する前にデータを演算する Orbit も利用できます。

四則演算と関数を利用する (Math)

既存の Query に対して、四則演算 (+-*/) や関数 (abs()log() など) を利用して、新しい Query を作成できます。

摂氏 (°C) から華氏 (°F) に変換して新しい Query を作成する例

たとえば、摂氏 (°C) で保存されている温度データを、Panel では華氏 (°F) で表示できます。

  1. Time series の Panel を作成し、「A」という名前の Query を作成します。

    Query A に、サンプルデータソース (Demo) の Device-1 の temperature を指定します。

    この「A」が摂氏 (°C) で保存されている温度データです。計算対象の Query です。

  2. [+Expression] をクリックします。

    「B」という名前の Expression が作成されます。

  3. 以下の項目を設定します。

    項目説明
    [Operation]「Math」を選択します。
    [Expression]摂氏 (°C) を、華氏 (°F) に変換する計算式 (${A} * 1.8 + 32) を入力します。${A} は、手順 1 で作成した、計算対象の Query の名前です。[Expression] で利用できる数字、演算子、関数については、Math の [Expression] で利用できる表現について を参照してください。

    華氏 (°F) のグラフが追加されます。

  4. Query「A」の [ (Disable/enable query)] をクリックします。

    摂氏 (°C) のグラフが非表示になり、華氏 (°F) のグラフだけが表示されます。

Math の [Expression] で利用できる表現について

[Expression] に入力できる数値 (定数)、Query の参照、演算子、関数を紹介します。

Query と Query の演算はタイムスタンプを基準に行われます

複数の Query の値を演算する際は、タイムスタンプごとに値が演算されます。

たとえば、Query「A」が 20 秒ごとに 1、Query「B」が 30 秒ごとに 2 になる場合、${A} + ${B} の演算結果は以下のとおりです。

タイムスタンプQuery「A」の値Query「B」の値${A} + ${B} の演算結果
10:00:00123
10:00:10
10:00:2011
10:00:3022
10:00:4011
10:00:50
10:01:00123

異なるデバイスから送信されたデータを演算して意味がある数値を取得するには、再集計 (Resample) をしてタイムスタンプを揃える方法があります。

たとえば、Query「A」の 20 秒ごとの平均値を「A Mean」として作成し、Query「B」の 20 秒ごとの平均値を「B Mean」として作成した場合、${A Mean} + ${B Mean} の演算結果は以下のとおりです。

タイムスタンプQuery「A Mean」の値Query「B Mean」の値${A Mean} + ${B Mean} の演算結果
10:00:55
10:00:15123
10:00:35123
10:01:55123

詳しくは、Grafana documentation の Math (英語) を参照してください。

数字 (定数)

数字は、10 進数、8 進数、16 進数、指数、符号などがサポートされています。

種類
10 進数
  • 1.56
  • 3.12e3: 3.12 x 10 の 3 乗
  • -0.8e-2: -0.8 x 10 の -2 乗
8 進数 (先頭に 0 をつける)074: 10 進数の 60
16 進数 (先頭に 0x をつける)0x6B: 10 進数の 107

Query のデータ

Query の名前を指定すると、Query のデータを利用できます。たとえば、Query「Temp query」のデータを利用する場合は、${Temp query} を入力します。

演算子

利用できる演算子は、以下のとおりです。

演算子の種類説明
算術演算子四則演算 (+-*/) および 剰余 (%)、累乗 (**)、括弧 (()) を利用できます。
関係演算子、論理演算子

いずれも、真の場合に 1、偽の場合は 0 になります。

演算子1 (真) になる例0 (偽) になる例
<: より小さい3 < 43 < 33 < 2
<=: 以下3 <= 33 <= 43 <= 2
>: より大きい4 > 33 > 32 > 3
>=: 以上4 >= 33 >= 32 >= 3
==: 等しい4 == 2 * 24 == 3
!=: 等しくない4 != 34 != 2 * 2
&&: 論理演算子 AND3 < 4 && 4 != 33 < 4 && 4 == 3
||: 論理演算子 OR3 < 4 || 4 == 33 < 3 || 4 != 3
!: 論理演算子 NOT!(4 == 3)!(4 == 2 * 2)

関数

代表的な関数は、以下のとおりです。

関数の種類意味
abs()絶対値
log()自然対数 (底が e)

関数について詳しくは、Grafana documentation の Math Functions (英語) を参照してください。

代表値を利用する (Reduce)

既存の Query の Dashboard で表示する時間範囲 または Panel ごとに表示する時間範囲 における代表値を、新しい Query として作成できます。代表値として、以下の項目を利用できます。

項目説明
Min最小値
Max最大値
Mean平均値
Sum合計値
Countデータ数
Last最終値

たとえば、定期的に送信される温度データの平均値 (Mean) を、Stat に表示できます。

  • 代表値はデータが 1 個のため、Time seriesBar chart など、複数のデータの表示に適した Panel の種類 を選択しているときは、データが表示されません。
  • Stat を利用すると折れ線グラフに代表値を重ねて表示できます。なお、Stat を利用する場合は、Expression 機能は利用しません。
  1. 以下の 2 つの Panel を作成し、どちらにも「A」という名前の Query を作成します。

    どちらの Panel にも Query A に、サンプルデータソース (Demo) の Device-1 の temperature を指定します。

    Stat の Query「A」が計算対象の Query です。手順 3 の [Input] で選択します。

  2. Stat の Panel のタイトル → [Edit] の順にクリックして、[+Expression] をクリックします。

    「B」という名前の Expression が作成されます。

  3. 以下の項目を設定します。

    項目説明
    [Operation]「Reduce」を選択します。
    [Function]「Mean」を選択します。
    [Input]「A」を選択します。「A」は手順 1 で作成した、計算対象の Query です。
    [Mode]

    計算対象の Query に数値以外のデータが含まれていた場合の計算方法を選択します。

    • Stict: 計算結果を NaN (Not a Number) にします。
    • Drop Non-numeric Values: 計算できないデータは無視して計算します。
    • Replace Non-numeric Values: 計算できないデータは、任意の値に置き換えて計算します。

  4. [ (Refresh dashboard)] をクリックします。

    平均値が表示されます。

  5. Query「A」の をクリックします。

    「A」の値が非表示になり、平均値だけが表示されます。

  6. [Apply] をクリックします。

    Dashboard に戻ります。

「Reduce」で取得した代表値は「Math」の計算式で利用できます

たとえば、「Reduce」で取得した代表値を「Math」の計算式に含めると、ある系列のデータについて平均との差を算出できます。

再集計する (Resample)

既存の Query を任意の時間間隔 (例: 10 分) で再集計して、新しい Query として作成できます。再集計する方法は、最小値、最大値、平均、合計から選択できます。値が存在しない場合に補うこともできます。たとえば、定期的に送信される温度データに対して、10 分ごとの平均値 (Mean) のグラフを表示できます。

  1. Time series の Panel を作成し、「A」という名前の Query を作成します。

    Query A に、サンプルデータソース (Demo) の Device-1 の temperature を指定します。

    この「A」が計算対象の Query です。

    ここでは、[Standard options][Color scheme] で「Red-Yellow-Green (by value)」を選択して、グラフの色を赤系にしています。

  2. [+Expression] をクリックします。

    「B」という名前の Expression が作成されます。

  3. 以下の項目を設定します。

    項目説明
    [Operation]「Resample」を選択します。
    [Input]「A」を選択します。「A」は手順 1 で作成した、計算対象の Query です。
    [Resample to]再集計する時間間隔 (10m) を入力します。単位の文字として、s (秒)、m (分)、h (時間)、d (日) を利用できます。
    [Downsample]「Mean」を選択します。
    [Upsample]

    [Resample] で指定した時間間隔にデータが含まれていない場合の値を選択します。

    • pad: 直前の値を利用します。
    • backfilling: 直後の値を利用します。
    • fillna: NaN (Not a Number) にします。

  4. [ (Refresh dashboard)] をクリックします。

    10 分ごとの平均値のグラフが追加されます。

  5. Query「A」の をクリックします。

    「A」の値が非表示になり、10 分ごとの平均値のグラフだけが表示されます。

真偽値を利用する (Classic condition)

既存の Query の Dashboard で表示する時間範囲 における値から、以下の定義済みの関数を利用して取得した真偽値 (条件を満たす場合に 1 になり、条件を満たさない場合に 0 になる) を、新しい Query として作成できます。

  • 1 行目の [WHEN] では、以下の項目を選択します。

    項目説明
    avg()平均値を計算します。
    min()最小値を計算します。
    max()最大値を計算します。
    sum()合計値を計算します。
    count()データの個数を数えます。
    last()最終値を取得します。
    median()中央値を取得します。中央値は、データを並べたときに中央にあるデータです。たとえば、7 個のデータが存在する場合は、4 番目のデータを取得できます。また、8 個のデータが存在する場合は、4 個目のデータと 5 個目のデータの平均値を取得できます。
    diff()最終値 - 最初値 を計算します。
    diff_abs()最終値 - 最初値 の絶対値を計算します。
    percent_diff()最初値から最終値までに増減した割合 (%) を計算します。たとえば、最初値が 26.92、最終値が 26.51 の場合、(26.92 / (26.51 - 26.92)) * 100 の値 (-1.55) が評価されます。
    percent_diff_abs()最初値から最終値までに増減した割合 (%) の絶対値を計算します。たとえば、最初値が 26.92、最終値が 26.51 の場合、(26.92 / (26.51 - 26.92)) * 100 の絶対値 (1.55) が評価されます。
    count_non_null()null を除いたデータの個数を数えます。
  • 1 行目の [OF] では、Query または Expression を選択します。

  • 2 行目の設定では、[WHEN][OF] で選択した内容に従って計算した値が、どのような条件のときに 1 にするかを設定します。

たとえば、以下のように設定すると、定期的に送信される温度データの平均値 (Mean) が、20 °C を超えたら 1 を表示できます。

Expression には Classic condition を利用できません

Classic condition の計算対象を選択する [OF] では、Query を選択してください。Expression を選択すると、エラーが発生します。

真偽値はデータが 1 個のため、Time seriesBar chart など、複数のデータの表示に適した Panel の種類 を選択しているときは、データが表示されません。

複数の条件を「OR」または「AND」を利用して組み合わせて評価できます

[] をクリックすると、1 つの Classic Condition に複数の条件を設定できます。その場合は、条件ごとに 1 または 0 を算出したうえで、「OR」または「AND」を利用して組み合わせた結果が Classic Condition の結果になります。ただし、以下の点に注意してください。

  • すべての条件で値 (1 または 0) を算出できた場合に限り (No Data にならなかった場合に限り)、「OR」または「AND」を利用して組み合わせた結果も値 (1 または 0) が算出されます。
  • いずれか 1 つの条件が参照している Query/Expression が No Data の場合は、Classic Condition の結果も No Data になります。
  • 各条件が算出した結果 (1 または 0) は、個別に確認できません。
  1. Stat の Panel を作成し、「A」という名前の Query を作成します。

    Query A に、サンプルデータソース (Demo) の Device-1 の temperature を指定します。

    この「A」が計算対象の Query です。次に、Stat の数値を平均値に変更します。

    ここでは、[Standard options][Color scheme] で「Blue-Purple (by value)」を選択して、グラフの色を青系にしています。

  2. [All] をクリックし、[Value options][Calculation] で「Mean」を選択します。

    Query「A」のグラフと平均値が表示されます。

  3. [+Expression] をクリックします。

    「B」という名前の Expression が作成されます。

  4. 以下の項目を設定します。

    項目説明
    [Operation]「Classic condition」を選択します。
    [Conditions]
    • [WHEN] で「avg()」を選択します。
    • [OF] で「A」を選択します。「A」は手順 2 で作成した、計算対象の Query です。
    • [IS ABOVE] (より大きい) が表示されていることを確認して「20」を入力します。
    [OF] で Expression を選択しないでください

    [OF] では、計算対象の Query を選択してください。Expression を選択すると、エラーが発生します。

  5. [ (Refresh dashboard)] をクリックします。

    Query「A」の平均値が「20」より大きい場合は 1 が表示されます。それ以外の場合は 0 が表示されます。

「Classic condition」で取得した真偽値は「Math」の計算式で利用できません。

しきい値を利用する (Threshold)

既存の Query の値が指定した範囲に含まれるかどうかを表す真偽値 (値が指定した値、または範囲に含まれる場合に 1 になり、そうでない場合に 0 になる) を、新しい Query として作成できます。

以下のような Time series を作成できます。この Panel は、緑 (temperature) が 19.5 より大きい値のときは、黄色い円がグラフの上部に表示される仕組みです。しきい値の 19.5 を青い線で表現しています。

項目設定
Quick rangesLast 15 minutes
A (Query)Demo > Device-1 > Standard > temperature
B (Expression)
  • [Operation]: Threshold
  • [Input]: A
  • [IS ABOVE]: 19.5
C (Expsesion)
  • [Operation]: Math
  • [Expression]: $A * 0 + 19.5
Override 1
  • [Fields returned by query]: B
  • [Standard options > Unit]: True / False
  • [Graph styles > Style]: Points
  • [Graph styles > Point size]: 15
Override 2
  • [Fields returned by query]: C
  • [Graph styles > Point size]: 1