Pular para o conteúdo principal

Tipo de ampliação

info

Visualização

Esse recurso está em Public Preview em Databricks Runtime 15.4 LTS e acima.

Tabelas com ampliação de tipo ativada permitem que você altere os tipos de dados da coluna para um tipo mais amplo sem reescrever os arquivos de dados subjacentes. O senhor pode alterar os tipos de coluna manualmente ou usar a evolução do esquema para desenvolver os tipos de coluna.

important

A ampliação de tipos está disponível em Databricks Runtime 15.4 LTS e acima. As tabelas com ampliação de tipo ativada só podem ser lidas em Databricks Runtime 15.4 LTS e acima.

O alargamento do tipo requer o Delta Lake. Todas as tabelas gerenciar Unity Catalog usam Delta Lake por default.

Alterações de tipo suportadas​

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

Tipo de origem

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 escala

date

timestampNTZ

Para evitar a promoção acidental de valores inteiros para decimais, o senhor deve alterar manualmente o tipo commitde byte, short, int, ou long para decimal ou double. Ao promover um tipo de inteiro para decimal ou double, se qualquer ingestão downstream gravar esse valor de volta em uma coluna de inteiro, Spark truncará a parte fracionária dos valores por default.

nota

Ao alterar qualquer tipo numérico para decimal, a precisão total deve ser igual ou maior que a precisão inicial. Se o senhor também aumentar a escala, a precisão total deverá aumentar em um valor correspondente.

A meta mínima para os tipos byte, short e 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 alvo mínimo é decimal(12,3).

As alterações de tipo são suportadas para colunas e campos de nível superior aninhados em estruturas, mapas e matrizes.

Ativar ampliação de texto​

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

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

Você também pode ativar a ampliação de texto durante a criação da tabela:

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

Quando o senhor ativa a ampliação de tipo, ele define o recurso de tabela typeWidening, que atualiza os protocolos de leitura e gravação. O senhor deve usar o site Databricks Runtime 15.4 ou o acima for para interagir com tabelas com a ampliação de tipos ativada. Se os clientes externos também interagirem com a tabela, verifique se eles suportam esse recurso da tabela. Consulte Delta Lake recurso compatibilidade e protocolos.

Aplicar manualmente uma alteração de tipo​

Use o comando ALTER COLUMN para alterar manualmente os tipos:

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

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

Ampliar os tipos com a evolução automática do esquema​

A evolução do esquema funciona com a ampliação do tipo para atualizar os tipos de dados nas tabelas de destino para que correspondam ao tipo de dados recebidos.

nota

Sem a ampliação do tipo ativada, a evolução do esquema sempre tenta fazer o downcast dos dados para corresponder aos tipos de coluna na tabela de destino. Se o senhor não quiser ampliar automaticamente os tipos de dados nas tabelas de destino, desative a ampliação de tipos antes de executar cargas de trabalho com a evolução do esquema ativada.

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

  • A execução do comando de gravação com a evolução automática do esquema ativada.
  • A tabela de destino tem a ampliação de tipos ativada.
  • O tipo de coluna de origem é mais largo do que o tipo de coluna de destino.
  • A ampliação de tipo suporta a mudança de tipo.
  • A mudança de tipo não é 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 promoção acidental de inteiros para decimais.

As incompatibilidades de tipos que não atendem a todas essas condições seguem as regras normais de imposição de esquema. Ver imposição de esquema.

Desativar o recurso de tabela de ampliação de tipos​

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

SQL
  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 tabela de ampliação de tipo nem desfaz os tipos que foram alterados.

Se o senhor precisar remover completamente o recurso da tabela de ampliação de tipo, poderá usar o comando DROP FEATURE, conforme mostrado no exemplo a seguir:

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

As tabelas que habilitaram a ampliação de tipo usando o Databricks Runtime 15.4 LTS exigem a eliminação do recurso typeWidening-preview.

Ao eliminar a ampliação de texto, todos os arquivos de dados que não estão em conformidade com o esquema de tabela atual são reescritos. Consulte Drop a Delta Lake table recurso e downgrade table protocol.

transmissão de uma tabela Delta​

nota

O suporte para Type Widening na transmissão estruturada está disponível em Databricks Runtime 16.3 e acima.

Na transmissão de uma tabela Delta, as alterações de tipo são tratadas como alterações de esquema não aditivas, de forma semelhante à renomeação ou eliminação de uma coluna com o Column Mapping.

O senhor pode fornecer um local de acompanhamento de esquema para permitir a transmissão de Delta Lake tabelas com uma alteração de tipo aplicada.

Cada transmissão lida 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.

nota

Para cargas de trabalho de transmissão que combinam dados de várias tabelas de origem Delta, o senhor deve especificar diretórios exclusivos no checkpointLocation para cada tabela de origem.

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

Depois de fornecer um local de acompanhamento do esquema, a transmissão evoluirá seu esquema rastreado sempre que uma alteração de tipo for detectada e, em seguida, parará. Nesse momento, o senhor pode tomar qualquer medida necessária para lidar com a mudança de tipo, como ativar a ampliação de tipo na tabela downstream ou atualizar a consulta de transmissão.

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

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")
)

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

Delta Sharing​

nota

O suporte para Type Widening em Delta Sharing está disponível em Databricks Runtime 16.1 e acima.

O compartilhamento de uma tabela Delta Lake com a ampliação de tipos ativada é suportado em Databricks-to-Databricks Delta Sharing. O provedor e o destinatário devem estar em Databricks Runtime 16.1 ou acima.

Para ler o Change Data Feed de uma tabela do Delta Lake com ampliação de tipo ativada usando o Delta Sharing, o senhor deve definir o formato de resposta como delta:

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

A leitura do feed de dados de alteração em todas as alterações de tipo não é suportada. Em vez disso, o senhor deve dividir as operações 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 o Iceberg​

Iceberg não é compatível com todas as alterações de tipo cobertas pela ampliação de tipo, consulte Iceberg evolução do esquema. Em particular, o Databricks não é compatível com as seguintes alterações de tipo:

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

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

Se o senhor aplicar uma dessas alterações de tipo sem suporte a uma tabela Delta Lake, a ativação da compatibilidade Uniforme com Iceberg na tabela resultará em um erro. Para resolver o erro, o senhor deve eliminar o recurso de tabela de ampliação de tipos.

Outras limitações​

  • Não há suporte para o fornecimento de um local de acompanhamento de esquema usando SQL quando a transmissão de uma tabela Delta Lake com uma alteração de tipo.
  • Não há suporte para o compartilhamento de uma tabela usando o Delta Sharing com a ampliação de tipo ativada com consumidores que não sejam da Databricks.
Última atualização em