Skip to main content
Last updated on

Clone a managed Iceberg table

Public Preview

Unity Catalog-managed Iceberg tables are available in Public Preview in Databricks Runtime 16.4 LTS and above.

You can create a full, independent copy of a managed Iceberg table using DEEP CLONE. A deep clone copies both the data files and the table metadata to a new managed Iceberg table in Unity Catalog.

Managed Iceberg tables support only deep cloning. Shallow cloning and format conversion during cloning are not supported.

Clone methods for Iceberg tables​

The clone operation you use depends on your source and target table types:

Source

Target

Operation

Managed Iceberg

Managed Iceberg

DEEP CLONE.

Foreign Iceberg

Managed Iceberg

DEEP CLONE. See Clone a foreign Iceberg table to managed Iceberg.

Parquet or foreign Iceberg

Managed or external Delta Lake

Incremental clone. See Incrementally clone Parquet and Apache Iceberg tables to Delta Lake.

To create a managed Iceberg table from query results instead of cloning an existing table, use CREATE TABLE ... AS SELECT. See CREATE TABLE [USING].

SHALLOW CLONE isn't supported for Iceberg tables. See Limitations.

Requirements​

To deep clone a managed Iceberg table, you need:

  • Databricks Runtime 16.4 LTS or above.
  • SELECT privileges on the source table.
  • If replacing an existing table, CREATE TABLE privileges on the target schema, or MODIFY privileges on the target table.
  • Predictive optimization enabled on the target catalog or schema.

Deep clone a managed Iceberg table​

Use CREATE TABLE ... DEEP CLONE to copy a managed Iceberg table:

SQL
CREATE TABLE <catalog>.<schema>.<target-table>
DEEP CLONE <catalog>.<schema>.<source-table>;

To replace an existing target table:

SQL
CREATE OR REPLACE TABLE <catalog>.<schema>.<target-table>
DEEP CLONE <catalog>.<schema>.<source-table>;

To create the target only if it does not already exist:

SQL
CREATE TABLE IF NOT EXISTS <catalog>.<schema>.<target-table>
DEEP CLONE <catalog>.<schema>.<source-table>;

For full CREATE TABLE CLONE syntax, see CREATE TABLE CLONE.

Archive a production table​

To create an independent snapshot of a production table for archival or compliance purposes:

SQL
CREATE TABLE prod_catalog.archive.orders_snapshot_may2026
DEEP CLONE prod_catalog.main.orders;

Copy a table to a development environment​

To clone a production table to a development catalog for safe experimentation without affecting production data:

SQL
CREATE OR REPLACE TABLE dev_catalog.test.orders
DEEP CLONE prod_catalog.main.orders;

Clone a foreign Iceberg table to managed Iceberg​

You can use DEEP CLONE to migrate a foreign Iceberg table into Unity Catalog as a managed Iceberg table. The clone copies all data and metadata into Unity Catalog storage. The original files managed by the external catalog aren't reused.

SQL
CREATE TABLE <uc-catalog>.<schema>.<target-table>
DEEP CLONE <foreign-catalog>.<schema>.<source-table>;

After the clone completes, the target table is a fully managed Iceberg table in Unity Catalog, independent of the source catalog.

note

Zero-copy migration from a foreign catalog is not supported. See Limitations.

Set table properties on a deep clone​

You can't set Iceberg table properties in the DEEP CLONE statement. To add or override properties on the cloned table, use ALTER TABLE SET TBLPROPERTIES after the clone completes.

For example, to set custom properties to record the source of a clone used as a snapshot:

SQL
CREATE TABLE prod_catalog.archive.orders_snapshot
DEEP CLONE prod_catalog.main.orders;

ALTER TABLE prod_catalog.archive.orders_snapshot
SET TBLPROPERTIES (
  'archive.source' = 'prod_catalog.main.orders',
  'archive.created_date' = '2026-05-11'
);

Clone behavior​

Important considerations for deep clone behavior:

  • A deep clone is a complete, independent copy of the source table. Changes to the clone do not affect the source, and changes to the source do not affect the clone.
  • A deep clone has an independent snapshot history. Time travel on the clone uses the clone's history, not the source's history.
  • The schema, partitioning information, and table properties are copied to the deep clone. Unity Catalog tags are not copied.
  • After creation, Unity Catalog manages the clone independently with predictive optimization.

Limitations​

  • Shallow cloning isn't supported for managed Iceberg tables.
  • Unity Catalog doesn't support zero-copy conversion of foreign Iceberg tables to managed Iceberg tables. You must use DEEP CLONE. All data is copied to Unity Catalog storage during the clone operation.
  • Deep clones don't copy table history, which affects time travel queries.
  • You can't change the table format during cloning. The target is always a managed Iceberg table.
  • You can't set table properties during cloning. Use ALTER TABLE SET TBLPROPERTIES after the deep clone completes. See Set table properties on a deep clone.
On this page