Package io.delta.kernel

Interface Snapshot

All Known Implementing Classes:
SnapshotImpl
@Evolving public interface Snapshot
Represents a snapshot of a Delta table at a specific version.

A Snapshot is a consistent view of a Delta table at a specific point in time, identified by a version number. It provides access to the table's metadata, schema, and capabilities for both reading and writing data. This interface serves as the entry point for table operations after resolving a table through a SnapshotBuilder.

The snapshot represents a consistent view of the table at the resolved version. All operations on this snapshot will see the same data and metadata, ensuring consistency across reads and writes within the same snapshot.

There are two ways to create a Snapshot:

  • New API (recommended): Use TableManager.loadSnapshot(String) to get a SnapshotBuilder, which can then be configured and built into a snapshot
  • Legacy API: Use Table.forPath(path) followed by methods like getLatestSnapshot(), getSnapshotAtTimestamp(), etc.
Since:
3.0.0

  • Method Details

    • getPath

      String getPath()
      Returns:
      the file system path to this table

    • getVersion

      long getVersion()
      Returns:
      the version of this snapshot in the Delta table

    • getPartitionColumnNames

      List<String> getPartitionColumnNames()
      Get the names of the partition columns in the Delta table at this snapshot.

      The partition column names are returned in the order they are defined in the Delta table schema. If the table does not define any partition columns, this method returns an empty list.

      Returns:
      a list of partition column names, or an empty list if the table is not partitioned.

    • getTimestamp

      long getTimestamp(Engine engine)
      Get the timestamp (in milliseconds since the Unix epoch) of the latest commit in this snapshot.
      Parameters:
      engine - the engine to use for IO operations
      Returns:
      the timestamp of the latest commit

    • getSchema

      StructType getSchema()
      Returns:
      the schema of the Delta table at this snapshot

    • getDomainMetadata

      Optional<String> getDomainMetadata(String domain)
      Returns the configuration for the provided domain if it exists in the snapshot. Returns empty if the domain is not present in the snapshot.
      Parameters:
      domain - the domain to look up
      Returns:
      the domain configuration or empty

    • getTableProperties

      Map<String,String> getTableProperties()
      Get all table properties for the Delta table at this snapshot.
      Returns:
      a Map of table properties.

    • getStatistics

      SnapshotStatistics getStatistics()
      Returns:
      statistics about this snapshot

    • getScanBuilder

      ScanBuilder getScanBuilder()
      Returns:
      a scan builder to construct a Scan to read data from this snapshot

    • buildUpdateTableTransaction

      UpdateTableTransactionBuilder buildUpdateTableTransaction(String engineInfo, Operation operation)
      Returns:
      a UpdateTableTransactionBuilder to build an update table transaction
      Since:
      3.4.0

    • publish

      Snapshot publish(Engine engine) throws PublishFailedException
      Publishes all catalog commits at this table version. Applicable only to catalog-managed tables. This method is a no-op for filesystem-managed tables, if the committer doesn't support publishing, or if there's no catalog commits to publish.

      Publishing copies ratified catalog commits to the Delta log as published Delta files, reducing catalog storage requirements and enabling some table maintenance operations, like checkpointing.

      Parameters:
      engine - the engine to use for publishing commits
      Returns:
      a new Snapshot reflecting the published state
      Throws:
      PublishFailedException - if the publish operation fails
      See Also:

    • writeChecksum

      void writeChecksum(Engine engine, Snapshot.ChecksumWriteMode mode) throws IOException
      Writes a checksum file for this snapshot using the specified mode:
      • SIMPLE: Uses pre-computed CRC information already loaded in memory. This is the fastest approach but requires CRC info to be available. Throws IllegalStateException if CRC information is not available.
      • FULL: Computes the necessary CRC information by replaying the delta log since the latest checksum (if present). This may be expensive for large tables when CRC information is not available.

      Use SnapshotStatistics.getChecksumWriteMode() to check if writing is needed and to determine the appropriate mode.

      This method should only be called if a checksum file does not already exist at this version. If it already does, this method is a no-op.

      If a concurrent writer creates the checksum file for this version between when this snapshot was loaded and when this method is called, the method will detect the existing checksum and return successfully without error. This ensures safe concurrent checksum writing.

      Parameters:
      engine - the engine to use for writing the checksum file and potentially reading the log
      mode - the mode specifying how to write the checksum (SIMPLE or FULL)
      Throws:
      IOException - if an I/O error occurs during checksum computation or writing
      IllegalStateException - if mode is SIMPLE but CRC information is not available
      See Also:

    • writeCheckpoint

      void writeCheckpoint(Engine engine) throws IOException, CheckpointAlreadyExistsException
      Writes a checkpoint for the current snapshot.
      Parameters:
      engine - The execution engine used to write the checkpoint and, if necessary, read log entries required to compute it.
      Throws:
      IOException - If an I/O error occurs while computing or writing the checkpoint.
      IllegalStateException - If attempting to create a checkpoint on an unpublished catalog managed commit.
      CheckpointAlreadyExistsException - If a checkpoint already exists for the target snapshot version.