如何在KQL中创建计算时间加权平均的用户定义聚合函数？

需求说明 #

需针对传感器时序数据，按指定时间窗口（如5分钟）计算时间加权平均值——即每个传感器数值的权重为其持续的时长，而非简单算术平均。

基础查询实现（非UDAF版） #

先通过普通KQL查询实现核心逻辑，验证计算结果：

tempMetrics
| partition by Name, bin(TimeStamp, 5m) into windowData {
    windowData
    | sort by TimeStamp asc
    // 确定当前窗口的起始与结束时间
    | extend window_start = bin(TimeStamp, 5m), window_end = window_start + 5m
    // 获取下一条记录的时间，最后一条记录用窗口结束时间作为下一时间点
    | extend next_TimeStamp = next(TimeStamp, 1, window_end)
    // 计算当前数值持续的分钟数
    | extend duration_min = datetime_diff('minute', next_TimeStamp, TimeStamp)
    // 计算数值的加权贡献值
    | extend weighted_value = Value * duration_min
    // 求和加权值与总时长，计算时间加权平均
    | summarize total_weighted = sum(weighted_value), total_duration = sum(duration_min) by window_start, Name
    | extend TimeWeightedAverage = total_weighted / total_duration
    | project TimeStamp = window_start, Name, TimeWeightedAverage
}

该查询会输出符合预期的结果：

封装为用户定义聚合函数（UDAF） #

为简化查询，将上述逻辑封装为可直接在summarize中使用的UDAF：

创建支持自定义时间间隔的UDAF

.create function with (folder = "CustomAggregates", docstring = "计算时间加权平均值，需配合summarize by bin(TimeStamp, <interval>)使用，参数为时间戳、数值、时间间隔")
time_weighted_avg(timestamp:datetime, value:decimal, interval:timespan)
{
    // 对分组内的记录按时间升序排序
    order by timestamp asc
    // 确定当前窗口的起始与结束时间
    let window_start = bin(min(timestamp), interval);
    let window_end = window_start + interval;
    // 获取下一条记录的时间，最后一条记录用窗口结束时间补全
    extend next_ts = next(timestamp, 1, window_end)
    // 计算数值持续的时长（分钟）
    extend duration_mins = datetime_diff('minute', next_ts, timestamp)
    // 计算加权贡献值
    extend weighted_val = value * duration_mins
    // 求和计算时间加权平均
    summarize total_weighted = sum(weighted_val), total_duration = sum(duration_mins)
    | project result = total_weighted / total_duration
    | take 1
}

使用UDAF的简化查询

tempMetrics
| summarize TimeWeightedAverage = time_weighted_avg(TimeStamp, Value, 5m) by bin(TimeStamp, 5m), Name

执行该查询即可直接得到时间加权平均结果，与基础查询输出一致。

注意事项 #

1. UDAF依赖summarize的by bin(TimeStamp, <interval>)分组逻辑，确保窗口范围计算准确；
2. 若所有记录均在窗口结束后，会自动用窗口结束时间补全最后一条记录的持续时长；
3. 可修改datetime_diff的单位（如秒、小时），调整时长计算精度。

内容的提问来源于stack exchange，提问作者G.Smulders