Referência de propriedades da tabela

Delta Lake e Apache Iceberg usam propriedades da tabela para controlar o comportamento e os recursos da tabela. Essas propriedades podem apresentar significados específicos e afetar comportamentos quando definidas.

nota

Todas as operações que definem ou atualizam propriedades de tabela entram em conflito com outras operações de gravação concorrentes, fazendo com que falhem. Databricks recomenda modificar uma propriedade da tabela apenas quando não houver operações de gravação concorrentes na tabela.

Modificar propriedades da tabela

Para alterar as propriedades de tabelas existentes, use SET TBLPROPERTIES.

Formatos Delta e Iceberg

Delta Lake e tabelas Apache Iceberg compartilham os mesmos nomes de propriedade de tabela, mas requerem prefixos diferentes:

• Tabelas Delta Lake : Use o prefixo delta.
• Tabelas Iceberg : Utilize o prefixo iceberg.

Por exemplo, para ativar vetores de exclusão em uma tabela:

Delta Lake table

SQL

ALTER TABLE <table-name> SET TBLPROPERTIES ('delta.enableDeletionVectors' = true);

Iceberg table

SQL

ALTER TABLE <table-name> SET TBLPROPERTIES ('iceberg.enableDeletionVectors' = true);

Propriedades da tabela e propriedades do SparkSession

Cada tabela possui suas próprias propriedades da tabela que controlam o seu comportamento. Algumas configurações do SparkSession sempre substituem as propriedades da tabela. Por exemplo, autoCompact.enabled e optimizeWrite.enabled ativam a compactação automática e gravações otimizadas no nível do SparkSession. A Databricks recomenda o uso de configurações com escopo de tabela para a maioria das cargas de trabalho.

Você pode definir valores padrão para novas tabelas usando as configurações do SparkSession. Essas configurações default aplicam-se apenas a novas tabelas e não afetam as propriedades de tabelas existentes. As configurações do SparkSession usam um prefixo diferente das propriedades da tabela, conforme mostrado na tabela a seguir:

Propriedade da tabela	Configuração do SparkSession
delta.<conf> iceberg.<conf>	spark.databricks.delta.properties.defaults.<conf> spark.databricks.iceberg.properties.defaults.<conf>

Por exemplo, para definir a propriedade appendOnly = true para todas as novas tabelas criadas em uma sessão, defina o seguinte:

Delta Lake table

SQL

SET spark.databricks.delta.properties.defaults.appendOnly = true

Iceberg table

SQL

SET spark.databricks.iceberg.properties.defaults.appendOnly = true

Propriedades da tabela

A maioria das propriedades de tabela a seguir estão disponíveis para tabelas Delta Lake e Apache Iceberg, exceto onde indicado. Use o prefixo delta. para tabelas Delta Lake e o prefixo iceberg. para tabelas Iceberg.

Propriedade	Descrição
autoOptimize.optimizeWrite	true para otimizar automaticamente a disposição dos arquivos para esta tabela durante as gravações. Consulte Gravações otimizadas. Tipo de dados: Boolean Default: (nenhum)
dataSkippingNumIndexedCols	O número de colunas nas quais coletar estatísticas para a omissão de dados. Um valor de -1 significa coletar estatísticas para todas as colunas. Consulte Ignorando dados. Tipo de dados: Int default: 32
dataSkippingStatsColumns	Uma lista separada por vírgulas de nomes de colunas para coletar estatísticas e aprimorar a funcionalidade de salto de dados. Esta propriedade tem precedência sobre dataSkippingNumIndexedCols. Consulte Ignorando dados. Tipo de dados: String Default: (nenhum)
deletedFileRetentionDuration	A menor duração para manter arquivos de dados excluídos logicamente antes de excluí-los fisicamente. Isso evita falhas em leitores defasados após compactações ou substituições de partição. O Databricks recomenda o valor default de 7 dias ou superior. Se o seu período de retenção for muito curto, jobs de longa duração poderão ter seus arquivos não confirmados excluídos antes que o job seja concluído. Consulte Configurar a retenção de dados para consultas de viagem do tempo. Tipo de dados: CalendarInterval default: interval 1 week
enableDeletionVectors	true para ativar vetores de exclusão e I/O preditivo para atualizações. Consulte Vetores de exclusão no Databricks e Ativar vetores de exclusão. Tipo de dados: Boolean Default: Depende das configurações do administrador do workspace e da versão do Databricks Runtime. Consulte Ative automaticamente vetores de exclusão.
logRetentionDuration	Por quanto tempo o histórico de uma tabela é mantido. VACUUM operações substituem este limite de retenção. Databricks limpa automaticamente os registros de log mais antigos que o intervalo de retenção cada vez que um ponto de verificação é gravado. Definir esta propriedade com um valor elevado mantém muitas entradas de log. Isso não impacta o desempenho porque as operações no log são de tempo constante. Operações na história são paralelas, mas se tornam mais caras à medida que o tamanho do log aumenta. Consulte Configurar a retenção de dados para consultas de viagem do tempo. Tipo de dados: CalendarInterval default: interval 30 days
minReaderVersion (Somente Delta Lake)	A versão mínima do leitor de protocolo necessária para ler desta tabela. A Databricks não recomenda configurar manualmente essa propriedade. Consulte a compatibilidade de recursos e protocolos do Delta Lake. Tipo de dados: Int default: 1
minWriterVersion (Somente Delta Lake)	A versão mínima necessária do protocolo de gravação para gravar nesta tabela. A Databricks não recomenda configurar manualmente essa propriedade. Consulte a compatibilidade de recursos e protocolos do Delta Lake. Tipo de dados: Int default: 2
format-version (Apenas tabelas gerenciadas do Apache Iceberg)	A versão do formato de tabela Iceberg. A Databricks não recomenda configurar manualmente essa propriedade. Veja Usar recursos v3 do Apache Iceberg. Tipo de dados: Int default: 2
randomizeFilePrefixes	true para gerar um prefixo aleatório para um caminho de arquivo em vez de informação de partição. Tipo de dados: Boolean default: false
targetFileSize	O tamanho do arquivo de destino em bytes ou unidades superiores para ajuste de arquivo. Por exemplo, 104857600 (bytes) ou 100mb. Consulte Controlar o tamanho do arquivo de dados. Tipo de dados: String Default: (nenhum)
parquet.compression.codec	O codec de compressão de uma tabela. Valores válidos: ZSTD, SNAPPY, GZIP, LZ4 e BROTLI (o suporte varia de acordo com o formato) Esta propriedade garante que todas as futuras gravações na tabela usem o codec escolhido, substituindo o default do cluster ou da sessão (spark.sql.parquet.compression.codec). No entanto, as configurações pontuais do DataFrame .write.option("compression", "...") ainda têm precedência. Disponível no Databricks Runtime 16.0 e superior. Observe que os arquivos existentes não são reescritos automaticamente. Para recomprimir os dados existentes com o formato escolhido, use OPTIMIZE table_name FULL. Tipo de dados: String default: ZSTD
parquet.format.version (Somente Delta Lake)	A versão do formato Parquet usada ao escrever arquivos de dados. A especificação de 2.12.0 faz com que o Databricks Runtime utilize codificações Parquet mais avançadas e cabeçalhos de página de dados. Os valores válidos são 1.0.0 e 2.12.0, que correspondem a versões do formato Apache Parquet. Esta propriedade é apenas para tabelas do Delta Lake. Não defina esta propriedade para tabelas Iceberg, UniForm ou tabelas que são acessadas por mecanismos que não são do Databricks Runtime. Tipo de dados: String default: 1.0.0
appendOnly	true para tornar a tabela somente de anexo. Tabelas somente para anexação não permitem excluir registros existentes ou atualizar valores existentes. Tipo de dados: Boolean default: false
autoOptimize.autoCompact	Combina automaticamente arquivos pequenos nas partições da tabela para reduzir os problemas com arquivos pequenos. Aceita auto (recomendado), true, legacy, ou false. Consulte Compactação automática. Tipo de dados: String Default: (nenhum)
checkpoint.writeStatsAsJson	true para gravar estatísticas de arquivos em pontos de controle no formato JSON para a coluna stats. Tipo de dados: Boolean default: false
checkpoint.writeStatsAsStruct	true gravar estatísticas de arquivo em pontos de verificação no formato struct para a coluna stats_parsed e gravar valores de partição como um struct para partitionValues_parsed. Tipo de dados: Boolean default: true
checkpointPolicy	classic para pontos de verificação clássicos. v2 para pontos de verificação v2. Consulte Ponto de verificação v2 e Compatibilidade para tabelas com clustering líquido. Tipo de dados: String default: classic
columnMapping.mode	Habilita o mapeamento de coluna para colunas de tabela e as colunas Parquet correspondentes que utilizam nomes diferentes. Os valores válidos são none, name e id. Consulte Renomear e eliminar colunas com o mapeamento de colunas do Delta Lake. Observação: Ativar columnMapping.mode ativa automaticamente randomizeFilePrefixes. Tipo de dados: DeltaColumnMappingMode default: none
compatibility.symlinkFormatManifest.enabled (Somente Delta Lake)	true Para configurar a tabela Delta Lake para que todas as operações de gravação na tabela atualizem automaticamente os manifestos. Tipo de dados: Boolean default: false
enableChangeDataFeed	true Habilitar o feed de dados de alteração. Veja o uso do feed de dados de alteração. Tipo de dados: Boolean default: false
enableTypeWidening	true para habilitar a ampliação de tipo. Consulte Ampliação de tipo. Tipo de dados: Boolean default: false
isolationLevel	O grau em que uma transação deve ser isolada de modificações feitas por transações concorrentes. Valores válidos são Serializable e WriteSerializable. Consulte Níveis de isolamento (serializável por gravação e serializável). Tipo de dados: String default: WriteSerializable
randomPrefixLength	O número de caracteres a serem gerados para prefixos aleatórios quando randomizeFilePrefixes for true. Tipo de dados: Int default: 2
setTransactionRetentionDuration	A menor duração dentro da qual novos Snapshots retêm identificadores de transação (por exemplo, SetTransactions). Novos Snapshots expiram e ignoram identificadores de transação anteriores ou iguais à duração especificada por esta propriedade. O identificador SetTransaction é usado para tornar as gravações idempotentes. Consulte Usar foreachBatch para gravações de tabela idempotentes para obter detalhes. Tipo de dados: CalendarInterval Default: (nenhum)