Package io.deephaven.engine.table.impl.util

Class KeyedTranspose

java.lang.Object
io.deephaven.engine.table.impl.util.KeyedTranspose
public class KeyedTranspose extends Object
Convert column values into column names for aggregated columns. This works similarly to a pivot table, except that it has no depth and is instead flattened into a single Deephaven table. This table is then suitable for downstream operations like any other table.

The keyedTranspose operation takes a source table with a set of aggregations and produces a new table where the columns specified in rowByColumns are the keys used for the aggregation, and the values for the columns specified in columnByColumns are used for the column names. An optional set of initialGroups can be provided to ensure that the output table contains the full set of aggregated columns, even if no data is present yet in the source table.

For example, given the following source table... 

       Date|     Level
 ----------+----------
 2025-08-05|INFO
 2025-08-05|INFO
 2025-08-06|WARN
 2025-08-07|ERROR
... and the usage ... 
 Table t = keyedTranspose(source, List.of(AggCount("Count")), new String[] {"Date"}, new String[] {"Level"});
The expected output for table "t" is ... 
       Date|                INFO|                WARN|               ERROR
 ----------+--------------------+--------------------+--------------------
 2025-08-05|                   2|(null)              |(null)
 2025-08-06|(null)              |                   1|(null)
 2025-08-07|(null)              |(null)              |                   1

In the example, you can see that the column names (e.g. INFO, WARN, ERROR) are taken from the values occurring for Level. But what if there are multiple aggregations or multiple columnByColumns specified? The resulting column names may yield duplicates. To avoid conflicts, the column naming works according to the following contract:

  • If aggregations = 1 and columnByColumns = 1: Column names are the value of the columnByColumns column. (ex. INFO, WARN)
  • If aggregations > 1: Column names are prefixed with the aggregation column name. (ex. Count_INFO, MySum_INFO)
  • If columnByColumns > 1: Values for the original columns are separated by an underscore (ex. INFO_OTHER1, WARN_OTHER2)
  • If Illegal Characters: Purge characters that are invalid for Deephaven column names. (ex. "1-2.3/4" becomes "1234")
  • If Starts with Number: Add the prefix "column_" to the column name. (ex. column_123)
  • If Duplicate Column Name: Add a suffix to differentiate the columns. (ex. INFO, INFO2)
Given the above contract, and to give you more control over the result, it may be necessary to sanitize data values that may be used as column names before using {code keyedTranspose}. Otherwise, "12.34" could be translated to "column_1234" instead of a more meaningful column name.

  • Constructor Details

    • KeyedTranspose

      public KeyedTranspose()

  • Method Details

    • keyedTranspose

      public static Table keyedTranspose(Table source, Collection<? extends Aggregation> aggregations, Collection<? extends ColumnName> rowByColumns, Collection<? extends ColumnName> columnByColumns)
      Transpose the source table using the specified aggregations, row and column keys.

      If a new column is detected, then the result table produces an error.

      Parameters:
      source - The source table to transpose.
      aggregations - The aggregations to apply to the source table.
      rowByColumns - The columns to use as row keys in the transposed table.
      columnByColumns - The columns whose values become the new aggregated columns.
      Returns:
      A new transposed table with the specified aggregations applied.

    • keyedTranspose

      public static Table keyedTranspose(Table source, Collection<? extends Aggregation> aggregations, Collection<? extends ColumnName> rowByColumns, Collection<? extends ColumnName> columnByColumns, Table initialGroups)
      Transpose the source table using the specified aggregations, row and column keys, and an initial set of groups.

      If a new column is detected, then the result table produces an error.

      Parameters:
      source - The source table to transpose.
      aggregations - The aggregations to apply to the source table.
      rowByColumns - The columns to use as row keys in the transposed table.
      columnByColumns - The columns whose values become the new aggregated columns.
      initialGroups - An optional initial set of groups to ensure all columns are present in the output.

    • keyedTranspose

      public static Table keyedTranspose(Table source, Collection<? extends Aggregation> aggregations, Collection<? extends ColumnName> rowByColumns, Collection<? extends ColumnName> columnByColumns, Table initialGroups, KeyedTranspose.NewColumnBehavior newColumnBehavior)
      Transpose the source table using the specified aggregations, row and column keys, and an initial set of groups.
      Parameters:
      source - The source table to transpose.
      aggregations - The aggregations to apply to the source table.
      rowByColumns - The columns to use as row keys in the transposed table.
      columnByColumns - The columns whose values become the new aggregated columns.
      initialGroups - An optional initial set of groups to ensure all columns are present in the output.
      newColumnBehavior - The behavior when a new column would be added