Compatibilidade de recursos e protocolos do Delta Lake

Os protocolos de tabela do Delta Lake especificam quais recursos um cliente deve oferecer suporte para ler ou gravar uma tabela. Esta página aborda versões de protocolo, recursos de tabela, requisitos de compatibilidade e como o Databricks gerencia as atualizações de protocolo. Consulte também Revisar detalhes da tabela com detalhes de descrição.

Protocolo da tabela e compatibilidade

Cada tabela Delta Lake possui uma especificação de protocolo que indica o conjunto de capacidades necessárias para ler e gravar na tabela. Os aplicativos usam a especificação do protocolo para determinar se podem oferecer suporte a todos os recursos que a tabela utiliza. Se um aplicativo não puder oferecer suporte a um recurso no protocolo atual de uma tabela, ele não poderá ler ou gravar nessa tabela.

A maioria dos novos recursos do Delta Lake exige que você atualize o protocolo da tabela.

A tabela a seguir lista os termos key que descrevem os protocolos do Delta Lake:

Termo	Descrição
Cliente Delta Lake	Qualquer sistema que lê ou grava em uma tabela Delta Lake.
Ler protocolo	Especifica o suporte exigido para que um cliente Delta Lake leia uma tabela.
Gravar protocolo	Especifica o suporte necessário para um cliente Delta Lake gravar em uma tabela.
minReaderVersion	Valor inteiro do protocolo do leitor. Valores válidos são 1, 2 ou 3.
minWriterVersion	Valor inteiro do protocolo do gravador. Os valores válidos são os inteiros 2 a 7.
Recurso de tabela	Uma alternativa refinada para versões de protocolo usadas quando minReaderVersion = 3 e minWriterVersion = 7. Os recursos da tabela correspondem aos recursos do Delta Lake ativados opcionalmente.
Recurso do Writer	Um recurso de tabela que requer suporte de cliente de gravação, mas não bloqueia o acesso somente leitura.
Recurso de leitor	Um recurso de tabela que exige suporte de cliente de leitura e gravação. Consulte Versões do Protocolo e Recursos da Tabela.

Os protocolos de escrita e os recursos do escritor afetam apenas a compatibilidade com clientes escritores, permitindo acesso somente leitura à tabela a partir de cargas de trabalho legadas.

Nem todos os recursos do Delta Lake são compatíveis entre si.

Alguns recursos de tabela não podem ser descartados depois de habilitados. Consulte Remover um recurso de tabela do Delta Lake e fazer downgrade do protocolo da tabela.

Versões de protocolo e recursos de tabela

Todas as tabelas do Delta Lake incluem uma versão de protocolo baseada em número inteiro representada por minReaderVersion e minWriterVersion. Cada versão reúne vários recursos, e os recursos são cumulativos entre as versões. Para estar em conformidade com o protocolo do Delta Lake, os clientes devem implementar suporte para todos os recursos em uma determinada versão, incluindo todos os recursos lançados anteriormente.

No Databricks Runtime 12.2 LTS e acima, os *recursos de tabela* substituem o protocolo baseado em inteiros por sinalizadores granulares que indicam quais recursos uma tabela utiliza. Isso permite verificações de compatibilidade mais granulares entre clientes e tabelas.

Os recursos de gravação de tabela afetam a forma como os dados são gravados. Eles exigem minWriterVersion=7, mas não bloqueiam clientes leitores.

Os recursos do leitor de tabela afetam a forma como os dados são lidos. Todos os recursos de leitura também são recursos de gravação e exigem minReaderVersion=3 e minWriterVersion=7. Um cliente não pode gravar em uma tabela que não consegue ler.

Quando os recursos da tabela estão habilitados, eles aparecem no protocolo como readerFeatures ou writerFeatures. O Delta Lake resolve o protocolo da tabela para a versão mais baixa que suporta todos os recursos habilitados. Consulte Protocolo mais baixo possível.

nota

Databricks inclui suporte parcial sem quebras para recursos de tabela em todas as versões compatíveis do Databricks Runtime. Clientes OSS do Delta Lake escolhem como implementar o suporte para determinados recursos.

Alterações de Protocolo

O protocolo para uma tabela muda nas seguintes condições:

• Se um novo recurso for ativado, o protocolo será atualizado.
• Se um recurso de tabela for descartado, o protocolo será rebaixado.

Desativar um recurso de tabela não resulta em um downgrade de protocolo. Você deve remover o recurso para removê-lo completamente do protocolo. Nem todos os recursos da tabela podem ser removidos. Consulte Remover um recurso de tabela do Delta Lake e fazer downgrade do protocolo de tabela.

Todas as operações de mudança de protocolo entram em conflito com gravações concorrentes. As leituras de transmissão falham quando encontram um commit que altera os metadados da tabela. Para continuar, reinicie as transmissões afetadas. Para métodos recomendados, consulte Considerações de produção para transmissão estructurada.

nota

A Databricks recomenda que você nunca altere diretamente as propriedades de tabela minReaderVersion e minWriterVersion. Alterar essas propriedades não impede atualizações de protocolo, e configurá-las para um valor mais baixo não faz downgrade da tabela. Consulte Remover um recurso de tabela do Delta Lake e fazer downgrade do protocolo da tabela.

O que aciona uma atualização de protocolo

Ao habilitar um recurso, o protocolo da tabela é automaticamente atualizado.

As atualizações de protocolo são acionadas das seguintes maneiras:

• Ativar automaticamente com base na sintaxe usada nas instruções CREATE ou ALTER. Por exemplo, CLUSTER BY em uma instrução CREATE TABLE ativa automaticamente o liquid clustering, e GENERATED ALWAYS AS ativa as colunas geradas.
• Habilitar explicitamente por meio das propriedades da tabela. Por exemplo, definir 'delta.enableDeletionVectors' = true habilita vetores de exclusão.
• Habilitar um recurso pode habilitar automaticamente recursos necessários. Por exemplo, habilitar o UniForm habilita automaticamente o mapeamento de colunas, e habilitar clusters líquidos habilita automaticamente o checkpoint V2. Revise a documentação da Databricks para determinar quais recursos de tabela um determinado recurso requer.

Os recursos do leitor atualizam os protocolos de leitura e gravação. Por exemplo, o mapeamento de coluna é um recurso do leitor e exige a atualização de ambos os protocolos, pois os dados são armazenados de forma diferente no armazenamento.

Os recursos do gravador, como restrições CHECK, apenas atualizam o protocolo de gravação.

atenção

A maioria das atualizações de versão de protocolo é irreversível e pode quebrar leitores, gravadores ou ambos os clientes de tabela existentes do Delta Lake. Atualize tabelas específicas apenas quando necessário e verifique se todas as ferramentas de produção atuais e futuras oferecem suporte à nova versão do protocolo.

Rebaixamentos de protocolo estão disponíveis para alguns recursos. Consulte Remover um recurso de tabela do Delta Lake e fazer downgrade do protocolo da tabela.

Protocolo mais baixo possível

O Delta Lake resolve o protocolo da tabela para a versão mais baixa que oferece suporte a todos os recursos habilitados. Isso pode apenas reduzir minReaderVersion ou minWriterVersion, nunca aumentá-los. Os recursos da tabela nunca são removidos automaticamente. Use DROP FEATURE para remover um recurso de tabela do protocolo.

Se todos os recursos ativados forem totalmente compatíveis com uma versão de protocolo baseada em inteiros inferior, a tabela poderá reverter para essa versão e descartar readerFeatures ou writerFeatures do protocolo. Isso não desativa nenhum recurso. As versões de protocolo anteriores aumentam a compatibilidade porque todos os clientes devem respeitá-las.

Compatibilidade do Databricks e do Databricks Runtime

O Databricks introduz suporte para novos recursos do Delta Lake nas versões do Databricks Runtime:

• Tabelas gravadas por uma versão inferior do Databricks Runtime têm suporte total de leitura e gravação em versões superiores do Databricks Runtime.
• Tabelas gravadas por uma versão superior do Databricks Runtime podem usar recursos de tabela não suportados em versões anteriores do Databricks Runtime.
• Alguns recursos permitem gravações de versões anteriores do Databricks Runtime sem aplicar totalmente todas as otimizações para o recurso habilitado.

Se você usa tabelas Delta Lake apenas através do Databricks, precisa apenas rastrear o suporte a recursos usando os requisitos mínimos do Databricks Runtime. Se você lê ou grava tabelas de sistemas externos, deve verificar se esses clientes suportam os recursos de tabela ativados em suas tabelas.

Suporte a recursos de tabela com backport

No Databricks Runtime 12.2 LTS e acima, os recursos de tabela substituíram o protocolo baseado em inteiro por sinalizadores granulares que indicam quais recursos uma tabela usa.

A Databricks transferiu o suporte a recursos de tabela para o Databricks Runtime 11.3 LTS e abaixo, em vez de apenas dar suporte a versões de protocolo inteiras, mas apenas para recursos já suportados nessa versão.

Por exemplo, você pode ler e escrever em uma tabela com colunas geradas habilitadas usando recursos da tabela no Databricks Runtime 9.1 LTS. No entanto, você não pode usar o Databricks Runtime 9.1 LTS para ler e escrever em uma tabela com colunas de identidade habilitadas usando recursos de tabela porque as colunas de identidade exigem o Databricks Runtime 10.4 LTS e acima.

Ao usar recursos de tabela com suporte de backport, algumas operações disponíveis em uma determinada versão do Databricks Runtime podem não estar disponíveis na versão correspondente do Delta Lake OSS. Se sua arquitetura inclui clientes Delta Lake OSS, teste a compatibilidade antes de habilitar recursos de tabela em tabelas de produção.

Recursos do Delta Lake e versões do Databricks Runtime necessárias

A tabela a seguir lista a versão mais baixa do Databricks Runtime com suporte total para cada recurso, de modo que todas as funcionalidades geralmente disponíveis para leituras e escritas sejam suportadas.

Recurso	Requer versão do Databricks Runtime ou superior	Documentação
CHECK restrições	Todas as versões do Databricks Runtime compatíveis	CHECK Restrição
Alterar feed de dados	Todas as versões do Databricks Runtime compatíveis	Usar o feed de dados de alteração no Databricks
Colunas geradas	Todas as versões do Databricks Runtime compatíveis	Colunas geradas pelo Delta Lake
Mapeamento de coluna	Todas as versões do Databricks Runtime compatíveis	Renomeie e solte colunas com mapeamento de coluna Delta Lake
Colunas de identidade	Todas as versões do Databricks Runtime compatíveis	Colunas de identidade
Recursos da tabela	Todas as versões do Databricks Runtime compatíveis	Versões do Protocolo e Recursos da Tabela
Vetores de deleção	Todas as versões do Databricks Runtime compatíveis	Vetores de deleção no Databricks
TimestampNTZ	Databricks Runtime 13.3 LTS	TIMESTAMP_NTZ Tipo
UniForm	Databricks Runtime 13.3 LTS	Ler tabelas Delta Lake com clientes Iceberg usando UniForm
Clusters líquidos	Databricks Runtime 13.3 LTS	Usar cluster líquido para tabelas
Acompanhamento de linha	Databricks Runtime 14.3 LTS	Acompanhamento de linha em Databricks
Ampliação de tipo	Databricks Runtime 15.4 LTS	Ampliação de tipo
Variante	Databricks Runtime 15.4 LTS	Suporte a tipos de variante para Apache Iceberg e Delta Lake
Colações	Databricks Runtime 16.1	Suporte a collations para Delta Lake
Pontos de verificação protegidos	Databricks Runtime 16.3	Remover um recurso da tabela Delta Lake e fazer downgrade do protocolo da tabela
Commits do Catálogo	Databricks Runtime 16.4 LTS	Commits do Catálogo

Consulte Notas sobre a versão e compatibilidade do Databricks Runtime.

nota

Lakeflow Spark Declarative Pipelines e Databricks SQL atualizam automaticamente os ambientes de runtime com lançamentos regulares para dar suporte a novos recursos. Consulte notas sobre a versão do LakeFlow Spark Declarative Pipelines e o processo de atualização da versão e notas sobre a versão do Databricks SQL.

Recursos por versão de protocolo

nota

Para compatibilidade com o Databricks Runtime, consulte Compatibilidade do Databricks e do Databricks Runtime.

O Delta Lake usa valores de minReaderVersion e minWriterVersion separados para especificar os recursos do protocolo. O protocolo de código aberto do Delta Lake padronizou o uso de recursos de tabela, mas alguns clientes ainda usam o versionamento de protocolo legado. Como alguns clientes podem não oferecer suporte a todos os recursos, a Databricks recomenda que você verifique a documentação do cliente e teste a compatibilidade antes de habilitar novos recursos em tabelas de produção.

Apache Iceberg usa uma única format-version em vez de versões separadas de leitor e gravador. Uma versão do formato Iceberg indica quais recursos estão disponíveis, mas não exige o seu uso. Os recursos são opcionais, exceto para o acompanhamento de linha, que é obrigatório na versão 3 do formato. Quando um recurso mostra *N/A* na coluna Iceberg, é um recurso específico do Delta sem um equivalente direto do Iceberg.

A tabela a seguir lista os requisitos de versão de protocolo para recursos de tabela do Delta Lake e do Apache Iceberg. O tipo de recurso indica se um recurso deve ser respeitado apenas para gravações ou para leituras e gravações.

Recurso	Delta minWriterVersion	Delta minReaderVersion	Iceberg format-version	Tipo de recurso
Funcionalidade básica	2	1	1	Gravador
CHECK restrições	3	1	N/A	Gravador
Alterar feed de dados	4	1	N/A	Gravador
Colunas geradas	4	1	N/A	Gravador
Mapeamento de coluna	5	2	N/A	Leitor e escritor
Colunas de identidade	6	1	N/A	Gravador
Acompanhamento de linha	7	1	3	Gravador
Vetores de deleção	7	3	3	Leitor e escritor
TimestampNTZ	7	3	1	Leitor e escritor
Clusters líquidos	7	3	1	Leitor e gravador (1)
Leitores Iceberg (UniForm)	7	2	N/A	Gravador (2)
Ampliação de tipo	7	3	N/A	Leitor e escritor
Variante	7	3	3	Leitor e escritor
Desagregação de variantes	7	3	3	Leitor e escritor
Colações	7	3	N/A	Leitor e escritor
Pontos de verificação protegidos	7	1	N/A	Gravador
Commits do Catálogo	7	3	N/A	Leitor e escritor

(1) : clusters líquidos implementam o particionamento oculto.

(2) : requer que o mapeamento de coluna seja ativado.