Pular para o conteúdo principal
Última atualização em

Renomeie e solte colunas com mapeamento de coluna Delta Lake

Esta página descreve como o mapeamento de colunas do Delta Lake permite alterações apenas de metadados para marcar colunas como excluídas ou renomeadas sem reescrever arquivos de dados.

Databricks oferece suporte a mapeamento de coluna para tabelas Delta Lake. O mapeamento de colunas permite alterações apenas de metadados para marcar colunas como excluídas ou renomeadas sem reescrever arquivos de dados. O mapeamento de coluna também permite o uso de caracteres não permitidos pelo Parquet em nomes de coluna, como espaços. Isso permite ingerir diretamente dados CSV ou JSON no Delta sem renomear colunas.

Pré-requisitos e limitações​

Antes de ativar o mapeamento de colunas, compreenda as seguintes limitações:

  • Tabelas com mapeamento de coluna habilitado só podem ser lidas no Databricks Runtime 10.4 LTS e acima.
  • Ativar mapeamento de coluna pode quebrar:

Ativar mapeamento de coluna​

Use o seguinte comando para habilitar o mapeamento de coluna com o modo id em uma nova tabela:

SQL
CREATE table <table-name> (
  id INT,
  name STRING
)
USING DELTA
TBLPROPERTIES (
  'delta.columnMapping.mode' = 'id'
);

Use o comando a seguir para habilitar o mapeamento de colunas com o modo name em uma tabela existente:

SQL
ALTER TABLE <table-name> SET TBLPROPERTIES (
  'delta.columnMapping.mode' = 'name'
)

Para obter detalhes sobre modos de mapeamento de colunas, consulte Modos de mapeamento de colunas.

Mapeamento de colunas exige os seguintes protocolos Delta:

  • Leitor versão 2 ou acima
  • Writer versão 5 ou acima

Consulte a compatibilidade de recursos e protocolos do Delta Lake.

Renomear uma coluna​

nota

Disponível no Databricks Runtime 10.4 LTS e acima.

Quando o mapeamento de colunas está ativado para uma tabela Delta Lake, é possível renomear uma coluna:

SQL
ALTER TABLE <table-name> RENAME COLUMN old_col_name TO new_col_name

Para mais exemplos, consulte Atualizar o esquema da tabela.

Soltar colunas​

nota

Disponível no Databricks Runtime 11.3 LTS e acima.

Quando o mapeamento de coluna está habilitado para uma tabela Delta Lake, é possível soltar uma ou mais colunas:

SQL
ALTER TABLE table_name DROP COLUMN col_name
ALTER TABLE table_name DROP COLUMNS (col_name_1, col_name_2, ...)

Para obter mais detalhes, consulte Atualizar esquema de tabela.

Modos de mapeamento de coluna​

A propriedade da tabela delta.columnMapping.mode permite alterações somente de metadados para marcar colunas como excluídas ou renomeadas sem reescrever arquivos de dados. Os seguintes modos estão disponíveis:

  • none (default): O mapeamento de colunas não está ativado. Os nomes das colunas estão sujeitos às restrições de nomenclatura do Parquet.
  • name ** **: Isso habilita renomeações e exclusões de colunas apenas nos metadados, e permite caracteres especiais nos nomes das colunas. O modo name pode ser definido em tabelas novas e existentes.
  • id ** **: Isso habilita renomeações e exclusões de colunas apenas nos metadados, e permite caracteres especiais nos nomes das colunas. O modo id deve ser definido na criação da tabela e não pode ser definido em tabelas existentes.
nota

A Databricks recomenda o modo id para a maioria dos casos de uso para fins de compatibilidade. No entanto, o modo name é definido automaticamente se nenhum valor for fornecido para delta.columnMapping.mode e se os recursos de compatibilidade do Iceberg, como UniForm, forem ativados.

Caracteres compatíveis em nomes de coluna​

Quando o mapeamento de colunas está habilitado para uma tabela do Delta Lake, é possível incluir espaços e qualquer um destes caracteres nos nomes das colunas: ,;{}()\n\t=.

Remover mapeamento de coluna​

Você pode remover mapeamento de coluna de uma tabela usando o seguinte comando:

SQL
ALTER TABLE <table-name> SET TBLPROPERTIES ('delta.columnMapping.mode' = 'none')
atenção

A remoção do mapeamento de colunas reescreve todos os arquivos de dados para substituir nomes de coluna físicos por nomes lógicos. Esta operação não suporta resolução de conflitos físicos ou em nível de linha.

Operações de escrita concorrentes causarão um ConcurrentModificationException. Antes de remover o mapeamento de coluna:

  1. Pausar todas as operações de gravação concorrentes, incluindo jobs de transmissão e pipelines ETL.
  2. Desativar otimização preditiva na tabela.
  3. Para tabelas grandes, programe esta operação durante períodos de baixa atividade.

Para uma abordagem alternativa que permite fazer o downgrade do protocolo da tabela, consulte Desativar mapeamento de coluna.

Desativar mapeamento de coluna​

No Databricks Runtime 15.3 e acima, é possível usar o comando DROP FEATURE para remover o mapeamento de coluna e fazer downgrade do protocolo da tabela. Utilize esta abordagem em vez de remover o mapeamento de coluna caso seja necessário rebaixar as versões do protocolo para compatibilidade com leitores mais antigos.

importante

Remover o mapeamento de coluna de uma tabela não remove os prefixos aleatórios usados em nomes de diretório para tabelas particionadas.

Consulte Remover um recurso de tabela do Delta Lake e fazer downgrade do protocolo da tabela.

Mapeamento de coluna e transmissão​

É possível fornecer um local de acompanhamento de esquema para habilitar a transmissão de tabelas Delta Lake com o mapeamento de colunas habilitado. Isso supera um problema onde alterações de esquema não aditivas poderiam resultar em transmissões interrompidas.

Cada leitura de transmissão em uma fonte de dados deve ter seu próprio schemaTrackingLocation especificado. O schemaTrackingLocation especificado deve estar contido no diretório especificado para o checkpointLocation da tabela de destino para gravação de transmissão. Para cargas de trabalho de transmissão que combinam dados de várias tabelas de origem do Delta Lake, é preciso especificar diretórios exclusivos dentro do checkpointLocation para cada tabela de origem. Para uma lista completa de opções de transmissão do Delta Lake, consulte Delta Lake.

Ativar o mapeamento de coluna em um Job em execução​

importante

Para ativar o mapeamento de coluna em um Job de transmissão em execução:

  1. Interromper o job
  2. Habilitar o mapeamento de coluna na tabela
  3. Reiniciar o Job (primeira reinicialização: inicializa o mapeamento de colunas)
  4. Reinicie o Job novamente (segundo reinício - permite alterações de esquema)

Quaisquer outras alterações de esquema (adição ou remoção de colunas, alteração de tipos de coluna) também exigem a reinicialização do Job.

Especificar o local de acompanhamento do esquema​

O exemplo a seguir mostra como especificar um schemaTrackingLocation para uma leitura por transmissão de uma tabela Delta Lake com mapeamento de coluna:

Python
checkpoint_path = "/path/to/checkpointLocation"

(spark.readStream
  .option("schemaTrackingLocation", checkpoint_path)
  .table("delta_source_table")
  .writeStream
  .option("checkpointLocation", checkpoint_path)
  .toTable("output_table")
)

Passos seguintes​

Nesta página