Package io.delta.kernel

Interface CommitRangeBuilder

All Known Implementing Classes:
CommitRangeBuilderImpl
@Experimental public interface CommitRangeBuilder
A builder for creating CommitRange instances that define a contiguous range of commits in a Delta Lake table.

The start boundary is required and provided via TableManager.loadCommitRange(String, CommitBoundary). If no end specification is provided, the range defaults to the latest available version.

Since:
3.4.0

  • Method Details

    • withEndBoundary

      CommitRangeBuilder withEndBoundary(CommitRangeBuilder.CommitBoundary endBoundary)
      Configures the builder to end the commit range at a specific version or timestamp.

      If not specified, the commit range will default to ending at the latest available version.

      Parameters:
      endBoundary - the boundary specification for the end of the commit range, must not be null
      Returns:
      this builder instance configured with the specified end boundary

    • withLogData

      CommitRangeBuilder withLogData(List<ParsedLogData> logData)
      Provides parsed log data to optimize the commit range construction.

      Note: If no end boundary is provided via withEndBoundary(CommitBoundary), or a timestamp-based end boundary is provided, the provided log data must include all available ratified commits. If a version-based end boundary is provided, the log data must include commits up to at least the end version (i.e., the tail of the log data must have a version greater than or equal to the end version).

      Parameters:
      logData - the list of pre-parsed log data, must not be null
      Returns:
      this builder instance configured with the specified log data

    • withMaxCatalogVersion

      CommitRangeBuilder withMaxCatalogVersion(long version)
      Specifies the maximum table version known by the catalog.

      This method is used by catalog implementations for catalog-managed Delta tables to indicate the latest ratified version of the table. This ensures that any commit range operations respect the catalog's view of the table state.

      Important: This method is required for catalog-managed tables and must not be used for file-system managed tables.

      When specified, the following additional constraints are enforced:

      • When the provided startBoundary is version-based, the start version must be less than or equal to the max catalog version.
      • If withEndBoundary(CommitBoundary) is used with a version, the requested version must be less than or equal to the max catalog version.
      • If the provided startBoundary is timestamp-based, or withEndBoundary(CommitBoundary) is used with a timestamp, the provided latest snapshot must have a version equal to the max catalog version.
      • If withLogData(List) is provided and no end boundary is specified (resolving to latest), the log data must end with the max catalog version.
      Parameters:
      version - the maximum table version known by the catalog (must be >= 0)
      Returns:
      a new builder instance with the specified max catalog version
      Throws:
      IllegalArgumentException - if version is negative

    • build

      CommitRange build(Engine engine)
      Builds and returns a CommitRange instance with the configured specifications.

      This method validates the builder configuration and constructs the commit range by resolving version numbers from timestamps if necessary and determining the actual commit files that fall within the specified range.

      Parameters:
      engine - the Engine to use for file system operations and log parsing
      Returns:
      a new CommitRange instance configured according to this builder's specifications
      Throws:
      IllegalArgumentException - if the builder configuration is invalid (e.g., start version > end version)