Clonar uma tabela no Azure Databricks

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

O Azure Databricks também suporta a clonagem de tabelas Parquet e Apache Iceberg. Veja Clonar de forma incremental tabelas Parquet e Apache Iceberg para o Delta Lake e Clonar uma tabela Iceberg gerida.

Para obter detalhes sobre como usar o clone com o Unity Catalog, consulte Clone superficial para tabelas do Unity Catalog.

Tipos de clones

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

Os metadados clonados incluem: esquema, informação de particionamento, invariantes, anulabilidade e TBLPROPERTIES. Apenas para clones profundos, os metadados de fluxo e COPY INTO também são clonados. Os metadados que não são clonados são a descrição da tabela, os metadados de commit definidos pelo utilizador, 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 for 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 estiver sendo substituída, quantos arquivos serão removidos da tabela atual.
• num_copied_files: Número de arquivos que foram copiados da origem (0 para clones superficiais).
• removed_files_size: Tamanho em bytes dos arquivos que estão sendo removidos da tabela atual.
• copied_files_size: Tamanho em bytes dos arquivos copiados para a tabela.

Permissions

Você deve configurar permissões para o controle de acesso à tabela do Azure Databricks e seu provedor de nuvem.

Controlo de acesso a tabelas

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

• SELECT permissão na tabela de origem.
• Se estiver a usar CLONE para criar uma nova tabela, deve ter permissões CREATE na base de dados onde está a criar a tabela.
• Se estiveres a usar CLONE para substituir uma tabela, deves ter permissão MODIFY na tabela.

Permissões do provedor de nuvem

Os leitores de um clone profundo precisam de acesso de leitura ao diretório do clone. Os redatores precisam de permissões de escrita no diretório do clone.

Os leitores de um clone superficial precisam de acesso de leitura tanto aos ficheiros de dados da tabela de origem como ao diretório do clone, porque os ficheiros de dados permanecem na origem. Os redatores precisam de permissões de escrita no diretório do clone.

Examples

Criar clones profundos ou rasos

Os seguintes exemplos de código demonstram como criar clones profundos e superficiais:

SQL

Crie um clone profundo:

CREATE TABLE target_table CLONE source_table;

Substituir um alvo existente:

CREATE OR REPLACE TABLE target_table CLONE source_table;

Crie uma cópia profunda ou ignore se o alvo já existir:

CREATE TABLE IF NOT EXISTS target_table CLONE source_table;

Crie uma clonagem superficial na versão mais recente, numa versão específica ou numa data e hora específicas. O carimbo temporal pode ser uma cadeia de datas 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 para 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 numa versão específica:

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

Clone a origem numa marca temporal específica:

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

Scala

A API Scala DeltaTable é específica de 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 numa versão específica:

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

Clone a origem numa marca temporal específica:

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

Para obter detalhes de sintaxe, consulte CREATE TABLE CLONE.

Verifique metadados copiados durante CLONE

Este exemplo mostra os metadados que são e os que não são copiados durante operações de CLONE, especificamente TBLPROPERTIES, as 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 logs não padrão, depois insera 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 uma cópia profunda e uma cópia superficial:

CREATE OR REPLACE TABLE test_clone_deep DEEP CLONE test_clone_source;

CREATE TABLE test_clone_shallow SHALLOW CLONE test_clone_source;

Confirma que TBLPROPERTIES foram copiados para os dois 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 para os 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';

Confirma que a história de Delta Lake não é copiada 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 o clone profundo para preservar o estado de uma tabela num determinado momento para fins de arquivo. Você pode sincronizar clones profundos incrementalmente para manter um estado atualizado de uma tabela de origem para recuperação de desastres.

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

CREATE OR REPLACE TABLE archive_table CLONE my_prod_table

Reprodução de modelos ML

Para casos de uso em aprendizagem automática, pode querer arquivar uma versão de uma tabela que foi usada para treinar um modelo de ML. Modelos futuros podem ser testados usando este conjunto de dados arquivado. Para arquivar uma versão de 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

Experiências de curto prazo numa mesa de produção

Para testar um fluxo de trabalho numa tabela de produção sem corromper a tabela, crie um clone superficial. Os clones superficiais permitem executar cargas de trabalho sobre a tabela clonada, que faz referência a todos os dados de produção, mas não afeta quaisquer cargas 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, volte a integrar as alterações. A fusão utiliza informações de atualização no clone para restringir, sempre que possível, apenas aos ficheiros alterados:

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 *;

Elimina o clone quando terminares:

DROP TABLE my_test;

Substituir propriedades da tabela

As substituições das propriedades da tabela são úteis para:

• Anotação de tabelas com informações do proprietário ou usuário ao compartilhar dados com diferentes unidades de negócios.
• Arquivar tabelas de Delta Lake quando precisas de viajar no tempo no arquivo. Podes especificar os períodos de retenção de dados e registos de forma independente para a tabela de arquivo. 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 em Python é específica para o 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 Scala DeltaTable é específica para 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 do metastore Hive legado

Para uma tabela Delta Lake registada na metastore Hive ou uma coleção de ficheiros não registados como tabela, clone apresenta os seguintes comportamentos:

• Alterações a clones profundos ou superficiais não afetam a tabela de origem.
• Clones superficiais referenciam ficheiros de dados no diretório de origem. Se correr VACUUM na tabela de origem, os clientes já não conseguem ler esses ficheiros de dados e isso gera um FileNotFoundException. Para reparar, usa clone com replace o clone superficial. Se isto acontecer frequentemente, considera 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 tanto os dados como os metadados.
• A clonagem com replace para um destino que já tem uma tabela nesse caminho cria um log Delta, caso ainda não exista. Execute VACUUM para limpar os dados existentes.
• Para tabelas Delta Lake existentes, a clonagem cria um novo commit incremental que inclui apenas novos metadados e dados da tabela de origem desde a última clonagem.
• Clonar uma tabela difere de Create Table As Select (CTAS). Um clone copia os metadados da tabela de origem para além dos dados. Não precisas de especificar particionamento, formatação, invariantes, anulabilidade ou outras definições.
• Uma tabela clonada tem um histórico independente de sua tabela de origem. As consultas de viagem no tempo numa tabela clonada não funcionam com as mesmas entradas que na tabela de origem.