Creates a copy of a Delta table, either as a lightweight metadata reference (shallow) or a full independent copy (deep).
CLONE <source> TO <target> [SHALLOW | DEEP] [VERSION <n>] [TIMESTAMP '<ts>'] [REPLACE]## Overview CLONE creates a copy of a Delta table at a new storage location. The clone can be shallow (metadata only, referencing source data files) or deep (full physical copy of all data files). Cloning supports time travel, allowing you to clone the table as it existed at a specific version or timestamp. ## Shallow Clone Semantics A shallow clone creates a new Delta transaction log at the target location. The AddFile actions in this log point to the same physical data files as the source table. No data is copied. - **Speed**: Near-instantaneous regardless of table size. - **Storage**: Only the transaction log metadata is written (typically a few KB to MB). - **Dependency**: The cloned table depends on the source table's storage. If the source files are deleted (for example, by VACUUM), queries against the shallow clone will fail with file-not-found errors. - **Writes**: New writes to the shallow clone produce files in the target location. Only the original referenced files remain in the source location. Shallow clones are ideal for creating development or testing environments, branching experiments, and short-lived staging copies. ## Deep Clone Semantics A deep clone physically copies every data file from the source location to the target location and creates a new transaction log. - **Speed**: Proportional to the amount of data copied. - **Storage**: Requires storage equal to the source table size. - **Independence**: The target table is fully independent. Deleting or vacuuming the source has no effect on the clone. Deep clones are ideal for backups, cross-environment migrations, and long-lived independent copies. ## Time Travel When VERSION AS OF or TIMESTAMP AS OF is specified, the clone reads the source table's snapshot at the requested point in time. The target table contains exactly the files that were active at that version or timestamp. This is useful for creating reproducible datasets from historical states. ## Transaction Log The clone operation creates a new table version at the target. The commit info records the source table path, the source version, and whether the clone was shallow or deep. This metadata is visible in DESCRIBE HISTORY output for the target table. ## Result Set Returns a result set with three rows: | metric | value | |--------|-------| | files_copied | Number of files in the cloned table | | bytes_copied | Total bytes of cloned data | | source_version | Version of the source that was cloned | ## Access Control | Privilege | Object | Notes | |-----------|--------|-------| | read | Source table | Required to read metadata and (for deep clones) data files. | | write or create | Target location | Required to write the cloned table. | ## Compatibility CLONE is a DeltaForge extension implementing Delta Lake shallow and deep clone semantics.
| Name | Type | Description |
|---|---|---|
source | Specifies the name or path of the source Delta table to clone. The table must be registered in the session. Fully qualified names are supported. | |
target | Specifies the name or path for the new cloned table. If the target is a registered table name, its configured storage path is used. Otherwise the value is treated as a direct storage path. | |
shallow | If true, creates a shallow clone (references source files). | |
source_version | Source version to clone. | |
source_timestamp | Source timestamp to clone. | |
replace | Whether to replace existing table at target. |
-- Create a shallow clone of the latest version (default)
CLONE production.orders TO staging.orders_copy;-- Create a deep clone for an independent backup
CLONE production.orders TO backup.orders_backup DEEP;-- Clone a specific version for point-in-time testing
CLONE production.orders VERSION AS OF 5 TO staging.orders_v5;-- Clone at a specific timestamp
CLONE production.orders TIMESTAMP AS OF '2024-06-01' TO staging.orders_june SHALLOW;-- Replace an existing staging table with a fresh clone
CLONE production.orders TO staging.orders_copy REPLACE;-- Deep clone a historical version for audit purposes
CLONE TABLE audit.transactions VERSION AS OF 100 TO archive.transactions_q1 DEEP;