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 Summary

Modifier and Type	Method and Description
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.
default ManageSnapshots	createBranch(java.lang.String name) Create a new branch.
ManageSnapshots	createBranch(java.lang.String name, long snapshotId) Create a new branch pointing to the given snapshot id.
ManageSnapshots	createTag(java.lang.String name, long snapshotId) Create a new tag pointing to the given snapshot id
ManageSnapshots	fastForwardBranch(java.lang.String from, java.lang.String to) Performs a fast-forward of from up to the to snapshot if from is an ancestor of to.
ManageSnapshots	removeBranch(java.lang.String name) Remove a branch by name
ManageSnapshots	removeTag(java.lang.String name) Remove the tag with the given name.
ManageSnapshots	renameBranch(java.lang.String name, java.lang.String newName) Rename a branch
ManageSnapshots	replaceBranch(java.lang.String name, long snapshotId) Replaces the branch with the given name to point to the specified snapshot
ManageSnapshots	replaceBranch(java.lang.String from, java.lang.String to) Replaces the from branch to point to the to snapshot.
ManageSnapshots	replaceTag(java.lang.String name, long snapshotId) Replaces the tag with the given name to point to the specified snapshot.
ManageSnapshots	rollbackTo(long snapshotId) Rollback table's state to a specific Snapshot identified by id.
ManageSnapshots	rollbackToTime(long timestampMillis) Roll this table's data back to the last Snapshot before the given timestamp.
ManageSnapshots	setCurrentSnapshot(long snapshotId) Roll this table's data back to a specific Snapshot identified by id.
ManageSnapshots	setMaxRefAgeMs(java.lang.String name, long maxRefAgeMs) Updates the retention policy for a reference.
ManageSnapshots	setMaxSnapshotAgeMs(java.lang.String branchName, long maxSnapshotAgeMs) Updates the max snapshot age for a branch.
ManageSnapshots	setMinSnapshotsToKeep(java.lang.String branchName, int minSnapshotsToKeep) Updates the minimum number of snapshots to keep for a branch.

Methods inherited from interface org.apache.iceberg.PendingUpdate

apply, commit, updateEvent

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 from,
                              java.lang.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(java.lang.String from,
                                  java.lang.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:

java.lang.IllegalArgumentException - if from is not an ancestor of to

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