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