deephaven.table¶
This module implements the Table, PartitionedTable and PartitionedTableProxy classes which are the main instruments for working with Deephaven refreshing and static data.
- class AsOfMatchRule(value)[source]¶
Bases:
enum.EnumAn enum defining matching rules on the final column to match by in as-of join and reverse as-of join operation.
- class PartitionedTable(j_partitioned_table)[source]¶
Bases:
deephaven._wrapper.JObjectWrapperA partitioned table is a table containing tables, known as constituent tables. Each constituent table has the same schema.
The partitioned table contains: 1. one column containing constituent tables 2. key columns (optional) 3. non-key columns (optional)
Key values can be used to retrieve constituent tables from the partitioned table and can be used to perform operations with other like-keyed partitioned tables.
- property constituent_changes_permitted¶
Can the constituents of the underlying partitioned table change? Specifically, can the values of the constituent column change?
If constituent changes are not permitted, the underlying partitioned table: 1. has no adds 2. has no removes 3. has no shifts 4. has no modifies that include the constituent column
Note, it is possible for constituent changes to not be permitted even if constituent tables are refreshing or if the underlying partitioned table is refreshing. Also note that the underlying partitioned table must be refreshing if it contains any refreshing constituents.
- property constituent_column¶
The name of the column containing constituent tables.
- property constituent_table_columns¶
The column definitions for constituent tables. All constituent tables in a partitioned table have the same column definitions.
- property constituent_tables¶
Returns all the current constituent tables.
- filter(filters)[source]¶
The filter method creates a new partitioned table containing only the rows meeting the filter criteria. Filters can not use the constituent column.
- classmethod from_constituent_tables(tables, constituent_table_columns=None)[source]¶
Creates a PartitionedTable with a single column named ‘__CONSTITUENT__’ containing the provided constituent tables.
The result PartitionedTable has no key columns, and both its unique_keys and constituent_changes_permitted properties are set to False. When constituent_table_columns isn’t provided, it will be set to the column definitions of the first table in the provided constituent tables.
- Parameters
- Return type
- Returns
a PartitionedTable
- Raises
DHError –
- classmethod from_partitioned_table(table, key_cols=None, unique_keys=None, constituent_column=None, constituent_table_columns=None, constituent_changes_permitted=None)[source]¶
Creates a PartitionedTable from the provided underlying partitioned Table.
Note: key_cols, unique_keys, constituent_column, constituent_table_columns, constituent_changes_permitted must either be all None or all have values. When they are None, their values will be inferred as follows:
key_cols: the names of all columns with a non-Table data type unique_keys: False constituent_column: the name of the first column with a Table data type constituent_table_columns: the column definitions of the first cell (constituent table) in the constituent
column. Consequently the constituent column can’t be empty
constituent_changes_permitted: the value of table.is_refreshing
- Parameters
table (Table) – the underlying partitioned table
key_cols (Union[str, List[str]]) – the key column name(s) of ‘table’
unique_keys (bool) – whether the keys in ‘table’ are guaranteed to be unique
constituent_column (str) – the constituent column name in ‘table’
constituent_table_columns (list[Column]) – the column definitions of the constituent table
constituent_changes_permitted (bool) – whether the values of the constituent column can change
- Return type
- Returns
a PartitionedTable
- Raises
DHError –
- get_constituent(key_values)[source]¶
Gets a single constituent table by its corresponding key column value(s). If there are no matching rows, the result is None. If there are multiple matching rows, a DHError is thrown.
- property is_refreshing¶
Whether the underlying partitioned table is refreshing.
- j_object_type¶
alias of
io.deephaven.engine.table.PartitionedTable
- property key_columns¶
The partition key column names.
- keys()[source]¶
Returns a Table containing all the keys of the underlying partitioned table.
- Return type
- merge()[source]¶
Makes a new Table that contains all the rows from all the constituent tables. In the merged result, data from a constituent table is contiguous, and data from constituent tables appears in the same order the constituent table appears in the PartitionedTable. Basically, merge stacks constituent tables on top of each other in the same relative order as the partitioned table.
- partitioned_transform(other, func)[source]¶
Join the underlying partitioned Tables from this PartitionedTable and other on the key columns, then apply the provided function to all pairs of constituent Tables with the same keys in order to produce a new PartitionedTable with the results as its constituents, with the same data for all other columns in the underlying partitioned Table from this.
Note that if the Tables underlying this PartitionedTable or other change, a corresponding change will propagate to the result.
- Parameters
other (PartitionedTable) – the other Partitioned table whose constituent tables will be passed in as the 2nd argument to the provided function
(Callable[[Table (func) – a function which takes two Tables as input and returns a new Table
Table] – a function which takes two Tables as input and returns a new Table
Table] – a function which takes two Tables as input and returns a new Table
- Return type
- Returns
a PartitionedTable
- Raises
DHError –
- proxy(require_matching_keys=True, sanity_check_joins=True)[source]¶
Makes a proxy that allows table operations to be applied to the constituent tables of this PartitionedTable.
- Parameters
require_matching_keys (bool) – whether to ensure that both partitioned tables have all the same keys present when an operation uses this PartitionedTable and another PartitionedTable as inputs for a
partitioned_transform(), default is Truesanity_check_joins (bool) – whether to check that for proxied join operations, a given join key only occurs
a (in exactly one constituent table of the underlying partitioned table. If the other table argument is also) –
PartitionedTableProxy –
constraint. (its constituents will also be subjected to this) –
- Return type
- sort(order_by, order=None)[source]¶
The sort method creates a new partitioned table where the rows are ordered based on values in a specified set of columns. Sort can not use the constituent column.
- Return type
-
- Args:
order_by (Union[str, Sequence[str]]): the column(s) to be sorted on. Can’t include the constituent column. order (Union[SortDirection, Sequence[SortDirection], optional): the corresponding sort directions for
each sort column, default is None, meaning ascending order for all the sort columns.
- Returns:
a new PartitionedTable
- Raises:
DHError
- property table¶
The underlying partitioned table.
- transform(func)[source]¶
Apply the provided function to all constituent Tables and produce a new PartitionedTable with the results as its constituents, with the same data for all other columns in the underlying partitioned Table. Note that if the Table underlying this PartitionedTable changes, a corresponding change will propagate to the result.
- Parameters
(Callable[[Table] (func) – a function which takes a Table as input and returns a new Table
Table] – a function which takes a Table as input and returns a new Table
- Return type
- Returns
a PartitionedTable
- Raises
DHError –
- property unique_keys¶
Whether the keys in the underlying table must always be unique. If keys must be unique, one can expect that self.table.select_distinct(self.key_columns) and self.table.view(self.key_columns) operations always produce equivalent tables.
- class PartitionedTableProxy(j_pt_proxy)[source]¶
Bases:
deephaven._wrapper.JObjectWrapperA PartitionedTableProxy is a table operation proxy for the underlying partitioned table. It provides methods that apply table operations to the constituent tables of the underlying partitioned table, produce a new partitioned table from the resulting constituent tables, and return a proxy of it.
- target¶
the underlying partitioned table of the proxy
- Type
- require_matching_keys¶
whether to ensure that both partitioned tables have all the same keys present when an operation uses this PartitionedTable and another PartitionedTable as inputs for a
partitioned_transform(), default is True- Type
bool
- sanity_check_joins¶
whether to check that for proxied join operations, a given join key only occurs in exactly one constituent table of the underlying partitioned table. If the other table argument is also a PartitionedTableProxy, its constituents will also be subjected to this constraint.
- Type
bool
- abs_sum_by(by=None)[source]¶
Applies the
abs_sum_by()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
by (Union[str, Sequence[str]], optional) – the group-by column name(s), default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- agg_all_by(agg, by=None)[source]¶
Applies the
agg_all_by()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.Note, because agg_all_by applies the aggregation to all the columns of the table, it will ignore any column names specified for the aggregation.
- Parameters
agg (Aggregation) – the aggregation
by (Union[str, Sequence[str]], optional) – the group-by column name(s), default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- agg_by(aggs, by=None)[source]¶
Applies the
agg_by()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
aggs (Union[Aggregation, Sequence[Aggregation]]) – the aggregation(s)
by (Union[str, Sequence[str]]) – the group-by column name(s), default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- aj(table, on, joins=None, match_rule=AsOfMatchRule.LESS_THAN_EQUAL)[source]¶
Applies the
aj()table operation to all constituent tables of the underlying partitioned table with the provided right table or PartitionedTableProxy, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.In the case of the right table being another PartitionedTableProxy, the
aj()table operation is applied to the matching pairs of the constituent tables from both underlying partitioned tables.- Parameters
table (Union[Table, PartitionedTableProxy]) – the right table or PartitionedTableProxy of the join
on (Union[str, Sequence[str]]) – the column(s) to match, can be a common name or an equal expression, i.e. “col_a = col_b” for different column names
joins (Union[str, Sequence[str]], optional) – the column(s) to be added from the right table to the result table, can be renaming expressions, i.e. “new_col = col”; default is None
match_rule (AsOfMatchRule) – the inexact matching rule on the last column to match specified in ‘on’, default is AsOfMatchRule.LESS_THAN_EQUAL. The other valid value is AsOfMatchRule.LESS_THAN.
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- avg_by(by=None)[source]¶
Applies the
avg_by()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
by (Union[str, Sequence[str]], optional) – the group-by column name(s), default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- count_by(col, by=None)[source]¶
Applies the
count_by()table operation to all constituent tables of the underlying partitioned table with the provided source table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
col (str) – the name of the column to store the counts
by (Union[str, Sequence[str]], optional) – the group-by column name(s), default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- exact_join(table, on, joins=None)[source]¶
Applies the
exact_join()table operation to all constituent tables of the underlying partitioned table with the provided right table or PartitionedTableProxy,and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.In the case of the right table being another PartitionedTableProxy, the
exact_join()table operation is applied to the matching pairs of the constituent tables from both underlying partitioned tables.- Parameters
table (Union[Table, PartitionedTableProxy]) – the right table or PartitionedTableProxy of the join
on (Union[str, Sequence[str]]) – the column(s) to match, can be a common name or an equal expression, i.e. “col_a = col_b” for different column names
joins (Union[str, Sequence[str]], optional) – the column(s) to be added from the right table to the result table, can be renaming expressions, i.e. “new_col = col”; default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- first_by(by=None)[source]¶
Applies the
first_by()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
by (Union[str, Sequence[str]], optional) – the group-by column name(s), default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- group_by(by=None)[source]¶
Applies the
group_by()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
by (Union[str, Sequence[str]], optional) – the group-by column name(s), default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- head(num_rows)[source]¶
Applies the
head()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
num_rows (int) – the number of rows at the head of the constituent tables
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- property is_refreshing¶
Whether this proxy represents a refreshing partitioned table.
- j_object_type¶
alias of
io.deephaven.engine.table.PartitionedTable$Proxy
- join(table, on=None, joins=None)[source]¶
Applies the
join()table operation to all constituent tables of the underlying partitioned table with the provided right table or PartitionedTableProxy, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.In the case of the right table being another PartitionedTableProxy, the
join()table operation is applied to the matching pairs of the constituent tables from both underlying partitioned tables.- Parameters
table (Union[Table, PartitionedTableProxy]) – the right table or PartitionedTableProxy of the join
on (Union[str, Sequence[str]]) – the column(s) to match, can be a common name or an equal expression, i.e. “col_a = col_b” for different column names; default is None
joins (Union[str, Sequence[str]], optional) – the column(s) to be added from the right table to the result table, can be renaming expressions, i.e. “new_col = col”; default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- last_by(by=None)[source]¶
Applies the
last_by()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
by (Union[str, Sequence[str]], optional) – the group-by column name(s), default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- max_by(by=None)[source]¶
Applies the
max_by()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
by (Union[str, Sequence[str]], optional) – the group-by column name(s), default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- median_by(by=None)[source]¶
Applies the
median_by()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
by (Union[str, Sequence[str]], optional) – the group-by column name(s), default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- min_by(by=None)[source]¶
Applies the
min_by()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
by (Union[str, Sequence[str]], optional) – the group-by column name(s), default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- natural_join(table, on, joins=None)[source]¶
Applies the
natural_join()table operation to all constituent tables of the underlying partitioned table with the provided right table or PartitionedTableProxy, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.In the case of the right table being another PartitionedTableProxy, the
natural_join()table operation is applied to the matching pairs of the constituent tables from both underlying partitioned tables.- Parameters
table (Union[Table, PartitionedTableProxy]) – the right table or PartitionedTableProxy of the join
on (Union[str, Sequence[str]]) – the column(s) to match, can be a common name or an equal expression, i.e. “col_a = col_b” for different column names
joins (Union[str, Sequence[str]], optional) – the column(s) to be added from the right table to the result table, can be renaming expressions, i.e. “new_col = col”; default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- raj(table, on, joins=None, match_rule=AsOfMatchRule.GREATER_THAN_EQUAL)[source]¶
Applies the
raj()table operation to all constituent tables of the underlying partitioned table with the provided right table or PartitionedTableProxy, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.In the case of the right table being another PartitionedTableProxy, the
raj()table operation is applied to the matching pairs of the constituent tables from both underlying partitioned tables.- Parameters
table (Union[Table, PartitionedTableProxy]) – the right table or PartitionedTableProxy of the join
on (Union[str, Sequence[str]]) – the column(s) to match, can be a common name or an equal expression, i.e. “col_a = col_b” for different column names
joins (Union[str, Sequence[str]], optional) – the column(s) to be added from the right table to the result table, can be renaming expressions, i.e. “new_col = col”; default is None
match_rule (AsOfMatchRule) – the inexact matching rule on the last column to match specified in ‘on’, default is AsOfMatchRule.GREATER_THAN_EQUAL. The other valid value is AsOfMatchRule.GREATER_THAN.
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- reverse()[source]¶
Applies the
reverse()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- select(formulas=None)[source]¶
Applies the
select()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
formulas (Union[str, Sequence[str]], optional) – the column formula(s), default is None
- Return type
- Returns
A new PartitionedTableProxy
- Raises
DHError –
- select_distinct(formulas=None)[source]¶
Applies the
select_distinct()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
formulas (Union[str, Sequence[str]], optional) – the column formula(s), default is None
- Return type
- Returns
A new PartitionedTableProxy
- Raises
DHError –
- snapshot(source_table, do_init=False, cols=None)[source]¶
Applies the
snapshot()table operation to all constituent tables of the underlying partitioned table with the provided source table or PartitionedTableProxy, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.In the case of source table being another PartitionedTableProxy, the
snapshot()table operation is applied to the matching pairs of the constituent tables from both underlying partitioned tables.Note, the constituent tables are often time tables that add new rows at a regular, user-defined interval.
- Parameters
source_table (Union[Table, PartitionedTableProxy]) – the table or PartitionedTableProxy to be snapshot
do_init (bool) – whether to snapshot when this method is initially called, default is False
cols (Union[str, List[str]]) – names of the columns of the constituent table to be included in the snapshot, default is None, meaning all the columns
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- sort(order_by, order=None)[source]¶
Applies the
sort()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
order_by (Union[str, Sequence[str]]) – the column(s) to be sorted on
order (Union[SortDirection, Sequence[SortDirection], optional) – the corresponding sort directions for each sort column, default is None, meaning ascending order for all the sort columns.
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- sort_descending(order_by)[source]¶
Applies the
sort_descending()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
order_by (Union[str, Sequence[str]]) – the column(s) to be sorted on
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- std_by(by=None)[source]¶
Applies the
std_by()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
by (Union[str, Sequence[str]], optional) – the group-by column name(s), default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- sum_by(by=None)[source]¶
Applies the
sum_by()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
by (Union[str, Sequence[str]], optional) – the group-by column name(s), default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- tail(num_rows)[source]¶
Applies the
tail()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
num_rows (int) – the number of rows at the end of the constituent tables
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- update(formulas)[source]¶
Applies the
update()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
formulas (Union[str, Sequence[str]]) – the column formula(s)
- Return type
- Returns
A new PartitionedTableProxy
- Raises
DHError –
- update_by(ops, by=None)[source]¶
Applies the
update_by()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
ops (Union[UpdateByOperation, List[UpdateByOperation]]) – the update-by operation definition(s)
by (Union[str, List[str]]) – the key column name(s) to group the rows of the table
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- update_view(formulas)[source]¶
Applies the
update_view()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
formulas (Union[str, Sequence[str]]) – the column formula(s)
- Return type
- Returns
A new PartitionedTableProxy
- Raises
DHError –
- var_by(by=None)[source]¶
Applies the
var_by()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
by (Union[str, Sequence[str]], optional) – the group-by column name(s), default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- view(formulas)[source]¶
Applies the
view()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
formulas (Union[str, Sequence[str]]) – the column formula(s)
- Return type
- Returns
A new PartitionedTableProxy
- Raises
DHError –
- weighted_avg_by(wcol, by=None)[source]¶
Applies the
weighted_avg_by()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
wcol (str) – the name of the weight column
by (Union[str, Sequence[str]], optional) – the group-by column name(s), default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- weighted_sum_by(wcol, by=None)[source]¶
Applies the
weighted_sum_by()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.- Parameters
wcol (str) – the name of the weight column
by (Union[str, Sequence[str]], optional) – the group-by column name(s), default is None
- Return type
- Returns
a new PartitionedTableProxy
- Raises
DHError –
- where(filters=None)[source]¶
Applies the
where()table operation to all constituent tables of the underlying partitioned table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.
- where_in(filter_table, cols)[source]¶
Applies the
where_in()table operation to all constituent tables of the underlying partitioned table with the provided filter table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.
- where_not_in(filter_table, cols)[source]¶
Applies the
where_not_in()table operation to all constituent tables of the underlying partitioned table with the provided filter table, and produces a new PartitionedTableProxy with the result tables as the constituents of its underlying partitioned table.
- class SortDirection(value)[source]¶
Bases:
enum.EnumAn enum defining the sorting orders.
- ASCENDING = 2¶
- DESCENDING = 1¶
- class Table(j_table)[source]¶
Bases:
deephaven._wrapper.JObjectWrapperA Table represents a Deephaven table. It allows applications to perform powerful Deephaven table operations.
Note: It should not be instantiated directly by user code. Tables are mostly created by factory methods, data ingestion operations, queries, aggregations, joins, etc.
- abs_sum_by(by=None)[source]¶
The abs_sum_by method creates a new table containing the absolute sum for each group.
- agg_all_by(agg, by=None)[source]¶
The agg_all_by method creates a new table containing grouping columns and grouped data. The resulting grouped data is defined by the aggregation specified.
Note, because agg_all_by applies the aggregation to all the columns of the table, it will ignore any column names specified for the aggregation.
- Parameters
agg (Aggregation) – the aggregation
by (Union[str, Sequence[str]], optional) – the group-by column name(s), default is None
- Return type
- Returns
a new table
- Raises
DHError –
- agg_by(aggs, by=None, preserve_empty=False, initial_groups=None)[source]¶
The agg_by method creates a new table containing grouping columns and grouped data. The resulting grouped data is defined by the aggregations specified.
- Parameters
aggs (Union[Aggregation, Sequence[Aggregation]]) – the aggregation(s)
by (Union[str, Sequence[str]]) – the group-by column name(s), if not provided, all rows from this table are grouped into a single group of rows before the aggregations are applied to the result, default is None.
preserve_empty (bool) – whether to keep result rows for groups that are initially empty or become empty as a result of updates. Each aggregation operator defines its own value for empty groups. Default is False.
initial_groups (Table) – a table whose distinct combinations of values for the group-by column(s) should be used to create an initial set of aggregation groups. All other columns are ignored. This is useful in combination with preserve_empty=True to ensure that particular groups appear in the result table, or with preserve_empty=False to control the encounter order for a collection of groups and thus their relative order in the result. Changes to this table are not expected or handled; if this table is a refreshing table, only its contents at instantiation time will be used. Default is None, the result will be the same as if a table is provided but no rows were supplied. When it is provided, the ‘by’ argument must be provided to explicitly specify the grouping columns.
- Return type
- Returns
a new table
- Raises
DHError –
- aj(table, on, joins=None, match_rule=AsOfMatchRule.LESS_THAN_EQUAL)[source]¶
The aj (as-of join) method creates a new table containing all of the rows and columns of the left table, plus additional columns containing data from the right table. For columns appended to the left table (joins), row values equal the row values from the right table where the keys from the left table most closely match the keys from the right table without going over. If there is no matching key in the right table, appended row values are NULL.
- Parameters
table (Table) – the right-table of the join
on (Union[str, Sequence[str]]) – the column(s) to match, can be a common name or an equal expression, i.e. “col_a = col_b” for different column names
joins (Union[str, Sequence[str]], optional) – the column(s) to be added from the right table to the result table, can be renaming expressions, i.e. “new_col = col”; default is None
match_rule (AsOfMatchRule) – the inexact matching rule on the last column to match specified in ‘on’, default is AsOfMatchRule.LESS_THAN_EQUAL. The other valid value is AsOfMatchRule.LESS_THAN.
- Return type
- Returns
a new table
- Raises
DHError –
- avg_by(by=None)[source]¶
The avg_by method creates a new table containing the average for each group.
- property columns¶
The column definitions of the table.
- count_by(col, by=None)[source]¶
The count_by method creates a new table containing the number of rows for each group.
- drop_columns(cols)[source]¶
The drop_columns method creates a new table with the same size as this table but omits any of specified columns.
- exact_join(table, on, joins=None)[source]¶
The exact_join method creates a new table containing all of the rows and columns of this table plus additional columns containing data from the right table. For columns appended to the left table (joins), row values equal the row values from the right table where the key values in the left and right tables are equal.
- Parameters
table (Table) – the right-table of the join
on (Union[str, Sequence[str]]) – the column(s) to match, can be a common name or an equal expression, i.e. “col_a = col_b” for different column names
joins (Union[str, Sequence[str]], optional) – the column(s) to be added from the right table to the result table, can be renaming expressions, i.e. “new_col = col”; default is None
- Return type
- Returns
a new table
- Raises
DHError –
- first_by(by=None)[source]¶
The first_by method creates a new table containing the first row for each group.
- format_column_where(col, cond, formula)[source]¶
Applies color formatting to a column of the table conditionally.
- Parameters
col (str) – the column name
cond (str) – the condition expression
formula (str) – the formatting string in the form of assignment expression “column=color expression” where color_expression can be a color name or a Java ternary expression that results in a color.
- Return type
- Returns
a new table
- Raises
DHError –
- format_row_where(cond, formula)[source]¶
Applies color formatting to rows of the table conditionally.
- Parameters
cond (str) – the condition expression
formula (str) – the formatting string in the form of assignment expression “column=color expression” where color_expression can be a color name or a Java ternary expression that results in a color.
- Return type
- Returns
a new table
- Raises
DHError –
- group_by(by=None)[source]¶
The group_by method creates a new table containing grouping columns and grouped data, column content is grouped into arrays.
- head(num_rows)[source]¶
The head method creates a new table with a specific number of rows from the beginning of the table.
- head_by(num_rows, by=None)[source]¶
The head_by method creates a new table containing the first number of rows for each group.
- head_pct(pct)[source]¶
The head_pct method creates a new table with a specific percentage of rows from the beginning of the table.
- property is_refreshing¶
Whether this table is refreshing.
- j_object_type¶
alias of
io.deephaven.engine.table.Table
- join(table, on=None, joins=None)[source]¶
The join method creates a new table containing rows that have matching values in both tables. Rows that do not have matching criteria will not be included in the result. If there are multiple matches between a row from the left table and rows from the right table, all matching combinations will be included. If no columns to match (on) are specified, every combination of left and right table rows is included.
- Parameters
table (Table) – the right-table of the join
on (Union[str, Sequence[str]]) – the column(s) to match, can be a common name or an equal expression, i.e. “col_a = col_b” for different column names; default is None
joins (Union[str, Sequence[str]], optional) – the column(s) to be added from the right table to the result table, can be renaming expressions, i.e. “new_col = col”; default is None
- Return type
- Returns
a new table
- Raises
DHError –
- last_by(by=None)[source]¶
The last_by method creates a new table containing the last row for each group.
- layout_hints(front=None, back=None, freeze=None, hide=None, column_groups=None)[source]¶
Sets layout hints on the Table
- Parameters
front (Union[str, List[str]]) – the columns to show at the front.
back (Union[str, List[str]]) – the columns to show at the back.
freeze (Union[str, List[str]]) – the columns to freeze to the front. These will not be affected by horizontal scrolling.
hide (Union[str, List[str]]) – the columns to hide.
column_groups (List[Dict]) –
A list of dicts specifying which columns should be grouped in the UI The dicts can specify the following:
name (str): The group name children (List[str]): The color (Optional[str]): The hex color string or Deephaven color name
- Return type
- Returns
a new table with the layout hints set
- Raises
DHError –
- lazy_update(formulas)[source]¶
The lazy_update method creates a new table containing a new, cached, formula column for each formula.
- max_by(by=None)[source]¶
The max_by method creates a new table containing the maximum value for each group.
- median_by(by=None)[source]¶
The median_by method creates a new table containing the median for each group.
- property meta_table¶
The column definitions of the table in a Table form.
- min_by(by=None)[source]¶
The min_by method creates a new table containing the minimum value for each group.
- move_columns(idx, cols)[source]¶
The move_columns method creates a new table with specified columns moved to a specific column index value.
- move_columns_down(cols)[source]¶
The move_columns_down method creates a new table with specified columns appearing last in order, to the far right.
- move_columns_up(cols)[source]¶
The move_columns_up method creates a new table with specified columns appearing first in order, to the far left.
- natural_join(table, on, joins=None)[source]¶
The natural_join method creates a new table containing all of the rows and columns of this table, plus additional columns containing data from the right table. For columns appended to the left table (joins), row values equal the row values from the right table where the key values in the left and right tables are equal. If there is no matching key in the right table, appended row values are NULL.
- Parameters
table (Table) – the right-table of the join
on (Union[str, Sequence[str]]) – the column(s) to match, can be a common name or an equal expression, i.e. “col_a = col_b” for different column names
joins (Union[str, Sequence[str]], optional) – the column(s) to be added from the right table to the result table, can be renaming expressions, i.e. “new_col = col”; default is None
- Return type
- Returns
a new table
- Raises
DHError –
- partition_by(by, drop_keys=False)[source]¶
Creates a PartitionedTable from this table, partitioned according to the specified key columns.
- Parameters
by (Union[str, Sequence[str]]) – the column(s) by which to group data
drop_keys (bool) – whether to drop key columns in the constituent tables, default is False
- Return type
- Returns
A PartitionedTable containing a sub-table for each group
- Raises
DHError –
- partitioned_agg_by(aggs, by=None, preserve_empty=False, initial_groups=None)[source]¶
The partitioned_agg_by method is a convenience method that performs an agg_by operation on this table and wraps the result in a PartitionedTable. If the argument ‘aggs’ does not include a partition aggregation created by calling
agg.partition(), one will be added automatically with the default constituent column name __CONSTITUENT__.- Parameters
aggs (Union[Aggregation, Sequence[Aggregation]]) – the aggregation(s)
by (Union[str, Sequence[str]]) – the group-by column name(s), default is None
preserve_empty (bool) – whether to keep result rows for groups that are initially empty or become empty as a result of updates. Each aggregation operator defines its own value for empty groups. Default is False.
initial_groups (Table) – a table whose distinct combinations of values for the group-by column(s) should be used to create an initial set of aggregation groups. All other columns are ignored. This is useful in combination with preserve_empty=True to ensure that particular groups appear in the result table, or with preserve_empty=False to control the encounter order for a collection of groups and thus their relative order in the result. Changes to this table are not expected or handled; if this table is a refreshing table, only its contents at instantiation time will be used. Default is None, the result will be the same as if a table is provided but no rows were supplied. When it is provided, the ‘by’ argument must be provided to explicitly specify the grouping columns.
- Return type
- Returns
a PartitionedTable
- Raises
DHError –
- raj(table, on, joins=None, match_rule=AsOfMatchRule.GREATER_THAN_EQUAL)[source]¶
The reverse-as-of join method creates a new table containing all of the rows and columns of the left table, plus additional columns containing data from the right table. For columns appended to the left table (joins), row values equal the row values from the right table where the keys from the left table most closely match the keys from the right table without going under. If there is no matching key in the right table, appended row values are NULL.
- Parameters
table (Table) – the right-table of the join
on (Union[str, Sequence[str]]) – the column(s) to match, can be a common name or an equal expression, i.e. “col_a = col_b” for different column names
joins (Union[str, Sequence[str]], optional) – the column(s) to be added from the right table to the result table, can be renaming expressions, i.e. “new_col = col”; default is None
match_rule (AsOfMatchRule) – the inexact matching rule on the last column to match specified in ‘on’, default is AsOfMatchRule.GREATER_THAN_EQUAL. The other valid value is AsOfMatchRule.GREATER_THAN.
- Return type
- Returns
a new table
- Raises
DHError –
- rename_columns(cols)[source]¶
The rename_columns method creates a new table with the specified columns renamed.
- restrict_sort_to(cols)[source]¶
The restrict_sort_to method only allows sorting on specified table columns. This can be useful to prevent users from accidentally performing expensive sort operations as they interact with tables in the UI.
- Parameters
cols (Union[str, Sequence[str]]) – the column name(s)
- Raises
DHError –
- reverse()[source]¶
The reverse method creates a new table with all of the rows from this table in reverse order.
- select(formulas=None)[source]¶
The select method creates a new in-memory table that includes one column for each formula. If no formula is specified, all columns will be included.
- select_distinct(formulas=None)[source]¶
The select_distinct method creates a new table containing all of the unique values for a set of key columns. When the selectDistinct method is used on multiple columns, it looks for distinct sets of values in the selected columns.
- property size¶
The current number of rows in the table.
- snapshot(source_table, do_init=False, cols=None)[source]¶
Produces an in-memory copy of a source table that refreshes when this table changes.
Note, this table is often a time table that adds new rows at a regular, user-defined interval.
- Parameters
source_table (Table) – the table to be snapshot
do_init (bool) – whether to snapshot when this method is initially called, default is False
cols (Union[str, List[str]]) – names of the columns of this table to be included in the snapshot, default is None, meaning all the columns
- Return type
- Returns
a new table
- Raises
DHError –
- snapshot_history(source_table)[source]¶
Produces an in-memory history of a source table that adds a new snapshot when this table (trigger table) changes.
The trigger table is often a time table that adds new rows at a regular, user-defined interval.
Columns from the trigger table appear in the result table. If the trigger and source tables have columns with the same name, an error will be raised. To avoid this problem, rename conflicting columns.
Because snapshot_history stores a copy of the source table for every trigger event, large source tables or rapidly changing trigger tables can result in large memory usage.
- sort(order_by, order=None)[source]¶
The sort method creates a new table where the rows are ordered based on values in a specified set of columns.
- Parameters
order_by (Union[str, Sequence[str]]) – the column(s) to be sorted on
order (Union[SortDirection, Sequence[SortDirection], optional) – the corresponding sort directions for each sort column, default is None, meaning ascending order for all the sort columns.
- Return type
- Returns
a new table
- Raises
DHError –
- sort_descending(order_by)[source]¶
The sort_descending method creates a new table where rows in a table are sorted in a largest to smallest order based on the order_by column(s).
- std_by(by=None)[source]¶
The std_by method creates a new table containing the standard deviation for each group.
- tail(num_rows)[source]¶
The tail method creates a new table with a specific number of rows from the end of the table.
- tail_by(num_rows, by=None)[source]¶
The tail_by method creates a new table containing the last number of rows for each group.
- tail_pct(pct)[source]¶
The tail_pct method creates a new table with a specific percentage of rows from the end of the table.
- to_string(num_rows=10, cols=None)[source]¶
Returns the first few rows of a table as a pipe-delimited string.
- Parameters
num_rows (int) – the number of rows at the beginning of the table
cols (Union[str, Sequence[str]]) – the column name(s), default is None
- Return type
str- Returns
string
- Raises
DHError –
- ungroup(cols=None)[source]¶
The ungroup method creates a new table in which array columns from the source table are unwrapped into separate rows.
- update(formulas)[source]¶
The update method creates a new table containing a new, in-memory column for each formula.
- update_by(ops, by=None)[source]¶
Creates a table with additional columns calculated from window-based aggregations of columns in this table. The aggregations are defined by the provided operations, which support incremental aggregations over the corresponding rows in the this table. The aggregations will apply position or time-based windowing and compute the results over the entire table or each row group as identified by the provided key columns.
- Parameters
ops (Union[UpdateByOperation, List[UpdateByOperation]]) – the update-by operation definition(s)
by (Union[str, List[str]]) – the key column name(s) to group the rows of the table
- Return type
- Returns
a new Table
- Raises
DHError –
- update_view(formulas)[source]¶
The update_view method creates a new table containing a new, formula column for each formula.
- var_by(by=None)[source]¶
The var_by method creates a new table containing the variance for each group.
- view(formulas)[source]¶
The view method creates a new formula table that includes one column for each formula.
- weighted_avg_by(wcol, by=None)[source]¶
The weighted_avg_by method creates a new table containing the weighted average for each group.
- weighted_sum_by(wcol, by=None)[source]¶
The weighted_sum_by method creates a new table containing the weighted sum for each group.
- where(filters=None)[source]¶
The where method creates a new table with only the rows meeting the filter criteria in the column(s) of the table.
- where_in(filter_table, cols)[source]¶
The where_in method creates a new table containing rows from the source table, where the rows match values in the filter table. The filter is updated whenever either table changes.
- where_not_in(filter_table, cols)[source]¶
The where_not_in method creates a new table containing rows from the source table, where the rows do not match values in the filter table.