Clonar uma tabela gerenciada que usa o Iceberg

Você pode criar uma cópia completa e independente de uma tabela gerenciada que usa o Iceberg com DEEP CLONE. Uma clonagem profunda copia tanto os arquivos de dados quanto os metadados da tabela para uma nova tabela gerenciada usando o Iceberg no Unity Catalog.

As tabelas gerenciadas que usam o Iceberg oferecem suporte apenas a clonagem profunda. Não há suporte para clonagem rasa e conversão de formato durante a clonagem.

Clonar métodos para tabelas Iceberg

A operação de clonagem que você usa depende dos tipos de tabela de origem e de destino:

Origem	Destino	Operação
Tabela gerenciada que usa Iceberg	Tabela gerenciada que usa Iceberg	DEEP CLONE.
Iceberg externo	Tabela gerenciada que usa Iceberg	DEEP CLONE. Consulte Clonar uma tabela Iceberg externa em uma tabela gerenciada usando o Iceberg.
Parquet ou Iceberg externo	Delta Lake gerenciado ou externo	Clone incremental. Consulte Clonar incrementalmente tabelas Parquet e Apache Iceberg para Delta Lake.

Origem	Destino	Operação
Tabela gerenciada que usa Iceberg	Tabela gerenciada que usa Iceberg	DEEP CLONE.
Iceberg externo	Tabela gerenciada que usa Iceberg	DEEP CLONE. Consulte Clonar uma tabela Iceberg externa em uma tabela gerenciada usando o Iceberg.
Parquet ou Iceberg externo	Delta Lake gerenciado ou externo	Clone incremental. Consulte Clonar incrementalmente tabelas Parquet e Apache Iceberg para Delta Lake.

Para criar uma tabela gerenciada usando o Iceberg a partir de resultados de query em vez de clonar uma tabela existente, use CREATE TABLE ... AS SELECT. Consulte CREATE TABLE [USING].

SHALLOW CLONE não é compatível com tabelas Iceberg. Consulte Limitações.

Requisitos

Para fazer um clone profundo de uma tabela gerenciada usando o Iceberg, você precisa:

• Databricks Runtime 16.4 LTS ou superior.
• SELECT Privilégios na tabela de origem.
• Se for substituir uma tabela existente, privilégios CREATE TABLE no esquema de destino ou privilégios MODIFY na tabela de destino.
• Otimização preditiva ativada no catálogo ou esquema de destino.

Clonagem profunda de uma tabela gerenciada usando o Iceberg

Use CREATE TABLE ... DEEP CLONE para copiar uma tabela gerenciada usando o Iceberg:

SQL

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

Para substituir uma tabela de destino existente:

SQL

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

Criar o destino somente se ele ainda não existir:

SQL

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

Para a sintaxe completa de CREATE TABLE CLONE, consulte CREATE TABLE CLONE.

Arquivar uma tabela de produção

Para criar um Snapshot independente de uma tabela de produção para fins de arquivamento ou compliance:

SQL

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

Copiar uma tabela para um ambiente de desenvolvimento

Para clonar uma tabela de produção em um catálogo de desenvolvimento para experimentação segura sem afetar os dados de produção:

SQL

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

Clonar uma tabela Iceberg externa em uma tabela gerenciada usando o Iceberg

You can use DEEP CLONE to migrate a foreign Iceberg table into Unity Catalog as a managed table using Iceberg. 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>;

Após a conclusão do clone, a tabela de destino é uma tabela totalmente gerenciada usando o Iceberg no Unity Catalog, independente do catálogo de origem.

nota

Migração sem cópia de um catálogo externo não é suportada. Consulte Limitações.

Definir propriedades da tabela em um clone profundo

Não é possível definir propriedades da tabela Iceberg na instrução DEEP CLONE. Para adicionar ou substituir propriedades na tabela clonada, use ALTER TABLE SET TBLPROPERTIES após a conclusão da clonagem.

Por exemplo, para definir propriedades personalizadas para registrar a origem de um clone usado como um 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'
);

Comportamento de Clonagem

Considerações importantes para o comportamento de clone profundo:

• Um clone profundo é uma cópia completa e independente da tabela de origem. Alterações no clone não afetam a origem, e alterações na origem não afetam o clone.
• Um clone profundo possui uma história de Snapshot independente. A viagem do tempo no clone usa o histórico do clone, não o histórico da origem.
• O esquema, as informações de particionamento e as propriedades da tabela são copiados para o clone profundo. Tags do Unity Catalog não são copiadas.
• Após a criação, o Unity Catalog gerencia o clone de forma independente com otimização preditiva.

Limitações

• O clone superficial não tem suporte para tabelas gerenciadas que usam Iceberg.
• O Unity Catalog não oferece suporte à conversão sem cópia de tabelas Iceberg externas em tabelas gerenciadas usando o Iceberg. Você deve usar DEEP CLONE. Todos os dados são copiados para o armazenamento do Unity Catalog durante a operação de clonagem.
• Clones profundos não copiam o histórico da tabela, o que afeta as consultas de viagem do tempo.
• Não é possível alterar o formato da tabela durante a clonagem. O destino é sempre uma tabela gerenciada que usa o Iceberg.
• Não é possível definir as propriedades da tabela durante a clonagem. Utilize ALTER TABLE SET TBLPROPERTIES após a conclusão do clone profundo. Consulte Definir propriedades da tabela em um clone profundo.