@deephaven/jsapi-types
    Preparing search index...

    Interface TableOperations

    Operations on a table that need none of its data or metadata, so they can be chained without waiting on a promise.

    Every instance represents one server-side table, with its definition fixed when created. Compared with a Table, it is "immutable", and has no methods to change its columns, filters, sort, etc. A ticking table's rows still change as the server's update graph adds, removes, and modifies them. Each operation returns a new pending table, so the caller decides the order of operations by how they chain them.

    Each table holds server resources until it is closed, by whoever owns it:

    • Awaiting a PendingTable gives the table it produces, and PendingTable.resolve() gives it as a ResolvedTable. Use one or the other, not both; repeating the same one gives the same instance, as awaiting a promise twice does. A pending table has no owner: whoever awaits or resolves it owns that instance, and is responsible for closing it.
    • A ResolvedTable is already the table: it cannot be awaited, since awaiting a thenable would also await what it resolves to, and needs no resolving.
    • Code that receives a table and its caller agree on whether that code may close it. Code given a TableOperations can only chain on it, so it never retains a table its caller cannot reach to close. Code that reads a table should take a ResolvedTable, which the sender resolves before handing it over, and code that keeps one it was lent can call ResolvedTable.copy() for a new instance with its own lifetime.
    To hand one table to several owners, resolve it once, give each owner a copy, and close the original:
    const t = await pending;
    popupA.show(t.copy());
    popupB.show(t.copy());
    t.close();
    

    No method throws: as from an async function, every failure rejects the pending table it returns. That includes invalid arguments, an operand from another connection and a closed table, which reject with the error and send nothing to the server, as well as a failure on the server or of a table the operation uses, if it was canceled, failed, or used too late. PendingTable describes how long a pending table may be used.

    async function process(table: dh.TableOperations) {
      const result = await table
          .where([dh.FilterValue.ofColumn("A").greaterThan(dh.FilterValue.ofNumber(5))])
          .sort([{column: "B", direction: "DESC"}])
          .head(10);
      // From here on, `table` may already be closed. This function did not retain it, and cannot tell whether the
      // caller did.
      try {
          const a = result.findColumn("A");
          const data = await result.createSnapshot({
              rows: {first: 0, last: 9},
              columns: [a, "B"]
          });
          return data.getData(0, a);
      } finally {
          result.close();
      }
    }
    

    The process example only chains on the table it is given, so it works whether the caller passes a pending or a resolved table, and closes only what its own chain produced. To keep a table for later, take a ResolvedTable and copy it: below, SwapFilters owns its copy and each filtered table it makes, and closes each when replaced or when it is closed.

    class SwapFilters {
        private readonly table: dh.ResolvedTable;
        private filteredTable: Promise<dh.ResolvedTable> | null = null;
        constructor(table: dh.ResolvedTable) {
            // The caller keeps its own table; this class owns the copy
            this.table = table.copy();
        }
        changeFilters(filters: ReadonlyArray<dh.FilterCondition>) {
            if (this.filteredTable) {
                // A table that failed has nothing to close
                this.filteredTable.then(t => t.close(), () => {});
            }
            this.filteredTable = Promise.resolve(this.table.where(filters));
        }
        async loadData(): Promise<dh.TableData> {
            if (!this.filteredTable) {
                throw new Error("no filters set");
            }
            const t = await this.filteredTable;
            return t.createSnapshot({
                rows: {first:0, last:1_000_000},
                columns: t.columns
            })
        }
        close() {
            this.table.close();
            if (this.filteredTable) {
                this.filteredTable.then(t => t.close(), () => {});
            }
        }
    }
    
    interface TableOperations {
        absSumBy(
            groupByColumns?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        aggAllBy(
            aggUnion: AggAllByUnion,
            groupByColumns?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        aggBy(options: AggByOptions): PendingTable<ResolvedTable>;
        aj(
            rightTable: TableReference,
            columnsToMatch: readonly (string | Column)[],
            columnsToAdd?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        avgBy(
            groupByColumns?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        countBy(
            columnName: string,
            groupByColumns?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        downsample(options: DownsampleTableOptions): PendingTable<ResolvedTable>;
        dropColumns(
            columnsToDrop: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        exactJoin(
            rightTable: TableReference,
            columnsToMatch: readonly (string | Column)[],
            columnsToAdd?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        firstBy(
            groupByColumns?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        flatten(): PendingTable<ResolvedTable>;
        groupBy(
            groupByColumns?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        head(size: number | LongWrapper): PendingTable<ResolvedTable>;
        join(
            rightTable: TableReference,
            columnsToMatch: readonly (string | Column)[],
            columnsToAdd?: readonly (string | Column)[],
            reserveBits?: number,
        ): PendingTable<ResolvedTable>;
        lastBy(
            groupByColumns?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        maxBy(
            groupByColumns?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        medianBy(
            groupByColumns?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        minBy(
            groupByColumns?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        naturalJoin(
            rightTable: TableReference,
            columnsToMatch: readonly (string | Column)[],
            columnsToAdd?: readonly (string | Column)[],
            joinType?: NaturalJoinType,
        ): PendingTable<ResolvedTable>;
        raj(
            rightTable: TableReference,
            columnsToMatch: readonly (string | Column)[],
            columnsToAdd?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        rangeJoin(
            rightTable: TableReference,
            exactMatches: readonly string[],
            rangeMatch: RangeJoinMatch,
            aggregations: readonly AggregationUnion[],
        ): PendingTable<ResolvedTable>;
        reverse(): PendingTable<ResolvedTable>;
        select(
            columns: readonly (string | CustomColumn)[],
        ): PendingTable<ResolvedTable>;
        selectDistinct(
            columnNames?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        slice(
            firstPositionInclusive: number | LongWrapper,
            lastPositionExclusive: number | LongWrapper,
        ): PendingTable<ResolvedTable>;
        snapshot(): PendingTable<ResolvedTable>;
        snapshotWhen(
            trigger: TableReference,
            options?: SnapshotWhenOptions,
        ): PendingTable<ResolvedTable>;
        sort(
            sorts: readonly (string | Column | Sort | SimpleSort)[],
        ): PendingTable<ResolvedTable>;
        stdBy(
            groupByColumns?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        sumBy(
            groupByColumns?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        tail(size: number | LongWrapper): PendingTable<ResolvedTable>;
        ungroup(options?: UngroupOptions): PendingTable<ResolvedTable>;
        update(
            columns: readonly (string | CustomColumn)[],
        ): PendingTable<ResolvedTable>;
        updateBy(options: UpdateByOptions): PendingTable<ResolvedTable>;
        updateView(
            columns: readonly (string | CustomColumn)[],
        ): PendingTable<ResolvedTable>;
        varBy(
            groupByColumns?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        view(
            columns: readonly (string | CustomColumn)[],
        ): PendingTable<ResolvedTable>;
        wavgBy(
            weightColumn: string | Column,
            groupByColumns?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        where(conditions: readonly FilterCondition[]): PendingTable<ResolvedTable>;
        whereIn(
            rightTable: TableReference,
            columnsToMatch: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        whereNotIn(
            rightTable: TableReference,
            columnsToMatch: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
        wsumBy(
            weightColumn: string | Column,
            groupByColumns?: readonly (string | Column)[],
        ): PendingTable<ResolvedTable>;
    }

    Hierarchy (View Summary)

    Index
    • Computes the sum of absolute values of each column within each group.

      Parameters

      • OptionalgroupByColumns: readonly (string | Column)[]

        columns to group by. If omitted, computes the absolute sum across all rows

      Returns PendingTable<ResolvedTable>

      a new table with the absolute sums

    • Aggregates the contents of this table into a new table. Each aggregation adds columns computed over each group, and can be made with a dh.agg.Aggregation factory or written as an object literal:

      const summary = await table.aggBy({
          aggregations: [
              dh.agg.Aggregation.AggWAvg("W", ["WAvgX = X"]),
              dh.agg.Aggregation.AggAvg(["AvgX = X"]),
              { type: "Count", col: "N" },
          ],
          groupByColumns: ["Key"],
      });
      

      Parameters

      • options: AggByOptions

        the aggregations, and optionally the columns to group by and the groups to start with

      Returns PendingTable<ResolvedTable>

      a table with one row per group, and a column for each aggregation

    • Performs an as-of join of this table with the right table: each row takes the right table's row with the closest as-of value at or before its own.

      Parameters

      • rightTable: TableReference

        the table to join with

      • columnsToMatch: readonly (string | Column)[]

        the columns to match on. All but the last are exact matches ("LeftCol=RightCol" or a name in both tables). The last is the as-of match: "LeftCol>=RightCol", "LeftCol>RightCol", or a name in both tables, which means >=.

      • OptionalcolumnsToAdd: readonly (string | Column)[]

        the columns to add from the right table. If omitted, adds all non-match columns

      Returns PendingTable<ResolvedTable>

      a new table with the joined columns

    • Computes the arithmetic mean of each column within each group.

      Parameters

      • OptionalgroupByColumns: readonly (string | Column)[]

        columns to group by. If omitted, computes the average across all rows

      Returns PendingTable<ResolvedTable>

      a new table with the averages

    • Counts the number of rows in each group, storing the result in a new column.

      Parameters

      • columnName: string

        the name of the new column to hold the row counts

      • OptionalgroupByColumns: readonly (string | Column)[]

        columns to group by. If omitted, counts all rows into a single result

      Returns PendingTable<ResolvedTable>

      a new table with a count column and optional group-by columns

    • Creates a table with fewer rows than this one that draws the same as a line plot at the given width, for plotting large time series. Each pixel of the width keeps the rows that set its first, last, minimum and maximum values. If the table has fewer rows than that, the result is the table unchanged.

      Parameters

      Returns PendingTable<ResolvedTable>

      the downsampled table

    • Creates a new table without the specified columns.

      Parameters

      • columnsToDrop: readonly (string | Column)[]

        the columns to drop. Should not be empty.

      Returns PendingTable<ResolvedTable>

      a new table without those columns

    • Performs an exact join of this table with the right table. Each row in this table must have exactly one matching row in the right table based on the match columns. If a row has no match, the operation fails.

      Parameters

      • rightTable: TableReference

        the table to join with

      • columnsToMatch: readonly (string | Column)[]

        the columns to match on, in "LeftCol=RightCol" format

      • OptionalcolumnsToAdd: readonly (string | Column)[]

        the columns to add from the right table. If omitted, adds all non-match columns

      Returns PendingTable<ResolvedTable>

      a new table with the joined columns

    • Returns the first row of each group.

      Parameters

      • OptionalgroupByColumns: readonly (string | Column)[]

        columns to group by. If omitted, returns the first row of the table

      Returns PendingTable<ResolvedTable>

      a new table with the first row from each group

    • Groups the table by the specified columns, accumulating the other columns into arrays. If no columns are provided, the resulting table has a single row.

      Parameters

      • OptionalgroupByColumns: readonly (string | Column)[]

        columns to group

      Returns PendingTable<ResolvedTable>

      a table with one row per group

    • Performs a cross join (Cartesian product) of this table with the right table, filtered to matching rows. Each row in this table is paired with every matching row in the right table.

      Parameters

      • rightTable: TableReference

        the table to join with

      • columnsToMatch: readonly (string | Column)[]

        the columns to match on, in "LeftCol=RightCol" format

      • OptionalcolumnsToAdd: readonly (string | Column)[]

        the columns to add from the right table. If omitted, adds all non-match columns

      • OptionalreserveBits: number

        the number of bits of key-space to initially reserve per group. The default is 10

      Returns PendingTable<ResolvedTable>

      a new table with the joined columns

    • Returns the last row of each group.

      Parameters

      • OptionalgroupByColumns: readonly (string | Column)[]

        columns to group by. If omitted, returns the last row of the table

      Returns PendingTable<ResolvedTable>

      a new table with the last row from each group

    • Returns the maximum value of each column within each group.

      Parameters

      • OptionalgroupByColumns: readonly (string | Column)[]

        columns to group by. If omitted, computes the maximum across all rows

      Returns PendingTable<ResolvedTable>

      a new table with the maximum values

    • Computes the median of each column within each group. When the group size is even, averages the two middle values of int, long, float and double columns, and uses the larger value for other types.

      Parameters

      • OptionalgroupByColumns: readonly (string | Column)[]

        columns to group by. If omitted, computes the median across all rows

      Returns PendingTable<ResolvedTable>

      a new table with the medians

    • Returns the minimum value of each column within each group.

      Parameters

      • OptionalgroupByColumns: readonly (string | Column)[]

        columns to group by. If omitted, computes the minimum across all rows

      Returns PendingTable<ResolvedTable>

      a new table with the minimum values

    • Perform a natural-join with the rightTable.

      Parameters

      • rightTable: TableReference

        the right side table on the join

      • columnsToMatch: readonly (string | Column)[]

        the match pair conditions

      • OptionalcolumnsToAdd: readonly (string | Column)[]

        the columns from the right table to add to the result. If omitted, adds all non-match columns

      • OptionaljoinType: NaturalJoinType

        the type of join to perform

      Returns PendingTable<ResolvedTable>

      the natural-joined table

    • Performs a reverse as-of join of this table with the right table: each row takes the right table's row with the closest as-of value at or after its own.

      Parameters

      • rightTable: TableReference

        the table to join with

      • columnsToMatch: readonly (string | Column)[]

        the columns to match on. All but the last are exact matches ("LeftCol=RightCol" or a name in both tables). The last is the as-of match: "LeftCol<=RightCol", "LeftCol<RightCol", or a name in both tables, which means <=.

      • OptionalcolumnsToAdd: readonly (string | Column)[]

        the columns to add from the right table. If omitted, adds all non-match columns

      Returns PendingTable<ResolvedTable>

      a new table with the joined columns

    • Joins each row of this table to the rows of rightTable that match it exactly on exactMatches and fall in its range, and aggregates those right rows into columns of the result. The result has one row per row of this table.

      At this time, the server supports only static (not refreshing) tables and Group aggregations. This operation remains under active development.

      Parameters

      • rightTable: TableReference

        the table to join to

      • exactMatches: readonly string[]

        columns that must be equal in both tables, as "Col" or "LeftCol=RightCol"

      • rangeMatch: RangeJoinMatch

        the columns and rules of the range match

      • aggregations: readonly AggregationUnion[]

        the aggregations to apply to each row's matching right rows

      Returns PendingTable<ResolvedTable>

      a table with one row per row of this table, and a column for each aggregation

    • Creates a new table with only the specified columns. Computes all formulas eagerly and stores their values in memory.

      Parameters

      • columns: readonly (string | CustomColumn)[]

        the columns or expressions to have in the new table

      Returns PendingTable<ResolvedTable>

      a new table with only those columns.

    • Creates a new table with only the distinct values of the specified columns. If no columns are specified, uses all columns.

      Parameters

      • OptionalcolumnNames: readonly (string | Column)[]

        the column names to distinct on. If empty/null, uses all columns

      Returns PendingTable<ResolvedTable>

      a new table with only the distinct values of the specified columns

    • Extracts a subset of a table by row position.

      If both firstPositionInclusive and lastPositionExclusive are positive, both count from the beginning of the table. The firstPositionInclusive is inclusive, and the lastPositionExclusive is exclusive. The head(N) call is equivalent to slice(0, N). The firstPositionInclusive must be less than or equal to the lastPositionExclusive.

      If firstPositionInclusive is positive and lastPositionExclusive is negative, the firstPositionInclusive counts from the beginning of the table, inclusively. The lastPositionExclusive counts from the end of the table. For example, slice(1, -1) includes all rows but the first and last. If the lastPositionExclusive would be before the firstPositionInclusive, the result is an empty table.

      If firstPositionInclusive is negative and lastPositionExclusive is zero, the firstPositionInclusive counts from the end of the table, and the slice ends at the end of the table. Calling slice(-N, 0) is equivalent to tail(N).

      If the firstPositionInclusive is negative and the lastPositionExclusive is negative, both count from the end of the table. For example, slice(-2, -1) returns the second to last row of the table.

      If firstPositionInclusive is negative and lastPositionExclusive is positive, the firstPositionInclusive counts from the end of the table, inclusively. The lastPositionExclusive counts 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 result is an empty table.

      Parameters

      • firstPositionInclusive: number | LongWrapper

        the first position to include in the result

      • lastPositionExclusive: number | LongWrapper

        the position after the last one to include in the result

      Returns PendingTable<ResolvedTable>

      a new table with the subset of rows from the original table

    • A server-side snapshot of the entire table as of the time the request is processed. The result does not update. This is what Table.freeze() does. The name here follows the other Deephaven clients.

      Returns PendingTable<ResolvedTable>

      a new, non-ticking table with the same contents as this table at that moment

    • Computes the sample standard deviation of each column within each group, using Bessel's correction.

      Parameters

      • OptionalgroupByColumns: readonly (string | Column)[]

        columns to group by. If omitted, computes the standard deviation across all rows

      Returns PendingTable<ResolvedTable>

      a new table with the standard deviations

    • Computes the sum of each column within each group.

      Parameters

      • OptionalgroupByColumns: readonly (string | Column)[]

        columns to group by. If omitted, computes the sum across all rows

      Returns PendingTable<ResolvedTable>

      a new table with the sums

    • 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 being ungrouped. Each output row repeats the values of the other columns from its input row.

      Parameters

      • Optionaloptions: UngroupOptions

        options to specify the behavior of the ungroup operation

      Returns PendingTable<ResolvedTable>

      an ungrouped table

    • Creates a new table, appending or replacing the specified columns. Computes all formulas eagerly and stores their values in memory.

      Parameters

      • columns: readonly (string | CustomColumn)[]

        the columns or expressions to have in the new table

      Returns PendingTable<ResolvedTable>

      a new table with those columns appended

    • Adds or replaces columns whose value in each row depends on the rows around it in its group: cumulative operations, rolling windows, exponential moving statistics, fills and deltas. Without UpdateByOptions.groupByColumns, the whole table is one group. For example, a weighted average over each row and the two before it in its group:

      const rolling = await table.updateBy({
          operations: [{
              spec: {
                  type: "UpdateByRollingWAvg",
                  weightColumn: "W",
                  reverseWindowScale: { type: "ticks", ticks: 3 },
              },
              matchPairs: ["RollWAvgX = X"],
          }],
          groupByColumns: ["Key"],
      });
      

      Parameters

      • options: UpdateByOptions

        the operations to apply, and optionally the columns to group by and control settings

      Returns PendingTable<ResolvedTable>

      a table with the same rows as this table, and each operation's output columns added or replacing the columns of the same name

    • Creates a new table, appending or replacing the specified columns. Computes each formula every time a value is read, and stores nothing.

      Parameters

      • columns: readonly (string | CustomColumn)[]

        the columns or expressions to have in the new table

      Returns PendingTable<ResolvedTable>

      a new table with those columns appended

    • Computes the sample variance of each column within each group, using Bessel's correction.

      Parameters

      • OptionalgroupByColumns: readonly (string | Column)[]

        columns to group by. If omitted, computes the variance across all rows

      Returns PendingTable<ResolvedTable>

      a new table with the variances

    • Creates a new table with only the specified columns. Computes each formula every time a value is read, and stores nothing.

      Parameters

      • columns: readonly (string | CustomColumn)[]

        the columns or expressions to have in the new table

      Returns PendingTable<ResolvedTable>

      a new table with only those columns.

    • Computes the weighted average of each column within each group: the sum of each value multiplied by its weight, divided by the sum of the weights. It averages every column other than the weight and the group-by columns, so each must be numeric. To choose and rename columns, or to combine with other aggregations, use TableOperations.aggBy() with dh.agg.Aggregation.AggWAvg.

      const byKey = await table.wavgBy("W", ["Key"]);
      

      Parameters

      • weightColumn: string | Column

        the column containing the weights

      • OptionalgroupByColumns: readonly (string | Column)[]

        columns to group by. If omitted, computes the weighted average across all rows

      Returns PendingTable<ResolvedTable>

      a new table with the weighted averages

    • Filters the contents of this table based on the set of values that match the provided right table.

      When the right table ticks, all the rows in this table are re-evaluated.

      Parameters

      • rightTable: TableReference

        the table with the filter criteria

      • columnsToMatch: readonly (string | Column)[]

        the column matches between the two tables

      Returns PendingTable<ResolvedTable>

      a new filtered table

    • Filters the contents of this table based on the set of values that do not match the provided right table.

      When the right table ticks, all the rows in this table are re-evaluated.

      Parameters

      • rightTable: TableReference

        the table with the filter criteria

      • columnsToMatch: readonly (string | Column)[]

        the column matches between the two tables

      Returns PendingTable<ResolvedTable>

      a new filtered table

    • Computes the weighted sum of each column within each group: the sum of each value multiplied by its weight.

      Parameters

      • weightColumn: string | Column

        the column containing the weights

      • OptionalgroupByColumns: readonly (string | Column)[]

        columns to group by. If omitted, computes the weighted sum across all rows

      Returns PendingTable<ResolvedTable>

      a new table with the weighted sums