Package io.delta.kernel

Interface SnapshotBuilder

All Known Implementing Classes:
SnapshotBuilderImpl
@Experimental public interface SnapshotBuilder
Builder for constructing a Snapshot instance.

This builder allows table managers (filesystems, catalogs) to provide any information they may know about a Delta table and get back a Snapshot. When build(Engine) is invoked, Kernel will automatically fill any missing information needed to construct the Snapshot by reading from the filesystem as needed.

If no version is specified, the builder will resolve to the latest version. Depending on the ParsedLogData provided, Kernel can avoid expensive filesystem operations to improve performance.

  • Method Details

    • atVersion

      SnapshotBuilder atVersion(long version)
      Configures the builder to resolve the table at a specific version.

      This method is mutually exclusive with atTimestamp(long, Snapshot). If both are called, an IllegalArgumentException will be thrown.

      Parameters:
      version - the version number to resolve to
      Returns:
      a new builder instance configured for the specified version

    • atTimestamp

      SnapshotBuilder atTimestamp(long millisSinceEpochUTC, Snapshot latestSnapshot)
      Configures the builder to resolve the table at a specific timestamp.

      This returns a Snapshot for the latest version of the table that was committed before or at the given timestamp. Specifically:

      • If a commit version exactly matches the provided timestamp, the snapshot at that version is resolved.
      • Otherwise, the latest commit version with a timestamp less than the provided one is resolved.
      • If the provided timestamp is less than the timestamp of any committed version, snapshot resolution will fail.
      • If the provided timestamp is after (strictly greater than) the timestamp of the latest version of the table, snapshot resolution will fail.

      This method is mutually exclusive with atVersion(long). If both are called, an IllegalArgumentException will be thrown.

      Parameters:
      millisSinceEpochUTC - timestamp to resolve the snapshot for in milliseconds since the unix epoch
      Returns:
      a new builder instance configured for the specified timestamp

    • withCommitter

      SnapshotBuilder withCommitter(Committer committer)
      Provides a custom committer to use at transaction commit time.

      Catalog implementations that wish to support the catalogManaged Delta table feature should provide to engines their own catalog-specific Committer implementation which may, for example, send a commit RPC to the catalog service to finalize the commit.

      If no committer is provided, a default committer will be created that only supports writing into filesystem-managed Delta tables.

      Parameters:
      committer - the committer to use
      Returns:
      a new builder instance with the provided committer
      See Also:

    • withLogData

      SnapshotBuilder withLogData(List<ParsedLogData> logData)
      Provides parsed log data to optimize table resolution.

      When log data is provided, Kernel can avoid reading from the filesystem for information that is already available in the parsed data, improving performance. Currently, only ratified staged commits are supported.

      Parameters:
      logData - the parsed log data to use for optimization
      Returns:
      a new builder instance with the provided log data

    • withProtocolAndMetadata

      SnapshotBuilder withProtocolAndMetadata(Protocol protocol, Metadata metadata)
      Provides protocol and metadata information to optimize table resolution.

      When protocol and metadata are provided, Kernel can avoid reading this information from the filesystem, improving performance.

      Parameters:
      protocol - the protocol information
      metadata - the metadata information
      Returns:
      a new builder instance with the provided protocol and metadata

    • withMaxCatalogVersion

      SnapshotBuilder 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 snapshot resolution 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. An IllegalArgumentException will be thrown at build time if this constraint is violated.

      When specified, the following additional constraints are enforced:

      • If atVersion(long) is used for time travel, the requested version must be less than or equal to the max catalog version.
      • If atTimestamp(long, Snapshot) is used for time travel, the provided latestSnapshot must have a version equal to the max catalog version.
      • If withLogData(List) is provided and atVersion(long) is used, the log data must include the requested version (i.e., the tail of the log data must have a version greater than or equal to the requested version).
      • If withLogData(List) is provided and no version 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

      Snapshot build(Engine engine)
      Constructs the Snapshot using the provided engine.

      This method will read any missing information from the filesystem using the provided engine to complete the snapshot resolution process.

      Parameters:
      engine - the engine to use for filesystem operations
      Returns:
      the resolved snapshot instance