---
title: 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](../create/timeTable.md), 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

<ParamTable>
<Param name="trigger" type="Table">

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

</Param>
<Param name="features" type="SnapshotWhenOptions.Flag...">

The snapshot features.

</Param>
<Param name="features" type="Collection<SnapshotWhenOptions.Flag>">

The snapshot features.

</Param>
<Param name="stampColumns" type="String...">

The stamp columns.

</Param>
<Param name="options" type="SnapshotWhenOptions">

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

</Param>
</ParamTable>

> [!CAUTION]
> The trigger table's stamp columns appear in the result table. If the source table has a column with the same name as a stamp column, `snapshotWhen` throws an exception. To avoid the conflict, rename the stamp column in the trigger table with [`renameColumns`](../select/rename-columns.md), or rename it in the stamp columns (for example, `"TriggerTimestamp = Timestamp"`).

## Returns

A new table that captures a snapshot of the source table whenever 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 zero or more string values corresponding to columns in the `trigger` table.

You can also build the options from [`SnapshotWhenOptions.Flag`](/core/javadoc/io/deephaven/api/snapshot/SnapshotWhenOptions.Flag.html) values. `SnapshotWhenOptions.of(Flag...)` takes only flags. `SnapshotWhenOptions.of(Iterable<Flag>, String...)` takes a collection of flags and the stamp columns.

- `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 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` (Boolean): 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.
- `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. If you pass no stamp columns, all trigger table columns are appended to the source table.

> [!NOTE]
> If `history` is `true`, `initial` and `incremental` _must_ be `false`.

## 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. To avoid a name conflict error, the `Timestamp` column in the `trigger` is [renamed](../select/rename-columns.md).

```groovy ticking-table order=null
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)
```

![The above `source`, `trigger`, and `result` tables](../../../assets/reference/table-operations/snapshot-when-1.gif)

Notice three things:

1. No stamp columns are passed, 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.

```groovy ticking-table order=null
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)
```

![The above `source`, `trigger`, and `result` tables](../../../assets/reference/table-operations/snapshot-when-2.gif)

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.

```groovy ticking-table order=null
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)
```

![The above `source`, `trigger`, and `result` tables](../../../assets/reference/table-operations/snapshot-when-3.gif)

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.

```groovy ticking-table order=null
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)
```

![The above `source`, `trigger`, and `result` tables](../../../assets/reference/table-operations/snapshot-when-4.gif)

## Related documentation

- [Create a new table](../../../how-to-guides/new-and-empty-table.md#newtable)
- [Capture the history of a ticking table](../../../how-to-guides/capture-table-history.md)
- [How to reduce the update frequency of ticking tables](../../../how-to-guides/performance/reduce-update-frequency.md)
- [`snapshot`](./snapshot.md)
- [`timeTable`](../create/timeTable.md)
- [`update`](../select/update.md)
- [Javadoc](https://deephaven.io/core/javadoc/io/deephaven/engine/table/impl/QueryTable.html#snapshotWhen(io.deephaven.engine.table.Table,io.deephaven.api.snapshot.SnapshotWhenOptions))
