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 batch of rows it was read from: its get(int) and the lazy List views returned by the typed accessors read the column data on each call. The list and its views can be held after the reader moves on and keep reading their own row; while one is reachable, the values of every projected column in that batch stay in memory. To keep a few lists of many rows, copy their elements out instead.

// 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 / ENUM / JSON, LocalDate for DATE, LocalTime for TIME, Instant for TIMESTAMP, BigDecimal for DECIMAL, UUID for UUID, PqInterval for INTERVAL, PqFile for FILE, 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 / ENUM / JSON, etc. Nested groups have no distinct raw form and surface as the same PqStruct / PqList / PqMap flyweight returned by get(int); a FILE element surfaces as the PqStruct of its children.

      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, decoded from UTF-8.
      Throws:
      IllegalArgumentException - if the element does not hold text, as FieldAccessor.getString(String) describes

    • binaries

      List<byte[]> binaries()
      View the elements as a List of binary (byte[]) values. Each get returns a new array.

    • 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. The element column must be a UTC-adjusted TIMESTAMP. For local-wall-clock element columns use localTimestamps().
      Throws:
      IllegalStateException - if the element column is a local-wall-clock TIMESTAMP

    • localTimestamps

      List<LocalDateTime> localTimestamps()
      View the elements as a List of LocalDateTime (local-wall-clock timestamp) values. The element column must be a local-wall-clock TIMESTAMP (isAdjustedToUTC = false). For UTC-adjusted element columns use timestamps().
      Throws:
      IllegalStateException - if the element column is a UTC-adjusted TIMESTAMP

    • 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.

    • files

      List<PqFile> files()
      View the elements as a List of PqFile references, for a list whose element is a group annotated FILE. Reading an element that is not a valid reference throws ParquetReadException, as StructAccessor.getFile(String) does.