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)