Package org.apache.iceberg.formats

Interface ModelWriteBuilder<D,S>

Type Parameters:
D - the output data type produced by the reader
S - the type of the schema for the output data type
public interface ModelWriteBuilder<D,S>
Builder interface for creating file writers across supported data file formats. The FormatModel implementations provide the appropriate ModelWriteBuilder instances.

The ModelWriteBuilder follows the builder pattern to configure and create FileAppender instances that write data to the target output files.

This interface is directly exposed to users for parameterizing when only an appender is required.

  • Method Details

    • schema

      ModelWriteBuilder<D,S> schema(Schema schema)
      Set the file schema.

    • engineSchema

      ModelWriteBuilder<D,S> engineSchema(S schema)
      Sets the engine's representation accepted by the writer.

      Some data types require additional type information from the engine schema that cannot be fully expressed by the Iceberg schema or the data itself. For example, a variant type may use a shredded representation that relies on engine-specific metadata to map back to the Iceberg schema.

      The engine schema must be aligned with the Iceberg schema, but may include representation details that Iceberg considers equivalent.

    • set

      ModelWriteBuilder<D,S> set(String property, String value)
      Set a writer configuration property which affects the writer behavior. Writer builders should ignore configuration keys not known for them.
      Parameters:
      property - a writer config property name
      value - config value
      Returns:
      this for method chaining

    • setAll

      default ModelWriteBuilder<D,S> setAll(Map<String,String> properties)
      Sets multiple writer configuration properties that affect the writer behavior. Writer builders should ignore configuration keys not known for them.
      Parameters:
      properties - writer config properties to set
      Returns:
      this for method chaining

    • meta

      ModelWriteBuilder<D,S> meta(String property, String value)
      Set a file metadata property in the created file.
      Parameters:
      property - a file metadata property name
      value - config value
      Returns:
      this for method chaining

    • meta

      default ModelWriteBuilder<D,S> meta(Map<String,String> properties)
      Sets multiple file metadata properties in the created file.
      Parameters:
      properties - file metadata properties to set
      Returns:
      this for method chaining

    • content

      ModelWriteBuilder<D,S> content(FileContent content)
      Based on the target file content the generated FileAppender needs different configuration.

    • metricsConfig

      ModelWriteBuilder<D,S> metricsConfig(MetricsConfig metricsConfig)
      Sets the metrics configuration used for collecting column metrics for the created file.

    • overwrite

      ModelWriteBuilder<D,S> overwrite()
      Overwrite the file if it already exists. By default, overwrite is disabled.

    • withFileEncryptionKey

      ModelWriteBuilder<D,S> withFileEncryptionKey(ByteBuffer encryptionKey)
      Sets the encryption key used for writing the file. If the writer does not support encryption, then an exception should be thrown.

    • withAADPrefix

      ModelWriteBuilder<D,S> withAADPrefix(ByteBuffer aadPrefix)
      Sets the additional authentication data (AAD) prefix used for writing the file. If the writer does not support encryption, then an exception should be thrown.

    • build

      FileAppender<D> build() throws IOException
      Finalizes the configuration and builds the FileAppender.
      Throws:
      IOException