Clonar uma tabela de Iceberg gerenciada

Você pode criar uma cópia completa e independente de uma tabela Iceberg gerenciada usando DEEP CLONE. Um clone profundo copia tanto os arquivos de dados quanto os metadados da tabela para uma nova tabela gerenciada do Iceberg no Unity Catalog.

As tabelas de Iceberg gerenciadas dão suporte apenas à clonagem profunda. Não há suporte para clonagem superficial e conversão de formato durante a clonagem.

Métodos de clonagem para tabelas Iceberg

A operação de clone usada depende dos tipos de tabela de origem e de destino:

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

SHALLOW CLONE não há suporte para tabelas Iceberg. Confira Limitações.

Requirements

Para clonar profundamente uma tabela de Iceberg gerenciada, você precisa:

• Databricks Runtime 16.4 LTS ou superior.
• SELECT permissões sobre a tabela de origem.
• Se for substituir uma tabela existente, privilégios CREATE TABLE sobre o esquema de destino ou privilégios MODIFY sobre a tabela de destino.
• Otimização preditiva habilitada no catálogo ou esquema de destino.

Clonar profundamente uma tabela de Iceberg gerenciada

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

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

Para substituir uma tabela de destino existente:

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

Para criar o destino somente se ele ainda não existir:

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

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

Arquivar uma tabela de produção

Para criar um instantâneo independente de uma tabela de produção para fins de arquivamento ou conformidade:

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:

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

Clonar uma tabela de Iceberg estrangeira para o Iceberg gerenciado

Você pode usar DEEP CLONE para migrar uma tabela Iceberg externa para o Unity Catalog como uma tabela Iceberg administrada. A clonagem copia todos os dados e metadados para o armazenamento do Unity Catalog. Os arquivos originais gerenciados pelo catálogo externo não são reutilizados.

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

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

Definir propriedades da tabela em um clone profundo

Você não pode definir as propriedades da tabela Iceberg na instrução DEEP CLONE . Para adicionar ou sobrescrever 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 instantâneo:

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 sobre o comportamento da clonagem profunda:

• Um clone profundo é uma cópia completa e independente da tabela de origem. As alterações no clone não afetam a fonte, e as alterações na fonte não afetam o clone.
• Um clone profundo tem um histórico de instantâneos independente. A viagem no tempo no clone usa o histórico do clone, não o histórico da fonte.
• O esquema, as informações de particionamento e as propriedades da tabela são copiados para o clone profundo. As tags do Unity Catalog não são copiadas.
• Após a criação, o Unity Catalog gerencia o clone de forma independente usando otimização preditiva.

Limitações

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