snapshot_when

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

Syntax

A PartitionedTableProxy has a snapshot_when method with the same parameters. It accepts a table or another proxy as the trigger table and returns a PartitionedTableProxy.

Parameters

Parameter	Type	Description
trigger_table	Table	The table that triggers the snapshot. This should be a ticking table, as changes in this table trigger the snapshot.
stamp_cols optional	Optional[Union[str, Sequence[str]]]	One or more column names to act as stamp columns. Each stamp column will be included in the final result, and will contain the value of the stamp column from the trigger table at the time of the snapshot. If only one column, a string or list can be used. If more than one column, a list must be used. The default value is None, which means that all columns from the trigger table will be appended to the source table.
initial optional	bool	Determines whether an initial snapshot is taken upon construction. The default value is False
incremental optional	bool	Determines whether the resulting table should be incremental. The default value is False. When False, the stamp column in the resulting table will always contain the latest value from the stamp column in the trigger table. This means that every single row in the resulting table will be updated each time the trigger table updates. When True, only rows that have been added or updated to the source table since the last snapshot will have the latest value from the stamp column.
history optional	bool	Determines whether the resulting table should keep history. The default value is False. When True, the result appends a full snapshot of the source table and the stamp columns for each row the trigger table already has when you create the result, and for each row it adds later, so the result grows very fast. The trigger table must be append-only; if it modifies or removes rows, the result fails and stops updating. When False, the result holds only the latest snapshot. 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 adds a row every second and the trigger table adds a row every five seconds. Thus, the result table updates each time trigger adds a row, about every five seconds. The Timestamp column in the trigger is renamed to avoid a name conflict error.

Notice three things:

1. stamp_cols is left blank, so every column from trigger is included in result.
2. incremental is False, so the entire TriggerTimestamp column in result is updated each time the trigger table updates and always contains the latest value from the TriggerTimestamp column in trigger.
3. history is False, so result holds only the latest snapshot of source. Each snapshot replaces the previous one instead of being appended.

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 an alternative to renaming the column in the trigger table.

In the following example, history is set to True. Therefore, every row in source gets snapshotted and appended to result each time trigger adds a row, regardless of whether source has changed or not.

In the following example, incremental is set to True. Thus, only the rows of source that were added or modified since the last snapshot get the latest Y value. Earlier rows keep the Y value from the snapshot that captured them. Contrast this with the first and second examples given above.

Related documentation

• Create a new table
• Capture the history of a ticking table
• How to reduce the update frequency of ticking tables
• time_table
• update
• Javadoc
• Pydoc