use_table_data

use_table_data lets you use the data of a table. This is useful when you want to listen to an updating table and use the data in your component.

Example

from deephaven import time_table, ui


@ui.component
def ui_table_data(table):
    table_data = ui.use_table_data(table)
    return ui.heading(f"The table data is {table_data}")


table_data = ui_table_data(time_table("PT1s").update("x=i").tail(5))

In the above example, ui_table_data is a component that listens to the last 5 rows of a table and displays the data. The table_data variable is updated every time the table updates.

Recommendations

Use use_table_data for listening to table updates: If you need to listen to a table for all the data, use use_table_data.
Use table operations to filter to the data you want: If your table has multiple rows and columns, use table operations such as .where, .select and .reverse to filter to the data you want to listen to.
Pass a Sentinel value to use_table_data: If you want to use a default value when the table is empty, pass a sentinel value to use_table_data. The default sentinel value is None, which is returned when the table is empty.

Empty tables

If the table is empty, the value of table_data will return the value of None.

from deephaven import time_table, ui
import datetime as dt


@ui.component
def ui_table_data(table):
    table_data = ui.use_table_data(table)
    if table_data is None:
        return ui.heading("No data yet.")
    return ui.heading(f"Table data: {table_data}")


start_time = dt.datetime.now() + dt.timedelta(seconds=2)
table_data = ui_table_data(
    time_table("PT1s", start_time=start_time).update("x=i").tail(5)
)

You can optionally provide a sentinel value to return when the table is empty instead.

from deephaven import time_table, ui
import datetime as dt


@ui.component
def ui_table_data(table):
    table_data = ui.use_table_data(table, sentinel="No data yet.")
    return ui.heading(f"Table data: {table_data}")


start_time = dt.datetime.now() + dt.timedelta(seconds=2)
table_data = ui_table_data(
    time_table("PT1s", start_time=start_time).update("x=i").tail(5)
)

Null values

If the table has null values, they will be represented in the data with pandas.NA.

from deephaven import time_table, ui
import datetime as dt


@ui.component
def ui_table_data(table):
    table_data = ui.use_table_data(table)
    if table_data is None:
        return ui.heading("No data yet.")
    if pd.isna(table_data["x"][0]):
        return ui.heading("First value of 'x' is null.")
    return ui.heading(f"Table data: {table_data}")


start_time = dt.datetime.now() + dt.timedelta(seconds=2)
table_data = ui_table_data(
    time_table("PT1s", start_time=start_time).update("x=i%2==0?null:i").tail(3)
)

API Reference

Returns a dictionary with the contents of the table. Component will redraw if the table changes, resulting in an updated frame.

Returns: Dict[str, List[Any]] | Any The table data or the sentinel value.

Parameters	Type	Default	Description
table	Table \| None		The table to listen to. If None, None will be returned, not the sentinel value.
sentinel	Any	None	The sentinel value to return if the table is ticking but empty. Defaults to None.
transform	Callable[[DataFrame \| Any \| None, bool], Any] \| None	None	A function to transform the table data and is_sentinel values. Defaults to None, which will return the data as TableData.