Skip to main content
Version: Python

snapshot_when

snapshot_when produces an in-memory copy of a source table that adds a new snapshot when another table, the trigger table, changes.

note

The trigger table is often a time table, a special type of table that adds new rows at a regular, user-defined interval. The sole column of a time table is Timestamp.

caution

Columns from the trigger table appear in the result table. If the trigger and source tables have columns with the same name, an error will be raised. To avoid this problem, omit duplicates via stamp columns or rename conflicting columns.

Syntax

source.snapshot_when(
trigger_table: Union[Table, PartitionedTableProxy],
stamp_cols: list[str],
initial: bool = False,
incremental: bool = False,
history: bool = False,
) -> PartitionedTableProxy

Parameters

ParameterTypeDescription
trigger_tableUnion[Table, PartitionedTableProxy

The table that triggers the snapshot.

stamp_colslist[str]

One or more column names to act as stamp keys. If only one column, a string or list can be used. If more than one column, a list must be used.

initial optionalbool

Defines whether an initial snapshot is taken upon construction. The default value is False

incremental optionalbool

Defines whether the resulting table should be incremental. The default value is False. When False, all rows have the latest stamp key. When True, only rows that have been added or updated will have the latest stamp key.

history optionalbool

Defines whether the resulting table should keep history. The default value is False. When True, a full snapshot of the table and the stamp key is appended. When False, only updating existing rows are appended. If this is True, incremental and initial must be False.

Returns

A new table that captures a snapshot of the source table whenever the trigger table updates.

Examples

In the following example, the source table updates once every second. The trigger table updates once every five seconds. Thus, the result table updates once every five seconds. The Timestamp column in the trigger is renamed to avoid a name conflict error. Notice how the result table only contains the values from the most recent row in the trigger table.

from deephaven import time_table

source = time_table("PT1S").update_view(["X = i"])
trigger = time_table("PT5S").rename_columns(["TriggerTimestamp = Timestamp"]).update_view(["Y = Math.sin(0.1 * i)"])
result = source.snapshot_when(trigger_table=trigger)

img

In the following example, the code is nearly identical to the one above it. However, in this case, the Y column is given as the stamp key. Thus, the Timestamp column in the trigger table is omitted from the result table, which avoids a name conflict error. This is typically a more elegant way to avoid name conflicts than renaming columns.

from deephaven import time_table

source = time_table("PT1S").update_view(["X = i"])
trigger = time_table("PT5S").update_view(["Y = i"])
result = source.snapshot_when(trigger_table=trigger, stamp_cols=["Y"])

img

In the following example, history is set to True. The result table is appended with a full snapshot every time trigger ticks, rather than just new rows.

from deephaven import time_table

source = time_table("PT1S").update_view(["X = i"])
trigger = time_table("PT5S").update_view(["Y = i"])
result = source.snapshot_when(trigger_table=trigger, stamp_cols=["Y"])

img

In the following example, incremental is set to True. Thus, the result table keeps previous values from the Y column in the trigger table.

from deephaven import time_table

source = time_table("PT1S").update_view(["X = i"])
trigger = time_table("PT5S").update_view(["Y = i"])
result = source.snapshot_when(trigger_table=trigger, stamp_cols=["Y"], incremental=True)

img