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	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.