Package io.deephaven.extensions.barrage.chunk

Interface ExpansionKernel<T>

Type Parameters:
T - The type of data being processed by this kernel.
All Known Subinterfaces:
ArrayExpansionKernel<T>, VectorExpansionKernel<T>
All Known Implementing Classes:
BooleanArrayExpansionKernel, BooleanVectorExpansionKernel, BoxedBooleanArrayExpansionKernel, ByteArrayExpansionKernel, ByteVectorExpansionKernel, CharArrayExpansionKernel, CharVectorExpansionKernel, DoubleArrayExpansionKernel, DoubleVectorExpansionKernel, FloatArrayExpansionKernel, FloatVectorExpansionKernel, IntArrayExpansionKernel, IntVectorExpansionKernel, LongArrayExpansionKernel, LongVectorExpansionKernel, ObjectArrayExpansionKernel, ObjectVectorExpansionKernel, ShortArrayExpansionKernel, ShortVectorExpansionKernel
public interface ExpansionKernel<T>
The ExpansionKernel interface provides methods for transforming chunks containing complex or nested data structures into flattened representations, and vice versa. This enables efficient handling of columnar data in scenarios involving arrays, or vectors, particularly within the Deephaven Barrage extensions for Flight/Barrage streams.

An ExpansionKernel supports two primary operations:

  • Expansion: Converts nested or multi-element data into a flattened form, along with metadata (e.g., row offsets) describing the original structure.
  • Contraction: Reconstructs the original nested data structure from a flattened representation and associated metadata.

  • Method Summary

    Modifier and Type
    Method
    Description
    default int
    computeSize(int ii, int sizePerOffset, @Nullable IntChunk<ChunkPositions> offsets, @Nullable IntChunk<ChunkLengths> lengths)
    Computes the length of a row at the specified index, based on provided metadata (offsets and lengths).
    <A extends Any>
    WritableObjectChunk<T,A>
    contract(@NotNull Chunk<A> source, int sizePerElement, @Nullable IntChunk<ChunkPositions> offsets, @Nullable IntChunk<ChunkLengths> lengths, @Nullable WritableChunk<A> outChunk, int outOffset, int totalRows)
    Contracts a flattened chunk of elements (T) back into a chunk of nested or multi-element data (T[] or Vector<T>), using provided metadata (e.g., row offsets or lengths) to reconstruct the original structure.
    <A extends Any>
    WritableChunk<A>
    expand(@NotNull ObjectChunk<T,A> source, int fixedSizeLength, @Nullable WritableIntChunk<ChunkPositions> offsetDest)
    Expands a chunk of nested or multi-element data (T[] or Vector<T>) into a flattened chunk of elements (T), along with metadata describing the structure of the original data.

  • Method Details

    • expand

      <A extends Any> WritableChunk<A> expand(@NotNull @NotNull ObjectChunk<T,A> source, int fixedSizeLength, @Nullable @Nullable WritableIntChunk<ChunkPositions> offsetDest)
      Expands a chunk of nested or multi-element data (T[] or Vector<T>) into a flattened chunk of elements (T), along with metadata describing the structure of the original data.

      The expansion involves unrolling arrays, or vectors, or other multi-element types into a single contiguous chunk. The number of elements belonging to each original row is recorded in offsetDest, which allows reconstructing the original structure when needed.

      If a non-zero fixedSizeLength is provided, each row will be truncated or padded with nulls to match the fixed size. A negative fixedSizeLength will pick elements from the end of the array/vector.

      Type Parameters:
      A - The attribute type of the source chunk.
      Parameters:
      source - The source chunk containing nested or multi-element data to expand.
      fixedSizeLength - The fixed size for each row, or 0 for variable-length rows. A negative value will pick elements from the end.
      offsetDest - The destination WritableIntChunk to store row offsets, or null if not needed.
      Returns:
      A flattened WritableChunk containing the expanded elements.

    • contract

      <A extends Any> WritableObjectChunk<T,A> contract(@NotNull @NotNull Chunk<A> source, int sizePerElement, @Nullable @Nullable IntChunk<ChunkPositions> offsets, @Nullable @Nullable IntChunk<ChunkLengths> lengths, @Nullable @Nullable WritableChunk<A> outChunk, int outOffset, int totalRows)
      Contracts a flattened chunk of elements (T) back into a chunk of nested or multi-element data (T[] or Vector<T>), using provided metadata (e.g., row offsets or lengths) to reconstruct the original structure.

      The contraction process supports multiple configurations:

      • If offsets is null, each row is assumed to have a fixed size defined by sizePerElement.
      • If lengths is null, each row's size is determined by differences between adjacent elements in offsets. An element's length is determined by subtracting its offset from the next offset, therefore offsets must contain one more element than the number of elements.
      • If both offsets and lengths are provided, lengths determines the row sizes.
      Type Parameters:
      A - The attribute type of the source chunk.
      Parameters:
      source - The source chunk containing flattened data to contract.
      sizePerElement - The fixed size for each row, or 0 for variable-length rows.
      offsets - An IntChunk describing row start positions, or null.
      lengths - An IntChunk describing row lengths, or null.
      outChunk - A reusable WritableChunk to store the contracted result, or null.
      outOffset - The starting position for writing into outChunk.
      totalRows - The total number of rows, or 0 if unknown.
      Returns:
      A WritableObjectChunk containing the reconstructed nested or multi-element data.

    • computeSize

      @FinalDefault default int computeSize(int ii, int sizePerOffset, @Nullable @Nullable IntChunk<ChunkPositions> offsets, @Nullable @Nullable IntChunk<ChunkLengths> lengths)
      Computes the length of a row at the specified index, based on provided metadata (offsets and lengths).

      The size computation follows these rules:

      • If offsets is null, each row is assumed to have a fixed size of sizePerOffset.
      • If lengths is null, the size is calculated from adjacent elements in offsets.
      • If both offsets and lengths are provided, lengths determines the row size.
      Parameters:
      ii - The row index for which to compute the size.
      sizePerOffset - The fixed size for each row, if applicable.
      offsets - An IntChunk describing row start positions, or null.
      lengths - An IntChunk describing row lengths, or null.
      Returns:
      The size of the row at the specified index.