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

Renomeie e solte colunas com mapeamento de coluna Delta Lake

O mapeamento de coluna do Delta Lake permite alterações apenas de metadados para renomear ou descartar colunas sem reescrever arquivos de dados. O mapeamento de colunas também permite caracteres não compatíveis com Parquet em nomes de colunas, como espaços, para que você possa ingerir dados CSV ou JSON diretamente no Delta Lake sem renomear colunas.

Pré-requisitos​

Antes de habilitar o mapeamento de colunas, analise as Limitações.

O mapeamento de colunas requer o seguinte:

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.

Renomear uma coluna​

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 esquemas de tabela com evolução do esquema.

Soltar colunas​

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 Atualização de esquemas de tabela com evolução do esquema.

Modos de mapeamento de coluna​

A propriedade de tabela delta.columnMapping.mode permite alterações apenas 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​

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.

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

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

Para remover o mapeamento de coluna e fazer downgrade do protocolo da tabela, consulte Manter a compatibilidade.

Manter a compatibilidade​

No Databricks Runtime 15.4 LTS e acima, você pode usar o comando DROP FEATURE para remover o mapeamento de coluna e fazer o downgrade do protocolo da tabela, mantendo a compatibilidade com leitores que usam o Databricks Runtime 10.3 e abaixo.

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​

Alterações de esquema não aditivas, como renomeação ou remoção de colunas, podem interromper leituras de transmissão. Use schemaTrackingLocation para permitir que o Delta Lake rastreie alterações de esquema e evite falhas de transmissão.

Configuração​

Ao configurar schemaTrackingLocation:

  • Cada leitura de transmissão de uma tabela de origem deve ter o seu próprio schemaTrackingLocation.
  • O schemaTrackingLocation deve estar dentro do diretório checkpointLocation do destino de gravação de transmissão.
  • Para cargas de trabalho que leem de várias tabelas de origem, especifique subdiretórios exclusivos dentro de checkpointLocation para cada origem.

Para uma lista completa de opções de transmissão do Delta Lake, consulte Delta Lake.

Ativar mapeamento de colunas em uma transmissão ativa​

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

  1. Interrompa a transmissão
  2. Habilitar o mapeamento de coluna na tabela
  3. Reiniciar a transmissão (primeira reinicialização - inicializa o mapeamento de colunas)
  4. Reinicie a transmissão novamente (segundo reinício – habilita as alterações de esquema).

Quaisquer alterações adicionais de esquema (adicionar ou descartar colunas, ou alterar tipos de coluna) exigem o reinício da transmissão.

Exemplo​

Para especificar um schemaTrackingLocation para uma leitura de transmissão de uma tabela Delta Lake com mapeamento de colunas, use o seguinte exemplo:

Python
checkpoint_path = "/path/to/checkpointLocation"

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

Limitações​

A ativação do mapeamento de coluna pode prejudicar o seguinte:

Recursos adicionais​

Nesta página