setStreamTableTimestamp

语法

setStreamTableTimestamp(streamTable, columnName)

详情

为指定的流数据表设置一个时间戳列。 设置后，向流表写入数据时，系统可以在输入数据不包含时间戳列的情况下，自动将写入时的系统时间填充到该列。该函数可用于统计数据写入流表时的系统接收时间或写入延迟。columnName 可以是流表中任意位置的 TEMPORAL 类型列。

写入已设置时间戳列的流表时，系统按以下规则处理输入数据：

  • 输入列数等于目标表物理列数时，认为输入数据已包含时间戳列，系统直接使用输入中的时间戳值。如果某一位置输入的时间为空，则依然会自动填充当前的系统时间。

  • 输入列数等于目标表物理列数减 1 时，认为输入数据不包含时间戳列，系统自动将当前系统时间填充到时间戳列，并按目标表列顺序写入。

  • 输入列数不属于上述两种情况时，系统报错。

  • 对于流引擎的输出表，如果已经通过 setStreamTableTimestamp 设置了时间戳列，则该列会被视为系统自动填充列。创建流引擎时，系统校验输出表结构时会跳过该时间戳列；引擎只需要输出除该时间戳列以外的其他列。引擎结果写入输出表时，系统会自动在该时间戳列填入当前系统时间，并按输出表的物理列顺序完成写入。

注：

  • 时间戳列必须是 TEMPORAL 类型，包括 DATE、MONTH、TIME、MINUTE、SECOND、DATETIME、TIMESTAMP、NANOTIME 或 NANOTIMESTAMP、DATAHOUR。

  • 时间戳列设置后不可更改或撤销。

  • 高可用流表只能在未使用状态下配置时间戳列。 应在 haStreamTable 返回后、写入数据或订阅之前调用该函数。

  • 持久化恢复、HA 日志重放和 HA checkpoint 恢复不会自动重新生成时间戳；恢复数据必须包含完整的时间戳列。

  • 非高可用持久化目前没有持久化 setStreamTableTimestamp 的时间列配置，非高可用的持久化流表重启之后恢复，需要再次 setStreamTableTimestamp 才能生效。

参数

streamTable 流数据表。可以是普通流表、键值流表、共享流表、持久化流表和高可用流表。

columnName 字符串，指定流数据表中用于记录系统写入时间的列名。该列必须是 TEMPORAL 类型。

例子

例 1：设置中间列为时间戳列，并插入包含所有列的数据。

share streamTable(10000:0,`symbol`timestamp`price, [SYMBOL,TIMESTAMP,DOUBLE]) as trades
//指定 timestamp 列为时间戳列
setStreamTableTimestamp(trades, `timestamp)

// 插入包含所有列的数据
insert into trades values(`A, 2026.03.19T03:17:49, 10.2)
select * from trades
symbol timestamp price
A 2026.03.19 03:17:49.000 10.2

例 2：插入不包含时间戳列的数据。

insert into trades values(`B, 10.2) // 自动填充当前的系统时间
select * from trades
symbol timestamp price
A 2026.03.19 03:17:49.000 10.2
B 2026.06.27 10:49:47.812 10.2

例 3：高可用流表应在创建后立即配置时间戳列。 若高可用流表已经写入数据或存在订阅，再调用该函数会报错。

colNames = `sym`recvTime`price
colTypes = [SYMBOL, NANOTIMESTAMP, DOUBLE]
t = table(1:0, colNames, colTypes)
haTrades = haStreamTable(2, t, `haTrades, 100000)
setStreamTableTimestamp(haTrades, `recvTime)