createTimeBucketEngine

createTimeBucketEngine(name,timeCutPoints,metrics,dummyTable,outputTable,timeColumn,[keyColumn],[useWindowStartTime],[closed='left'],[fill='none'],[keyPurgeFreqInSec=-1],[outputElapsedMicroseconds=false],[parallelism=1],[outputHandler=NULL],[msgAsTable=false])

创建一个自定义窗口长度（长度相同或不同）的时间序列聚合引擎。该引擎基于数据时间，按照指定的长度对输入数据进行窗口划分，并在窗口内执行增量聚合计算。通常和时序聚合引擎（createTimeSeriesEngine ）级联使用，接收其输出秒级或分钟级聚合结果（例如 K 线）进行进一步处理。

返回值：返回一个表对象，通过向该表对象写入，将数据注入引擎进行计算。

name 字符串标量，表示时间序列分组引擎的名称，作为其在一个数据节点/计算节点上的唯一标识。可包含字母，数字和下划线，但必须以字母开头。

timeCutPoints MINUTE 或 SECOND 类型向量，且不能包含空值。由 timeCutPoints 向量的任意两个相邻元素确定窗口的左、右边界。

注意：

• timeCutPoints 指定的时间精度必须不高于 timeColumn 列的精度。

• timeCutPoints 指定的时间精度决定关闭窗口右边界的时间精度。如果 timeCutPoints 是 MINUTE 类型，则窗口右边界的时间精度是分；如果 timeCutPoints 是 SECOND 类型，则窗口右边界的时间精度是秒。

dummyTable 一个表对象，和订阅的流数据表的 schema 一致，可以含有数据，亦可为空表。

outputTable 计算结果的输出表，可以是内存表或者分布式表。在使用 createTimeBucketEngine 函数之前，需要将输出表预先设立为一个空表，并指定各列列名以及数据类型。引擎会将计算结果插入该表。

输出表的列顺序如下：

1. 时间列。当 timeColumn 为标量时，输出表中时间列的数据类型与 timeColumn 列 一致。否则输出表中时间列的数据类型与 timeColumn 中日期和时间列应用 concatDateTime 的结果一致。

2. 分组列。如果 keyColumn 不为空，则其后几列和 keyColumn 设置的列及其顺序保持一致。

3. 耗时列。如果指定 outputElapsedMicroseconds = true，则指定一个 LONG 类型的列用于存储耗时（单位：微秒）。

4. 计算结果列，数量和 metrics 中指定的算子个数相同。若 metrics 指定的某个算子返回多个计算结果，则它们将以数组向量的形式输出，因此，该算子对应的计算结果列必须的类型必须是数组向量。

timeColumn 字符串标量或长度为2的向量，用于输入表中时间列的名称。

注：若 timeColumn 指定为向量，则第一个元素（date）的类型为 DATE，第二个元素（time）的类型为 TIME, SECOND 或 NANOTIME。此时，输出表第一列的时间类型必须与 concatDateTime(date, time) 的类型一致。

keyColumn 可选参数，字符串标量或向量，表示分组列名。若设置，则分组进行聚合计算，例如以每支股票为一组进行聚合计算。

useWindowStartTime 可选参数。布尔值，表示输出表中的时间是否为数据窗口起始时间。默认值为 false，表示输出表中的时间为窗口结束时间。

keyPurgeFreqInSec 正整数，表示清理窗口数据为空的分组的时间间隔，单位为秒。指定该参数后，若当前数据注入时间与上一次清理时间的间隔大于等于 keyPurgeFreqInSec，则触发对当前窗口数据为空的分组信息的清理。若指定该参数，则必须指定 keyColumn，且不能指定 fill。

outputElapsedMicroseconds 布尔值，表示是否输出每个窗口从触发计算到计算完成输出结果的耗时（若指定了 keyColumn 则包含数据分组的耗时），默认为 false。指定参数 outputElapsedMicroseconds 后，在定义 outputTable 时需要在时间列和分组列后增加一个 LONG 类型的列，详见 outputTable 参数说明。

parallelism 为不超过 63 的正整数，可选参数，表示并行计算的工作线程数，默认值为 1。在计算量较大时，合理地调整该参数能够有效利用计算资源，降低计算耗时。建议小于机器核数，推荐值为 4 到 8 。

outputHandler 一元函数。设置此参数时，引擎计算结束后，不再将计算结果写到输出表，而是会调用此函数处理计算结果。默认值为 NULL，表示仍将结果写到输出表。

msgAsTable 布尔标量，表示在设置了参数 outputHandler 时，将引擎的计算结果以表的结构调用函数。默认值为 false，此时将计算结果的每一列作为元素组成元组。

通过时序聚合引擎计算1分钟 K 线，然后通过 createTimeBucketEngine 将 1 分钟 K 线聚合为 5 分钟。在窗口左闭右开的情况下，可以提前一分钟结束窗口并计算输出，从而比使用 createTimeSeriesEngine 减少延时。

share streamTable(1000:0, `time`sym`price`volume, [TIMESTAMP, SYMBOL, DOUBLE, INT]) as trades
share streamTable(10000:0, `time`sym`firstPrice`maxPrice`minPrice`lastPrice`sumVolume, [TIMESTAMP, SYMBOL, DOUBLE, DOUBLE, DOUBLE, DOUBLE, INT]) as output1
timeSeries1 = createTimeSeriesEngine(name="timeSeries1", windowSize=60000, step=60000, metrics=<[first(price), max(price), min(price), last(price), sum(volume)]>, dummyTable=trades, outputTable=output1, timeColumn=`time, useSystemTime=false, keyColumn=`sym, useWindowStartTime=false)
subscribeTable(tableName="trades", actionName="timeSeries1", offset=0, handler=append!{timeSeries1}, msgAsTable=true);

// 定义 createTimeBucketEngine 的输出表和窗口区间
share streamTable(10000:0, `time`sym`firstPrice`maxPrice`minPrice`lastPrice`sumVolume, [TIMESTAMP, SYMBOL, DOUBLE, DOUBLE, DOUBLE, DOUBLE, INT]) as output2
timeCutPoints=[10:00m, 10:05m, 10:10m, 10:15m]

timeBucket1 = createTimeBucketEngine(name="timeBucket1", timeCutPoints=timeCutPoints, metrics=<[first(firstPrice), max(maxPrice), min(minPrice), last(lastPrice), sum(sumVolume)]>, dummyTable=output1, outputTable=output2, timeColumn=`time,  keyColumn=`sym)
subscribeTable(tableName="output1", actionName="timeBucket1", offset=0, handler=append!{timeBucket1}, msgAsTable=true);


insert into trades values(2024.10.08T10:01:01.785,`A, 10.83, 2110)
insert into trades values(2024.10.08T10:01:02.125,`B,21.73, 1600)
insert into trades values(2024.10.08T10:01:12.457,`A,10.79, 2850)
insert into trades values(2024.10.08T10:03:10.789,`A,11.81, 2250)
insert into trades values(2024.10.08T10:03:12.005,`B, 22.96, 1980)
insert into trades values(2024.10.08T10:08:02.236,`A, 11.25, 2400)
insert into trades values(2024.10.08T10:08:04.412,`B, 23.03, 2130)
insert into trades values(2024.10.08T10:08:05.152,`B, 23.18, 1900)
insert into trades values(2024.10.08T10:08:30.021,`A, 11.04, 2300)
insert into trades values(2024.10.08T10:10:20.123,`A, 11.85, 2200)
insert into trades values(2024.10.08T10:11:02.236,`A, 11.06, 2200)
insert into trades values(2024.10.08T10:13:04.412,`B, 23.15, 1880)
insert into trades values(2024.10.08T10:15:12.005,`B, 22.06, 2100)

sleep(10)

// 查看时序引擎输出的 1 分钟 K 线结果
select * from output1;

查看 5 分钟 K 线结果：

select * from output2;