pydeephaven.table#

class Table(session, ticket, schema_header=b'', size=None, is_static=None, schema=None)[source]#

Bases: TableInterface

A Table object represents a reference to a table on the server. It is the core data structure of Deephaven and supports a rich set of operations such as filtering, sorting, aggregating, joining, snapshotting etc.

Note, an application should never instantiate a Table object directly. Table objects are always provided through factory methods such as Session.empty_table(), or import/export methods such as Session.import_table(), open_table(), or any of the Table operations.

is_closed#

check if the table has been closed on the server

Type:

bool

agg_by(agg, by)#

Perform a Combined Aggregation operation on the table and return the result table.

Parameters:

  • agg (ComboAggregation) – the combined aggregation definition

  • by (List[str]) – the group-by column names

Returns:

a Table object

Raises:

DHError –

aj(table, on, joins=[], match_rule=MatchRule.LESS_THAN_EQUAL)#

Perform a as-of join between this table as the left table and another table as the right table) and returns the result table.

Parameters:

  • table (Table) – the right-table of the join

  • on (List[str]) – the columns to match, can be a common name or an equal expression, i.e. “col_a = col_b” for different column names

  • joins (List[str], optional) – a list of the columns to be added from the right table to the result table, can be renaming expressions, i.e. “new_col = col”; default is empty

  • match_rule (MatchRule, optional) – the match rule for the as-of join, default is LESS_THAN_EQUAL

Returns:

a Table object

Raises:

DHError –

avg_by(by=[])#

Perform avg-by aggregation on the table and return the result table. Columns not used in the grouping must be of numeric types.

Parameters:

by (List[str], optional) – the group-by column names, default is empty

Returns:

a Table object

Raises:

DHError –

close()[source]#

Close the table reference on the server.

Raises:

DHError –

Return type:

None

count(col)#

Count the number of values in the specified column on the table and return the result in a table with one row and one column.

Parameters:

col (str) – the name of the column whose values to be counted

Returns:

a Table object

Raises:

DHError –

count_by(col, by=[])#

Perform count-by aggregation on the table and return the result table. The count of each group is stored in a new column named after the ‘col’ parameter.

Parameters:

  • col (str) – the name of the column to store the counts

  • by (List[str], optional) – the group-by column names, default is empty

Returns:

a Table object

Raises:

DHError –

drop_columns(cols)#

Drop the specified columns from the table and return the result table.

Parameters:

cols (List[str]) – the list of column names

Returns:

a Table object

Raises:

DHError –

exact_join(table, on, joins=[])#

Perform a exact-join between this table as the left table and another table as the right table) and returns the result table.

Parameters:

  • table (Table) – the right-table of the join

  • on (List[str]) – the columns to match, can be a common name or an equal expression, i.e. “col_a = col_b” for different column names

  • joins (List[str], optional) – a list of the columns to be added from the right table to the result table, can be renaming expressions, i.e. “new_col = col”; default is empty

Returns:

a Table object

Raises:

DHError –

first_by(by=[])#

Perform First-by aggregation on the table and return the result table which contains the first row of each distinct group.

Parameters:

by (List[str], optional) – the group-by column names, default is empty

Returns:

a Table object

Raises:

DHError –

group_by(by=[])#

Perform a group-by aggregation on the table and return the result table. After the operation, the columns not in the group-by columns become array-type.

If no group-by column is given,the content of each column is grouped into its own array.

Parameters:

by (List[str], optional) – the group-by column names; default is empty

Returns:

a Table object

Raises:

DHError –

head(num_rows)#

Perform a head operation on the table and return the result table.

Parameters:

num_rows (int) – the number of rows at the head of table

Returns:

a Table object

Raises:

DHError –

head_by(num_rows, by)#

Perform a head-by aggregation on the table and return the result table.

Parameters:

  • num_rows (int) – the number of rows at the beginning of each group

  • by (List[str]) – the group-by column names

Returns:

a Table object

Raises:

DHError –

join(table, on=[], joins=[], reserve_bits=10)#

Perform a cross-join between this table as the left table and another table as the right table) and returns the result table.

Parameters:

  • table (Table) – the right-table of the join

  • on (List[str]) – the columns to match, can be a common name or an equal expression, i.e. “col_a = col_b” for different column names

  • joins (List[str], optional) – a list of the columns to be added from the right table to the result table, can be renaming expressions, i.e. “new_col = col”; default is empty

  • reserve_bits (int, optional) – the number of bits of key-space to initially reserve per group; default is 10

Returns:

a Table object

Raises:

DHError –

last_by(by=[])#

Perform last-by aggregation on the table and return the result table which contains the last row of each distinct group.

Parameters:

by (List[str], optional) – the group-by column names, default is empty

Returns:

a Table object

Raises:

DHError –

lazy_update(formulas)#

Perform a lazy-update operation on the table and return the result table.

Parameters:

formulas (List[str]) – the column formulas

Returns:

a Table object

Raises:

DHError –

max_by(by=[])#

Perform max-by aggregation on the table and return the result table. Columns not used in the grouping must be of numeric types.

Parameters:

by (List[str], optional) – the group-by column names, default is empty

Returns:

a Table object

Raises:

DHError –

median_by(by=[])#

Perform median-by aggregation on the table and return the result table. Columns not used in the grouping must be of numeric types.

Parameters:

by (List[str], optional) – the group-by column names, default is empty

Returns:

a Table object

Raises:

DHError –

min_by(by=[])#

Perform min-by aggregation on the table and return the result table. Columns not used in the grouping must be of numeric types.

Parameters:

by (List[str], optional) – the group-by column names, default is empty

Returns:

a Table object

Raises:

DHError –

natural_join(table, on, joins=[])#

Perform a natural-join between this table as the left table and another table as the right table) and returns the result table.

Parameters:

  • table (Table) – the right-table of the join

  • on (List[str]) – the columns to match, can be a common name or an equal expression, i.e. “col_a = col_b” for different column names

  • joins (List[str], optional) – a list of the columns to be added from the right table to the result table, can be renaming expressions, i.e. “new_col = col”; default is empty

Returns:

a Table object

Raises:

DHError –

raj(table, on, joins=[], match_rule=MatchRule.GREATER_THAN_EQUAL)#

Perform a reverse as-of join between this table as the left table and another table as the right table) and returns the result table.

Parameters:

  • table (Table) – the right-table of the join

  • on (List[str]) – the columns to match, can be a common name or an equal expression, i.e. “col_a = col_b” for different column names

  • joins (List[str], optional) – a list of the columns to be added from the right table to the result table, can be renaming expressions, i.e. “new_col = col”; default is empty

  • match_rule (MatchRule, optional) – the match rule for the as-of join, default is GREATER_THAN_EQUAL

Returns:

a Table object

Raises:

DHError –

select(formulas=[])#

Perform a select operation on the table and return the result table.

Parameters:

formulas (List[str], optional) – the column formulas, default is empty

Returns:

a Table object

Raises:

DHError –

select_distinct(cols=[])#

Perform a select-distinct operation on the table and return the result table.

Parameters:

cols (List[str], optional) – the list of column names, default is empty

Returns:

a Table object

Raises:

DHError –

snapshot()#

Returns a static snapshot table.

Returns:

a new Table

Raises:

DHError –

snapshot_when(trigger_table, stamp_cols=None, initial=False, incremental=False, history=False)#

Returns a table that captures a snapshot of this table whenever trigger_table updates.

When trigger_table updates, a snapshot of this table and the “stamp key” from trigger_table form the resulting table. The “stamp key” is the last row of the trigger_table, limited by the stamp_cols. If trigger_table is empty, the “stamp key” will be represented by NULL values.

Parameters:

  • trigger_table (Table) – the trigger table

  • stamp_cols (List[str]) – The columns from trigger_table that form the “stamp key”, may be renames. None, or empty, means that all columns from trigger_table form the “stamp key”.

  • initial (bool) – Whether to take an initial snapshot upon construction, default is False. When False, the resulting table will remain empty until trigger_table first updates.

  • incremental (bool) – Whether the resulting table should be incremental, default is False. When False, all rows of this table will have the latest “stamp key”. When True, only the rows of this table that have been added or updated will have the latest “stamp key”.

  • history (bool) – Whether the resulting table should keep history, default is False. A history table appends a full snapshot of this table and the “stamp key” as opposed to updating existing rows. The history flag is currently incompatible with initial and incremental: when history is True, incremental and initial must be False.

Returns:

a new Table

Raises:

DHError –

sort(order_by, order=[])#

Perform a sort operation on the table and return the result table.

Parameters:

  • order_by (List[str]) – the names of the columns to be sorted on

  • order (List[SortDirection], optional) – the corresponding sort directions for each sort column, default is empty. In the absence of explicit sort directions, data will be sorted in the ascending order.

Returns:

a Table object

Raises:

DHError –

std_by(by=[])#

Perform std-by aggregation on the table and return the result table. Columns not used in the grouping must be of numeric types.

Parameters:

by (List[str]) – the group-by column names

Returns:

a Table object

Raises:

DHError –

sum_by(by=[])#

Perform sum-by aggregation on the table and return the result table. Columns not used in the grouping must be of numeric types.

Parameters:

by (List[str]) – the group-by column names

Returns:

a Table object

Raises:

DHError –

tail(num_rows)#

Perform a tail operation on the table and return the result table.

Parameters:

num_rows (int) – the number of rows at the end of table

Returns:

a Table object

Raises:

DHError –

tail_by(num_rows, by)#

Perform a tail-by aggregation on the table and return the result table.

Parameters:

  • num_rows (int) – the number of rows at the end of each group

  • by (List[str]) – the group-by column names

Returns:

a Table object

Raises:

DHError –

to_arrow()[source]#

Take a snapshot of the table and return a pyarrow Table.

Return type:

Table

Returns:

a pyarrow.Table

Raises:

DHError –

ungroup(cols=[], null_fill=True)#

Perform an ungroup operation on the table and return the result table. The ungroup columns should be of array types.

Parameters:

  • cols (List[str], optional) – the names of the array columns, if empty, all array columns will be ungrouped, default is empty

  • null_fill (bool, optional) – indicates whether null should be used to fill missing cells, default is True

Returns:

a Table object

Raises:

DHError –

update(formulas)#

Perform an update operation on the table and return the result table.

Parameters:

formulas (List[str]) – the column formulas

Returns:

a Table object

Raises:

DHError –

update_by(ops, by)#

Perform an update-by operation on the table and return the result table.

Parameters:

  • ops (List[UpdateByOperation]) – the UpdateByOperations to be applied

  • by (List[str]) – the group-by column names

Returns:

a Table object

Raises:

DHError –

update_view(formulas)#

Perform an update-view operation on the table and return the result table.

Parameters:

formulas (List[str]) – the column formulas

Returns:

a Table object

Raises:

DHError –

var_by(by=[])#

Perform var-by aggregation on the table and return the result table. Columns not used in the grouping must be of numeric types.

Parameters:

by (List[str], optional) – the group-by column names, default is empty

Returns:

a Table object

Raises:

DHError –

view(formulas)#

Perform a view operation on the table and return the result table.

Parameters:

formulas (List[str]) – the column formulas

Returns:

a Table object

Raises:

DHError –

where(filters)#

Perform a filter operation on the table and return the result table.

Parameters:

filters (List[str]) – a list of filter condition expressions

Returns:

a Table object

Raises:

DHError –