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.

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

Bases: object

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 (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

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().

abstract 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.

abstract on_snapshot(snap)

Called when a new pivot table snapshot is available.

Parameters:

snap (PivotSnapshot) – New PivotSnapshot.

class PivotSnapshot(batch, md_bytes)

Bases: object

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 (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

property column_key_names

Get the names of the column key columns.

Returns:

List of column key column names.

Return type:

list[str]

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

property num_columns

Get the number of visible columns in the pivot table.

Returns:

Number of visible columns.

Return type:

int

property num_rows

Get the number of visible rows in the pivot table.

Returns:

Number of visible rows.

Return type:

int

property num_values

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

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

property row_key_names

Get the names of the row key columns.

Returns:

List of row key column names.

Return type:

list[str]

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

property total_col_count

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

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

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]

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

class PivotTable(server_object, descriptor, pivot_client)

Bases: object

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 (ServerObject) – Server-side pivot table object.

• descriptor (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

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 of output columns to include.

• row_expansions – Optional table of row expansion states.

• col_expansions – Optional table of column expansion states.

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

• initial_cols – 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)

Bases: object

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 – Deephaven session.

• server_object – Server-side pivot table object.

• row_expansions – Table containing row expansion states.

• col_expansions – Table containing column expansion states.

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

• initial_cols – 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 of (start, end) for row viewport.

• cols – 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 (Session) – Deephaven Session that corresponds to the ServerObject.

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

Returns:

A new PivotTable instance from the provided Session and ServerObject.

Return type:

PivotTable