Extract table values

Deephaven provides several ways to extract values from tables into Groovy. Most queries don't need this. It's useful for debugging, for logging, and for code that reads table data directly, such as table listeners.

Choose a method based on how you need to find the values:

  • To read a value by its position in the table, use ColumnVectors. This is the simplest option, and most code should use it.
  • To loop over every value in a column, use a column iterator. An iterator reads values in bulk, so it's faster than reading each position separately.
  • To read a value by the engine's internal row key, use a ColumnSource. Use this when your code already has row keys, such as the row sets a table listener receives.

Note

These methods are for extracting values from Deephaven to Groovy, not for transforming table data. To create or modify columns, use operations like update. See Recipes, not loops! for more details.

ColumnVectors (positional index access)

A row's positional index is its position in the table, counting from 0. The recommended way to extract values by positional index is ColumnVectors. Each ColumnVectors method wraps one column in a vector, such as an IntVector for an int column. The vector's get method returns the value at a row position.

Use the method that matches the column's type, such as ofInt for an int column or ofObject(table, columnName, type) for an object column, for example ColumnVectors.ofObject(t, "Sym", String). For the full list of methods, see The ColumnVectors class.

Warning

Random access via the vector's get(position) method is less efficient than bulk iteration. Use iteration when processing multiple values. See Iterate over a column.

Note

For a refreshing (ticking) table, a vector is only valid for the current update cycle. Inside a listener, read previous values (each row's values before the current update cycle's changes) by passing true as the final usePreviousValues argument. For example, ColumnVectors.ofInt(table, "Integers", true) reads the previous values of the Integers column. For the limits on previous-values vectors, see Refreshing tables.

Iterate over a column

To loop over all values in a column, use columnIterator. To read primitive values without wrapping each one in a Java object, use a typed variant such as integerColumnIterator. If you stop before the iterator is exhausted, call its close method to release its resources.

This example loops over the result table created in ColumnVectors (positional index access):

If you already have a vector from ColumnVectors, you can iterate over it directly with its iterator method instead. See Iterate over tables with ColumnVectors.

Advanced: ColumnSource (row key access)

Most code should use ColumnVectors. Use row-key access when your code already has row keys rather than positions, such as the added and modified row sets a table listener receives.

The getColumnSource method returns a ColumnSource that provides access to column data by row key, not positional index. A row key is the internal identifier the engine assigns to a row. It can differ from the row's positional index, especially in filtered tables or tables whose rows have been added, removed, or shifted. To learn how row keys and positional indices change as tables update, see the row keys and positional indices FAQ.

To find the row key for a position, look it up in the table's RowSet, the ordered set of row keys the table contains. Then read the value with a type-specific method:

Type-specific ColumnSource methods:

  • getInt(rowKey) for int columns
  • getLong(rowKey) for long columns
  • getDouble(rowKey) for double columns
  • getFloat(rowKey) for float columns
  • getShort(rowKey) for short columns
  • getByte(rowKey) for byte columns
  • getChar(rowKey) for char columns
  • getBoolean(rowKey) for Boolean columns
  • get(rowKey) for object columns

get also works on primitive columns, but it wraps each value in a Java object, so prefer the type-specific methods for primitives.

Note

For a refreshing table, values read through a ColumnSource are consistent only while no update can change them: inside a listener that listens to the table or waits for it as a dependency, or while your code holds the table's update graph shared or exclusive lock. Console scripts already hold the exclusive lock, so this matters mainly for code that runs on other threads. See Engine locking.

Note

Inside a listener, use the getPrev* methods, such as getPrevInt, to read previous values, meaning each row's values before the current update cycle's changes. These methods take a previous row key: one from the update's removed or getModifiedPreShift row sets, or one you look up in the table's previous RowSet, for example result.getRowSet().prev().get(2).