Package org.apache.iceberg

Interface ManageSnapshots

All Superinterfaces:
PendingUpdate<Snapshot>
All Known Implementing Classes:
SnapshotManager
public interface ManageSnapshots extends PendingUpdate<Snapshot>
API for managing snapshots. Allows rolling table data back to a stated at an older table snapshot. Rollback:

This API does not allow conflicting calls to setCurrentSnapshot(long) and rollbackToTime(long).

When committing, these changes will be applied to the current table metadata. Commit conflicts will not be resolved and will result in a CommitFailedException. Cherrypick:

In an audit workflow, new data is written to an orphan snapshot that is not committed as the table's current state until it is audited. After auditing a change, it may need to be applied or cherry-picked on top of the latest snapshot instead of the one that was current when the audited changes were created. This class adds support for cherry-picking the changes from an orphan snapshot by applying them to the current snapshot. The output of the operation is a new snapshot with the changes from cherry-picked snapshot.

  • Method Details

    • setCurrentSnapshot

      ManageSnapshots setCurrentSnapshot(long snapshotId)
      Roll this table's data back to a specific Snapshot identified by id.
      Parameters:
      snapshotId - long id of the snapshot to roll back table data to
      Returns:
      this for method chaining
      Throws:
      IllegalArgumentException - If the table has no snapshot with the given id

    • rollbackToTime

      ManageSnapshots rollbackToTime(long timestampMillis)
      Roll this table's data back to the last Snapshot before the given timestamp.
      Parameters:
      timestampMillis - a long timestamp, as returned by System.currentTimeMillis()
      Returns:
      this for method chaining
      Throws:
      IllegalArgumentException - If the table has no old snapshot before the given timestamp

    • rollbackTo

      ManageSnapshots rollbackTo(long snapshotId)
      Rollback table's state to a specific Snapshot identified by id.
      Parameters:
      snapshotId - long id of snapshot id to roll back table to. Must be an ancestor of the current snapshot
      Throws:
      IllegalArgumentException - If the table has no snapshot with the given id
      ValidationException - If given snapshot id is not an ancestor of the current state

    • cherrypick

      ManageSnapshots cherrypick(long snapshotId)
      Apply supported changes in given snapshot and create a new snapshot which will be set as the current snapshot on commit.
      Parameters:
      snapshotId - a snapshotId whose changes to apply
      Returns:
      this for method chaining
      Throws:
      IllegalArgumentException - If the table has no snapshot with the given id
      DuplicateWAPCommitException - In case of a WAP workflow and if the table has a duplicate commit with same wapId

    • createBranch

      default ManageSnapshots createBranch(String name)
      Create a new branch. The branch will point to current snapshot if the current snapshot is not NULL. Otherwise, the branch will point to a newly created empty snapshot.
      Parameters:
      name - branch name
      Returns:
      this for method chaining
      Throws:
      IllegalArgumentException - if a branch with the given name already exists

    • createBranch

      ManageSnapshots createBranch(String name, long snapshotId)
      Create a new branch pointing to the given snapshot id.
      Parameters:
      name - branch name
      snapshotId - id of the snapshot which will be the head of the branch
      Returns:
      this for method chaining
      Throws:
      IllegalArgumentException - if a branch with the given name already exists

    • createTag

      ManageSnapshots createTag(String name, long snapshotId)
      Create a new tag pointing to the given snapshot id
      Parameters:
      name - tag name
      snapshotId - snapshotId for the head of the new branch.
      Returns:
      this for method chaining
      Throws:
      IllegalArgumentException - if a tag with the given name already exists

    • removeBranch

      ManageSnapshots removeBranch(String name)
      Remove a branch by name
      Parameters:
      name - branch name
      Returns:
      this for method chaining
      Throws:
      IllegalArgumentException - if the branch does not exist

    • renameBranch

      ManageSnapshots renameBranch(String name, String newName)
      Rename a branch
      Parameters:
      name - name of branch to rename
      newName - the desired new name of the branch
      Throws:
      IllegalArgumentException - if the branch to rename does not exist or if there is already a branch with the same name as the desired new name.

    • removeTag

      ManageSnapshots removeTag(String name)
      Remove the tag with the given name.
      Parameters:
      name - tag name
      Returns:
      this for method chaining
      Throws:
      IllegalArgumentException - if the branch does not exist

    • replaceTag

      ManageSnapshots replaceTag(String name, long snapshotId)
      Replaces the tag with the given name to point to the specified snapshot.
      Parameters:
      name - Tag to replace
      snapshotId - new snapshot id for the given tag
      Returns:
      this for method chaining

    • replaceBranch

      ManageSnapshots replaceBranch(String name, long snapshotId)
      Replaces the branch with the given name to point to the specified snapshot
      Parameters:
      name - Branch to replace
      snapshotId - new snapshot id for the given branch
      Returns:
      this for method chaining

    • replaceBranch

      ManageSnapshots replaceBranch(String from, String to)
      Replaces the from branch to point to the to snapshot. The to will remain unchanged, and from branch will retain its retention properties. If the from branch does not exist, it will be created with default retention properties.
      Parameters:
      from - Branch to replace
      to - The branch from should be replaced with
      Returns:
      this for method chaining

    • fastForwardBranch

      ManageSnapshots fastForwardBranch(String from, String to)
      Performs a fast-forward of from up to the to snapshot if from is an ancestor of to. The to will remain unchanged, and from will retain its retention properties. If the from branch does not exist, it will be created with default retention properties.
      Parameters:
      from - Branch to fast-forward
      to - Ref for the from branch to be fast forwarded to
      Returns:
      this for method chaining
      Throws:
      IllegalArgumentException - if from is not an ancestor of to

    • setMinSnapshotsToKeep

      ManageSnapshots setMinSnapshotsToKeep(String branchName, int minSnapshotsToKeep)
      Updates the minimum number of snapshots to keep for a branch.
      Parameters:
      branchName - branch name
      minSnapshotsToKeep - minimum number of snapshots to retain on the branch
      Returns:
      this for method chaining
      Throws:
      IllegalArgumentException - if the branch does not exist

    • setMaxSnapshotAgeMs

      ManageSnapshots setMaxSnapshotAgeMs(String branchName, long maxSnapshotAgeMs)
      Updates the max snapshot age for a branch.
      Parameters:
      branchName - branch name
      maxSnapshotAgeMs - maximum snapshot age in milliseconds to retain on branch
      Returns:
      this for method chaining
      Throws:
      IllegalArgumentException - if the branch does not exist

    • setMaxRefAgeMs

      ManageSnapshots setMaxRefAgeMs(String name, long maxRefAgeMs)
      Updates the retention policy for a reference.
      Parameters:
      name - branch name
      maxRefAgeMs - retention age in milliseconds of the tag reference itself
      Returns:
      this for method chaining
      Throws:
      IllegalArgumentException - if the reference does not exist