Package io.deephaven.pivot

Interface PivotTable

All Superinterfaces:
AttributeMap<PivotTable>, LivenessReferent
public interface PivotTable extends AttributeMap<PivotTable>, LivenessReferent
A pivot table is a display-only object that aggregates using a list of row by-columns and column by-columns, presenting the aggregated value for each combination of row and column by-column as a single cell.

Each row by-column or column by-column creates a level of aggregation that can be expanded or contracted, as in a rollup. For each logical combination of row and column values, multiple aggregation outputs are permitted.

The PivotTable may be filtered by row or column by-columns; and the rows or columns sorted by their by-columns.

A PivotTable is not a Table. It does not send updates or allow you to listen to changes. The mechanism to access data is the snapshot method.

  • Method Details

    • make

      @NotNull static @NotNull PivotTable make(Table source, Collection<Aggregation> aggregations, Collection<? extends ColumnName> rowByColumns, Collection<? extends ColumnName> columnByColumns)
      Create a new PivotTable.
      Parameters:
      source - the table to aggregate
      aggregations - the list of aggregations
      rowByColumns - the columns that serve as key columns for the row aggregations. Each unique value (and unique value prefix) creates another row in the output grid.
      columnByColumns - the columns that serve as key columns for the column aggregations. Each unique value (and unique value prefix) creates another (logical) column in the output grid.
      Returns:
      a new PivotTable

    • getSource

      Table getSource()
      Return the source used to generate this PivotTable.
      Returns:
      the source used to generate this PivotTable

    • getDescription

      String getDescription()
      Returns:
      a textual description of this PivotTable for use in performance logs

    • getRowTableDefinition

      @NotNull @NotNull TableDefinition getRowTableDefinition()
      Returns:
      the definition of the row portion of the snapshot

    • getRowStructuralColumns

      @NotNull @NotNull Collection<ColumnDefinition<?>> getRowStructuralColumns()
      Returns:
      the structural columns for the row key table
      See Also:

    • getColumnTableDefinition

      @NotNull @NotNull TableDefinition getColumnTableDefinition()
      Returns:
      the definition of the column portion of the snapshot

    • getColumnStructuralColumns

      @NotNull @NotNull Collection<ColumnDefinition<?>> getColumnStructuralColumns()
      Returns:
      the structural columns for the column key table
      See Also:

    • getValuesTableDefinition

      @NotNull @NotNull TableDefinition getValuesTableDefinition()
      Returns:
      the definition of the values portion of the snapshot

    • apply

      @NotNull @NotNull PivotTable apply(Collection<SortColumn> rowSorts, Collection<SortColumn> columnSorts, List<? extends Filter> filters)
      Apply transformations to this pivot.
      Parameters:
      rowSorts - the sorting columns for the rows in this pivot
      columnSorts - the sorting columns for the columns in this pivot
      filters - the filters for this pivot, only permitted for row and column keys
      Returns:
      a PivotTable with the operations applied

    • rebase

      @NotNull @NotNull PivotTable rebase(Table newSource)
      Create a new PivotTable based on newSource, inheriting this Pivot's aggregations, getRowByColumns() row by-columns, column by-columns, and applied operations (i.e. filters and sorts).
      Parameters:
      newSource - A new source table that must have the same definition as the source of this pivot; that is, newSource.getDefinition().equals(getSource().getDefinition()) must be true
      Returns:
      The new PivotTable

    • makeSnapshotState

      @NotNull @NotNull PivotTable.SnapshotState makeSnapshotState()
      Make a re-usable snapshot state. The result will ensure liveness for this PivotTable if the source isRefreshing, and callers must similarly retain the result for the duration of their usage under the same conditions.
      Returns:
      a SnapshotState for use with the snapshot(SnapshotState, Table, Table, ColumnName, ColumnName, Collection, RowSequence, RowSequence) method.

    • getRowExpandedColumn

      @NotNull @NotNull ColumnName getRowExpandedColumn()
      Get the name of a column of Booleans that denotes whether a row is expanded (or expandable). It takes on the value null for rows that are not expandable, false for expandable but unexpanded rows, and true for expanded rows. This column is "synthetic"; that is, it's not part of the data, but rather calculated as part of snapshotting.
      Returns:
      The name of a column that denotes whether a row is expanded or expandable

    • getRowDepthColumn

      @NotNull @NotNull ColumnName getRowDepthColumn()
      Get the name of a column that denotes row depth. This column is "synthetic"; that is, it's not part of the data, but rather calculated as part of snapshotting.
      Returns:
      The name of a column that denotes row depth

    • getColumnExpandedColumn

      @NotNull @NotNull ColumnName getColumnExpandedColumn()
      Get the name of a column of Booleans that denotes whether a column is expanded (or expandable). It takes on the value null for columns that are not expandable, false for expandable but unexpanded columns, and true for expanded columns. This column is "synthetic"; that is, it's not part of the data, but rather calculated as part of snapshotting.
      Returns:
      The name of a column that denotes whether a column is expanded or expandable

    • getColumnDepthColumn

      @NotNull @NotNull ColumnName getColumnDepthColumn()
      Get the name of a column that denotes column depth. This column is "synthetic"; that is, it's not part of the data, but rather calculated as part of snapshotting.
      Returns:
      The name of a column that denotes column depth

    • getAggregations

      @NotNull @NotNull Collection<Aggregation> getAggregations()
      Get the aggregations used to construct this PivotTable.
      Returns:
      the aggregations used to construct this PivotTable

    • getOutputColumns

      @NotNull @NotNull List<ColumnName> getOutputColumns()
      Get the column names of the aggregation outputs that are available for subscription.
      Returns:
      the column names that are available as aggregation outputs

    • getRowByColumns

      @NotNull @NotNull Collection<? extends ColumnName> getRowByColumns()
      Get the row keys used to create this Pivot.
      Returns:
      the row keys used to create this Pivot

    • getColumnByColumns

      @NotNull @NotNull Collection<? extends ColumnName> getColumnByColumns()
      Get the column keys used to create this Pivot.
      Returns:
      the columns keys used to create this Pivot

    • getEmptyRowExpansionsTable

      @NotNull @NotNull Table getEmptyRowExpansionsTable()
      Get a re-usable, static key Table with zero rows that will cause a snapshot to expand only the default nodes in the row dimension.
      Returns:
      An empty key Table for default row expansions

    • getEmptyColumnExpansionsTable

      @NotNull @NotNull Table getEmptyColumnExpansionsTable()
      Get a re-usable, static key Table with zero rows that will cause a snapshot to expand only the default nodes in the column dimension.
      Returns:
      An empty key Table for default column expansions

    • getRowSortableColumns

      @Nullable @Nullable Set<String> getRowSortableColumns()
      The set of column names that can be row sorted.
      Returns:
      the set of column names that can be row sorted

    • getColumnSortableColumns

      @Nullable @Nullable Set<String> getColumnSortableColumns()
      The set of column names that can be column sorted.
      Returns:
      the set of column names that can be column sorted

    • snapshot

      @NotNull @NotNull PivotTable.PivotSnapshot snapshot(@NotNull @NotNull PivotTable.SnapshotState snapshotState, @NotNull @NotNull Table rowKeyTable, @NotNull @NotNull Table columnKeyTable, @Nullable @Nullable ColumnName rowKeyTableActionColumn, @Nullable @Nullable ColumnName columnKeyTableActionColumn, @Nullable @Nullable Collection<ColumnName> valueColumns, @NotNull @NotNull RowSequence rows, @NotNull @NotNull RowSequence columns)
      Generate a snapshot of this PivotTable.
      Parameters:
      snapshotState - the snapshot state, generated with makeSnapshotState()
      rowKeyTable - a table of row key values (corresponding to the row by-columns and other columns annotated with PivotTableSchemaConstants.PIVOT_TABLE_IS_ROW_EXPAND_BY_COLUMN) that should be expanded
      columnKeyTable - a table of column key values (corresponding to the column by-columns and other columns annotated with PivotTableSchemaConstants.PIVOT_TABLE_IS_COLUMN_EXPAND_BY_COLUMN) that should be expanded
      rowKeyTableActionColumn - the name of the action column in the rowKeyTable. If not present, the action is assumed to be HierarchicalTable.KEY_TABLE_ACTION_EXPAND
      columnKeyTableActionColumn - the name of the action column in the columnKeyTable. If not present, the action is assumed to be HierarchicalTable.KEY_TABLE_ACTION_EXPAND
      valueColumns - the names of the value columns to include in the snapshot
      rows - a row sequence of rows to include in the snapshot, must be contiguous or be row 0 (the totals row) and one more contiguous region.
      columns - a row sequence of columns to include in the snapshot, must be contiguous
      Returns:
      a snapshot of the current pivot table values