Core: Interface based DataFile reader and writer API - PoC #12298

pvary · 2025-02-17T15:03:50Z

Here is what the PR does:

Created 3 interface classes which are implemented by the file formats:
- ReadBuilder - Builder for reading data from data files
- AppenderBuilder - Builder for writing data to data files
- ObjectModel - Providing ReadBuilders, and AppenderBuilders for the specific data file format and object model pair
Updated the Parquet, Avro, ORC implementation for this interfaces, and deprecated the old reader/writer APIs
Created interface classes which will be used by the actual readers/writers of the data files:
- AppenderBuilder - Builder for writing a file
- DataWriterBuilder - Builder for generating a data file
- PositionDeleteWriterBuilder - Builder for generating a position delete file
- EqualityDeleteWriterBuilder - Builder for generating an equality delete file
- No ReadBuilder here - the file format reader builder is reused
Created a WriterBuilder class which implements the interfaces above (AppenderBuilder/DataWriterBuilder/PositionDeleteWriterBuilder/EqualityDeleteWriterBuilder) based on a provided file format specific AppenderBuilder
Created an ObjectModelRegistry which stores the available ObjectModels, and engines and users could request the readers (ReadBuilder) and writers (AppenderBuilder/DataWriterBuilder/PositionDeleteWriterBuilder/EqualityDeleteWriterBuilder) from.
Created the appropriate ObjectModels:
- GenericObjectModels - for reading and writing Iceberg Records
- SparkObjectModels - for reading (vectorized and non-vectorized) and writing Spark InternalRow/ColumnarBatch objects
- FlinkObjectModels - for reading and writing Flink RowData objects
- An arrow object model is also registered for vectorized reads of Parquet files into Arrow ColumnarBatch objects
Updated the production code where the reading and writing happens to use the ObjectModelRegistry and the new reader/writer interfaces to access data files
Kept the testing code intact to ensure that the new API/code is not breaking anything

core/src/main/java/org/apache/iceberg/io/datafile/DataFileServiceRegistry.java

snazy · 2025-02-18T15:52:38Z

core/src/main/java/org/apache/iceberg/io/datafile/DataFileServiceRegistry.java

+    public Key(FileFormat fileFormat, String dataType, String builderType) {
+      this.fileFormat = fileFormat;
+      this.dataType = dataType;
+      this.builderType = builderType;


I was thinking of defining the default one using a priority (int) based approach and let the one with the highest priority be the default one. WDYT?

We have a concrete example for this: Comet vectorized parquet reader spark.sql.iceberg.parquet.reader-type

I think it is good if the reader/writer choice is a conscious decision, and not happening based on some behind the scenes algorithm.

+1 for simplicity. This code should not determine things like whether Comet is used. This should have a single purpose, which is to standardize how object models plug in.

Moved the config to properties, and the builder method will create the different readers based on this config

snazy · 2025-02-18T15:56:34Z

core/src/main/java/org/apache/iceberg/io/datafile/AppenderBuilder.java

+import org.apache.iceberg.io.FileAppender;
+
+/** Builder API for creating {@link FileAppender}s. */
+public interface AppenderBuilder extends InternalData.WriteBuilder {


Wonder that AppenderBuilder has a base interface but the other builders don't.
Guess it might help to have a common DataFileIoBuilder interface defining the common builder attributes (table, schema, properties, meta). It's a bit of an "adventure in Java generics", but doable.

If you take a look at the other PRs (#12164, #12069), you can see that first, I took that adventurous route, but the result was too many classes/interfaces and casts.

This PR is aiming for the minimal set of changes, and the InternalData.WriteBuilder is already introduced to Iceberg by #12060. We either need to widen that interface or inherit from it here.

I'm also confused by this inheritance. We're extending but overriding everything and it's not clear to me what we really gain by going with this approach. It looks like it ends up as a completely different builder that produces the same build result.

The goal with the PR was to show the minimal changes required to make the idea work.
We either create a different builder class for the InternalData.WriteBuilder and the DataFile.WriteBuilder, or we need to have inheritance of the interfaces.

Based on our discussion below we might end up using a different strategy, so revisit this comment later.

snazy · 2025-02-18T15:57:46Z

data/src/main/java/org/apache/iceberg/data/GenericReader.java

+    return DataFileServiceRegistry.read(
+            task.file().format(), Record.class.getName(), input, fileProjection, partition)
+        .split(task.start(), task.length())
+        .caseSensitive(caseSensitive)
+        .reuseContainers(reuseContainers)
+        .filter(task.residual())
+        .build();


I like these simplifications!

liurenjie1024

Thanks @pvary for this proposal, I left some comments.

liurenjie1024 · 2025-02-21T09:55:30Z

core/src/main/java/org/apache/iceberg/io/datafile/ReaderBuilder.java

+
+  /** Enables reusing the containers returned by the reader. Decreases pressure on GC. */
+  @Override
+  default ReaderBuilder reuseContainers() {


Seems it should not be here? These are parquet reader specific.

It is also used by Avro.
See:

iceberg/core/src/main/java/org/apache/iceberg/avro/AvroIterable.java

Line 51 in 604422b

this.reuseContainers = reuseContainers;

liurenjie1024 · 2025-02-21T09:57:56Z

core/src/main/java/org/apache/iceberg/io/datafile/DataFileServiceRegistry.java

+   * @param rowType of the native input data
+   * @return {@link DataWriterBuilder} for building the actual writer
+   */
+  public static <S> DataWriterBuilder dataWriterBuilder(


I don't quite understand in what case need this? I think append would be enough?

I will check this. We might be able to remove this.

Based on the current approach, the file format api implementation creates the appender, and the PR creates the writers for the different data/delete files

liurenjie1024 · 2025-02-21T09:59:32Z

core/src/main/java/org/apache/iceberg/io/datafile/DataFileServiceRegistry.java

+   * @return {@link AppenderBuilder} for building the actual writer
+   */
+  public static <S, B extends EqualityDeleteWriterBuilder<B>>
+      EqualityDeleteWriterBuilder<B> equalityDeleteWriterBuilder(


I don't think file format should consider eqaulity deletion/pos deletion here.

Current Avro positional delete writer behaves differently than Parquet/ORC positional delete writers.
In case of the positional delete files the schema provided to the Avro writer should omit the PATH and the POS fields, and only needs the actual table schema. The writer handles the PATH/POS fields by static code:

iceberg/core/src/main/java/org/apache/iceberg/avro/Avro.java

Lines 614 to 618 in b8fdd84

public void write(PositionDelete<D> delete, Encoder out) throws IOException {

PATH_WRITER.write(delete.path(), out);

POS_WRITER.write(delete.pos(), out);

rowWriter.write(delete.row(), out);

}

The Parquet/ORC positional delete writers behave in the same way. They expect the same input.

If we are ready for a more invasive change we can harmonize the writers.
I have aimed for a minimal changeset to allow easier acceptance for the PR.

The appender doesn't need to know about these, but the file formats and the writer implementations need this

liurenjie1024 · 2025-02-21T10:04:29Z

core/src/main/java/org/apache/iceberg/io/datafile/DataFileServiceRegistry.java

+   * issues.
+   */
+  private static final class Registry {
+    private static final Map<Key, ReaderService> READ_BUILDERS = Maps.newConcurrentMap();


This is more like a convention problem, I think maybe we just need to store in FileFormatService in registry?

Sometimes we don't have writers (arrow), or we have multiple readers vectorized/non-vectorized readers. Also Parquet has Comet reader. So I kept the writers and the readers separate

liurenjie1024 · 2025-02-21T10:05:38Z

core/src/main/java/org/apache/iceberg/io/datafile/DataFileServiceRegistry.java

+  /** Key used to identify readers and writers in the {@link DataFileServiceRegistry}. */
+  public static class Key {
+    private final FileFormat fileFormat;
+    private final String dataType;


Is this things like arrow, internal row?

Yeah,
Currenly we have:

Record - generic readers/writers

ColumnarBatch (arrow) - arrow

RowData - Flink

InternalRow - Spark

ColumnarBatch (spark) - Spark batch

pvary · 2025-02-21T14:10:03Z

I will start to collect the differences here between the different writer types (appender/dataWriter/equalityDeleteWriter/positionalDeleteWriter) for reference:

Writer context is different between delete and data files. This contains TableProperties/Configurations which could be different between delete and data files. For example for parquet: RowGroupSize/PageSize/PageRowLimit/DictSize/Compression etc. For ORC and Avro we have some similar changing configs
Specific writer functions for position deletes to write out the PositionDelete records
Positional delete PathTransformFunction to convert writer data type for the path to file format data type

danielcweeks · 2025-02-21T19:31:33Z

core/src/main/java/org/apache/iceberg/io/datafile/DataWriterBuilder.java

+import org.apache.iceberg.io.DataWriter;
+
+/** Builder API for creating {@link DataWriter}s. */
+public interface DataWriterBuilder {


Why not put the builder interface into the DataWriter class and put it in the same package? It seems odd to me that we're introducing this new datafile package.

The classes which has to be implemented by the file formats are kept in the io package, but moved the others to the data package

core/src/main/java/org/apache/iceberg/avro/Avro.java

core/src/main/java/org/apache/iceberg/io/datafile/DataFileServiceRegistry.java

...urces/META-INF/services/org.apache.iceberg.io.datafile.DataFileServiceRegistry$WriterService

rdblue · 2025-02-22T00:10:36Z

While I think the goal here is a good one, the implementation looks too complex to be workable in its current form.

The primary issue that we currently have is adapting object models (like Iceber's internal StructLike, Spark's InternalRow, or Flink's RowData) to file formats so that you can separately write object model to format glue code and have it work throughout support for an engine. I think a diff from the InternalData PR demonstrates it pretty well:

-    switch (format) {
-      case AVRO:
-        AvroIterable<ManifestEntry<F>> reader =
-            Avro.read(file)
-                .project(ManifestEntry.wrapFileSchema(Types.StructType.of(fields)))
-                .createResolvingReader(this::newReader)
-                .reuseContainers()
-                .build();
+    CloseableIterable<ManifestEntry<F>> reader =
+        InternalData.read(format, file)
+            .project(ManifestEntry.wrapFileSchema(Types.StructType.of(fields)))
+            .reuseContainers()
+            .build();
 
-        addCloseable(reader);
+    addCloseable(reader);
 
-        return CloseableIterable.transform(reader, inheritableMetadata::apply);
+    return CloseableIterable.transform(reader, inheritableMetadata::apply);
-
-      default:
-        throw new UnsupportedOperationException("Invalid format for manifest file: " + format);
-    }

This shows:

Rather than a switch, the format is passed to create the builder
There is no longer a callback passed to create readers for the object model (createResolvingReader)

In this PR, there are a lot of other changes as well. I'm looking at one of the simpler Spark cases in the row reader.

The builder is initialized from DataFileServiceRegistry and now requires a format, class name, file, projection, and constant map:

    return DataFileServiceRegistry.readerBuilder(
            format, InternalRow.class.getName(), file, projection, idToConstant)

There are also new static classes in the file. Each creates a new service and each service creates the builder and object model:

  public static class AvroReaderService implements DataFileServiceRegistry.ReaderService {
    @Override
    public DataFileServiceRegistry.Key key() {
      return new DataFileServiceRegistry.Key(FileFormat.AVRO, InternalRow.class.getName());
    }

    @Override
    public ReaderBuilder builder(
        InputFile inputFile,
        Schema readSchema,
        Map<Integer, ?> idToConstant,
        DeleteFilter<?> deleteFilter) {
      return Avro.read(inputFile)
          .project(readSchema)
          .createResolvingReader(schema -> SparkPlannedAvroReader.create(schema, idToConstant));
    }

The createResolvingReader line is still there, just moved into its own service class instead of in branches of a switch statement.

In addition, there are now a lot more abstractions:

A builder for creating an appender for a file format
A builder for creating a data file writer for a file format
A builder for creating an equality delete writer for a file format
A builder for creating a position delete writer for a file format
A builder for creating a reader for a file format
A "service" registry (what is a service?)
A "key"
A writer service
A reader service

I think that the next steps are to focus on making this a lot simpler, and there are some good ways to do that:

Focus on removing boilerplate and hiding the internals. For instance, Key, if needed, should be an internal abstraction and not complexity that is exposed to callers
The format-specific data and delete file builders typically wrap an appender builder. Is there a way to handle just the reader builder and appender builder?
Is the extra "service" abstraction helpful?
Remove ServiceLoader and use a simpler solution. I think that formats could simply register themselves like we do for InternalData. I think it would be fine to have a trade-off that Iceberg ships with a list of known formats that can be loaded, and if you want to replace that list it's at your own risk.
Standardize more across the builders for FileFormat. How idToConstant is handled is a good example. That should be passed to the builder instead of making the whole API more complicated. Projection is the same.

pvary · 2025-02-24T10:34:16Z

While I think the goal here is a good one, the implementation looks too complex to be workable in its current form.

I'm happy that we agree with the goals. I created a PR to start the conversation. If there are willing reviewers we can introduce more invasive changes to archive a better API. I'm all for it!

The primary issue that we currently have is adapting object models (like Iceber's internal StructLike, Spark's InternalRow, or Flink's RowData) to file formats so that you can separately write object model to format glue code and have it work throughout support for an engine.

I think we need to keep this direct transformations to prevent the performance loss which would be caused by multiple transformations between object model -> common model -> file format.

We have a matrix of transformation which we need to encode somewhere:

Source	Target
Parquet	StructLike
Parquet	InternalRow
Parquet	RowData
Parquet	Arrow
Avro	...
ORC	...

[..]

Rather than a switch, the format is passed to create the builder

There is no longer a callback passed to create readers for the object model (createResolvingReader)

The InternalData reader has one advantage over the data file readers/writers. The internal object model is static for these readers/writers. For the DataFile readers/writers we have multiple object models to handle.

[..]
I think that the next steps are to focus on making this a lot simpler, and there are some good ways to do that:

Focus on removing boilerplate and hiding the internals. For instance, Key, if needed, should be an internal abstraction and not complexity that is exposed to callers

If we allow adding new builders for the file formats we can remove a good chunk of the boilerplate code. Let me see how this would look like

The format-specific data and delete file builders typically wrap an appender builder. Is there a way to handle just the reader builder and appender builder?

We need to refactor the Avro positional delete write for this, or add a positionalWriterFunc. Also need to consider that the format specific configurations which are different for the appenders and the delete files (DELETE_PARQUET_ROW_GROUP_SIZE_BYTES vs. PARQUET_ROW_GROUP_SIZE_BYTES)

Is the extra "service" abstraction helpful?

If we are ok with having a new Builder for the readers/writers, then we don't need the service. It was needed to keep the current APIs and the new APIs compatible.

Remove ServiceLoader and use a simpler solution. I think that formats could simply register themselves like we do for InternalData. I think it would be fine to have a trade-off that Iceberg ships with a list of known formats that can be loaded, and if you want to replace that list it's at your own risk.

Will do

Standardize more across the builders for FileFormat. How idToConstant is handled is a good example. That should be passed to the builder instead of making the whole API more complicated. Projection is the same.

Will see what could be arcived

…quetFormatModel.ReadBuilderWrapper

parquet/src/main/java/org/apache/iceberg/parquet/ParquetFormatModel.java

core/src/main/java/org/apache/iceberg/avro/AvroFormatModel.java

parquet/src/main/java/org/apache/iceberg/parquet/ParquetFormatModel.java

parquet/src/main/java/org/apache/iceberg/parquet/VectorizedParquetReader.java

parquet/src/test/java/org/apache/iceberg/parquet/TestParquet.java

parquet/src/main/java/org/apache/iceberg/parquet/Parquet.java

data/src/main/java/org/apache/iceberg/data/GenericFormatModels.java

rdblue · 2026-01-15T00:14:57Z

core/src/main/java/org/apache/iceberg/avro/AvroFormatModel.java

+  private final Class<D> type;
+  private final Class<S> schemaType;
+  private final BiFunction<Schema, Map<Integer, ?>, DatumReader<D>> readerFunction;
+  private final BiFunction<org.apache.avro.Schema, S, DatumWriter<D>> writerFunction;


I'm going through the different reader/writer functions and how they are supplied by Spark and generics. All of the variations are pretty wacky. This is a good example, where the read side uses an Iceberg Schema but the write side uses an Avro schema. In addition, only the write paths for Spark pass the inputSchema from Spark (even though the readers are parameterized by its type).

I know that we're trying to avoid doing extra work right now, but it seems to me that this is an area where we should do work now since we're ensuring that we can pass the engine schema around and we aren't going to want to make substantial changes to the FormatModel interface. What happens if we want to use the Iceberg schema in addition to the Avro schema for writes? I'd like to know now rather than later and would lean toward plumbing it through these interfaces; at a minimum, I'd make sure that we have Iceberg schema, engine schema, and file schema for writes (which is what is needed for Parquet) and I'd pass Iceberg schema, file schema, and constants map for reads. I also suspect that we are going to want engine schema for reads so we may want to add it now as well. Having a common set of metadata supported by the builders and the formats is going to make this easier to think about and build for, without needing to make substantial changes to plumbing when we actually want to use these.

Created a BaseFormatModel abstract class, and updated the PR to use that in the Parquet, Avro and ORC models.

pvary · 2026-01-15T16:38:42Z

parquet/src/main/java/org/apache/iceberg/parquet/ParquetFormatModel.java

+              .createBatchedReaderFunc(
+                  (icebergSchema, messageType) ->
+                      (VectorizedReader<?>)
+                          readerFunction.read(icebergSchema, messageType, null, idToConstant))


We send in "null", as currently the engine schema setter is removed from the API, as it is not used anywhere at this point. We might want to consider adding it back, so it is wired in correctly

rashworld-max

#14751

github-actions bot added spark parquet arrow core data flink ORC labels Feb 17, 2025

pvary force-pushed the file_Format_api_without_base branch 6 times, most recently from 907089c to 313c2d5 Compare February 18, 2025 09:13

snazy reviewed Feb 18, 2025

View reviewed changes

pvary force-pushed the file_Format_api_without_base branch 2 times, most recently from c528a52 to 9975b4f Compare February 20, 2025 09:45

pvary changed the title ~~WIP: Interface based FileFormat API~~ WIP: Interface based DataFile reader and writer API Feb 20, 2025

liurenjie1024 reviewed Feb 21, 2025

View reviewed changes

danielcweeks reviewed Feb 21, 2025

View reviewed changes

core/src/main/java/org/apache/iceberg/avro/Avro.java Outdated Show resolved Hide resolved

danielcweeks reviewed Feb 21, 2025

View reviewed changes

core/src/main/java/org/apache/iceberg/io/datafile/DataFileServiceRegistry.java Outdated Show resolved Hide resolved

rdblue reviewed Feb 21, 2025

View reviewed changes

...urces/META-INF/services/org.apache.iceberg.io.datafile.DataFileServiceRegistry$WriterService Outdated Show resolved Hide resolved

pvary force-pushed the file_Format_api_without_base branch 5 times, most recently from c488d32 to 71ec538 Compare February 25, 2025 16:53

pvary added 2 commits January 6, 2026 10:39

Proposed API interfaces - squashed for rebase

748b34e

Using Parquet.icebergSchema instead of keeping track of it in the Par…

7117cc9

…quetFormatModel.ReadBuilderWrapper

pvary force-pushed the file_Format_api_without_base branch 3 times, most recently from f50aad4 to 7206c7b Compare January 6, 2026 14:09

Create a marker class for the Comet reader and a few extra nits

b41cb69

pvary force-pushed the file_Format_api_without_base branch from 7206c7b to b41cb69 Compare January 7, 2026 07:37

pvary added this to the Iceberg 1.11.0 milestone Jan 7, 2026