Initialization and updates

This guide covers safe patterns for working with ticking tables in Groovy, particularly during script initialization when external data sources may not have data yet.

How Deephaven executes your script

Deephaven execution has two phases:

  1. Initialization — Your script runs, creating tables and building the dependency graph (DAG). External data sources (Kafka, etc.) may not have data yet.
  2. Real-time updates — Data flows in continuously. Changes propagate through the DAG automatically. Listeners fire.

The key issue: when your script creates a table from an external source, the table may be empty during initialization. Data arrives asynchronously. Trying to read data immediately can fail or return nothing.

For more details on how updates propagate, see Incremental update model.

Safe patterns

Use snapshot for point-in-time extraction

When you need to read data from a ticking table, create a static copy first:

Use snapshotWhen for periodic extraction

To extract data at controlled intervals:

Use awaitUpdate to wait for data

In app mode scripts, wait for external data before proceeding:

You can specify a timeout: trades.awaitUpdate(5000) returns false if no update occurs within 5 seconds.

Use listeners for ongoing updates

For reacting to changes, use table listeners:

Caution

Keep listener execution fast — listeners block further Update Graph processing while running.

Use locking for direct access (advanced)

When you must read directly from a ticking table:

Caution

Keep lock duration minimal — it blocks update processing while held.

What NOT to do

  • Don't read ticking data without synchronization — use snapshot or locking.
  • Only access the table you are listening to within a listener — other tables are not guaranteed to have been consistently updated.
  • Don't hold locks during long computations — extract data quickly, then process outside the lock.
  • Don't mix data from different update cycles — use upstream.getModifiedPreShift for before/after comparisons within the same update, or store only computed results (not raw data) between cycles.