Partilhar via

Alargamento do tipo

Importante

Esse recurso está no Public Preview no Databricks Runtime 15.4 LTS e superior.

As tabelas com alargamento de tipo ativado permitem alterar os tipos de dados de coluna para um tipo mais amplo sem reescrever arquivos de dados subjacentes. Você pode alterar os tipos de coluna manualmente ou usar a evolução do esquema para evoluir os tipos de coluna.

Importante

A ampliação de tipo está disponível a partir do Databricks Runtime 15.4 LTS e nas versões posteriores. As tabelas com alargamento de tipo ativado só podem ser lidas no Databricks Runtime 15.4 LTS e superior.

O alargamento do tipo requer Delta Lake. Todas as tabelas gerenciadas pelo Unity Catalog usam Delta Lake por padrão.

Alterações de tipo suportadas

Você pode ampliar os tipos de acordo com as seguintes regras:

Tipo de fonte Tipos mais amplos suportados
byte short, int, long, decimal, double
short int, long, decimal, double
int long, decimal, double
long decimal
float double
decimal decimal com maior precisão e amplitude
date timestampNTZ

Para evitar a promoção acidental de valores inteiros para decimais, você deve confirmar manualmente as alterações de tipo de byte, short, int, ou long para decimal ou double. Ao promover um tipo de dado inteiro para decimal ou double, se qualquer processamento a jusante gravar esse valor de volta numa coluna do tipo inteiro, o Spark truncará, por padrão, a parte fracionária dos valores.

Nota

Ao alterar qualquer tipo numérico para decimal, a precisão total deve ser igual ou superior à precisão inicial. Se aumentar também a escala, a precisão total deve aumentar em uma quantidade correspondente.

O objetivo mínimo para os tipos byte, shorte int é decimal(10,0). A meta mínima para long é decimal(20,0).

Se você quiser adicionar duas casas decimais a um campo com decimal(10,1), o destino mínimo é decimal(12,3).

Há suporte para alterações de tipo para colunas de nível superior e campos aninhados dentro de estruturas, mapas e matrizes.

Ativar expansão de tipo

Você pode habilitar a ampliação de tipo em uma tabela existente definindo a propriedade da tabela delta.enableTypeWidening como true.

  ALTER TABLE <table_name> SET TBLPROPERTIES ('delta.enableTypeWidening' = 'true')

Você também pode habilitar a ampliação de tipos durante a criação da tabela.

  CREATE TABLE T(c1 INT) TBLPROPERTIES('delta.enableTypeWidening' = 'true')

Importante

Quando se ativa o alargamento de tipo, define o recurso de tabela typeWidening, que melhora os protocolos de leitura e escrita. Você deve usar o Databricks Runtime 15.4 ou superior para interagir com tabelas com alargamento de tipo habilitado. Se os clientes externos também interagirem com a tabela, verifique se eles oferecem suporte a esse recurso de tabela. Consulte Compatibilidade de recursos e protocolos do Delta Lake.

Aplicar manualmente uma alteração de tipo

Use o comando ALTER COLUMN para alterar manualmente tipos:

ALTER TABLE <table_name> ALTER COLUMN <col_name> TYPE <new_type>

Esta operação atualiza o esquema de tabela sem reescrever os arquivos de dados subjacentes.

Amplie os tipos com evolução automática do esquema

A evolução do esquema funciona com alargamento de tipos para atualizar os tipos de dados nas tabelas de destino para corresponder ao tipo de dados recebidos.

Nota

Sem o alargamento de tipo habilitado, a evolução do esquema tenta sempre converter dados para um tipo inferior para corresponder aos tipos de coluna na tabela de destino. Se você não quiser ampliar automaticamente os tipos de dados em suas tabelas de destino, desative a ampliação de tipos antes de executar cargas de trabalho com a evolução do esquema habilitada.

Para usar a evolução do esquema para ampliar o tipo de dados de uma coluna durante a ingestão, você deve atender às seguintes condições:

  • O comando write é executado com a evolução automática do esquema ativada.
  • A tabela de destino tem a expansão de tipo ativada.
  • O tipo de coluna de origem é maior do que o tipo de coluna de destino.
  • O alargamento de tipo suporta a alteração de tipo.
  • A alteração de tipo não é uma de byte, short, int, ou long para decimal ou double. Essas alterações de tipo só podem ser aplicadas manualmente usando ALTER TABLE para evitar a conversão inadvertida de inteiros para decimais.

Incompatibilidades de tipo que não atendem a todas essas condições seguem as regras normais de imposição de esquema. Consulte imposição de esquema.

Desativar o recurso de tabela de alargamento de tipo

Você pode evitar o alargamento acidental de tipos em tabelas habilitadas definindo a propriedade como false:

  ALTER TABLE <table_name> SET TBLPROPERTIES ('delta.enableTypeWidening' = 'false')

Essa configuração impede futuras alterações de tipo na tabela, mas não remove o recurso de ampliação de tipo da tabela nem desfaz os tipos que foram alterados.

Se precisa remover completamente as funcionalidades da tabela de alargamento de tipo, pode usar o comando DROP FEATURE, conforme demonstrado no exemplo a seguir:

 ALTER TABLE <table-name> DROP FEATURE 'typeWidening' [TRUNCATE HISTORY]

Nota

As tabelas que permitiram a expansão de tipos usando o Databricks Runtime 15.4 LTS requerem eliminação do recurso typeWidening-preview.

Ao descartar a ampliação de tipo, todos os arquivos de dados que não estão em conformidade com o esquema de tabela atual são reescritos. Consulte Remover uma funcionalidade da tabela Delta Lake e fazer downgrade do protocolo da tabela.

Streaming a partir de uma tabela Delta

Nota

O suporte para Expansão de Tipo no Streaming Estruturado está disponível no Databricks Runtime 16.3 e posterior.

Ao transmitir a partir de uma tabela Delta, as alterações de tipo são tratadas como alterações de esquema não aditivas, semelhantes a renomear ou soltar uma coluna com o Mapeamento de Coluna.

Você pode fornecer um local de rastreamento de esquema para habilitar o streaming de tabelas Delta Lake com uma alteração de tipo aplicada.

Cada fluxo lido em relação a uma fonte de dados deve ter sua própria schemaTrackingLocation especificação. O especificado schemaTrackingLocation deve estar contido no diretório especificado para checkpointLocation da tabela de destino para escrita em fluxo contínuo.

Nota

Para cargas de trabalho de streaming que combinam dados de várias tabelas Delta de origem, deve especificar diretórios únicos no checkpointLocation para cada tabela de origem.

A opção schemaTrackingLocation é usada para especificar o caminho para o rastreamento de esquema, conforme mostrado no exemplo de código a seguir:

Python

checkpoint_path = "/path/to/checkpointLocation"

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

linguagem de programação Scala

val checkpointPath = "/path/to/checkpointLocation"

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

Depois de fornecer um local de rastreamento de esquema, o fluxo evoluirá seu esquema rastreado sempre que uma alteração de tipo for detetada e, em seguida, parar. Nesse momento, você pode tomar qualquer ação necessária para lidar com a alteração de tipo, como habilitar o alargamento de tipo na tabela downstream ou atualizar a consulta de streaming.

Para retomar o processamento, defina a configuração spark.databricks.delta.streaming.allowSourceColumnTypeChange do Spark ou a opção allowSourceColumnTypeChangede leitor DataFrame :

Python

checkpoint_path = "/path/to/checkpointLocation"

(spark.readStream
  .option("schemaTrackingLocation", checkpoint_path)
  .option("allowSourceColumnTypeChange", "<delta_source_table_version>")
  # alternatively to allow all future type changes for this stream:
  # .option("allowSourceColumnTypeChange", "always")
  .table("delta_source_table")
  .writeStream
  .option("checkpointLocation", checkpoint_path)
  .toTable("output_table")
)

linguagem de programação Scala

val checkpointPath = "/path/to/checkpointLocation"

spark.readStream
  .option("schemaTrackingLocation", checkpointPath)
  .option("allowSourceColumnTypeChange", "<delta_source_table_version>")
  // alternatively to allow all future type changes for this stream:
  // .option("allowSourceColumnTypeChange", "always")
  .table("delta_source_table")
  .writeStream
  .option("checkpointLocation", checkpointPath)
  .toTable("output_table")

SQL

  -- To unblock for this particular stream just for this series of schema change(s):
  SET spark.databricks.delta.streaming.allowSourceColumnTypeChange.ckpt_<checkpoint_id> = "<delta_source_table_version>"
  -- To unblock for this particular stream:
  SET spark.databricks.delta.streaming.allowSourceColumnTypeChange = "<delta_source_table_version>"
  -- To unblock for all streams:
  SET spark.databricks.delta.streaming.allowSourceColumnTypeChange = "always"

O ID <checkpoint_id> do ponto de verificação e a versão <delta_source_table_version> da tabela de origem do Delta Lake são exibidos na mensagem de erro quando o fluxo é interrompido.

Compartilhamento Delta

Nota

O suporte para a Ampliação de Tipos no Delta Sharing passa a estar disponível no Databricks Runtime 16.1 e em versões superiores.

O compartilhamento de uma tabela Delta Lake com a ampliação de tipo habilitada é suportado no Databricks-to-Databricks Delta Sharing. O provedor e o destinatário devem estar no Databricks Runtime 16.1 ou superior.

Para ler o Feed de Dados de Mudança de uma tabela Delta Lake com alargamento de tipo ativado usando o Compartilhamento Delta, deve definir o formato de resposta como delta:

spark.read
  .format("deltaSharing")
  .option("responseFormat", "delta")
  .option("readChangeFeed", "true")
  .option("startingVersion", "<start version>")
  .option("endingVersion", "<end version>")
  .load("<table>")

Não há suporte para a leitura do Feed de Dados de Alteração quando ocorrem mudanças de tipo. Em vez disso, você deve dividir a operação em duas leituras separadas, uma terminando na versão da tabela que contém a alteração de tipo e a outra começando na versão que contém a alteração de tipo.

Limitações

Compatibilidade com Apache Iceberg

O Apache Iceberg não suporta todas as alterações de tipo cobertas pelo alargamento de tipo, consulte Iceberg Schema Evolution. Em particular, o Azure Databricks não suporta as seguintes alterações de tipo:

  • byte, short, int, long para decimal ou double
  • aumento da escala decimal
  • date a timestampNTZ

Quando a compatibilidade UniForm com Iceberg está habilitada em uma tabela Delta Lake, a aplicação de uma dessas alterações de tipo resulta em um erro.

Se você aplicar uma dessas alterações de tipo sem suporte a uma tabela Delta Lake, habilitar a compatibilidade Uniforme com Iceberg na tabela resultará em um erro. Para resolver o erro, deve eliminar a funcionalidade da tabela de expansão de tipo.

Outras Limitações

  • Não há suporte para fornecer um local de monitorização do esquema usando SQL ao efetuar streaming de uma tabela Delta Lake com uma alteração de tipo.
  • Não há suporte para o compartilhamento de uma tabela usando o Compartilhamento Delta com ampliação de tipo habilitada com consumidores que não são do Databricks.
  • Last updated on