function_generated_table

The function_generated_table method is useful for creating tables that are dependent on one or more ticking tables, or for creating tables that need to be refreshed at a regular interval. The method creates a table by running the user-defined table_generator function. This function runs once when the table is created, and then again when either the source_tables tick or when refresh_interval_ms milliseconds have elapsed. At most one of source_tables and refresh_interval_ms may be specified; when neither is specified there is no refresh trigger, so the table_generator runs exactly once and the result is a static table.

Note

The table_generator may access data in the source_tables, but should not perform further table operations without careful handling. Table operations may be memoized, and it is possible that a table operation will return a table created by a previous invocation of the same operation. Since that result will not have been included in the source_table’, it is not automatically treated as a dependency for purposes of determining when it is safe to invoke table_generator. This allows race conditions to exist between (1) accessing the operation result and (2) that result’s own update processing.

It is best to include all dependencies directly in source_table or only compute on-demand inputs under a LivenessScope.

Every refresh in which the table_generator produces a table replaces the result in full: the table update removes all previous rows and adds all newly generated rows, with no modified rows and no shifts, even when the generated data is unchanged. A refresh in which the table_generator returns None retains the previous result with no update (or clears a blink result). The copy_data and blink_table parameters refine this behavior independently of one another.

Syntax

function_generated_table(
  table_generator: Callable[..., Optional[Table]],
  source_tables: Union[Table, List[Table]] = None,
  refresh_interval_ms: int = None,
  exec_ctx: ExecutionContext = None,
  args: tuple = (),
  kwargs: dict = {},
  copy_data: bool = True,
  blink_table: bool = False,
  table_definition: TableDefinitionLike = None,
) -> Table

Parameters

Parameter	Type	Description
table_generator	Callable[..., Optional[Table]]	The table generator function. This function must return a table, or `None` to decline producing a new table, in which case the previous cycle's result is retained (or, for a blink table, cleared). If the first invocation returns `None`, `table_definition` must be provided so that the result's columns are known.
source_tables optional	Union[Table, List[Table]]	The source tables to be used by the generator function. This parameter and `refresh_interval_ms` are mutually exclusive. When neither is specified, the result is static.
refresh_interval_ms optional	int	The interval (in milliseconds) at which the `table_generator` function is re-run. A non-positive interval is treated the same as no trigger at all, producing a static result. This parameter and `source_tables` are mutually exclusive. When neither is specified, the result is static.
exec_ctx optional	ExecutionContext	A custom execution context to use for this operation. If not specified, the default execution context will be used.
args optional	tuple	A Tuple of positional arguments to pass to `table_generator`. Defaults to `()`.
kwargs optional	dict	Dictionary of keyword arguments to pass to `table_generator`. Defaults to `{}`.
copy_data optional	bool	When `True` (the default), the generated data is copied into the result's own column sources, and the result uses a flat, contiguous row set. When `False`, the result delegates directly to the generated table's column sources, avoiding the copy and adopting the generated table's row set as-is: the added rows of each update are the generated table's row set, and the removed rows are the previous cycle's row set. In that case, a refreshing generated table must expose immutable column sources; a generated table that changes values in place is rejected. A static table produced fresh on each refresh — for example, via `snapshot` — always satisfies this requirement.
blink_table optional	bool	When `True`, the result is presented as a blink table, retaining only the rows generated during the current cycle. Each update is still a full replacement; the blink attribute changes how downstream operations interpret it and is independent of `copy_data`. Rows generated in one update cycle are removed on the next cycle whether or not the `table_generator` runs again. On a cycle where the `table_generator` returns `None`, the blink result is cleared. Requires a refresh trigger (`refresh_interval_ms` or `source_tables`). Defaults to `False`.
table_definition optional	TableDefinitionLike	When provided, it is authoritative: it defines the result's columns and their order, and every table the `table_generator` produces must be compatible with it. Defaults to `None`, in which case the generated table's definition is used.

Returns

A new function-generated table.

Example

In the following example, we create an execution context and a table_generator function, which we then use to generate a table that re-runs the table_generator function every 2000ms.

from deephaven.execution_context import get_exec_ctx
from deephaven import empty_table
import random, threading, time
from deephaven import function_generated_table


def make_table():
    return empty_table(5).update(
        ["X = randomInt(0, 10)", "Y = randomDouble(-50.0, 50.0)"]
    )


ctx = get_exec_ctx()  # Get the systemic execution context

result = function_generated_table(
    table_generator=make_table, refresh_interval_ms=2000, exec_ctx=ctx
)

If the table_generator function depends on one or more ticking tables, the tables must be specified. Adding tt as a source_tables parameter causes the generated table to be recomputed on each tick of the time table.

from deephaven.execution_context import get_exec_ctx
from deephaven import empty_table, time_table
import random, threading, time
from deephaven import function_generated_table


def make_table():
    return empty_table(5).update(
        ["X = randomInt(0, 10)", "Y = randomDouble(-50.0, 50.0)"]
    )


ctx = get_exec_ctx()  # Get the systemic execution context

tt = time_table("PT1S")

result = function_generated_table(
    table_generator=make_table, source_tables=tt, exec_ctx=ctx
)

function_generated_table's args and kwargs parameters allow you to pass positional and keyword arguments to the table_generator function.

from deephaven.execution_context import get_exec_ctx
from deephaven import empty_table
import random, threading, time
from deephaven import function_generated_table


def make_table(nrows, x_lower, x_upper, y_lower, y_upper):
    return empty_table(nrows).update(
        [
            f"X = randomInt({x_lower}, {x_upper})",
            f"Y = randomDouble({y_lower}, {y_upper})",
        ]
    )


ctx = get_exec_ctx()  # Get the systemic execution context

result = function_generated_table(
    table_generator=make_table,
    refresh_interval_ms=2000,
    exec_ctx=ctx,
    args=(10, 0, 100),
    kwargs={"y_lower": 0.0, "y_upper": 1.0},
)

function_generated_table

Syntax

Parameters

Returns

Example

Related documentation