Skip to main content
Version: Java (Groovy)

snapshotWhen

The snapshotWhen method 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.

caution

When snapshotWhen stores table history, it stores a copy of the source table for every trigger event. This means large source tables or rapidly changing trigger tables can result in large memory usage.

Syntax​

result = source.snapshotWhen(trigger)
result = source.snapshotWhen(trigger, features...)
result = source.snapshotWhen(trigger, features, stampColumns...)
result = source.snapshotWhen(trigger, options)

Parameters​

ParameterTypeDescription
triggerTable

The table that triggers the snapshot. This should be a ticking table, as changes in this table trigger the snapshot.

featuresSnapshotWhenOptions.Flag...

The snapshot features.

featuresCollection<SnapshotWhenOptions.Flag>

The snapshot features.

stampColumnsString...

The stamp columns.

optionsSnapshotWhenOptions

The options dictate whether to take an initial snapshot, do incremental snapshots, keep history, and set stamp columns.

caution

The trigger table's stamp column(s) appear in the result table. If the source table has a column with the same name as the stamp column, an error will be raised. To avoid this problem, rename the stamp column in the trigger table using renameColumns.

Returns​

An in-memory history of a source table that adds a new snapshot when the trigger table updates.

SnapshotWhenOptions​

The snapshotWhen method's options parameter takes a SnapshotWhenOptions object. These are constructed using SnapshotWhenOptions.of(...). The syntax is given below.

import io.deephaven.api.snapshot.SnapshotWhenOptions

myOpts = SnapshotWhenOptions.of(INITIAL, INCREMENTAL, HISTORY, stampColumns)

Where INITIAL, INCREMENTAL, and HISTORY are booleans and stampColumns is one or more string values corresponding to columns in the trigger table.

  • INITIAL (Boolean): Whether or not to take an initial snapshot upon creating the result table. The default is false.
  • INCREMENTAL (Boolean): 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 row in the resulting table will be updated each cycle. 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 (Boolean): Determines whether the resulting table should keep history. The default value is false. When true, a full snapshot of the source table and the stamp column is appended to the resulting table every time the trigger table changes. This means that the resulting table will grow very fast. When false, only rows from the source table that have changed since the last snapshot will be appended to the resulting table.
  • stampColumns (String...): 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. The default value is None, meaning all trigger table columns will be appended to the source table.
note

If HISTORY is true, INITIAL and INCREMENTAL must be false.

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. To avoid a name conflict error, the Timestamp column in the trigger is renamed.

source = timeTable("PT00:00:01").updateView("X = i")
trigger = timeTable("PT00:00:05").renameColumns("TriggerTimestamp = Timestamp").updateView("Y = Math.sin(0.1 * i)")
result = source.snapshotWhen(trigger)

img

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 every cycle and always contains the latest value from the TriggerTimestamp column in trigger.
  3. historical is false, so only updated rows from source get appended to result on each snapshot.

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.

import io.deephaven.api.snapshot.SnapshotWhenOptions

myOpts = SnapshotWhenOptions.of(false, false, false, "Y")

source = timeTable("PT00:00:01").updateView("X = i")
trigger = timeTable("PT00:00:05").updateView("Y = Math.sin(0.1 * i)")
result = source.snapshotWhen(trigger, myOpts)

img

In the following example, HISTORY is set to true. Therefore, every row in source gets snapshotted and appended to result when trigger changes, regardless of whether source has changed.

import io.deephaven.api.snapshot.SnapshotWhenOptions

myOpts = SnapshotWhenOptions.of(false, false, true, "Y")

source = timeTable("PT00:00:01").updateView("X = i")
trigger = timeTable("PT00:00:05").updateView("Y = Math.sin(0.1 * i)")
result = source.snapshotWhen(trigger, myOpts)

img

In the following example, INCREMENTAL is set to true. Thus, the Y column in result only updates when corresponding rows in trigger have changed. Contrast this with the first and second examples given above.

import io.deephaven.api.snapshot.SnapshotWhenOptions

myOpts = SnapshotWhenOptions.of(false, true, false, "Y")

source = timeTable("PT00:00:01").updateView("X = i")
trigger = timeTable("PT00:00:05").updateView("Y = Math.sin(0.1 * i)")
result = source.snapshotWhen(trigger, myOpts)

img