Interface PqList

public interface PqList

Type-safe list interface for reading Parquet list values.

Provides type-specific accessor methods for iterating over list elements. Primitive int/long/double element lists surface as the dedicated PqIntList / PqLongList / PqDoubleList types (with PrimitiveIterator.OfInt and friends — no boxing). All other typed accessors return List.

A PqList is a flyweight over the underlying read batch — its get(int) and the lazy List views returned by the typed accessors resolve to column data on each call. The flyweight is valid for as long as the batch it was obtained from is current; it is not safe to hold across rowReader.next() calls.

// String list
PqList tags = rowReader.getList("tags");
for (String tag : tags.strings()) {
    System.out.println(tag);
}

// Nested struct list
PqList items = rowReader.getList("items");
for (PqStruct item : items.structs()) {
    String name = item.getString("name");
}

// Primitive int list — no boxing
PqList scores = rowReader.getList("scores");
PqIntList ints = scores.ints();
for (var it = ints.iterator(); it.hasNext(); ) {
    int v = it.nextInt();
}

// Nested list (2D matrix)
PqList matrix = rowReader.getList("matrix");
for (PqList row : matrix.lists()) {
    PqIntList ints = row.ints();
    for (var it = ints.iterator(); it.hasNext(); ) {
        int value = it.nextInt();
    }
}

// Triple nested list (3D cube)
PqList cube = rowReader.getList("cube");
for (PqList plane : cube.lists()) {
    for (PqList row : plane.lists()) {
        PqIntList ints = row.ints();
        // ...
    }
}

  • Method Details

    • size

      int size()
      Get the number of elements in this list.
      Returns:
      the element count

    • isEmpty

      boolean isEmpty()
      Check if this list is empty.
      Returns:
      true if the list has no elements

    • get

      Object get(int index)

      Get an element by index, decoded to its logical-type representation.

      Returns the value in the same form as the typed accessors below: Integer / Long / Float / Double / Boolean for primitives, String for STRING, LocalDate for DATE, LocalTime for TIME, Instant for TIMESTAMP, BigDecimal for DECIMAL, UUID for UUID, PqInterval for INTERVAL, and byte[] for BYTE_ARRAY / FIXED_LEN_BYTE_ARRAY with no logical-type annotation. Nested groups surface as PqStruct / PqList / PqMap.

      Parameters:
      index - the element index (0-based)
      Returns:
      the decoded element value, or null if the element is null
      Throws:
      IndexOutOfBoundsException - if index is out of range

    • isNull

      boolean isNull(int index)
      Check if an element is null by index.
      Parameters:
      index - the element index (0-based)
      Returns:
      true if the element is null

    • values

      List<Object> values()

      View the elements as a List, each decoded to its logical-type representation.

      Element types match get(int): Integer / String / LocalDate / Instant / BigDecimal / UUID / PqInterval / etc., with byte[] for un-annotated BYTE_ARRAY / FIXED_LEN_BYTE_ARRAY columns and PqStruct / PqList / PqMap for nested groups. The returned list is a live view: each get(int) decodes lazily on demand.

    • getRaw

      Object getRaw(int index)

      Get an element by index in its underlying physical form, mirroring the getRawValue accessors on RowReader / PqStruct / PqMap.Entry.

      Returns Integer / Long / Float / Double / Boolean / byte[] for the physical storage type — Long micros instead of Instant for TIMESTAMP(MICROS), unscaled byte[] instead of BigDecimal for DECIMAL, byte[] instead of String for STRING / JSON, etc. Nested groups have no distinct raw form and surface as the same PqStruct / PqList / PqMap flyweight returned by get(int).

      Parameters:
      index - the element index (0-based)
      Returns:
      the raw element value, or null if the element is null
      Throws:
      IndexOutOfBoundsException - if index is out of range

    • rawValues

      List<Object> rawValues()
      View the elements as a List in their underlying physical form, as in getRaw(int).

    • ints

      PqIntList ints()
      View the elements as a PqIntList (no boxing).

    • longs

      PqLongList longs()
      View the elements as a PqLongList (no boxing).

    • floats

      List<Float> floats()
      View the elements as a List of float values.

    • doubles

      PqDoubleList doubles()
      View the elements as a PqDoubleList (no boxing).

    • booleans

      List<Boolean> booleans()
      View the elements as a List of boolean values.

    • strings

      List<String> strings()
      View the elements as a List of String values.

    • binaries

      List<byte[]> binaries()
      View the elements as a List of binary (byte[]) values.

    • dates

      List<LocalDate> dates()
      View the elements as a List of LocalDate values.

    • times

      List<LocalTime> times()
      View the elements as a List of LocalTime values.

    • timestamps

      List<Instant> timestamps()
      View the elements as a List of Instant (timestamp) values.

    • decimals

      List<BigDecimal> decimals()
      View the elements as a List of BigDecimal values.

    • uuids

      List<UUID> uuids()
      View the elements as a List of UUID values.

    • intervals

      List<PqInterval> intervals()
      View the elements as a List of PqInterval values.

    • structs

      List<PqStruct> structs()
      View the elements as a List of nested structs.

    • lists

      List<PqList> lists()
      View the elements as a List of nested lists. Use this for list-of-list structures; call ints() / longs() / doubles() on the inner PqList for primitive-typed inner lists.

    • maps

      List<PqMap> maps()
      View the elements as a List of nested maps.

    • variants

      List<PqVariant> variants()

      View the elements as a List of PqVariant values.

      Only unshredded variants are supported in repeated contexts today; iterating a list of shredded variants throws UnsupportedOperationException on first access.