setStreamTableTimestamp

setStreamTableTimestamp(streamTable, columnName)

Sets a timestamp column for the specified stream table.

After the timestamp column is set, when data is written to the stream table, the system can automatically populate this column with the system time if the input data does not include the timestamp column. This function can be used to record the system receive time or measure write latency when data is written to a stream table. columnName can be a TEMPORAL column at any position in the stream table.

When data is written to a stream table with a timestamp column configured, the system processes the input data according to the following rules:

• If the number of input columns equals the number of physical columns in the target table, the system treats the input data as containing the timestamp column and uses the timestamp from the input directly. If the time value at a given position in the input is null, the system still automatically fills it with the current system time.
• If the number of input columns equals the number of physical columns in the target table minus one, the system treats the input data as not containing the timestamp column. It automatically fills the timestamp column with the current system time and writes the data in the column order of the target table.
• If the number of input columns does not match either of these cases, the system reports an error.
• For the output table of a streaming engine, if a timestamp column has been set using setStreamTableTimestamp, that column is treated as an auto-populated column. When creating the streaming engine, the system skips this timestamp column during output table schema validation; the engine only needs to produce columns other than the timestamp column. When writing results into the output table, the system automatically fills the timestamp column with the current system time and writes the data according to the physical column order of the output table.

streamTable is a stream table. It can be a regular stream table, keyed stream table, shared stream table, persisted stream table, or high-availability stream table.

columnName is a string that specifies the name of the column in the stream table used to record the system write time. This column must be of TEMPORAL type.

Example 1: Set a middle column as the timestamp column and insert data that contains all columns.

share streamTable(10000:0,`symbol`timestamp`price, [SYMBOL,TIMESTAMP,DOUBLE]) as trades
// Set timestamp as the timestamp column
setStreamTableTimestamp(trades, `timestamp)

// Insert data that contains all columns
insert into trades values(`A, 2026.03.19T03:17:49, 10.2)
select * from trades

Example 2: Insert data that does not contain the timestamp column.

insert into trades values(`B, 10.2) // Automatically fills in the current system time
select * from trades

Example 3: Configure the timestamp column immediately after creating a high-availability stream table. If data has been written to the high-availability stream table or subscriptions already exist, calling this function again reports an error.

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