Ampliação de tipo

Tabelas com ampliação de tipo habilitada permitem alterar 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 tipos de coluna.

A ampliação de tipo requer Delta Lake. Todas as tabelas gerenciadas do Catálogo do Unity usam o Delta Lake por padrão.

Alterações de tipo com suporte

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

Para evitar a conversão acidental de valores inteiros para decimais, você deve confirmar manualmente alterações de tipo de byte, short, int ou long para decimal ou double. Ao promover um tipo inteiro para decimal ou double, se houver qualquer ingestão downstream que grave esse valor novamente em uma coluna inteira, o Spark truncará a parte fracionária dos valores por padrão.

Há suporte para as alterações de tipo nas colunas de nível superior e campos aninhados no structs, mapas e matrizes.

Habilitar ampliaçã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 tipo durante a criação da tabela:

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

Aplicar manualmente uma alteração de tipo

Use o comando ALTER COLUMN para alterar manualmente os 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.

Ampliar tipos com evolução automática de esquema

A evolução do esquema funciona com a ampliação de tipos para atualizar tipos de dados nas tabelas de destino para corresponder ao tipo de dados de entrada.

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

• O comando de gravação é executado com a evolução automática do esquema habilitada.
• A tabela de destino tem a ampliação de tipo habilitada.
• O tipo de coluna de origem é maior que o tipo de coluna de destino.
• A ampliação de tipo dá suporte à alteração de tipo.
• A alteração de tipo não é de byte, shortou intpara long ou decimaldouble. Essas alterações de tipo só podem ser aplicadas manualmente usando-se ALTER TABLE para evitar a promoção acidental de inteiros para decimais.

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

Desabilitar o recurso de tabela de ampliação de tipo

Você pode impedir a ampliação acidental de tipo 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 expansão de tipo da tabela ou desfaz os tipos que foram alterados.

Se você precisar remover completamente os recursos de tabela de ampliação de tipo, poderá usar o comando DROP FEATURE, conforme mostrado no exemplo a seguir:

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

Ao remover 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. Confira Remover um recurso de tabela do Delta Lake e fazer downgrade do protocolo de tabela.

Streaming de uma tabela Delta

Ao transmitir de uma tabela Delta, as alterações de tipo são tratadas como alterações de esquema não aditivas, semelhantes à renomeação ou à remoção de uma coluna com 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 leitura de streaming em uma fonte de dados deve ter seu próprio schemaTrackingLocation especificado. O especificado schemaTrackingLocation deve estar contido no diretório especificado para a checkpointLocation tabela de destino para gravação de streaming.

A opção schemaTrackingLocation é usada para especificar o caminho para o rastreamento do 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")
)

Scala (linguagem de programação)

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 acompanhamento de esquema, o fluxo evoluirá seu esquema rastreado sempre que uma alteração de tipo for detectada e, em seguida, interromperá. Nesse momento, você pode tomar qualquer ação necessária para lidar com a alteração de tipo, como habilitar a ampliação 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 allowSourceColumnTypeChangeleitor de 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")
)

Scala (linguagem de programação)

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"

A 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 exibidas na mensagem de erro quando o fluxo é interrompido.

Compartilhamento Delta

Há suporte para o compartilhamento de uma tabela Delta Lake com ampliação de tipo habilitada 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 Alteração de Dados de uma tabela do Delta Lake com habilitação de ampliação de tipo usando o Compartilhamento Delta, você 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ções entre alterações 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 do Apache Iceberg

O Apache Iceberg não dá suporte a todas as alterações de tipo cobertas pela ampliação de tipo, consulte a Evolução do Esquema de Iceberg. Em particular, o Azure Databricks não dá suporte às seguintes alterações de tipo:

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

Quando a compatibilidade do UniForm com Iceberg é 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, você deve remover o recurso de tabela de ampliação de tipo.

Outras limitações

• Não há suporte para fornecer um local para rastreamento de esquema usando SQL ao transmitir a partir de uma tabela Delta Lake com uma mudança de tipo.
• Não há suporte para compartilhar uma tabela usando o Compartilhamento Delta com ampliação de tipos habilitada para consumidores fora do Databricks.