Replay a table programmatically

ReplayAccess is a type-specific table access that replays a static table from db as a refreshing table based on a simulated clock. It's a lighter-weight, programmatic alternative to a Replay Query: a Replay Query replaces an entire Persistent Query's db.liveTable calls with replayed data, whereas ReplayAccess replays just the table you ask for, without needing a dedicated Persistent Query.

ReplayAccess is obtained via db.as:

By default, this:

  • Infers the timestamp column from the table's schema — it must have exactly one Instant column.
  • Replays relative to the system clock.
  • Replays in unsorted mode (see Sorted vs. unsorted replay below).
  • Produces an add-only output table.

Pass a timestampColumnName explicitly if the schema has more than one timestamp-typed column:

Advanced options

For more control — a custom Clock, a different Source, sorted replay, or blink/static output — build ReplayAccess.Options directly with Options.of(clock, source, mode, timestampColumnName, outputAttributes).

Source

  • Source.historical(schema) — replay from db.historicalTable.
  • Source.live(schema) — replay from db.liveTable (fetched with TableOptions.isRefreshing() as false).
  • Source.tableAccess(factory, options) — replay from another db.as(...) accessor, such as IcebergTableAccess. The table must be static. If a non-static table is provided, an exception will be thrown.

Sorted vs. unsorted replay

  • ReplayMode.unsorted() — replays the data, preserving the source's original order between rows.
  • ReplayMode.sorted() — replays the data, sorted by timestamp.

As a simplified example, if the source table contains "timestamps" [1, 5, 3] (where each element in the list is a row), a replay might proceed as follows:

Simulated timestampUnsortedSorted
0[][]
2[1][1]
4[1, 3][1, 3]
6[1, 5, 3][1, 3, 5]

Output attributes

  • OutputAttributes.addOnly() — refreshing, add-only output (the default used by the table(namespace, tableName, startInstant[, timestampColumnName]) convenience overloads).
  • OutputAttributes.blink() — refreshing, blink-table output.
  • OutputAttributes.staticOutput() — non-refreshing output containing only the rows released so far, evaluated at the time it is requested.