Package org.apache.iceberg.formats

Class FormatModelRegistry

java.lang.Object
org.apache.iceberg.formats.FormatModelRegistry
public final class FormatModelRegistry extends Object
A registry that manages file-format-specific readers and writers through a unified object model factory interface.

This registry provides access to ReadBuilders for data consumption and FileWriterBuilders for writing various types of Iceberg content files. The appropriate builder is selected based on FileFormat and object model class.

FormatModel objects are registered through register(FormatModel) and used for creating readers and writers.

  • Method Details

    • register

      public static void register(FormatModel<?,?> formatModel)
      Registers an FormatModel in this registry.

      The FormatModel creates readers and writers for a specific combinations of file format (Parquet, ORC, Avro) and object model (for example: "generic", "spark", "flink", etc.). Registering custom factories allows integration of new data processing engines for the supported file formats with Iceberg's file access mechanisms.

      Each factory must be uniquely identified by its combination of file format and object model name. This uniqueness constraint prevents ambiguity when selecting factories for read and write operations.

      Parameters:
      formatModel - the factory implementation to register
      Throws:
      IllegalArgumentException - if a factory is already registered for the combination of FormatModel.format() and FormatModel.type()

    • readBuilder

      public static <D, S> ReadBuilder<D,S> readBuilder(FileFormat format, Class<? extends D> type, InputFile inputFile)
      Returns a reader builder for the specified file format and object model.

      The returned ReadBuilder provides a fluent interface for configuring how data is read from the input file and converted to the output objects.

      Type Parameters:
      D - the type of data records the reader will produce
      S - the type of the output schema for the reader
      Parameters:
      format - the file format (Parquet, Avro, ORC) that determines the parsing implementation
      type - the output type
      inputFile - source file to read data from
      Returns:
      a configured reader builder for the specified format and object model

    • dataWriteBuilder

      public static <D, S> FileWriterBuilder<DataWriter<D>,S> dataWriteBuilder(FileFormat format, Class<? extends D> type, EncryptedOutputFile outputFile)
      Returns a writer builder for generating a DataFile.

      The returned builder produces a writer that accepts records defined by the specified object model and persists them using the provided file format. Unlike basic writers, this writer collects file metadata during the writing process and generates a DataFile that can be used for table operations.

      Type Parameters:
      D - the type of data records the writer will accept
      S - the type of the input schema for the writer
      Parameters:
      format - the file format used for writing
      type - the input type
      outputFile - destination for the written data
      Returns:
      a configured data write builder for creating a DataWriter

    • equalityDeleteWriteBuilder

      public static <D, S> FileWriterBuilder<EqualityDeleteWriter<D>,S> equalityDeleteWriteBuilder(FileFormat format, Class<D> type, EncryptedOutputFile outputFile)
      Creates a writer builder for generating a DeleteFile with equality deletes.

      The returned builder produces a writer that accepts records defined by the specified object model and persists them using the given file format. The writer persists equality delete records that identify rows to be deleted based on the configured equality fields, producing a DeleteFile that can be used for table operations.

      Type Parameters:
      D - the type of data records the writer will accept
      S - the type of the input schema for the writer
      Parameters:
      format - the file format used for writing
      type - the input type
      outputFile - destination for the written data
      Returns:
      a configured delete write builder for creating an EqualityDeleteWriter

    • positionDeleteWriteBuilder

      public static <D> FileWriterBuilder<PositionDeleteWriter<D>,?> positionDeleteWriteBuilder(FileFormat format, EncryptedOutputFile outputFile)
      Creates a writer builder for generating a DeleteFile with position-based deletes.

      The returned builder produces a writer that accepts records defined by the specified object model and persists them using the given file format. The writer accepts PositionDelete records that identify rows to be deleted by file path and position, producing a DeleteFile that can be used for table operations.

      Note: This method is only applicable to format-version 2 tables. Format-version 3 tables use deletion vectors, which are always written in Puffin format. Registered FormatModel implementations for PositionDelete are not consulted for format-version 3+ tables.

      Parameters:
      format - the file format used for writing
      outputFile - destination for the written data
      Returns:
      a configured delete write builder for creating a PositionDeleteWriter