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 Detail

      • 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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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​(java.lang.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:
        java.lang.IllegalArgumentException - if a branch with the given name already exists

      • createBranch

        ManageSnapshots createBranch​(java.lang.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:
        java.lang.IllegalArgumentException - if a branch with the given name already exists

      • createTag

        ManageSnapshots createTag​(java.lang.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:
        java.lang.IllegalArgumentException - if a tag with the given name already exists

      • removeBranch

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

      • renameBranch

        ManageSnapshots renameBranch​(java.lang.String name,
                             java.lang.String newName)
        Rename a branch
        Parameters:
        name - name of branch to rename
        newName - the desired new name of the branch
        Throws:
        java.lang.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​(java.lang.String name)
        Remove the tag with the given name.
        Parameters:
        name - tag name
        Returns:
        this for method chaining
        Throws:
        java.lang.IllegalArgumentException - if the branch does not exist

      • replaceTag

        ManageSnapshots replaceTag​(java.lang.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​(java.lang.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​(java.lang.String name,
                              java.lang.String source)
        Replaces the branch with the given name to point to the source snapshot. The source branch will remain unchanged, the target branch will retain its retention properties.
        Parameters:
        name - Branch to replace
        source - Source reference for the target to be replaced with
        Returns:
        this for method chaining

      • fastForwardBranch

        ManageSnapshots fastForwardBranch​(java.lang.String name,
                                  java.lang.String source)
        Performs a fast-forward of the given target branch up to the source snapshot if target is an ancestor of source. The source branch will remain unchanged, the target branch will retain its retention properties.
        Parameters:
        name - Branch to fast-forward
        source - Source reference for the target to be fast forwarded to
        Returns:
        this for method chaining
        Throws:
        java.lang.IllegalArgumentException - if the target branch is not an ancestor of source

      • setMinSnapshotsToKeep

        ManageSnapshots setMinSnapshotsToKeep​(java.lang.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:
        java.lang.IllegalArgumentException - if the branch does not exist

      • setMaxSnapshotAgeMs

        ManageSnapshots setMaxSnapshotAgeMs​(java.lang.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:
        java.lang.IllegalArgumentException - if the branch does not exist

      • setMaxRefAgeMs

        ManageSnapshots setMaxRefAgeMs​(java.lang.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:
        java.lang.IllegalArgumentException - if the reference does not exist