Clonar uma tabela no Azure Databricks

Clone uma tabela Delta Lake ou Apache Iceberg usando o CLONE comando para criar uma cópia independente em uma versão específica. Clones profundos copiam dados e metadados. Clones rasos copiam apenas metadados e referenciam os arquivos de dados de origem, usando menos computação e armazenamento do que clones profundos.

O Azure Databricks também dá suporte à clonagem de tabelas Parquet e Apache Iceberg. Veja clonar incrementalmente as tabelas Parquet e Apache Iceberg no Delta Lake e clonar uma tabela de Iceberg gerenciada.

Para obter detalhes sobre como clonar com o Unity Catalog, veja Clone superficial para tabelas do Unity Catalog.

Tipos de clone

Os seguintes tipos de clone estão disponíveis:

Metadados clonados incluem: esquema, informações de particionamento, invariáveis, nulidade e TBLPROPERTIES. Somente para clones profundos, os metadados de COPY INTO e de fluxo também são clonados. Os metadados que não são clonados incluem a descrição da tabela, os metadados de confirmação definidos pelo usuário, o histórico da tabela do Delta Lake e as propriedades do Unity Catalog, como tags.

Métricas de clonagem

CLONE relata as seguintes métricas como um DataFrame de linha única quando a operação é concluída:

• source_table_size: tamanho da tabela de origem que está sendo clonada em bytes.
• source_num_of_files: o número de arquivos na tabela de origem.
• num_removed_files: se a tabela está sendo substituída, quantos arquivos são removidos da tabela atual.
• num_copied_files: Número de arquivos copiados da origem (0 para clones superficiais).
• removed_files_size: o tamanho em bytes dos arquivos que estão sendo removidos da tabela atual.
• copied_files_size: o tamanho em bytes dos arquivos copiados para a tabela.

Permissões

Você deve configurar permissões para controle de acesso a tabelas no Azure Databricks e no seu provedor de nuvem.

Controle de acesso de tabela

As seguintes permissões são necessárias para clones profundos e superficiais:

• SELECT permissão na tabela de origem.
• Se você usar CLONE para criar uma nova tabela, é necessária a permissão CREATE no banco de dados onde a tabela está sendo criada.
• Se você está usando CLONE para substituir uma tabela, precisa ter a permissão MODIFY na tabela.

Permissões do provedor de nuvem

Os leitores de um clone profundo precisam ter acesso de leitura ao diretório do clone. Os usuários com permissão de escrita precisam de acesso de escrita ao diretório do clone.

Os leitores de um clone superficial precisam de acesso de leitura aos arquivos de dados da tabela de origem e ao diretório do clone, pois os arquivos de dados permanecem na tabela de origem. Os usuários com permissão de escrita precisam de acesso de escrita ao diretório do clone.

Examples

Criar clones profundos ou rasos

Os exemplos de código a seguir demonstram como criar clones profundos e rasos:

SQL

Crie um clone profundo:

CREATE TABLE target_table CLONE source_table;

Substitua um destino existente:

CREATE OR REPLACE TABLE target_table CLONE source_table;

Crie um clone profundo ou ignore se o destino já existir:

CREATE TABLE IF NOT EXISTS target_table CLONE source_table;

Crie um clone superficial na versão mais recente, em uma versão específica ou em um carimbo de data/hora específico. O carimbo de data/hora pode ser uma cadeia de caracteres de data, como '2019-01-01', ou uma expressão, como date_sub(current_date(), 1).

CREATE TABLE target_table SHALLOW CLONE source_table;

CREATE TABLE target_table SHALLOW CLONE source_table VERSION AS OF version;

CREATE TABLE target_table SHALLOW CLONE source_table TIMESTAMP AS OF timestamp_expression;

Python

A API Python DeltaTable é específica do Delta Lake.

Clone o código-fonte na versão mais recente:

from delta.tables import *

deltaTable = DeltaTable.forName(spark, "source_table")
deltaTable.clone(target="target_table", isShallow=True, replace=False)

Clone o código-fonte em uma versão específica:

deltaTable.cloneAtVersion(version=1, target="target_table", isShallow=True, replace=False)

Clone o código-fonte em um timestamp específico:

deltaTable.cloneAtTimestamp(timestamp="2019-01-01", target="target_table", isShallow=True, replace=False)

Scala

A API Scala DeltaTable é específica do Delta Lake.

Clone o código-fonte na versão mais recente:

import io.delta.tables._

val deltaTable = DeltaTable.forName(spark, "source_table")
deltaTable.clone(target="target_table", isShallow=true, replace=false)

Clone o código-fonte em uma versão específica:

deltaTable.cloneAtVersion(version=1, target="target_table", isShallow=true, replace=false)

Clone o código-fonte em um timestamp específico:

deltaTable.cloneAtTimestamp(timestamp="2019-01-01", target="target_table", isShallow=true, replace=false)

Para obter detalhes da sintaxe, consulte CREATE TABLE CLONE.

Verificar metadados copiados durante CLONE

Este exemplo mostra os metadados que são e que não são copiados durante operações CLONE, especificamente TBLPROPERTIES, tags do Unity Catalog e o histórico do Delta Lake.

Crie uma tabela de origem com uma propriedade personalizada e uma duração de retenção de log não padrão e, em seguida, insira dados para gerar o histórico da tabela:

CREATE OR REPLACE TABLE test_clone_source (id INT, val STRING)
TBLPROPERTIES ('my.custom.prop' = 'hello', 'delta.logRetentionDuration' = '12 days');

ALTER TABLE test_clone_source SET TAGS ('team' = 'data-eng', 'env' = 'prod');
INSERT INTO test_clone_source VALUES (1, 'a');
INSERT INTO test_clone_source VALUES (2, 'b');

Crie um clone profundo e um clone superficial:

CREATE OR REPLACE TABLE test_clone_deep DEEP CLONE test_clone_source;

CREATE TABLE test_clone_shallow SHALLOW CLONE test_clone_source;

Confirme que TBLPROPERTIES seja copiado para ambos os clones:

SHOW TBLPROPERTIES test_clone_source;
SHOW TBLPROPERTIES test_clone_deep;
SHOW TBLPROPERTIES test_clone_shallow;

Confirme que as tags do Unity Catalog não são copiadas em clones:

SELECT catalog_name, schema_name, table_name, tag_name, tag_value FROM information_schema.table_tags WHERE table_name = 'test_clone_source';
SELECT catalog_name, schema_name, table_name, tag_name, tag_value FROM information_schema.table_tags WHERE table_name = 'test_clone_deep';
SELECT catalog_name, schema_name, table_name, tag_name, tag_value FROM information_schema.table_tags WHERE table_name = 'test_clone_shallow';

Confirme se o histórico do Delta Lake não é copiado para clones:

DESCRIBE HISTORY test_clone_source;
DESCRIBE HISTORY test_clone_deep;
DESCRIBE HISTORY test_clone_shallow;

Limpeza:

DROP TABLE IF EXISTS test_clone_shallow;
DROP TABLE IF EXISTS test_clone_source;
DROP TABLE IF EXISTS test_clone_deep;

Arquivamento de dados

Você pode usar um clone profundo para preservar o estado de uma tabela em um determinado momento para fins de arquivamento. Você pode sincronizar clones profundos incrementalmente para manter um estado atualizado de uma tabela de origem para recuperação de desastre.

Execute o comando a seguir uma vez por mês para sincronizar o arquivo:

CREATE OR REPLACE TABLE archive_table CLONE my_prod_table

Reprodução de modelo de ML

Para casos de uso de machine learning, convém arquivar uma versão de uma tabela que foi usada para treinar um modelo de ML. Modelos futuros podem ser testados usando esse conjunto de dados arquivado. Para arquivar uma versão do conjunto de dados com CLONE, faça o seguinte:

Por exemplo, para arquivar a versão de uma tabela usada para treinar um modelo na versão 15:

CREATE TABLE model_dataset CLONE entire_dataset VERSION AS OF 15

Experimentos de curto prazo em uma tabela de produção

Para testar um fluxo de trabalho em uma tabela de produção sem corromper a tabela, crie um clone superficial. Clonagens rasas permitem executar cargas de trabalho na tabela clonada, que faz referência a todos os dados de produção, sem afetar nenhuma carga de trabalho de produção.

Crie um clone superficial da tabela de produção:

CREATE TABLE my_test SHALLOW CLONE my_prod_table;

Execute atualizações e validações no clone:

UPDATE my_test WHERE user_id is null SET invalid=true;

Quando estiver pronto, incorpore as alterações de volta. A mesclagem usa informações de atualização do clone para limitar-se apenas aos arquivos alterados, sempre que possível:

MERGE INTO my_prod_table
USING my_test
ON my_test.user_id <=> my_prod_table.user_id
WHEN MATCHED AND my_test.user_id is null THEN UPDATE *;

Solte o item clonado quando terminar:

DROP TABLE my_test;

Sobrescrever propriedades da tabela

As substituições de propriedade de tabela são úteis para:

• Para anotar tabelas com informações de proprietário ou usuário ao compartilhar dados com unidades de negócios diferentes.
• Arquivar tabelas do Delta Lake quando você precisar de acesso a versões anteriores no arquivo. Você pode especificar os períodos de retenção de dados e logs de forma independente para a tabela de arquivos. Por exemplo:

SQL

Para uma tabela Delta Lake:

CREATE OR REPLACE TABLE archive_table CLONE prod.my_table
TBLPROPERTIES (
delta.logRetentionDuration = '3650 days',
delta.deletedFileRetentionDuration = '3650 days'
)

Para uma tabela Iceberg:

CREATE OR REPLACE TABLE archive_table CLONE prod.my_table
TBLPROPERTIES (
iceberg.logRetentionDuration = '3650 days',
iceberg.deletedFileRetentionDuration = '3650 days'
)

Python

A API DeltaTable do Python é específica do Delta Lake.

dt = DeltaTable.forName(spark, "prod.my_table")
tblProps = {
"delta.logRetentionDuration": "3650 days",
"delta.deletedFileRetentionDuration": "3650 days"
}
dt.clone(target="archive_table", isShallow=False, replace=True, tblProps)

Scala

A API DeltaTable Scala é específica do Delta Lake.

val dt = DeltaTable.forName(spark, "prod.my_table")
val tblProps = Map(
"delta.logRetentionDuration" -> "3650 days",
"delta.deletedFileRetentionDuration" -> "3650 days"
)
dt.clone(target="archive_table", isShallow = false, replace = true, properties = tblProps)

Comportamento da operação de clonagem para metastore herdado do Hive

Para uma tabela Delta Lake registrada no metastore Hive ou uma coleção de arquivos não registrada como tabela, a clonagem apresenta os seguintes comportamentos:

• Alterações em clones profundos ou rasos não afetam a tabela de origem.
• Clones superficiais referenciam arquivos de dados no diretório de origem. Se você executar VACUUM na tabela de origem, os clientes não poderão mais ler esses arquivos de dados e isso gerará um FileNotFoundException. Para reparar, execute o comando clone com replace no clone raso. Se isso acontecer com frequência, considere usar um clone profundo, que não depende da tabela de origem.
• Clones profundos não dependem da tabela de origem, mas são caros de criar porque copiam os dados e os metadados.
• A clonagem com replace para um destino que já tem uma tabela nesse caminho cria um log do Delta, caso ainda não exista. Execute VACUUM para limpar todos os dados existentes.
• Para tabelas existentes do Delta Lake, a clonagem cria um novo commit incremental que inclui apenas novos metadados e dados da tabela de origem desde a última clonagem.
• A clonagem de uma tabela é diferente de Create Table As Select (CTAS). Um clone copia os metadados da tabela de origem além dos dados. Você não precisa especificar particionamento, formato, invariáveis, nulidade ou outras configurações.
• O histórico de tabelas clonadas é independente do histórico das tabelas de origem. As consultas de viagem no tempo em uma tabela clonada não funcionam com as mesmas entradas que na tabela de origem.