Package io.delta.kernel.internal

Class UpdateTableTransactionBuilderImpl

Object
io.delta.kernel.internal.UpdateTableTransactionBuilderImpl
All Implemented Interfaces:
UpdateTableTransactionBuilder
public class UpdateTableTransactionBuilderImpl extends Object implements UpdateTableTransactionBuilder

  • Constructor Details

    • UpdateTableTransactionBuilderImpl

      public UpdateTableTransactionBuilderImpl(SnapshotImpl snapshot, String engineInfo, Operation operation)

  • Method Details

    • withUpdatedSchema

      public UpdateTableTransactionBuilder withUpdatedSchema(StructType schema)
      Description copied from interface: UpdateTableTransactionBuilder
      Set a new schema for the table, enabling schema evolution.

      Schema evolution allows you to modify the table's structure by adding, removing, renaming, or reordering columns. Column mapping must be enabled on the table for schema evolution to be supported.

      The provided schema should preserve field metadata (such as field IDs and physical names) for existing columns. Columns without metadata will be considered new columns and be assigned new IDs and physical names automatically.

      Supported schema evolution operations:

      • Add columns: New columns can be added at any position
      • Rename columns: Change the logical name while preserving the physical name
      • Type widening: Compatible type changes (e.g., int to long)
      • Reorder columns: Change the position of columns in the schema
      • Drop columns: Remove columns (with restrictions)
      Specified by:
      withUpdatedSchema in interface UpdateTableTransactionBuilder
      Parameters:
      schema - The new schema for the table. Cannot be null. Must be compatible with the current schema and follow schema evolution rules.

    • withTablePropertiesAdded

      public UpdateTableTransactionBuilder withTablePropertiesAdded(Map<String,String> properties)
      Description copied from interface: UpdateTableTransactionBuilder
      Add or update table properties (configuration).

      Properties specified here will be added to the table or override existing values. To remove properties, use UpdateTableTransactionBuilder.withTablePropertiesRemoved(Set).

      Specified by:
      withTablePropertiesAdded in interface UpdateTableTransactionBuilder
      Parameters:
      properties - A map of property names to their values. The properties will be validated and normalized. Cannot be null.

    • withTablePropertiesRemoved

      public UpdateTableTransactionBuilder withTablePropertiesRemoved(Set<String> propertyKeys)
      Description copied from interface: UpdateTableTransactionBuilder
      Remove table properties from the table configuration.

      The specified property keys will be removed from the table's configuration. Attempting to remove a property that doesn't exist is not an error.

      Currently only user-properties (in other words, ones that are not prefixed by 'delta.') can be removed using this API. Adding and removing the same key in the same transaction is not allowed.

      Specified by:
      withTablePropertiesRemoved in interface UpdateTableTransactionBuilder
      Parameters:
      propertyKeys - A set of property names to remove. Cannot be null.

    • withClusteringColumns

      public UpdateTableTransactionBuilder withClusteringColumns(List<Column> clusteringColumns)
      Description copied from interface: UpdateTableTransactionBuilder
      Update the clustering columns for the table and enable clustering if it is not already enabled. Note: clustering cannot be enabled for a partitioned table.
      Specified by:
      withClusteringColumns in interface UpdateTableTransactionBuilder
      Parameters:
      clusteringColumns - The columns to cluster by. Cannot be null.

    • withTransactionId

      public UpdateTableTransactionBuilder withTransactionId(String applicationId, long transactionVersion)
      Description copied from interface: UpdateTableTransactionBuilder
      Set a transaction identifier for idempotent operations.

      Transaction identifiers allow you to implement idempotent operations by ensuring that multiple attempts to perform the same logical operation don't result in duplicate effects. This is useful for:

      • Retry logic in distributed systems
      • Exactly-once processing guarantees
      • Recovery from failures

      If a transaction with the same application ID and version (or higher) has already been committed the transaction will fail.

      Specified by:
      withTransactionId in interface UpdateTableTransactionBuilder
      Parameters:
      applicationId - A unique identifier for the application or process. Cannot be null.
      transactionVersion - A monotonically increasing version number for this application ID.

    • withMaxRetries

      public UpdateTableTransactionBuilder withMaxRetries(int maxRetries)
      Description copied from interface: UpdateTableTransactionBuilder
      Set the maximum number of retries for handling concurrent write conflicts.

      When multiple writers attempt to modify the same Delta table simultaneously, conflicts can occur. This setting controls how many times the operation will be retried with conflict resolution before giving up.

      Specified by:
      withMaxRetries in interface UpdateTableTransactionBuilder
      Parameters:
      maxRetries - The maximum number of retries. Must be at least 0. Default is 200.

    • withLogCompactionInterval

      public UpdateTableTransactionBuilder withLogCompactionInterval(int logCompactionInterval)
      Description copied from interface: UpdateTableTransactionBuilder
      Set the log compaction interval for optimizing the transaction log.

      Log compaction creates periodic checkpoint files that consolidate multiple transaction log entries, improving read performance and reducing the number of files that need to be processed when reading table metadata.

      A value of 0 disables automatic log compaction for this transaction. Positive values specify how many commits should occur between compactions. Defaults to 0.

      Specified by:
      withLogCompactionInterval in interface UpdateTableTransactionBuilder
      Parameters:
      logCompactionInterval - The number of commits between checkpoints. Must be at least 0. A value of 0 disables log compaction.

    • withClock

      @VisibleForTesting public UpdateTableTransactionBuilder withClock(Clock clock)

    • build

      public Transaction build(Engine engine)
      Description copied from interface: UpdateTableTransactionBuilder
      Build the transaction for updating the Delta table.

      This validates all the configuration and creates a Transaction that can be used to update the existing Delta table. The transaction must be committed using Transaction.commit(Engine, CloseableIterable) to actually apply the changes.

      Specified by:
      build in interface UpdateTableTransactionBuilder
      Parameters:
      engine - The Engine instance to use for the transaction. Cannot be null.
      Returns:
      A configured Transaction for updating the table.