timewrap interval: const duration, count: const int64, label_column: const string, [index_column: const string]?

Replicates the input count times along a timeline, shifting each copy by 0, 1, …, count - 1 multiples of a fixed duration, and labels each copy so you can compare the same signal across recent periods side by side.

Arguments interval and count must be compile-time constants; interval must be positive and count at least 1. You supply label_column as a new string column name (it must not already exist); its values are human-readable labels such as "now", "1d ago", "2d ago", derived from the interval and index.

You may pass a fourth argument, index_column, to also materialize the shift index as a non-negative int64 (0 means the unshifted copy). index_column must differ from label_column.

The new label is appended to the primary key, every candidate key, and the grouping key. Temporal alignment metadata on the output is cleared because the verb unions multiple shifted timelines.

The verb requires a temporal input; plain tables are rejected at compile time.

Using timewrap together with non-temporal verbs such as exists or follow can return incomplete data.

Categories

• Metadata
• Metrics

Accelerable

timewrap is always accelerable if the input is accelerable. A dataset that only uses accelerable verbs can be accelerated, making queries on the dataset respond faster.

Examples

timewrap 1d, 4, "period"

Produces four shifted copies of each row (today through three days back) with a string label column naming each overlay.

timewrap 1h, 3, "window_label", "window_index"

Adds both a readable shift label and an explicit integer index column for the same three-way hourly overlay.