pydeephaven.table¶

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

Bases: pydeephaven._table_interface.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: 0>)¶

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: 2>)¶

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()[source]¶

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

Return type: Table
Returns: a pyarrow.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 –

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_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 –