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