RESTORE TO VERSION

Restores a Delta table to the state it had at a specific version number.

Category: maintenanceDeltaForge extension

Syntax

RESTORE <table> TO VERSION <n>

Description

## Overview RESTORE TO VERSION reverts a Delta table to the exact state it had at a previous version. This is the primary mechanism for undoing accidental modifications, recovering from failed ETL runs, or reverting schema changes. ## How It Works RESTORE does not roll back the transaction log or delete commits. Instead, it creates a new table version whose content matches the target version: 1. **Load target snapshot**: Reads the table snapshot at the specified version to obtain the set of active files. 2. **Load current snapshot**: Reads the current (latest) table snapshot. 3. **Compute diff**: Determines which files need to be added (present in the target but not the current version) and which need to be removed (present in the current version but not the target). 4. **Commit**: Writes a new commit containing the computed AddFile and RemoveFile actions. The commit's operation metadata records this as a RESTORE operation. After the restore, the new version is the latest version. The table's data matches the target version exactly, but the version number is incremented (not rewound). ## Data File Dependency RESTORE depends on the target version's data files still being present on storage. If VACUUM has deleted files that were active at the target version, the restore will fail because those files cannot be recovered. To maximize the window for safe restores, ensure that the VACUUM retention period (default 168 hours) covers the timeframe you may need to restore to. For critical tables, consider longer retention periods or deep clones as backups. ## Version History After Restore The restore operation is recorded in the table's history. Running DESCRIBE HISTORY after a restore shows: - All original versions (including the ones after the target version) - The new restore version at the end This provides a complete audit trail. No history is lost. ## Result Set Returns a message with the following information: - Target version restored to - Number of files added (restored from the target version) - Number of files removed (from the current version) - New table version number ## Access Control | Privilege | Object | Notes | |-----------|--------|-------| | Ownership or write | Table | Required to commit the restore operation. | ## Compatibility RESTORE TO VERSION is a DeltaForge extension implementing the Delta Lake restore protocol.

Parameters

Name	Type	Description
`table`		Specifies the name or path of the Delta table to restore. The table must be registered in the session. Fully qualified names (zone.schema.table) are supported.
`version`		Version number to restore to.

Examples

-- Restore to version 5
RESTORE orders TO VERSION 5;

-- Restore using AS OF syntax
RESTORE orders TO VERSION AS OF 5;

-- Restore with the optional TABLE keyword
RESTORE TABLE warehouse.sales.transactions TO VERSION 12;

-- Restore after identifying the correct version from history
DESCRIBE HISTORY orders;
-- Find the version before the problematic operation
RESTORE orders TO VERSION 42;

Pitfalls

If VACUUM has deleted files that were active at the target version, the restore will fail. Always verify that the target version's files are still available before restoring.
RESTORE creates a new version rather than rolling back. The version number always increases. This means queries using VERSION AS OF for versions between the target and the restore will still return their original data.
Restoring to a version with a different schema changes the table's active schema. Downstream consumers should be prepared for schema changes after a restore.
RESTORE is a write operation that modifies the transaction log. It may conflict with concurrent writers. Coordinate restores during maintenance windows when possible.