---
title: 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](../../../conceptual/table-update-model.md) 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

```python 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

<ParamTable>
<Param name="table_generator" type="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.

</Param>
<Param name="source_tables" type="Union[Table, List[Table]]" optional>

The source tables to be used by the generator function. Every source table must be a refreshing table.

This parameter and `refresh_interval_ms` are mutually exclusive. When neither is specified, the result is static.

</Param>
<Param name="refresh_interval_ms" type="int" optional>

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.

</Param>
<Param name="exec_ctx" type="ExecutionContext" optional>

A custom [execution context](../../../conceptual/execution-context.md) to use for this operation. If not specified, the current execution context is used.

</Param>
<Param name="args" type="tuple" optional>

A Tuple of positional arguments to pass to `table_generator`. Defaults to `()`.

</Param>
<Param name="kwargs" type="dict" optional>

Dictionary of keyword arguments to pass to `table_generator`. Defaults to `{}`.

</Param>
<Param name="copy_data" type="bool" optional>

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`](../snapshot/snapshot.md) — always satisfies this requirement.

</Param>
<Param name="blink_table" type="bool" optional>

When `True`, the result is presented as a [blink table](../../../conceptual/table-types.md#specialization-3-blink), 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`.

</Param>
<Param name="table_definition" type="TableDefinitionLike" optional>

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.

</Param>
</ParamTable>

## Returns

A new function-generated table.

## Example

In the following example, we create an [execution context](../../../conceptual/execution-context.md) and a `table_generator` function, which we then use to generate a table that re-runs the `table_generator` function every 2000ms.

```python order=result
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.

```python order=result
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.

```python order=result
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},
)
```

## Related documentation

- [Execution Context](../../../conceptual/execution-context.md)
- [How to create function-generated tables](../../../how-to-guides/function-generated-tables.md)
- [Pydoc](/core/pydoc/code/deephaven.html#deephaven.function_generated_table)
