Time travel queries
This guide describes how to leverage the time travel feature. This feature helps access historical data at a specific time.
PREMIUM EDITION FEATURE
This feature is exclusive to RisingWave Premium Edition that offers advanced capabilities beyond the free versions. For a full list of premium features, see RisingWave Premium Edition. If you encounter any questions, please contact sales team at sales@risingwave-labs.com.
PUBLIC PREVIEW
This feature is in the public preview stage, meaning it’s nearing the final product but is not yet fully stable. If you encounter any issues or have feedback, please contact us through our Slack channel. Your input is valuable in helping us improve the feature. For more information, see our Public preview feature list.
Prerequisites
Time travel requires the meta store type to be SQL-compatible. We recommend reserving at least 50 GB of disk space for the meta store.
The system parameter time_travel_retention_ms
controls time travel functionality. By default, it’s set to 0
, which means time travel is turned off. To enable time travel, you need to alter this system parameter to a non-zero value.
For example, you can set time_travel_retention_ms
to 86400000
(1 day). Then historical data older than this period will be deleted and no longer accessible.
Enabling time travel will introduce additional overhead to both the meta store and the object store.
Syntax
Specify FOR SYSTEM_TIME AS OF
separately for each table accessing historical data. The following subclauses can be used:
- Unix timestamp in seconds. For example,
SELECT * FROM t_foo FOR SYSTEM_TIME AS OF 1721024455;
. - Datetime. For example,
SELECT * FROM t_foo FOR SYSTEM_TIME AS OF '2000-02-29T12:13:14-08:30';
. - NOW() [ - Interval ]. For example,
SELECT * FROM t_foo FOR SYSTEM_TIME AS OF NOW() - '10' SECOND;
.
If you specify a point in time that is outside the time travel period, the query will return an error, like time travel: version not found for epoch
.
Storage space reclamation
Stale time travel data in both the meta and object stores is automatically removed in the background, freeing up storage space. The default cleanup schedule is as below, which is usually sufficient for most situations.
- The interval to reclaim the meta store is 30 seconds by default. You can change this interval by adjusting the
vacuum_interval_sec
setting. After changing this setting, restart the meta node for it to take effect. - The interval to reclaim the object store is 1 day by default. You can customize this schedule by adjusting two settings:
full_gc_interval_sec
andmin_sst_retention_time_sec
. After modifying these values, restart the meta node to apply the changes.