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
result = source.snapshot_when(trigger_table)
result = source.snapshot_when(trigger_table, stamp_cols)
result = source.snapshot_when(trigger_table, initial=True)
result = source.snapshot_when(trigger_table, incremental=True)
result = source.snapshot_when(trigger_table, history=True)
Parameters
| Parameter | Type | Description |
|---|---|---|
| trigger_table | Table | The table that triggers the snapshot. |
| stamp_cols | List[string] | 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 optional | boolean | Defines whether an initial snapshot is taken upon construction. The default value is |
| incremental optional | boolean | Defines whether the resulting table should be incremental. The default value is |
| history optional | boolean | Defines whether the resulting table should keep history. The default value is |
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("00:00:01").update_view(["X = i"])
trigger = time_table("00:00:05").rename_columns(["TriggerTimestamp = Timestamp"]).update_view(["Y = Math.sin(0.1 * i)"])
result = source.snapshot_when(trigger_table=trigger)
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("00:00:01").update_view(["X = i"])
trigger = time_table("00:00:05").update_view(["Y = i"])
result = source.snapshot_when(trigger_table=trigger, stamp_cols=["Y"])
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("00:00:01").update_view(["X = i"])
trigger = time_table("00:00:05").update_view(["Y = i"])
result = source.snapshot_when(trigger_table=trigger, stamp_cols=["Y"])
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("00:00:01").update_view(["X = i"])
trigger = time_table("00:00:05").update_view(["Y = i"])
result = source.snapshot_when(trigger_table=trigger, stamp_cols=["Y"], incremental=True)
