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

Atualizar o esquema de uma tabela de transmissão com ALTER TABLE

info

Beta

A atualização de um esquema de tabela de transmissão com ALTER TABLE está em Beta. Para solicitar acesso, inscreva-se na versão Beta.

ALTER TABLE oferece suporte a alterações de esquema em nível de coluna: adicionar, remover e renomear colunas, e ampliar o tipo de uma coluna. Estas são operações somente de metadados. Eles não exigem um refresh completo, não reset o checkpoint de transmissão e não reingerem dados.

nota

O Auto Loader rastreia seu próprio esquema de origem, portanto, DROP COLUMN e RENAME COLUMN podem não entrar em vigor totalmente em tabelas com suporte do Auto Loader. Consulte Os esquemas de origem do Auto Loader não são atualizados.

Operações compatíveis​

Todas as operações exigem um pipeline que publique no Unity Catalog. Eles também exigem metadados externos, exceto em tabelas gerenciadas criadas com CREATE TABLE ... FLOW. Algumas operações têm requisitos adicionais:

Operação

Requisitos adicionais

ADD COLUMN

Nenhum requisito adicional.

DROP COLUMN

Modo de mapeamento de coluna name

RENAME COLUMN

Modo de mapeamento de coluna name

ALTER COLUMN ... TYPE

Ampliação de tipo

Operação

Requisitos adicionais

ADD COLUMN

Nenhum requisito adicional.

DROP COLUMN

Modo de mapeamento de coluna name

RENAME COLUMN

Modo de mapeamento de coluna name

ALTER COLUMN ... TYPE

Ampliação de tipo

Habilitar metadados externos​

Operações de coluna exigem metadados externos no pipeline que possui a tabela de transmissão. Se não estiver habilitado, o comando falha com um erro. Consulte Habilitar acesso a dados externos para tabelas de streaming e views materializadas.

nota

Metadados externos não são necessários para tabelas gerenciadas em pipelines criados com a sintaxe CREATE TABLE ... FLOW.

Defina pipelines.externalMetadata.enabled como true na configuração do pipeline:

JSON
{
  "configuration": {
    "pipelines.externalMetadata.enabled": "true"
  }
}

Para definir isso no Editor de Pipelines do Lakeflow, selecione as configurações do pipeline e adicione pipelines.externalMetadata.enabled com o valor true.

Execute uma atualização de pipeline após habilitá-la. As operações de coluna ALTER TABLE ficam disponíveis a partir de então.

Ativar mapeamento de colunas​

DROP COLUMN e RENAME COLUMN exigem o modo de mapeamento de coluna name. Defina-o na definição do pipeline, o que o aplicará na próxima atualização:

SQL
CREATE OR REFRESH STREAMING TABLE orders
  TBLPROPERTIES ('delta.columnMapping.mode' = 'name')
  AS SELECT * FROM STREAM read_files('/Volumes/main/sales/raw');
atenção

Habilitar o mapeamento de colunas é irreversível e aumenta as versões do protocolo de leitura e escrita da tabela. Versões mais antigas do Databricks Runtime e leitores externos podem não conseguir mais ler a tabela. Consulte Evolução do esquema no Databricks.

Ativar a ampliação de tipo​

ALTER COLUMN ... TYPE requer ampliação de tipo. Sem isso, a instrução falha em vez de ampliar a coluna. Habilite-o para cada tabela no pipeline com a configuração pipelines.enableTypeWidening:

JSON
{
  "configuration": {
    "pipelines.enableTypeWidening": "true"
  }
}

Ou habilite-o para uma única tabela com a propriedade de tabela delta.enableTypeWidening:

SQL
CREATE OR REFRESH STREAMING TABLE orders
  TBLPROPERTIES ('delta.enableTypeWidening' = 'true')
  AS SELECT * FROM STREAM read_files('/Volumes/main/sales/raw');

Tabelas com ampliação de tipo habilitada requerem Databricks Runtime 15.4 LTS ou superior para leitura. Consulte ampliação de tipo em LakeFlow Pipelines.

Atualize o código-fonte do seu pipeline após o ALTER​

ALTER TABLE altera a tabela. Isso não altera o código-fonte do seu pipeline. Se sua tabela de transmissão declarar um esquema explícito, você deverá fazer a mesma alteração no código-fonte do pipeline, ou a próxima atualização do pipeline reconciliará a tabela de volta ao esquema declarado. Este é o comportamento geral descrito em Limitação: atualizações de pipeline e alterações feitas com ALTER.

Para uma tabela de transmissão com um esquema implícito, como CREATE OR REFRESH STREAMING TABLE st AS SELECT * FROM ..., nenhuma alteração no código-fonte é necessária.

Se o pipeline for executado em um agendamento, uma atualização de Trigger poderá ocorrer entre o seu ALTER TABLE e a alteração do código-fonte e reconciliar a tabela com o esquema declarado. Para evitar isso, pause o pipeline enquanto realiza a alteração correspondente:

  1. Pause o cronograma do pipeline.
  2. Execute o comando ALTER TABLE.
  3. Atualize o código-fonte do pipeline para corresponder ao novo esquema.
  4. Retome o programar do pipeline.

Lidar com uma alteração de tipo de origem incompatível​

Se uma origem alterar um tipo de coluna de forma incompatível, por exemplo, user_id de STRING para INT, a atualização do pipeline falhará porque o Delta não consegue converter a coluna existente. Migre a coluna no local em vez de executar um refresh completo:

SQL
-- 1. Add a column with the new type.
ALTER TABLE main.bronze.users ADD COLUMN user_id_new INT;

-- 2. Backfill it from the old column.
UPDATE main.bronze.users SET user_id_new = CAST(user_id AS INT);

-- 3. Drop the old column.
ALTER TABLE main.bronze.users DROP COLUMN user_id;

-- 4. Rename the new column into place.
ALTER TABLE main.bronze.users RENAME COLUMN user_id_new TO user_id;

Em seguida, atualize o código-fonte do pipeline para declarar user_id como INT e execute uma execução. A atualização é bem-sucedida sem um Reset de ponto de verificação ou um refresh completo.

O passo 2 é uma instrução DML em uma tabela de transmissão, que possui seus próprios requisitos. Consulte Adicionar, alterar ou excluir dados em uma tabela de transmissão de destino. Se uma query downstream fizer streaming a partir desta tabela, talvez seja necessário definir skipChangeCommits ao lê-la para que o backfill não falhe nessa transmissão.

Lidar com alterações de esquema de origem não aditivas​

Quando uma fonte lida pela sua tabela de transmissão remove ou renomeia uma coluna, a transmissão para e relata a alteração em vez de tentar adivinhar sua intenção. Reconheça a alteração para continuar:

JSON
{
  "configuration": {
    "spark.databricks.delta.streaming.allowSourceColumnDrop": "always",
    "spark.databricks.delta.streaming.allowSourceColumnRename": "always"
  }
}

Defina cada configuração como always ou para uma versão específica da tabela Delta:

  • always reconhece todas as alterações atuais e futuras desse tipo para o pipeline.
  • Um número de versão reconhece todas as alterações de esquema até e incluindo essa versão da tabela de origem. Encontre a versão no histórico da tabela de origem com DESCRIBE HISTORY, ou a partir do erro relatado quando a transmissão para.
nota

Reconhecer uma alteração de origem não a propaga para a tabela de transmissão. Use ALTER TABLE para fazer a alteração correspondente no destino.

Limitações​

As seguintes limitações se aplicam ao atualizar um esquema de tabela de transmissão com ALTER TABLE.

  • Um refresh completo regenera a tabela de transmissão a partir do código-fonte do pipeline, portanto, as alterações de coluna feitas com ALTER TABLE não são preservadas. Faça a alteração equivalente no código-fonte do pipeline se precisar que ela sobreviva a um refresh completo.
  • O Auto Loader rastreia seu esquema de origem independentemente da tabela de transmissão. Para fazer com que DROP COLUMN ou RENAME COLUMN entrem em vigor em uma tabela com suporte do Auto Loader, consulte Os esquemas de origem do Auto Loader não são atualizados.
  • Views de transmissão não são suportadas. A evolução do esquema não funciona quando uma view de transmissão está no caminho para a tabela de transmissão, abrangendo tanto os fluxos que leem de uma view de transmissão quanto os fluxos definidos a partir de uma. Use operações de coluna ALTER TABLE apenas em tabelas de transmissão cujos fluxos leem diretamente de suas fontes.
  • DROP COLUMN e RENAME COLUMN são bloqueados em tabelas de transmissão com um fluxo AUTO CDC, que rastreia o estado dos dados de alteração indexados por identificadores de coluna. O comando falha com um erro. ADD COLUMN e ALTER COLUMN ... TYPE são suportados.
  • Somente colunas de nível superior são aceitas. Alterações em campos aninhados dentro de estruturas, matrizes ou mapas não são.

Os esquemas de origem do Auto Loader não são atualizados​

Se um fluxo faz a leitura com o Auto Loader, o Auto Loader rastreia o esquema de seus arquivos de origem separadamente do esquema da tabela de transmissão, e ALTER TABLE não o altera. Para uma fonte que continua produzindo a coluna:

  • DROP COLUMN: O Auto Loader continua a inferir a coluna dos arquivos de origem, e a próxima atualização a grava de volta na tabela.
  • RENAME COLUMN: O Auto Loader continua produzindo o nome de coluna antigo. Para uma tabela de esquema implícito, a coluna antiga é adicionada novamente ao lado da nova.

Para que uma exclusão ou renomeação entre em vigor em uma tabela de transmissão com suporte do Auto Loader, restrinja também o que o Auto Loader lê. Declare um esquema de leitor explícito que omita a coluna e defina a opção rescuedDataColumn para que o campo omitido seja enviado para a coluna de dados resgatados em vez de ser descartado. Quando você fornece um esquema, o Auto Loader não adiciona uma coluna de dados resgatados para você, portanto, sem essa opção, o campo é descartado. Consulte Qual é a coluna de dados resgatados?.

Outros recursos​

Nesta página