time_window_rolling_avg_fl()

  • [アーティクル]

関数 time_window_rolling_avg_fl() は、一定の期間の時間枠で必要な値のローリング平均を計算する ユーザー定義関数 (UDF) です。

一定の時系列 (つまり間隔が一定) の一定時間ウィンドウに対するローリング平均の計算は、一定時間ウィンドウを等しい係数の固定幅フィルターに変換できるので、series_fir() を使用して実現できます。 ただし、不規則な時系列に対して計算する方が、ウィンドウ内の実際のサンプル数が変化するため、複雑です。 それでも、強力な scan 演算子を使用して実現できます。

この種類のローリング ウィンドウ計算は、メトリック値が変化した場合にのみ出力される (一定の間隔ではない) ユース ケースに必要です。 たとえば、エッジ デバイスが変更時にのみメトリックをクラウドに送信する IoT で通信帯域幅を最適化するような場合です。

構文

T | invoke time_window_rolling_avg_fl(, t_col, y_col, key_coldt [,direction ])

構文規則について詳しく知る。

パラメーター

名前 型 必須 説明
t_col string ✔️ レコードのタイム スタンプを含む列の名前。
y_col string ✔️ レコードのメトリック値を含む列の名前。
key_col string ✔️ レコードのパーティション キーを含む列の名前。
dt timespan ✔️ ローリング ウィンドウの期間。
direction int 集計の方向。 指定できる値は+1 または -1 です。 ローリング ウィンドウは、現在の時刻から順方向または後方にそれぞれ設定されます。 ストリーミング シナリオで可能な方法は後方ローリング ウィンドウだけであるため、既定値は -1 です。

関数の定義

関数を定義するには、次のようにコードをクエリ定義関数として埋め込むか、データベースに格納された関数として作成します。

次の let ステートメントを使用して関数を定義します。 権限は必要ありません。

重要

let ステートメントを単独で実行することはできません。 その後に 表形式の式ステートメントを指定する必要があります。 の動作例 time_window_rolling_avg_fl()を実行するには、「 例」を参照してください。

let time_window_rolling_avg_fl=(tbl:(*), t_col:string, y_col:string, key_col:string, dt:timespan, direction:int=int(-1))
{
    let tbl_ex = tbl | extend timestamp = column_ifexists(t_col, datetime(null)), value = column_ifexists(y_col, 0.0), key = column_ifexists(key_col, '');
    tbl_ex 
    | partition hint.strategy=shuffle by key 
    (
        extend timestamp=pack_array(timestamp, timestamp - direction*dt), delta = pack_array(-direction, direction)
        | mv-expand timestamp to typeof(datetime), delta to typeof(long)
        | sort by timestamp asc, delta desc    
        | scan declare (cum_sum:double=0.0, cum_count:long=0) with 
        (
            step s: true => cum_count = s.cum_count + delta, 
                            cum_sum = s.cum_sum + delta * value; 
        )
        | extend avg_value = iff(direction == 1, prev(cum_sum)/prev(cum_count), cum_sum/cum_count)
        | where delta == -direction 
        | project timestamp, value, avg_value, key
    )
};
// Write your query to use the function here.

例

次の例では、 invoke 演算子 を使用して関数を実行します。

クエリ定義関数を使用するには、埋め込み関数定義の後で呼び出します。

クエリを実行する

let time_window_rolling_avg_fl=(tbl:(*), t_col:string, y_col:string, key_col:string, dt:timespan, direction:int=int(-1))
{
    let tbl_ex = tbl | extend timestamp = column_ifexists(t_col, datetime(null)), value = column_ifexists(y_col, 0.0), key = column_ifexists(key_col, '');
    tbl_ex 
    | partition hint.strategy=shuffle by key 
    (
        extend timestamp=pack_array(timestamp, timestamp - direction*dt), delta = pack_array(-direction, direction)
        | mv-expand timestamp to typeof(datetime), delta to typeof(long)
        | sort by timestamp asc, delta desc    
        | scan declare (cum_sum:double=0.0, cum_count:long=0) with 
        (
            step s: true => cum_count = s.cum_count + delta, 
                            cum_sum = s.cum_sum + delta * value; 
        )
        | extend avg_value = iff(direction == 1, prev(cum_sum)/prev(cum_count), cum_sum/cum_count)
        | where delta == -direction 
        | project timestamp, value, avg_value, key
    )
};
let tbl = datatable(ts:datetime,  val:real, key:string) [
    datetime(8:00), 1, 'Device1',
    datetime(8:01), 2, 'Device1',
    datetime(8:05), 3, 'Device1',
    datetime(8:05), 10, 'Device2',
    datetime(8:09), 20, 'Device2',
    datetime(8:40), 4, 'Device1',
    datetime(9:00), 5, 'Device1',
    datetime(9:01), 6, 'Device1',
    datetime(9:05), 30, 'Device2',
    datetime(9:50), 7, 'Device1'
];
tbl
| invoke time_window_rolling_avg_fl('ts', 'val', 'key', 10m)

出力

timestamp value avg_value key
2021-11-29 08:05:00.0000000 10 10 Device2
2021-11-29 08:09:00.0000000 20 15 Device2
2021-11-29 09:05:00.0000000 30 30 Device2
2021-11-29 08:00:00.0000000 1 1 Device1
2021-11-29 08:01:00.0000000 2 1.5 Device1
2021-11-29 08:05:00.0000000 3 2 Device1
2021-11-29 08:40:00.0000000 4 4 Device1
2021-11-29 09:00:00.0000000 5 5 Device1
2021-11-29 09:01:00.0000000 6 5.5 Device1
2021-11-29 09:50:00.0000000 7 7 Device1

8:05 の最初の値 (10) には 1 つの値だけが含まれ、10 分の後方ウィンドウに入ります。2 番目の値 (15) は 8:09 と 8:05 の 2 つのサンプルの平均です。