deephaven_enterprise.pivot.client.pivot_client

Pivot table client implementation for Deephaven Enterprise.

This module provides classes and functionality for creating and managing pivot tables over gRPC.

The PivotClient creates new PivotTables from your pydeephaven.session. Once you have a PivotTable, you can apply changes or call PivotTable.view() to create a PivotTableSubscription. The subscription provides a PivotSnapshot of your viewport on each change, via a PivotListener passed to PivotTableSubscription.listen() method.

Alternatively, call PivotTable.snapshot() to obtain a single PivotSnapshot without establishing a subscription.

Module Contents

class PivotClient(session, plugin_name=None, ticket=None)

Client interface for creating pivot tables in Deephaven Enterprise.

session

The Deephaven Session this client is attached to.

plugin_client

Plugin client for pivot table operations.

Initialize a new PivotClient.

Parameters:

• session (pydeephaven.Session) – Deephaven Session to use for operations.

• plugin_name – Optional name of the plugin to use (scope variable).

• ticket – Optional ticket for the plugin.

Raises:

RuntimeError – If plugin_client initialization fails.

create_pivot(row_by_keys, col_by_keys, aggs, source_table)

Create a new pivot table.

Parameters:

• row_by_keys – Keys to group rows by.

• col_by_keys – Keys to group columns by.

• aggs – Aggregations to perform.

• source_table – Source table to pivot.

Returns:

A new pivot table instance.

Return type:

PivotTable

class PivotListener

Bases: abc.ABC

Abstract base class for pivot table snapshot listeners.

Implement this class to receive a notification on each new pivot table snapshot. Listeners must be registered with a call to PivotTableSubscription.listen(); and may be removed with a call to PivotTableSubscription.remove_listener().

abstractmethod on_complete(error)

Called when the listener will receive no further updates from this subscription. If an error occurred, then error is populated, otherwise None.

Parameters:

error (Optional[Exception])

abstractmethod on_snapshot(snap)

Called when a new pivot table snapshot is available.

Parameters:

snap (PivotSnapshot) – New PivotSnapshot.

class PivotSnapshot(batch, md_bytes)

A snapshot of pivot table data including row/column information and values.

This class encapsulates all the data for a specific state of a pivot table, including row and column metadata, values, and viewport information.

Initialize a new PivotSnapshot.

Parameters:

• batch (pyarrow.RecordBatch) – PyArrow RecordBatch containing the pivot table data.

• md_bytes (bytes) – Metadata bytes containing viewport information.

Raises:

DHError – If required pivot table schema columns are missing or invalid.

batch()

Get the raw PyArrow RecordBatch.

Returns:

The raw RecordBatch containing the data.

Return type:

pyarrow.RecordBatch

col_depths()

Get the column depths as a PyArrow Array.

Returns:

Array of column depths.

Return type:

pyarrow.Array

col_expanded()

Get the column expanded states as a PyArrow Array.

Returns:

Array of column expanded states.

Return type:

pyarrow.Array

column_keys()

Get the column keys as a PyArrow Table.

Returns:

Table containing the column keys.

Return type:

pyarrow.Table

column_totals()

Get the column totals as a PyArrow Table.

Returns:

Table containing the column totals.

Return type:

pyarrow.Table

grand_totals()

Get the grand totals as a PyArrow Table.

Returns:

Table containing the grand total values.

Return type:

pyarrow.Table

row_depths()

Get the row depths as a PyArrow Array.

Returns:

Array of row depths.

Return type:

pyarrow.Array

row_expanded()

Get the row expanded states as a PyArrow Array.

Returns:

Array of row expanded states.

Return type:

pyarrow.Array

row_keys()

Get the row keys as a PyArrow Table.

Returns:

Table containing the row keys.

Return type:

pyarrow.Table

row_totals()

Get the row totals as a PyArrow Table.

Returns:

Table containing the row totals.

Return type:

pyarrow.Table

values()

Get the field of values as a PyArrow Table.

Each value is stored in column major order and forms a grid of num_visible_rows() by num_visible_cols() values.

Returns:

Table containing the values.

Return type:

pyarrow.Table

property column_key_names: list[str]

Get the names of the column key columns.

Returns:

List of column key column names.

Return type:

list[str]

property num_columns: int

Get the number of visible columns in the pivot table.

Returns:

Number of visible columns.

Return type:

int

property num_rows: int

Get the number of visible rows in the pivot table.

Returns:

Number of visible rows.

Return type:

int

property num_values: int

Get the number of value columns in the pivot table.

The row, column, and grand totals have the same counts and names.

Returns:

Number of value columns.

Return type:

int

property row_key_names: list[str]

Get the names of the row key columns.

Returns:

List of row key column names.

Return type:

list[str]

property total_col_count: int

Get the total number of columnsin the pivot table given the current expansions.

The number of visible columns may be less than this value, based on the column viewport. If the columns were fully expanded, then there may be more columns.

Returns:

Total number columns given the current expansions.

Return type:

int

property total_row_count: int

Get the total number of rows in the pivot table given the current expansions.

The number of visible rows may be less than this value, based on the row viewport. If the rows were fully expanded, then there may be more rows.

Returns:

Total number of rows given the current expansions.

Return type:

int

property value_names: list[str]

Get the names of the value columns.

The row, column, and grand totals have the same counts and names.

Returns:

List of value column names.

Return type:

list[str]

class PivotTable(server_object, descriptor, pivot_client)

Represents a pivot table.

Provides interface for applying operations to pivot tables and creating subscriptions for snapshots.

Initialize a new pivot table.

Parameters:

• server_object (pydeephaven.ticket.ServerObject) – Server-side pivot table object.

• descriptor (deephaven_enterprise.proto.pivot.pivottable_pb2.PivotTableDescriptorMessage) – Descriptor message containing table information.

• pivot_client (PivotClient) – Associated PivotClient instance.

apply(row_sorts, col_sorts, filters)

Apply sorting and filtering operations to the pivot table.

Parameters:

• row_sorts (list[str]) – List of row sort expressions.

• col_sorts (list[str]) – List of column sort expressions.

• filters (list[str]) – List of filter expressions.

Returns:

New pivot table with applied operations.

Return type:

PivotTable

empty_expansions()

Get empty expansion tables for rows and columns.

This table can be used as a prototype for the row and expansion tables for the :method:`view` method.

Returns:

(row_expansions, col_expansions) tables.

Return type:

tuple

outputs()

Get the list of output column names.

Returns:

List of output column names.

Return type:

list[str]

refreshing()

Check if this pivot table is refreshing.

Returns:

True if the table is refreshing, False if static.

Return type:

bool

snapshot(outputs=None, row_expansions=None, col_expansions=None, rows=None, columns=None)

Take a single snapshot of the pivot table.

This method takes the same arguments as view(), but instead of establishing a subscription it returns a single PivotSnapshot.

Parameters:

• outputs (Optional[list[str]]) – Optional list of output columns to include.

• row_expansions (Optional[pydeephaven.Table]) – Optional table of row expansion states.

• col_expansions (Optional[pydeephaven.Table]) – Optional table of column expansion states.

• rows (Optional[tuple[int, int]]) – Optional tuple of (start, end) for row viewport.

• columns (Optional[tuple[int, int]]) – Optional tuple of (start, end) for column viewport.

Returns:

A snapshot of the pivot table data.

Return type:

PivotSnapshot

view(outputs=None, row_expansions=None, col_expansions=None, initial_rows=None, initial_cols=None)

Create a subscription view of the pivot table.

Parameters:

• outputs (Optional[list[str]]) – Optional list of output columns to include.

• row_expansions (Optional[pydeephaven.Table]) – Optional table of row expansion states.

• col_expansions (Optional[pydeephaven.Table]) – Optional table of column expansion states.

• initial_rows (Optional[tuple[int, int]]) – Optional tuple of (start, end) for initial row viewport.

• initial_cols (Optional[tuple[int, int]]) – Optional tuple of (start, end) for initial column viewport.

Returns:

New subscription to pivot table updates.

Return type:

PivotTableSubscription

class PivotTableSubscription(session, server_object, row_expansions, col_expansions, initial_rows=None, initial_cols=None)

Manages a subscription to pivot table snapshots.

Handles the communication channel for receiving pivot table updates and manages listeners for update notifications.

Initialize a new pivot table subscription.

Parameters:

• session (pydeephaven.Session) – Deephaven session.

• server_object (pydeephaven.ticket.ServerObject) – Server-side pivot table object.

• row_expansions (pydeephaven.Table) – Table containing row expansion states.

• col_expansions (pydeephaven.Table) – Table containing column expansion states.

• initial_rows (Optional[tuple[int, int]]) – Optional tuple of (start, end) for initial row viewport.

• initial_cols (Optional[tuple[int, int]]) – Optional tuple of (start, end) for initial column viewport.

add_listener(listener)

Register a new pivot table snapshot listener.

If the subscription has already been completed, then an exception is raised.

The listener is called once with the most recent snapshot state (if available).

If a listener raises an Exception while processing the initial PivotSnapshot in the :method:`on_snapshot` method, then the Listener is not added, and the Exception is re-raised.

After the initial PivotSnapshot, if a listener’s on_complete method raises an Exception, the exception is ignored. If a listener’s on_snapshot method raises an Exception, then the on_complete method is called and the subscription is closed.

Parameters:

listener (PivotListener) – PivotListener instance to register.

close()

Close the subscription and receive no further updates.

col_expansions()

Get the table of column expansion states.

If the column expansion table is an input table, then any modifications are reflected in the snapshots for this subscription.

Returns:

Table containing column expansion states.

Return type:

pydeephaven.Table

remove_listener(listener)

Remove a registered pivot table snapshot listener.

Parameters:

listener (PivotListener) – PivotListener instance to remove.

row_expansions()

Get the table of row expansion states.

If the row expansion table is an input table, then any modifications are reflected in the snapshots for this subscription.

Returns:

Table containing row expansion states.

Return type:

pydeephaven.Table

set_viewport(rows, cols)

Update the viewport for rows and columns.

Note that totals are always sent, so the row and columns viewports only account for the field of values. Additionally, the column viewport represents the number of column keys that are visible. When multiple values are requested, you may choose to display those values in distinct columns (as is done in the :method:`deephaven_enterprise.pivot.client.formatter.format_grid` method), and your column viewport must be adjusted accordingly.

Parameters:

• rows (tuple[int, int]) – Tuple of (start, end) for row viewport.

• cols (tuple[int, int]) – Tuple of (start, end) for column viewport.

fetch(session, server_object)

Fetch a PivotTable.

The ServerObject must refer to a server-side Pivot table, and the session must correspond to the ServerObject.

If the object is not a pivot table or the ticket is otherwise invalid, then a DHError or gRPC exception is raised.

Parameters:

• session (pydeephaven.Session) – Deephaven Session that corresponds to the ServerObject.

• server_object (pydeephaven.ticket.ServerObject) – Server object representing the PivotTable.

Returns:

A new PivotTable instance from the provided Session and ServerObject.

Return type:

PivotTable