Arrays vs vectors

Deephaven tables can store multi-element data in two forms: Java primitive arrays and Deephaven vectors. While both represent ordered collections of elements, they have important differences that affect how you work with them.

Quick comparison

Feature	Java Arrays	Deephaven Vectors
Type examples	`int[]`, `double[]`, `String[]`	`IntVector`, `DoubleVector`, `ObjectVector`
Index type	`int` (max ~2.1 billion elements)	`long` (supports larger datasets)
Out-of-bounds access	Throws exception	Returns null constant (e.g., `NULL_INT`)
Created by	Explicit construction	Table operations (`groupBy`, rolling ops)
Memory model	Owns contiguous memory	May be a view into table data
Slicing	`Arrays.copyOfRange`	`subVector` (no copy)

Java primitive arrays

Java arrays are standard fixed-size collections. Create them explicitly using Java syntax:

from deephaven import empty_table

result = empty_table(1).update(
    [
        "IntArray = new int[]{1, 2, 3}",
        "DoubleArray = new double[]{1.1, 2.2, 3.3}",
        "StringArray = new String[]{`a`, `b`, `c`}",
    ]
)
result_meta = result.meta_table

Java arrays use int-based indexing. Accessing an index outside the array bounds throws an ArrayIndexOutOfBoundsException.

Deephaven vectors

Deephaven vectors are Deephaven's specialized collection type, implemented by the Vector interface and its subclasses (IntVector, DoubleVector, etc.). Table operations that group data produce vector columns:

from deephaven import empty_table

result = empty_table(5).update(["X = ii % 2", "Y = (int) ii"]).group_by("X")
result_meta = result.meta_table

The Y column is an IntVector, not an int[].

Key advantages of vectors

Long-based indexing: Vectors use long indices, supporting datasets larger than 2.1 billion elements.

Safe out-of-bounds access: Accessing an invalid index returns the appropriate null constant rather than throwing an exception:

from deephaven import empty_table

source = empty_table(3).update("X = ii")

result = source.update(
    [
        "ValidAccess = X_[1]",
        "OutOfBounds = X_[100]",
    ]
)

Efficient slicing: The subVector method creates a view without copying data:

from deephaven import empty_table

source = empty_table(10).update("X = ii").group_by()

result = source.update(
    [
        "Slice = X.subVector(2, 5)",
        "FirstOfSlice = Slice[0]",
    ]
)

Column access with underscore: Access any column as a vector using the _ suffix:

from deephaven import empty_table

source = empty_table(5).update("X = ii")

result = source.update(
    [
        "PrevValue = X_[ii - 1]",
        "NextValue = X_[ii + 1]",
    ]
)

Converting between arrays and vectors

Use the built-in array and vec functions to convert between types:

from deephaven import empty_table

source = empty_table(5).update("X = ii").group_by()

converted = source.update(
    [
        "AsArray = array(X)",
        "BackToVector = vec(AsArray)",
    ]
)
converted_meta = converted.meta_table

Supported conversions

`vec()` input	`array()` input
`byte[]`	`ByteVector`
`char[]`	`CharVector`
`double[]`	`DoubleVector`
`float[]`	`FloatVector`
`int[]`	`IntVector`
`long[]`	`LongVector`
`short[]`	`ShortVector`

Choosing between arrays and vectors

Use Java arrays when:

Passing data to external Java libraries that expect arrays
Working with fixed, known-size data
You need to mutate elements in place.

Use Deephaven vectors when:

Working with grouped table data.
Accessing previous or future row values via Column_[ii ± n].
Slicing data without copying.
Handling potentially large datasets.

Operations that create vectors

The following table operations produce vector columns: