Class ColumnBatch

java.lang.Object
dev.hardwood.writer.ColumnBatch
public final class ColumnBatch extends Object

One aligned slice of a file's columns. Every column in a batch must have the same number of values, which is the batch's row count.

A batch is not constructed directly: ColumnWriter.writeBatch(Consumer) creates it, bound to the schema, hands it to a filler that populates the columns, then submits it — so there is no separate build or submit step to forget. Columns are addressed by index or by name, and the schema binding lets every identifier be validated as it is added — an unknown name, an out-of-range index, a column of the wrong physical type, or setting the same column twice (whether by index or name) all fail eagerly rather than at write time.

The values are checked as eagerly. A value outside the range its column's annotation declares — 300 on a UINT_8 column, an unscaled value of more digits than a DECIMAL's precision — is rejected where it is handed over, because writing it produces a file whose values fall outside the range its own annotation declares. The values at rows a column's Validity marks null are never encoded, and so are never checked.

columns.writeBatch(b -> b
        .ints(0, idColumn)
        .ints("value", valueColumn));

An OPTIONAL column carries its nulls as a Validity alongside its values. The values array is full length — one slot per row — and the entry at a null row is ignored. The Validity uses the null-centric polarity the reader exposes (Validity#isNull), so a value read back as null is written by marking that row null. Because Validity is an interface, the caller picks the representation through its factory: Validity.NO_NULLS for none, Validity.ofNulls(boolean[]) to bridge a plain boolean[] mask, Validity.of(long[]) for a packed present-bitmap — and, in the future, a sparse form — all consumed identically by the writer.

columns.writeBatch(b -> b
        .ints(0, idColumn)
        .ints("value", valueColumn, valueNulls));       // boolean[] nulls, true = null

The [#ints(int, int[], boolean[])] overload is convenience sugar over Validity.ofNulls(boolean[]). The mask-less [#ints(int, int[])] setter is the all-present form for both REQUIRED and OPTIONAL columns; a null mask is only accepted for an OPTIONAL column.

  • Method Summary

    Modifier and Type
    Method
    Description
    ColumnBatch
    booleans(int columnIndex, boolean[] values)
    Adds the values for a REQUIRED BOOLEAN column, addressed by index.
    ColumnBatch
    booleans(int columnIndex, boolean[] values, boolean[] nulls)
    Adds the values for an OPTIONAL BOOLEAN column, addressed by index, with a plain mask.
    ColumnBatch
    booleans(int columnIndex, boolean[] values, Validity nulls)
    Adds the values for an OPTIONAL BOOLEAN column, addressed by index.
    ColumnBatch
    booleans(String columnName, boolean[] values)
    Adds the values for a REQUIRED BOOLEAN column, addressed by name.
    ColumnBatch
    booleans(String columnName, boolean[] values, boolean[] nulls)
    Adds the values for an OPTIONAL BOOLEAN column, addressed by name, with a plain mask.
    ColumnBatch
    booleans(String columnName, boolean[] values, Validity nulls)
    Adds the values for an OPTIONAL BOOLEAN column, addressed by name.
    ColumnBatch
    bytes(int columnIndex, byte[][] values)
    Adds the values for a REQUIRED BYTE_ARRAY column, addressed by index.
    ColumnBatch
    bytes(int columnIndex, byte[][] values, boolean[] nulls)
    Adds the values for an OPTIONAL BYTE_ARRAY column, addressed by index, with a plain mask.
    ColumnBatch
    bytes(int columnIndex, byte[][] values, Validity nulls)
    Adds the values for an OPTIONAL BYTE_ARRAY column, addressed by index.
    ColumnBatch
    bytes(String columnName, byte[][] values)
    Adds the values for a REQUIRED BYTE_ARRAY column, addressed by name.
    ColumnBatch
    bytes(String columnName, byte[][] values, boolean[] nulls)
    Adds the values for an OPTIONAL BYTE_ARRAY column, addressed by name, with a plain mask.
    ColumnBatch
    bytes(String columnName, byte[][] values, Validity nulls)
    Adds the values for an OPTIONAL BYTE_ARRAY column, addressed by name.
    ColumnBatch
    doubles(int columnIndex, double[] values)
    Adds the values for a REQUIRED DOUBLE column, addressed by index.
    ColumnBatch
    doubles(int columnIndex, double[] values, boolean[] nulls)
    Adds the values for an OPTIONAL DOUBLE column, addressed by index, with a plain mask.
    ColumnBatch
    doubles(int columnIndex, double[] values, Validity nulls)
    Adds the values for an OPTIONAL DOUBLE column, addressed by index.
    ColumnBatch
    doubles(String columnName, double[] values)
    Adds the values for a REQUIRED DOUBLE column, addressed by name.
    ColumnBatch
    doubles(String columnName, double[] values, boolean[] nulls)
    Adds the values for an OPTIONAL DOUBLE column, addressed by name, with a plain mask.
    ColumnBatch
    doubles(String columnName, double[] values, Validity nulls)
    Adds the values for an OPTIONAL DOUBLE column, addressed by name.
    ColumnBatch
    fixed(int columnIndex, byte[][] values)
    Adds the values for a REQUIRED FIXED_LEN_BYTE_ARRAY column, addressed by index.
    ColumnBatch
    fixed(int columnIndex, byte[][] values, boolean[] nulls)
    Adds the values for an OPTIONAL FIXED_LEN_BYTE_ARRAY column, addressed by index, with a plain mask.
    ColumnBatch
    fixed(int columnIndex, byte[][] values, Validity nulls)
    Adds the values for an OPTIONAL FIXED_LEN_BYTE_ARRAY column, addressed by index.
    ColumnBatch
    fixed(String columnName, byte[][] values)
    Adds the values for a REQUIRED FIXED_LEN_BYTE_ARRAY column, addressed by name.
    ColumnBatch
    fixed(String columnName, byte[][] values, boolean[] nulls)
    Adds the values for an OPTIONAL FIXED_LEN_BYTE_ARRAY column, addressed by name, with a plain mask.
    ColumnBatch
    fixed(String columnName, byte[][] values, Validity nulls)
    Adds the values for an OPTIONAL FIXED_LEN_BYTE_ARRAY column, addressed by name.
    ColumnBatch
    floats(int columnIndex, float[] values)
    Adds the values for a REQUIRED FLOAT column, addressed by index.
    ColumnBatch
    floats(int columnIndex, float[] values, boolean[] nulls)
    Adds the values for an OPTIONAL FLOAT column, addressed by index, with a plain mask.
    ColumnBatch
    floats(int columnIndex, float[] values, Validity nulls)
    Adds the values for an OPTIONAL FLOAT column, addressed by index.
    ColumnBatch
    floats(String columnName, float[] values)
    Adds the values for a REQUIRED FLOAT column, addressed by name.
    ColumnBatch
    floats(String columnName, float[] values, boolean[] nulls)
    Adds the values for an OPTIONAL FLOAT column, addressed by name, with a plain mask.
    ColumnBatch
    floats(String columnName, float[] values, Validity nulls)
    Adds the values for an OPTIONAL FLOAT column, addressed by name.
    ColumnBatch
    ints(int columnIndex, int[] values)
    Adds the values for a REQUIRED INT32 column, addressed by index.
    ColumnBatch
    ints(int columnIndex, int[] values, boolean[] nulls)
    Adds the values for an OPTIONAL INT32 column, addressed by index, with nulls given as a plain mask.
    ColumnBatch
    ints(int columnIndex, int[] values, Validity nulls)
    Adds the values for an OPTIONAL INT32 column, addressed by index.
    ColumnBatch
    ints(String columnName, int[] values)
    Adds the values for a REQUIRED INT32 column, addressed by name.
    ColumnBatch
    ints(String columnName, int[] values, boolean[] nulls)
    Adds the values for an OPTIONAL INT32 column, addressed by name, with nulls given as a plain mask.
    ColumnBatch
    ints(String columnName, int[] values, Validity nulls)
    Adds the values for an OPTIONAL INT32 column, addressed by name.
    ColumnBatch
    list(String listPath, int[] offsets)
    Sets the entry offsets of a LIST, addressed by the list group's dot-separated path.
    ColumnBatch
    list(String listPath, int[] offsets, Validity nulls)
    Sets the entry offsets of a LIST together with its per-instance nulls (which lists are themselves absent), distinct from an empty list carrying a zero-delta offset.
    ColumnBatch
    longs(int columnIndex, long[] values)
    Adds the values for a REQUIRED INT64 column, addressed by index.
    ColumnBatch
    longs(int columnIndex, long[] values, boolean[] nulls)
    Adds the values for an OPTIONAL INT64 column, addressed by index, with a plain mask.
    ColumnBatch
    longs(int columnIndex, long[] values, Validity nulls)
    Adds the values for an OPTIONAL INT64 column, addressed by index.
    ColumnBatch
    longs(String columnName, long[] values)
    Adds the values for a REQUIRED INT64 column, addressed by name.
    ColumnBatch
    longs(String columnName, long[] values, boolean[] nulls)
    Adds the values for an OPTIONAL INT64 column, addressed by name, with a plain mask.
    ColumnBatch
    longs(String columnName, long[] values, Validity nulls)
    Adds the values for an OPTIONAL INT64 column, addressed by name.
    ColumnBatch
    map(String mapPath, int[] offsets)
    Sets the entry offsets of a MAP, addressed by the map group's dot-separated path.
    ColumnBatch
    map(String mapPath, int[] offsets, Validity nulls)
    Sets the entry offsets of a MAP together with its per-instance nulls (which maps are themselves absent), distinct from an empty map carrying a zero-delta offset.
    ColumnBatch
    struct(String structPath, Validity nulls)
    Sets the per-instance nulls of an OPTIONAL struct group, addressed by its dot-separated path.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • struct

      @Experimental public ColumnBatch struct(String structPath, Validity nulls)
      Sets the per-instance nulls of an OPTIONAL struct group, addressed by its dot-separated path. Omitting the call leaves every instance of the group present. The values of leaf columns beneath a null struct instance are ignored.
      Parameters:
      structPath - the group's path (e.g. "address")
      nulls - the group's nulls; nulls.isNull(i) marks instance i absent
      Returns:
      this batch, for chaining
      Throws:
      IllegalArgumentException - if the path does not name an OPTIONAL struct group, or the group is already set in this batch

    • list

      @Experimental public ColumnBatch list(String listPath, int[] offsets)
      Sets the entry offsets of a LIST, addressed by the list group's dot-separated path. offsets has length parentCount + 1; offsets[i+1] - offsets[i] is the number of entries of list i, and a zero delta is an empty list. The list's element leaf is filled separately through ints(int, int[]), its values holding the concatenated entries.
      Parameters:
      listPath - the list group's path (e.g. "phones")
      offsets - the entry offsets
      Returns:
      this batch, for chaining
      Throws:
      IllegalArgumentException - if the path does not name a LIST, the list is already set, or offsets is empty

    • list

      @Experimental public ColumnBatch list(String listPath, int[] offsets, Validity nulls)
      Sets the entry offsets of a LIST together with its per-instance nulls (which lists are themselves absent), distinct from an empty list carrying a zero-delta offset.
      Parameters:
      listPath - the list group's path
      offsets - the entry offsets
      nulls - the list nulls; nulls.isNull(i) marks list i absent
      Returns:
      this batch, for chaining
      Throws:
      IllegalArgumentException - if the path does not name an OPTIONAL LIST, the list is already set, or offsets is empty

    • map

      @Experimental public ColumnBatch map(String mapPath, int[] offsets)
      Sets the entry offsets of a MAP, addressed by the map group's dot-separated path. A thin alias over [#list(String, int[])]: the map's key and value leaves share this one offsets array, offsets[i+1] - offsets[i] being the number of entries of map i, and a zero delta an empty map. The key and value leaves are filled through ints(int, int[]) at <mapPath>.key_value.key and <mapPath>.key_value.value.
      Parameters:
      mapPath - the map group's path (e.g. "props")
      offsets - the entry offsets
      Returns:
      this batch, for chaining
      Throws:
      IllegalArgumentException - if the path does not name a MAP, the map is already set, or offsets is empty

    • map

      @Experimental public ColumnBatch map(String mapPath, int[] offsets, Validity nulls)
      Sets the entry offsets of a MAP together with its per-instance nulls (which maps are themselves absent), distinct from an empty map carrying a zero-delta offset.
      Parameters:
      mapPath - the map group's path
      offsets - the entry offsets
      nulls - the map nulls; nulls.isNull(i) marks map i absent
      Returns:
      this batch, for chaining
      Throws:
      IllegalArgumentException - if the path does not name an OPTIONAL MAP, the map is already set, or offsets is empty

    • ints

      public ColumnBatch ints(int columnIndex, int[] values)

      Adds the values for a REQUIRED INT32 column, addressed by index.

      The array is referenced, not copied, so it must not be mutated until the batch has been written. Every physical type has the same setter shapes (longs, floats, doubles, booleans, …): by index or name, all-present or nullable (Validity or boolean[] mask).

      Parameters:
      columnIndex - zero-based leaf-column index
      values - the column's values for this batch
      Returns:
      this batch, for chaining
      Throws:
      IndexOutOfBoundsException - if columnIndex is not in [0, leaf column count)
      IllegalArgumentException - if the column is not INT32, the column is already set, a value falls outside the range the column's annotation declares, or the length does not match the other columns in this batch

    • ints

      public ColumnBatch ints(String columnName, int[] values)
      Adds the values for a REQUIRED INT32 column, addressed by name.
      See Also:

    • ints

      @Experimental public ColumnBatch ints(int columnIndex, int[] values, Validity nulls)
      Adds the values for an OPTIONAL INT32 column, addressed by index. The values array is full length — one slot per row — and the entry at a null row is ignored.
      Parameters:
      columnIndex - zero-based leaf-column index
      values - the column's values for this batch
      nulls - the column's nulls; nulls.isNull(i) marks row i null
      Returns:
      this batch, for chaining
      Throws:
      IndexOutOfBoundsException - if columnIndex is not in [0, leaf column count)
      IllegalArgumentException - if the column is not OPTIONAL INT32, the column is already set, or a value at a present row falls outside the range the column's annotation declares

    • ints

      @Experimental public ColumnBatch ints(String columnName, int[] values, Validity nulls)
      Adds the values for an OPTIONAL INT32 column, addressed by name.
      See Also:

    • ints

      @Experimental public ColumnBatch ints(int columnIndex, int[] values, boolean[] nulls)
      Adds the values for an OPTIONAL INT32 column, addressed by index, with nulls given as a plain mask. Convenience sugar over [#ints(int, int[], Validity)] and Validity.ofNulls(boolean[]); unlike the Validity form, the mask length is checked against the values.
      Parameters:
      columnIndex - zero-based leaf-column index
      values - the column's values for this batch
      nulls - the per-row null mask; nulls[i] == true marks row i null
      Returns:
      this batch, for chaining
      Throws:
      IndexOutOfBoundsException - if columnIndex is not in [0, leaf column count)
      IllegalArgumentException - if the column is not OPTIONAL INT32, the column is already set, or the lengths do not agree

    • ints

      @Experimental public ColumnBatch ints(String columnName, int[] values, boolean[] nulls)
      Adds the values for an OPTIONAL INT32 column, addressed by name, with nulls given as a plain mask.
      See Also:

    • longs

      public ColumnBatch longs(int columnIndex, long[] values)
      Adds the values for a REQUIRED INT64 column, addressed by index.
      See Also:

    • longs

      public ColumnBatch longs(String columnName, long[] values)
      Adds the values for a REQUIRED INT64 column, addressed by name.
      See Also:

    • longs

      @Experimental public ColumnBatch longs(int columnIndex, long[] values, Validity nulls)
      Adds the values for an OPTIONAL INT64 column, addressed by index.
      See Also:

    • longs

      @Experimental public ColumnBatch longs(String columnName, long[] values, Validity nulls)
      Adds the values for an OPTIONAL INT64 column, addressed by name.
      See Also:

    • longs

      @Experimental public ColumnBatch longs(int columnIndex, long[] values, boolean[] nulls)
      Adds the values for an OPTIONAL INT64 column, addressed by index, with a plain mask.
      See Also:

    • longs

      @Experimental public ColumnBatch longs(String columnName, long[] values, boolean[] nulls)
      Adds the values for an OPTIONAL INT64 column, addressed by name, with a plain mask.
      See Also:

    • floats

      public ColumnBatch floats(int columnIndex, float[] values)
      Adds the values for a REQUIRED FLOAT column, addressed by index.
      See Also:

    • floats

      public ColumnBatch floats(String columnName, float[] values)
      Adds the values for a REQUIRED FLOAT column, addressed by name.
      See Also:

    • floats

      @Experimental public ColumnBatch floats(int columnIndex, float[] values, Validity nulls)
      Adds the values for an OPTIONAL FLOAT column, addressed by index.
      See Also:

    • floats

      @Experimental public ColumnBatch floats(String columnName, float[] values, Validity nulls)
      Adds the values for an OPTIONAL FLOAT column, addressed by name.
      See Also:

    • floats

      @Experimental public ColumnBatch floats(int columnIndex, float[] values, boolean[] nulls)
      Adds the values for an OPTIONAL FLOAT column, addressed by index, with a plain mask.
      See Also:

    • floats

      @Experimental public ColumnBatch floats(String columnName, float[] values, boolean[] nulls)
      Adds the values for an OPTIONAL FLOAT column, addressed by name, with a plain mask.
      See Also:

    • doubles

      public ColumnBatch doubles(int columnIndex, double[] values)
      Adds the values for a REQUIRED DOUBLE column, addressed by index.
      See Also:

    • doubles

      public ColumnBatch doubles(String columnName, double[] values)
      Adds the values for a REQUIRED DOUBLE column, addressed by name.
      See Also:

    • doubles

      @Experimental public ColumnBatch doubles(int columnIndex, double[] values, Validity nulls)
      Adds the values for an OPTIONAL DOUBLE column, addressed by index.
      See Also:

    • doubles

      @Experimental public ColumnBatch doubles(String columnName, double[] values, Validity nulls)
      Adds the values for an OPTIONAL DOUBLE column, addressed by name.
      See Also:

    • doubles

      @Experimental public ColumnBatch doubles(int columnIndex, double[] values, boolean[] nulls)
      Adds the values for an OPTIONAL DOUBLE column, addressed by index, with a plain mask.
      See Also:

    • doubles

      @Experimental public ColumnBatch doubles(String columnName, double[] values, boolean[] nulls)
      Adds the values for an OPTIONAL DOUBLE column, addressed by name, with a plain mask.
      See Also:

    • booleans

      public ColumnBatch booleans(int columnIndex, boolean[] values)
      Adds the values for a REQUIRED BOOLEAN column, addressed by index.
      See Also:

    • booleans

      public ColumnBatch booleans(String columnName, boolean[] values)
      Adds the values for a REQUIRED BOOLEAN column, addressed by name.
      See Also:

    • booleans

      @Experimental public ColumnBatch booleans(int columnIndex, boolean[] values, Validity nulls)
      Adds the values for an OPTIONAL BOOLEAN column, addressed by index.
      See Also:

    • booleans

      @Experimental public ColumnBatch booleans(String columnName, boolean[] values, Validity nulls)
      Adds the values for an OPTIONAL BOOLEAN column, addressed by name.
      See Also:

    • booleans

      @Experimental public ColumnBatch booleans(int columnIndex, boolean[] values, boolean[] nulls)
      Adds the values for an OPTIONAL BOOLEAN column, addressed by index, with a plain mask.
      See Also:

    • booleans

      @Experimental public ColumnBatch booleans(String columnName, boolean[] values, boolean[] nulls)
      Adds the values for an OPTIONAL BOOLEAN column, addressed by name, with a plain mask.
      See Also:

    • bytes

      public ColumnBatch bytes(int columnIndex, byte[][] values)
      Adds the values for a REQUIRED BYTE_ARRAY column, addressed by index. Each value is a byte[]; the arrays are referenced, not copied.
      See Also:

    • bytes

      public ColumnBatch bytes(String columnName, byte[][] values)
      Adds the values for a REQUIRED BYTE_ARRAY column, addressed by name.
      See Also:

    • bytes

      @Experimental public ColumnBatch bytes(int columnIndex, byte[][] values, Validity nulls)
      Adds the values for an OPTIONAL BYTE_ARRAY column, addressed by index.
      See Also:

    • bytes

      @Experimental public ColumnBatch bytes(String columnName, byte[][] values, Validity nulls)
      Adds the values for an OPTIONAL BYTE_ARRAY column, addressed by name.
      See Also:

    • bytes

      @Experimental public ColumnBatch bytes(int columnIndex, byte[][] values, boolean[] nulls)
      Adds the values for an OPTIONAL BYTE_ARRAY column, addressed by index, with a plain mask.
      See Also:

    • bytes

      @Experimental public ColumnBatch bytes(String columnName, byte[][] values, boolean[] nulls)
      Adds the values for an OPTIONAL BYTE_ARRAY column, addressed by name, with a plain mask.
      See Also:

    • fixed

      public ColumnBatch fixed(int columnIndex, byte[][] values)
      Adds the values for a REQUIRED FIXED_LEN_BYTE_ARRAY column, addressed by index. Every present value must be exactly the column's declared type length.
      See Also:

    • fixed

      public ColumnBatch fixed(String columnName, byte[][] values)
      Adds the values for a REQUIRED FIXED_LEN_BYTE_ARRAY column, addressed by name.
      See Also:

    • fixed

      @Experimental public ColumnBatch fixed(int columnIndex, byte[][] values, Validity nulls)
      Adds the values for an OPTIONAL FIXED_LEN_BYTE_ARRAY column, addressed by index.
      See Also:

    • fixed

      @Experimental public ColumnBatch fixed(String columnName, byte[][] values, Validity nulls)
      Adds the values for an OPTIONAL FIXED_LEN_BYTE_ARRAY column, addressed by name.
      See Also:

    • fixed

      @Experimental public ColumnBatch fixed(int columnIndex, byte[][] values, boolean[] nulls)
      Adds the values for an OPTIONAL FIXED_LEN_BYTE_ARRAY column, addressed by index, with a plain mask.
      See Also:

    • fixed

      @Experimental public ColumnBatch fixed(String columnName, byte[][] values, boolean[] nulls)
      Adds the values for an OPTIONAL FIXED_LEN_BYTE_ARRAY column, addressed by name, with a plain mask.
      See Also: