Package io.deephaven.engine.table.impl

Interface TableAdapter

All Superinterfaces:
AttributeMap<Table>, DynamicNode, GridAttributes<Table>, LivenessManager, LivenessNode, LivenessReferent, LogOutputAppendable, LongSizedDataStructure, NotificationQueue.Dependency, SystemicObject<Table>, Table, TableDefaults, TableOperations<Table,Table>, TableOperationsDefaults<Table,Table>
public interface TableAdapter extends TableDefaults
Adapter sub-interface of TableDefaults that allows implementors to selectively support an opt-in subset of the typical concrete methods for a Table implementation.

  • Method Details

    • append

      default LogOutput append(LogOutput logOutput)
      Specified by:
      append in interface LogOutputAppendable

    • size

      default long size()
      Description copied from interface: LongSizedDataStructure
      The size of this data structure.
      Specified by:
      size in interface LongSizedDataStructure
      Returns:
      The size

    • getDefinition

      default TableDefinition getDefinition()
      Specified by:
      getDefinition in interface Table

    • getDescription

      default String getDescription()
      Specified by:
      getDescription in interface Table

    • getUpdateGraph

      default UpdateGraph getUpdateGraph()
      Specified by:
      getUpdateGraph in interface NotificationQueue.Dependency
      Returns:
      the update graph that this dependency is a part of

    • isRefreshing

      default boolean isRefreshing()
      Description copied from interface: DynamicNode
      Is the node updating?
      Specified by:
      isRefreshing in interface DynamicNode
      Specified by:
      isRefreshing in interface Table
      Returns:
      true if the node is updating; false otherwise.

    • setRefreshing

      default boolean setRefreshing(boolean refreshing)
      Description copied from interface: DynamicNode
      Change the node's run mode.
      Specified by:
      setRefreshing in interface DynamicNode
      Parameters:
      refreshing - true to cause the node to update; false otherwise.
      Returns:
      new refreshing state

    • addParentReference

      default void addParentReference(Object parent)
      Description copied from interface: DynamicNode
      Called on a dependent node to ensure that a strong reference is maintained to any parent object that is required for the proper maintenance and functioning of the dependent. In the most common case, the parent object is a child listener to a parent node. The parent node only keeps a weak reference to its child listener, but the listener maintains a strong reference to the parent node. In this scenario, the only strong reference to the listener (and thus indirectly to the parent node itself) is the reference kept by the dependent node.
      Specified by:
      addParentReference in interface DynamicNode
      Parameters:
      parent - A parent of this node

    • getRowSet

      default TrackingRowSet getRowSet()
      Specified by:
      getRowSet in interface Table
      Returns:
      The TrackingRowSet that exposes the row keys present in this Table

    • isFlat

      default boolean isFlat()
      Description copied from interface: Table
      Return true if this table is guaranteed to be flat. The RowSet of a flat table will be from 0...numRows-1.
      Specified by:
      isFlat in interface Table

    • withAttributes

      default Table withAttributes(@NotNull @NotNull Map<String,Object> toAdd, @NotNull @NotNull Collection<String> toRemove)
      Description copied from interface: AttributeMap
      Get an AttributeMap that is the same as this, but with the specified attributes added/replaced or removed. If the supplied attributes toAdd and toRemove would not result in any changes to this, implementations may return this.
      Specified by:
      withAttributes in interface AttributeMap<Table>
      Parameters:
      toAdd - Attribute key-value pairs to add or replace (if the key already exists on this). Neither keys nor values may be null.
      toRemove - Attribute keys to remove
      Returns:
      The result AttributeMap

    • withAttributes

      default Table withAttributes(@NotNull @NotNull Map<String,Object> toAdd)
      Description copied from interface: AttributeMap
      Get an AttributeMap that is the same as this, but with the specified attributes added/replaced. If the supplied attributes toAdd would not result in any changes to this, implementations may return this.
      Specified by:
      withAttributes in interface AttributeMap<Table>
      Parameters:
      toAdd - Attribute key-value pairs to add or replace (if the key already exists on this)
      Returns:
      The result AttributeMap

    • withoutAttributes

      default Table withoutAttributes(@NotNull @NotNull Collection<String> toRemove)
      Description copied from interface: AttributeMap
      Get an AttributeMap that is the same as this, but with the specified attributes removed. If the supplied attributes toRemove would not result in any changes to this, implementations may return this.
      Specified by:
      withoutAttributes in interface AttributeMap<Table>
      Parameters:
      toRemove - Attribute keys to remove
      Returns:
      The result AttributeMap

    • retainingAttributes

      default Table retainingAttributes(@NotNull @NotNull Collection<String> toRetain)
      Description copied from interface: AttributeMap
      Get an AttributeMap that is the same as this, but with only the specified attributes retained. If the supplied attributes toAdd would not result in any changes to this, implementations may return this.
      Specified by:
      retainingAttributes in interface AttributeMap<Table>
      Parameters:
      toRetain - Attribute keys to retain
      Returns:
      The result AttributeMap

    • getAttribute

      @Nullable default @Nullable Object getAttribute(@NotNull @NotNull String key)
      Description copied from interface: AttributeMap
      Get the value for the specified attribute key.
      Specified by:
      getAttribute in interface AttributeMap<Table>
      Parameters:
      key - The name of the attribute
      Returns:
      The value, or null if there was none.

    • getAttributeKeys

      @NotNull default @NotNull Set<String> getAttributeKeys()
      Description copied from interface: AttributeMap
      Get an immutable set of all the attributes that have values in this AttributeMap.
      Specified by:
      getAttributeKeys in interface AttributeMap<Table>
      Returns:
      An immutable set of attribute keys (names)

    • hasAttribute

      default boolean hasAttribute(@NotNull @NotNull String name)
      Description copied from interface: AttributeMap
      Check if the specified attribute exists in this AttributeMap.
      Specified by:
      hasAttribute in interface AttributeMap<Table>
      Parameters:
      name - The key (name) of the attribute
      Returns:
      true if the attribute exists

    • getAttributes

      @NotNull default @NotNull Map<String,Object> getAttributes()
      Description copied from interface: AttributeMap
      Get all attributes in this AttributeMap.
      Specified by:
      getAttributes in interface AttributeMap<Table>
      Returns:
      An immutable map containing all attributes from this AttributeMap

    • getAttributes

      @NotNull default @NotNull Map<String,Object> getAttributes(@Nullable @Nullable Predicate<String> included)
      Description copied from interface: AttributeMap
      Get all attributes from this AttributeMap whose keys are accepted by included.
      Specified by:
      getAttributes in interface AttributeMap<Table>
      Parameters:
      included - A predicate to determine which attribute keys to include
      Returns:
      An immutable map containing AttributeMap's attributes whose keys are accepted by included

    • getColumnSource

      default <T> ColumnSource<T> getColumnSource(String sourceName)
      Description copied from interface: Table
      Retrieves a ColumnSource. It is conveniently cast to ColumnSource<Object> using the type that caller expects. This differs from Table.getColumnSource(String, Class) which uses the provided Class object to verify that the data type is a subclass of the expected class.

      The success of this call is equivalent to getDefinition().checkColumn(sourceName), which is the preferred way to check for compatibility in scenarios where the caller does not want the implementation to potentially invoke Table.coalesce().

      Specified by:
      getColumnSource in interface Table
      Type Parameters:
      T - The target type, as a type parameter. Inferred from context.
      Parameters:
      sourceName - The name of the column
      Returns:
      The column source for sourceName, parameterized by T
      See Also:

    • getColumnSourceMap

      default Map<String,? extends ColumnSource<?>> getColumnSourceMap()
      Specified by:
      getColumnSourceMap in interface Table

    • getColumnSources

      default Collection<? extends ColumnSource<?>> getColumnSources()
      Specified by:
      getColumnSources in interface Table

    • columnIterator

      default <DATA_TYPE> CloseableIterator<DATA_TYPE> columnIterator(@NotNull @NotNull String columnName)
      Specified by:
      columnIterator in interface Table

    • characterColumnIterator

      default CloseablePrimitiveIteratorOfChar characterColumnIterator(@NotNull @NotNull String columnName)
      Specified by:
      characterColumnIterator in interface Table

    • byteColumnIterator

      default CloseablePrimitiveIteratorOfByte byteColumnIterator(@NotNull @NotNull String columnName)
      Specified by:
      byteColumnIterator in interface Table

    • shortColumnIterator

      default CloseablePrimitiveIteratorOfShort shortColumnIterator(@NotNull @NotNull String columnName)
      Specified by:
      shortColumnIterator in interface Table

    • integerColumnIterator

      default CloseablePrimitiveIteratorOfInt integerColumnIterator(@NotNull @NotNull String columnName)
      Specified by:
      integerColumnIterator in interface Table

    • longColumnIterator

      default CloseablePrimitiveIteratorOfLong longColumnIterator(@NotNull @NotNull String columnName)
      Specified by:
      longColumnIterator in interface Table

    • floatColumnIterator

      default CloseablePrimitiveIteratorOfFloat floatColumnIterator(@NotNull @NotNull String columnName)
      Specified by:
      floatColumnIterator in interface Table

    • doubleColumnIterator

      default CloseablePrimitiveIteratorOfDouble doubleColumnIterator(@NotNull @NotNull String columnName)
      Specified by:
      doubleColumnIterator in interface Table

    • objectColumnIterator

      default <DATA_TYPE> CloseableIterator<DATA_TYPE> objectColumnIterator(@NotNull @NotNull String columnName)
      Specified by:
      objectColumnIterator in interface Table

    • objectColumnIterator

      default <DATA_TYPE> CloseableIterator<DATA_TYPE> objectColumnIterator(@NotNull @NotNull String columnName, @NotNull @NotNull Class<? extends DATA_TYPE> clazz)
      Specified by:
      objectColumnIterator in interface Table

    • wouldMatch

      default Table wouldMatch(WouldMatchPair... matchers)
      Description copied from interface: Table
      A table operation that applies the supplied predicate to each row in the table and produces columns containing the pass/fail result of the predicate application. This is similar to TableOperations.where(String...) except that instead of selecting only rows that meet the criteria, new columns are added with the result of the comparison.
      Specified by:
      wouldMatch in interface Table
      Returns:
      a table with new columns containing the filter result for each row.

    • dropColumns

      default Table dropColumns(String... columnNames)
      Description copied from interface: TableOperations
      Creates a new table without the columnNames from this.
      Specified by:
      dropColumns in interface TableOperations<Table,Table>
      Parameters:
      columnNames - the columns to drop
      Returns:
      the table

    • renameColumns

      default Table renameColumns(Collection<Pair> pairs)
      Description copied from interface: Table
      Produce a new table with the specified columns renamed using the specified pairs. The renames are simultaneous and unordered, enabling direct swaps between column names. The resulting table retains the original column ordering after applying the specified renames.

      NOTE: If a new column name conflicts with an existing column name in the table, the existing column will be silently replaced.

      IllegalArgumentException will be thrown:

      • if a source column does not exist
      • if a source column is used more than once
      • if a destination column is used more than once
      Specified by:
      renameColumns in interface Table
      Parameters:
      pairs - The columns to rename
      Returns:
      The new table, with the columns renamed

    • moveColumns

      default Table moveColumns(int index, String... columnsToMove)
      Description copied from interface: Table
      Produce a new table with the specified columns moved to the specified index. Column indices begin at 0. Columns can be renamed with the usual syntax, i.e. "NewColumnName=OldColumnName"). The renames are simultaneous and unordered, enabling direct swaps between column names. The resulting table retains the original column ordering except for the specified columns, which are inserted at the specified index, in the order of columnsToMove, after the effects of applying any renames.

      IllegalArgumentException will be thrown:

      • if a source column does not exist
      • if a source column is used more than once
      • if a destination column is used more than once

      Values of index outside the range of 0 to the number of columns in the table (exclusive) will be clamped to the nearest valid index.

      Specified by:
      moveColumns in interface Table
      Parameters:
      index - The index to which the specified columns should be moved
      columnsToMove - The columns to move to the specified index (and, optionally, to rename)
      Returns:
      The new table, with the columns rearranged as explained above

    • slice

      default Table slice(long firstPositionInclusive, long lastPositionExclusive)
      Description copied from interface: TableOperations
      Extracts a subset of a table by row position.

      If both firstPosition and lastPosition are positive, then the rows are counted from the beginning of the table. The firstPosition is inclusive, and the lastPosition is exclusive. The TableOperations.head(long)(N) call is equivalent to slice(0, N). The firstPosition must be less than or equal to the lastPosition.

      If firstPosition is positive and lastPosition is negative, then the firstRow is counted from the beginning of the table, inclusively. The lastPosition is counted from the end of the table. For example, slice(1, -1) includes all rows but the first and last. If the lastPosition would be before the firstRow, the result is an emptyTable.

      If firstPosition is negative, and lastPosition is zero, then the firstRow is counted from the end of the table, and the end of the slice is the size of the table. slice(-N, 0) is equivalent to TableOperations.tail(long)(N).

      If the firstPosition is negative and the lastPosition is negative, they are both counted from the end of the table. For example, slice(-2, -1) returns the second to last row of the table.

      If firstPosition is negative and lastPosition is positive, then firstPosition is counted from the end of the table, inclusively. The lastPosition is counted from the beginning of the table, exclusively. For example, slice(-3, 5) returns all rows starting from the third-last row to the fifth row of the table. If there are no rows between these positions, the function will return an empty table.

      Specified by:
      slice in interface TableOperations<Table,Table>
      Parameters:
      firstPositionInclusive - the first position to include in the result
      lastPositionExclusive - the last position to include in the result
      Returns:
      a new Table, which is the request subset of rows from the original table

    • slicePct

      default Table slicePct(double startPercentInclusive, double endPercentExclusive)
      Description copied from interface: Table
      Extracts a subset of a table by row percentages.

      Returns a subset of table in the range [floor(startPercentInclusive * sizeOfTable), floor(endPercentExclusive * sizeOfTable)). For example, for a table of size 10, slicePct(0.1, 0.7) will return a subset from the second row to the seventh row. Similarly, slicePct(0, 1) would return the entire table (because row positions run from 0 to size-1). The percentage arguments must be in range [0,1], otherwise the function returns an error.

      Specified by:
      slicePct in interface Table
      Parameters:
      startPercentInclusive - the starting percentage point for rows to include in the result, range [0, 1]
      endPercentExclusive - the ending percentage point for rows to include in the result, range [0, 1]
      Returns:
      a new Table, which is the requested subset of rows from the original table

    • headPct

      default Table headPct(double percent)
      Description copied from interface: Table
      Provides a head that selects a dynamic number of rows based on a percent.
      Specified by:
      headPct in interface Table
      Parameters:
      percent - the fraction of the table to return between [0, 1]. The number of rows will be rounded up. For example if there are 3 rows, headPct(50) returns the first two rows. For percent values outside [0, 1], the function will throw an exception.

    • tailPct

      default Table tailPct(double percent)
      Description copied from interface: Table
      Provides a tail that selects a dynamic number of rows based on a percent.
      Specified by:
      tailPct in interface Table
      Parameters:
      percent - the fraction of the table to return between [0, 1]. The number of rows will be rounded up. For example if there are 3 rows, tailPct(50) returns the last two rows. For percent values outside [0, 1], the function will throw an exception.

    • exactJoin

      default Table exactJoin(Table rightTable, Collection<? extends JoinMatch> columnsToMatch, Collection<? extends JoinAddition> columnsToAdd)
      Description copied from interface: TableOperations
      Perform an exact-join with the rightTable.

      Similar to TableOperations.naturalJoin(Object, Collection, Collection), but requires that exactly one match from the rightTable.

      Specified by:
      exactJoin in interface TableOperations<Table,Table>
      Parameters:
      rightTable - The right side table on the join.
      columnsToMatch - The match pair conditions.
      columnsToAdd - The columns from the right side that need to be added to the left side as a result of the match.
      Returns:
      the exact-joined table

    • asOfJoin

      default Table asOfJoin(Table rightTable, Collection<? extends JoinMatch> exactMatches, AsOfJoinMatch asOfMatch, Collection<? extends JoinAddition> columnsToAdd)
      Specified by:
      asOfJoin in interface TableOperations<Table,Table>

    • naturalJoin

      default Table naturalJoin(Table rightTable, Collection<? extends JoinMatch> columnsToMatch, Collection<? extends JoinAddition> columnsToAdd, NaturalJoinType joinType)
      Description copied from interface: TableOperations
      Perform a natural-join with the rightTable.
      Specified by:
      naturalJoin in interface TableOperations<Table,Table>
      Parameters:
      rightTable - The right side table on the join.
      columnsToMatch - The match pair conditions.
      columnsToAdd - The columns from the right side that need to be added to the left side as a result of the match.
      joinType - The type of join to perform
      Returns:
      the natural-joined table

    • join

      default Table join(Table rightTable, Collection<? extends JoinMatch> columnsToMatch, Collection<? extends JoinAddition> columnsToAdd, int reserveBits)
      Description copied from interface: TableOperations
      Perform a cross join with the rightTable.

      Returns a table that is the cartesian product of left rows X right rows, with one column for each of this table's columns, and one column corresponding to each of the rightTable's columns that are included in the columnsToAdd argument. The rows are ordered first by the this table then by the rightTable. If columnsToMatch is non-empty then the product is filtered by the supplied match conditions.

      To efficiently produce updates, the bits that represent a key for a given row are split into two. Unless specified, join reserves 16 bits to represent a right row. When there are too few bits to represent all of the right rows for a given aggregation group the table will shift a bit from the left side to the right side. The default of 16 bits was carefully chosen because it results in an efficient implementation to process live updates.

      An io.deephaven.engine.table.impl.util.OutOfKeySpaceException is thrown when the total number of bits needed to express the result table exceeds that needed to represent Long.MAX_VALUE. There are a few work arounds:

      - If the left table is sparse, consider flattening the left table.

      - If there are no key-columns and the right table is sparse, consider flattening the right table.

      - If the maximum size of a right table's group is small, you can reserve fewer bits by setting reserveBits on initialization.

      Note: If you know that a given group has at most one right-row then you should prefer using TableOperations.naturalJoin(Object, Collection, Collection).

      Specified by:
      join in interface TableOperations<Table,Table>
      Parameters:
      rightTable - The right side table on the join.
      columnsToMatch - The match pair conditions.
      columnsToAdd - The columns from the right side that need to be added to the left side as a result of the match.
      reserveBits - The number of bits to reserve for rightTable groups.
      Returns:
      a new table joined according to the specification in columnsToMatch and columnsToAdd

    • rangeJoin

      default Table rangeJoin(@NotNull @NotNull Table rightTable, @NotNull @NotNull Collection<? extends JoinMatch> exactMatches, @NotNull @NotNull RangeJoinMatch rangeMatch, @NotNull @NotNull Collection<? extends Aggregation> aggregations)
      Description copied from interface: TableOperations
      Perform a range join with rightTable. For each row in this Table, this operation joins aggregations over a range of responsive rows from rightTable according to zero-or-more exact join matches and one range join match.

      Matching Rules

      The exact join matches identify possibly-responsive rows according to exactly matching values between the left exact match columns and the right exact match columns, similar to other join operations. The range join match bounds the beginning of the responsive range for a given output row by the relationship between a left start column and a right range column, governed by the rangeStartRule, and bounds the end of the responsive range for a given output row by the relationship between a left end column and the same right range column, governed by the rangeEndRule.

      Right Table Row-Inclusion Criteria and Relative Ordering Requirements

      Rows from rightTable with null or NaN values for the right range column are discarded; that is, they are never included in the responsive range for any output row. Within a group sharing the same values for the right exact match columns, rightTable must be relatively ordered (as if sorted) according to the right range column for all rows that are not discarded.

      Special Cases

      In order to produce aggregated output, it is required that the two relative match expressions define a range of values to determine the responsive rows to aggregate. There are a few noteworthy special cases of ranges.

      empty range
      An empty range occurs for any left row with no responsive right rows. That is, no non-null, non-NaN right rows were found using the exact join matches, or none were in range according to the range join match.
      single-value ranges
      A single-value range is a range where the left row’s values for the left start column and left end column are equal and both relative matches are inclusive (<= and >=, respectively). For a single-value range, only rows within the bucket where the right range column matches the single value are included in the output aggregations.
      invalid ranges
      An invalid range occurs in two scenarios: First, when the range is inverted, i.e. when the value of the left start column is greater than the value of the left end column. Second, when either relative-match is exclusive (< or >) and the value in the left start column is equal to the value in the left end column (because value < value == false). Specifying "allow preceding" or "allow following" for either rule will not constitute an exception to either of these defined scenarios. For invalid ranges, the result row will be null for all aggregation output columns.
      undefined ranges
      An undefined range occurs when either the left start column or the left end column is NaN. For rows with an undefined range, the corresponding output values will be null (as with invalid ranges).
      Unbounded Ranges
      A partially or fully unbounded range occurs when either the left start column or the left end column is null. If the left start column value is null the range is unbounded at the beginning, and all matched right rows will be included if they respect the match rule for the left end column. If the left end column value is null the range is unbounded at the end, and all matched right rows will be included if they respect the match rule for the left start column. If both the left start column and left end column values are null the range is unbounded in both directions, and all matched right rows will be included.
      Specified by:
      rangeJoin in interface TableOperations<Table,Table>
      Parameters:
      rightTable - The Table to join with
      exactMatches - Possibly-empty collection of join matches that dictate exact-match criteria. That is, rows from rightTable that might be responsive to rows from this Table will have identical values for the column pairs expressed by these matches.
      rangeMatch - Specifies the range match criteria for determining the responsive rows from rightTable for each row from this Table, within the buckets created by matching on the exactMatches
      aggregations - The aggregations to perform over the responsive ranges from rightTable for each row from this Table
      Returns:
      The result Table

    • headBy

      default Table headBy(long nRows, String... groupByColumnNames)
      Specified by:
      headBy in interface Table

    • tailBy

      default Table tailBy(long nRows, String... groupByColumnNames)
      Specified by:
      tailBy in interface Table

    • apply

      default <R> R apply(Function<Table,R> function)
      Description copied from interface: Table
      Applies a function to this table.

      This is useful if you have a reference to a table or a proxy and want to run a series of operations against the table without each individual operation resulting in an RMI.

      Specified by:
      apply in interface Table
      Type Parameters:
      R - the return type of function
      Parameters:
      function - the function to run, its single argument will be this table
      Returns:
      the return value of function

    • removeBlink

      default Table removeBlink()
      Description copied from interface: Table
      If this table is a blink table, i.e. it has Table.BLINK_TABLE_ATTRIBUTE set to true, return a child without the attribute, restoring standard semantics for aggregation operations.

      Removing the blink attribute does not change the underlying update pattern of the table. On each cycle, all existing rows are removed. When used with an aggregation this has the effect of providing the aggregated values for only this cycle, because aggregating the result table will no longer apply special blink semantics.

      Some aggregations (in particular TableOperations.groupBy() and Table.partitionBy(boolean, java.lang.String...) cannot provide the desired blink table aggregation semantics because doing so would require storing the entire stream of blink updates in memory. If that behavior is desired, use blinkToAppendOnly. If on the other hand, you would like to group or partition only values from the current update, remove the blink attribute with this method.

      To add the blink attribute to a table that generates updates consistent with blink semantics, use Table.assertBlink().

      Specified by:
      removeBlink in interface Table
      Returns:
      A non-blink child table, or this table if it is not a blink table

    • assertBlink

      default Table assertBlink()
      Description copied from interface: Table
      Returns this or a child Table with Table.BLINK_TABLE_ATTRIBUTE set to true.

      This table must already produce an update pattern that conforms to blink semantics. If it produces an update that does not conform to blink semantics, then the returned table will notify of an error and cease updating.

      Specified by:
      assertBlink in interface Table
      Returns:
      A child table with the blink attribute set, or this table if already a blink table.

    • assertAddOnly

      default Table assertAddOnly()
      Description copied from interface: Table
      Returns this or a child Table with Table.ADD_ONLY_TABLE_ATTRIBUTE set to true.

      This table must already produce an update pattern that conforms to add-only semantics. If it produces an update that does not conform to add-only semantics, then the returned table will notify of an error and cease updating.

      If the engine can identify a table as add only, then some query operations may be optimized (for example, a lastBy operation need only track the current last row per-group rather than all of the rows in a group). In formulas, the k variable (for the current row key) can be used safely.

      Specified by:
      assertAddOnly in interface Table
      Returns:
      A child table with the add-only attribute set, or this table if the attribute is already set.

    • assertAppendOnly

      default Table assertAppendOnly()
      Description copied from interface: Table
      Returns this or a child Table with Table.APPEND_ONLY_TABLE_ATTRIBUTE set to true.

      This table must already produce an update pattern that conforms to append-only semantics. If it produces an update that does not conform to append-only semantics, then the returned table will notify of an error and cease updating.

      If the engine can identify a table as append only, then some query operations may be optimized (for example, a lastBy operation need only track the current last row per-group rather than all of the rows in a group). In formulas, the i (for the current row position), ii (for the current row position), and k (for the current row key) variables can be used safely.

      Specified by:
      assertAppendOnly in interface Table
      Returns:
      A child table with the append-only attribute set, or this table if the attribute is already set.

    • partitionBy

      default PartitionedTable partitionBy(boolean dropKeys, String... keyColumnNames)
      Description copied from interface: Table
      Create a PartitionedTable from this table, partitioned according to the specified key columns.

      The underlying partitioned table backing the result contains each row in this table in exactly one of the result's constituent tables.

      Specified by:
      partitionBy in interface Table
      Parameters:
      dropKeys - Whether to drop key columns in the output constituent tables
      keyColumnNames - The names of the key columns to partition by
      Returns:
      A PartitionedTable keyed by keyColumnNames

    • partitionedAggBy

      default PartitionedTable partitionedAggBy(Collection<? extends Aggregation> aggregations, boolean preserveEmpty, Table initialGroups, String... keyColumnNames)
      Description copied from interface: Table
      Convenience method that performs an TableOperations.aggBy(io.deephaven.api.agg.Aggregation) and wraps the result in a PartitionedTable. If aggregations does not include a partition, one will be added automatically with the default constituent column name and behavior used in Table.partitionBy(String...).
      Specified by:
      partitionedAggBy in interface Table
      Parameters:
      aggregations - The aggregations to apply
      preserveEmpty - 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.
      initialGroups - A table whose distinct combinations of values for the groupByColumns should be used to create an initial set of aggregation groups. All other columns are ignored. This is useful in combination with preserveEmpty == true to ensure that particular groups appear in the result table, or with preserveEmpty == false to control the encounter order for a collection of groups and thus their relative order in the result. Changes to initialGroups are not expected or handled; if initialGroups is a refreshing table, only its contents at instantiation time will be used. If initialGroups == null, the result will be the same as if a table with no rows was supplied.
      keyColumnNames - The names of the key columns to aggregate by
      Returns:
      A PartitionedTable keyed by keyColumnNames

    • rollup

      default RollupTable rollup(Collection<? extends Aggregation> aggregations, boolean includeConstituents, Collection<? extends ColumnName> groupByColumns)
      Description copied from interface: Table
      Create a rollup table.

      A rollup table aggregates by the specified columns, and then creates a hierarchical table which re-aggregates using one less aggregation column on each level. The column that is no longer part of the aggregation key is replaced with null on each level.

      Specified by:
      rollup in interface Table
      Parameters:
      aggregations - The aggregations to perform
      includeConstituents - set to true to include the constituent rows at the leaf level
      groupByColumns - the columns to group by
      Returns:
      a hierarchical table with the rollup applied

    • tree

      default TreeTable tree(String idColumn, String parentColumn)
      Description copied from interface: Table
      Create a hierarchical tree table.

      The structure of the table is encoded by an "id" and a "parent" column. The id column should represent a unique identifier for a given row, and the parent column indicates which row is the parent for a given row. Rows that have a null parent are part of the "root" table.

      It is possible for rows to be "orphaned" if their parent is non-null and does not exist in the table. See TreeTable.promoteOrphans(Table, String, String).

      Specified by:
      tree in interface Table
      Parameters:
      idColumn - The name of a column containing a unique identifier for a particular row in the table
      parentColumn - The name of a column containing the parent's identifier, null for rows that are part of the root table
      Returns:
      A TreeTable organized according to the parent-child relationships expressed by idColumn and parentColumn

    • getSubTable

      default Table getSubTable(TrackingRowSet rowSet)
      Description copied from interface: Table
      Get a Table that contains a sub-set of the rows from this. The result will share the same column sources and definition as this table.

      The result will not update on its own. The caller must also establish an appropriate listener to update rowSet and propagate updates.

      Specified by:
      getSubTable in interface Table
      Parameters:
      rowSet - The row set for the result
      Returns:
      A new sub-table

    • flatten

      default Table flatten()
      Description copied from interface: Table
      Creates a version of this table with a flat RowSet.
      Specified by:
      flatten in interface Table

    • withKeys

      default Table withKeys(String... columns)
      Description copied from interface: Table
      Set the table's key columns.
      Specified by:
      withKeys in interface Table
      Returns:
      A copy of this table with the key columns specified, or this if no change was needed

    • withUniqueKeys

      default Table withUniqueKeys(String... columns)
      Description copied from interface: Table
      Set the table's key columns and indicate that each key set will be unique.
      Specified by:
      withUniqueKeys in interface Table
      Returns:
      A copy of this table with the unique key columns specified, or this if no change was needed

    • setTotalsTable

      default Table setTotalsTable(String directive)
      Description copied from interface: Table
      Set a totals table for this Table.
      Specified by:
      setTotalsTable in interface Table
      Parameters:
      directive - A packed string of totals table instructions
      Returns:
      A copy of this Table with the totals table attribute set

    • awaitUpdate

      default void awaitUpdate() throws InterruptedException
      Description copied from interface: Table

      Wait for updates to this Table. Should not be invoked from a TableListener or other notification on this Table's update graph. It may be suitable to wait from another update graph if doing so does not introduce any cycles.

      In some implementations, this call may also terminate in case of interrupt or spurious wakeup.

      Specified by:
      awaitUpdate in interface Table
      Throws:
      InterruptedException - In the event this thread is interrupted
      See Also:

    • awaitUpdate

      default boolean awaitUpdate(long timeout) throws InterruptedException
      Description copied from interface: Table

      Wait for updates to this Table. Should not be invoked from a TableListener or other notification on this Table's update graph. It may be suitable to wait from another update graph if doing so does not introduce any cycles.

      In some implementations, this call may also terminate in case of interrupt or spurious wakeup.

      Specified by:
      awaitUpdate in interface Table
      Parameters:
      timeout - The maximum time to wait in milliseconds.
      Returns:
      false if the timeout elapses without notification, true otherwise.
      Throws:
      InterruptedException - In the event this thread is interrupted
      See Also:

    • addUpdateListener

      default void addUpdateListener(ShiftObliviousListener listener, boolean replayInitialImage)
      Description copied from interface: Table
      Subscribe for updates to this table. After the optional initial image, listener will be invoked via the NotificationQueue associated with this Table.
      Specified by:
      addUpdateListener in interface Table
      Parameters:
      listener - listener for updates
      replayInitialImage - true to process updates for all initial rows in the table plus all changes; false to only process changes

    • addUpdateListener

      default void addUpdateListener(TableUpdateListener listener)
      Description copied from interface: Table
      Subscribe for updates to this table. listener will be invoked via the NotificationQueue associated with this Table.
      Specified by:
      addUpdateListener in interface Table
      Parameters:
      listener - listener for updates

    • addUpdateListener

      default boolean addUpdateListener(TableUpdateListener listener, long requiredLastNotificationStep)
      Description copied from interface: Table
      Subscribe for updates to this table if its last notification step matches requiredLastNotificationStep. listener will be invoked via the NotificationQueue associated with this Table.
      Specified by:
      addUpdateListener in interface Table
      Parameters:
      listener - listener for updates
      requiredLastNotificationStep - the expected last notification step to match
      Returns:
      true if the listener was added, false if the last notification step requirement was not met

    • removeUpdateListener

      default void removeUpdateListener(ShiftObliviousListener listener)
      Description copied from interface: Table
      Unsubscribe the supplied listener.
      Specified by:
      removeUpdateListener in interface Table
      Parameters:
      listener - listener for updates

    • removeUpdateListener

      default void removeUpdateListener(TableUpdateListener listener)
      Description copied from interface: Table
      Unsubscribe the supplied listener.
      Specified by:
      removeUpdateListener in interface Table
      Parameters:
      listener - listener for updates

    • isFailed

      default boolean isFailed()
      Specified by:
      isFailed in interface Table
      Returns:
      true if this table is in a failure state.

    • tryManage

      default boolean tryManage(@NotNull @NotNull LivenessReferent referent)
      Description copied from interface: LivenessManager
      Attempt to add referent to this manager. Will succeed if referent is live and if this manager is not a LivenessReferent or is live.
      Specified by:
      tryManage in interface LivenessManager
      Parameters:
      referent - The referent to add
      Returns:
      Whether the referent was in fact added

    • tryUnmanage

      default boolean tryUnmanage(@NotNull @NotNull LivenessReferent referent)
      Description copied from interface: LivenessManager
      If this manager manages referent one or more times, drop one such reference. If this manager is also a LivenessReferent, then this method is a no-op if this is not live.

      Strongly prefer using LivenessManager.tryUnmanage(Stream)} when multiple referents should be unmanaged.

      Specified by:
      tryUnmanage in interface LivenessManager
      Parameters:
      referent - The referent to drop
      Returns:
      If this node is also a LivenessReferent, whether this node was live and thus in fact tried to drop a reference. Else always returns true if dropping a reference via this method is supported by the implementation.

    • tryUnmanage

      default boolean tryUnmanage(@NotNull @NotNull Stream<? extends LivenessReferent> referents)
      Description copied from interface: LivenessManager
      For each referent in referents, if this manager manages referent one or more times, drop one such reference. If this manager is also a LivenessReferent, then this method is a no-op if this is not live.
      Specified by:
      tryUnmanage in interface LivenessManager
      Parameters:
      referents - The referents to drop
      Returns:
      If this node is also a LivenessReferent, whether this node was live and thus in fact tried to drop the references. Else always returns true if dropping a reference via this method is supported by the implementation.

    • tryRetainReference

      default boolean tryRetainReference()
      Description copied from interface: LivenessReferent
      If this referent is "live", behave as LivenessReferent.retainReference() and return true. Otherwise, returns false rather than throwing an exception.
      Specified by:
      tryRetainReference in interface LivenessReferent
      Returns:
      True if this referent was retained, false otherwise

    • dropReference

      default void dropReference()
      Description copied from interface: LivenessReferent
      Drop a previously-retained reference to this referent.
      Specified by:
      dropReference in interface LivenessReferent

    • getWeakReference

      default WeakReference<? extends LivenessReferent> getWeakReference()
      Description copied from interface: LivenessReferent
      Get a WeakReference to this referent. This may be cached, or newly created.
      Specified by:
      getWeakReference in interface LivenessReferent
      Returns:
      A new or cached reference to this referent

    • satisfied

      default boolean satisfied(long step)
      Description copied from interface: NotificationQueue.Dependency
      Is this ancestor satisfied? Note that this method must be safe to call on any thread.
      Specified by:
      satisfied in interface NotificationQueue.Dependency
      Parameters:
      step - The step for which we are testing satisfaction
      Returns:
      Whether the dependency is satisfied on step (and will not fire subsequent notifications)

    • head

      default Table head(long size)
      Specified by:
      head in interface TableOperations<Table,Table>

    • tail

      default Table tail(long size)
      Specified by:
      tail in interface TableOperations<Table,Table>

    • reverse

      default Table reverse()
      Specified by:
      reverse in interface TableOperations<Table,Table>

    • snapshot

      default Table snapshot()
      Description copied from interface: TableOperations
      Creates a table with a single static snapshot of this.
      Specified by:
      snapshot in interface TableOperations<Table,Table>
      Returns:
      the snapshot

    • snapshotWhen

      default Table snapshotWhen(Table trigger, SnapshotWhenOptions options)
      Description copied from interface: TableOperations
      Creates a table that captures a snapshot of this whenever trigger updates.
      Specified by:
      snapshotWhen in interface TableOperations<Table,Table>
      Parameters:
      trigger - the trigger table
      options - the snapshot options
      Returns:
      the snapshotting table
      See Also:

    • sort

      default Table sort(Collection<SortColumn> columnsToSortBy)
      Specified by:
      sort in interface TableOperations<Table,Table>

    • where

      default Table where(Filter filter)
      Specified by:
      where in interface TableOperations<Table,Table>

    • whereIn

      default Table whereIn(Table rightTable, Collection<? extends JoinMatch> columnsToMatch)
      Description copied from interface: TableOperations
      Filters this table based on the set of values in the rightTable.

      Note that when the rightTable ticks, all of the rows in this table are going to be re-evaluated, thus the intention is that the rightTable is fairly slow moving compared with this table.

      Specified by:
      whereIn in interface TableOperations<Table,Table>
      Parameters:
      rightTable - the filtering table.
      columnsToMatch - the columns to match between the two tables
      Returns:
      a new table filtered on right table

    • whereNotIn

      default Table whereNotIn(Table rightTable, Collection<? extends JoinMatch> columnsToMatch)
      Description copied from interface: TableOperations
      Filters this table based on the set of values not in the rightTable.

      Note that when the rightTable ticks, all of the rows in this table are going to be re-evaluated, thus the intention is that the rightTable is fairly slow moving compared with this table.

      Specified by:
      whereNotIn in interface TableOperations<Table,Table>
      Parameters:
      rightTable - the filtering table.
      columnsToMatch - the columns to match between the two tables
      Returns:
      a new table filtered on right table

    • view

      default Table view(Collection<? extends Selectable> columns)
      Specified by:
      view in interface TableOperations<Table,Table>

    • updateView

      default Table updateView(Collection<? extends Selectable> columns)
      Specified by:
      updateView in interface TableOperations<Table,Table>

    • update

      default Table update(Collection<? extends Selectable> columns)
      Specified by:
      update in interface TableOperations<Table,Table>

    • lazyUpdate

      default Table lazyUpdate(Collection<? extends Selectable> columns)
      Description copied from interface: TableOperations
      Compute column formulas on demand.

      Lazy update defers computation until required for a set of values, and caches the results for a set of input values. This uses less RAM than an update statement when you have a smaller set of unique values. Less computation than an updateView is needed, because the results are saved in a cache.

      If you have many unique values, you should instead use an update statement, which will have more memory efficient structures. Values are never removed from the lazyUpdate cache, so it should be used judiciously on a ticking table.

      Specified by:
      lazyUpdate in interface TableOperations<Table,Table>
      Parameters:
      columns - the columns to add
      Returns:
      a new Table with the columns added; to be computed on demand

    • select

      default Table select(Collection<? extends Selectable> columns)
      Specified by:
      select in interface TableOperations<Table,Table>

    • aggAllBy

      default Table aggAllBy(AggSpec spec, ColumnName... groupByColumns)
      Specified by:
      aggAllBy in interface TableOperations<Table,Table>

    • aggBy

      default Table aggBy(Collection<? extends Aggregation> aggregations, boolean preserveEmpty, Table initialGroups, Collection<? extends ColumnName> groupByColumns)
      Description copied from interface: TableOperations
      Produce an aggregated result by grouping this according to the groupByColumns and applying aggregations to each resulting group of rows. The result table will have one row per group, ordered by the encounter order within this, thereby ensuring that the row key for a given group never changes.
      Specified by:
      aggBy in interface TableOperations<Table,Table>
      Parameters:
      aggregations - The aggregations to apply
      preserveEmpty - 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.
      initialGroups - A table whose distinct combinations of values for the groupByColumns should be used to create an initial set of aggregation groups. All other columns are ignored. This is useful in combination with preserveEmpty == true to ensure that particular groups appear in the result table, or with preserveEmpty == false to control the encounter order for a collection of groups and thus their relative order in the result. Changes to initialGroups are not expected or handled; if initialGroups is a refreshing table, only its contents at instantiation time will be used. If initialGroups == null, the result will be the same as if a table with no rows was supplied.
      groupByColumns - The columns to group by
      Returns:
      A new table aggregating the rows of this

    • updateBy

      default Table updateBy(UpdateByControl control, Collection<? extends UpdateByOperation> operations, Collection<? extends ColumnName> byColumns)
      Description copied from interface: TableOperations
      Creates a table with additional columns calculated from window-based aggregations of columns in its parent. The aggregations are defined by the operations, which support incremental aggregation over the corresponding rows in the parent table. The aggregations will apply position or time-based windowing and compute the results for the row group (as determined by the byColumns).
      Specified by:
      updateBy in interface TableOperations<Table,Table>
      Parameters:
      control - the control to use when updating the table.
      operations - the operations to apply to the table.
      byColumns - the columns to group by before applying.
      Returns:
      a table with the same rowSet, with the specified operations applied to each group defined by the byColumns

    • selectDistinct

      default Table selectDistinct(Collection<? extends Selectable> columns)
      Specified by:
      selectDistinct in interface TableOperations<Table,Table>

    • ungroup

      default Table ungroup(boolean nullFill, Collection<? extends ColumnName> columnsToUngroup)
      Description copied from interface: TableOperations
      Ungroups a table by expanding columns of arrays or vectors into columns of singular values, creating one row in the output table for each value in the columns to be ungrouped. Columns that are not ungrouped have their values duplicated in each output row corresponding to a given input row.
      Specified by:
      ungroup in interface TableOperations<Table,Table>
      Parameters:
      nullFill - indicates if the ungrouped table should allow disparate sized arrays filling shorter columns with null values. If set to false, then all arrays should be the same length.
      columnsToUngroup - the columns to ungroup
      Returns:
      the ungrouped table

    • restrictSortTo

      default Table restrictSortTo(@NotNull @NotNull String... allowedSortingColumns)
      Description copied from interface: GridAttributes
      Disallow sorting on all but the specified columns.
      Specified by:
      restrictSortTo in interface GridAttributes<Table>
      Parameters:
      allowedSortingColumns - The columns for which sorting is to be allowed
      Returns:
      A copy of this grid with the sort restrictions applied, or this if no change was needed

    • clearSortingRestrictions

      default Table clearSortingRestrictions()
      Description copied from interface: GridAttributes
      Clear all sorting restrictions that were applied to the grid.
      Specified by:
      clearSortingRestrictions in interface GridAttributes<Table>
      Returns:
      A copy of this grid with the sort restrictions removed, or this if no change was needed

    • withDescription

      default Table withDescription(@NotNull @NotNull String description)
      Description copied from interface: GridAttributes
      Apply a description to this grid.
      Specified by:
      withDescription in interface GridAttributes<Table>
      Parameters:
      description - The description to apply
      Returns:
      A copy of this grid with the description applied, or this if no change was needed

    • withColumnDescription

      default Table withColumnDescription(@NotNull @NotNull String column, @NotNull @NotNull String description)
      Description copied from interface: GridAttributes
      Add a description for a specific column. Users should use GridAttributes.withColumnDescriptions(Map) to set several descriptions at once.
      Specified by:
      withColumnDescription in interface GridAttributes<Table>
      Parameters:
      column - The name of the column
      description - The column description
      Returns:
      A copy of this grid with the description applied, or this if no change was needed

    • withColumnDescriptions

      default Table withColumnDescriptions(@NotNull @NotNull Map<String,String> descriptions)
      Description copied from interface: GridAttributes
      Add a set of column descriptions to the grid.
      Specified by:
      withColumnDescriptions in interface GridAttributes<Table>
      Parameters:
      descriptions - A map of column name to column description
      Returns:
      A copy of this grid with the descriptions applied, or this if no change was needed

    • setLayoutHints

      default Table setLayoutHints(@NotNull @NotNull String hints)
      Description copied from interface: GridAttributes
      Set layout hints for this grid.
      Specified by:
      setLayoutHints in interface GridAttributes<Table>
      Parameters:
      hints - A packed string of layout hints
      Returns:
      A copy of this grid with the layout hints applied, or this if no change was needed