Referência das propriedades da tabela

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

nota

Todas as operações que definem ou atualizam as propriedades da tabela entram em conflito com outras operações de gravação concorrente, causando falhas. Databricks recomenda que o senhor modifique uma propriedade da tabela somente quando não houver operações de gravação concorrente na tabela.

Modificar propriedades da tabela

Para modificar as propriedades das tabelas existentes, use SET TBLPROPERTIES.

Formatos Delta e Iceberg

As tabelas do Delta Lake e do Apache Iceberg compartilham os mesmos nomes de propriedades, mas exigem prefixos diferentes:

• Tabelas Delta : Use o prefixo delta.
• TabelasIceberg : Use o prefixo iceberg.

Por exemplo:

• Para habilitar vetores de exclusão em uma tabela Delta: delta.enableDeletionVectors
• Para habilitar vetores de exclusão em uma tabela Iceberg: iceberg.enableDeletionVectors

Propriedades da tabela e propriedades da SparkSession

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

Você pode definir valores default para novas tabelas usando as configurações SparkSession . Essas configurações padrão se aplicam 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:

SQL

-- For Delta tables
SET spark.databricks.delta.properties.defaults.appendOnly = true

-- For Iceberg tables
SET spark.databricks.iceberg.properties.defaults.appendOnly = true

Propriedades da tabela

As seguintes propriedades de tabela estão disponíveis para as tabelas Delta Lake e Apache Iceberg. Use o prefixo delta. para tabelas Delta e o prefixo iceberg. para tabelas Iceberg.

Propriedade	Descrição
autoOptimize.optimizeWrite	true para otimizar automaticamente a disponibilidade dos arquivos para esta tabela durante as gravações. Veja Escritas otimizadas. Tipo de dados: Boolean padrão: (nenhum)
dataSkippingNumIndexedCols	Número de colunas para coletar estatísticas sobre a omissão de dados. O valor -1 significa coletar estatísticas para todas as colunas. Consulte Ignorando dados. Tipo de dados: Int padrão: 32
dataSkippingStatsColumns	Uma lista de nomes de colunas separados por vírgulas para coletar estatísticas e aprimorar a funcionalidade de omissão de dados. Esta propriedade tem precedência sobre dataSkippingNumIndexedCols. Consulte Ignorando dados. Tipo de dados: String padrão: (nenhum)
deletedFileRetentionDuration	O menor tempo necessário para manter arquivos de dados logicamente excluídos antes de excluí-los fisicamente. Isso evita falhas em leitores obsoletos após compactações ou sobrescritas de partições. Defina esse valor como suficientemente grande para garantir que: O valor excede a duração máxima possível de um Job quando você executa VACUUM com leitores ou escritores concorrentes acessando a tabela. As consultas de transmissão que leem da tabela não param por mais tempo do que este valor. Caso contrário, a consulta não poderá ser reiniciada, pois precisa ler arquivos antigos. Consulte Configurar a retenção de dados para consultas de viagem do tempo. Tipo de dados: CalendarInterval padrão: interval 1 week
enableDeletionVectors	true para ativar vetores de exclusão e E/S preditiva para atualizações. Consulte Vetores de exclusão no Databricks e Ativar vetores de exclusão. Tipo de dados: Boolean Padrão: Depende das configurações de administração workspace e da versão Databricks Runtime . Consulte Ativar vetores de exclusão automaticamente.
logRetentionDuration	Por quanto tempo devo manter a história em uma mesa? As operações VACUUM substituem esse limite de retenção. O Databricks limpa automaticamente as entradas de log mais antigas que o intervalo de retenção sempre que um ponto de verificação é gravado. Definir essa propriedade com um valor alto retém muitas entradas de log. Isso não afeta o desempenho porque as operações no log têm tempo constante. As operações em logs são paralelas, mas tornam-se mais caras à medida que o tamanho log aumenta. Consulte Configurar a retenção de dados para consultas de viagem do tempo. Tipo de dados: CalendarInterval padrão: interval 30 days
minReaderVersion (Apenas Delta Lake )	A versão mínima necessária do leitor de protocolo para ler esta tabela. A Databricks não recomenda a configuração manual dessa propriedade. Consulte Delta Lake recurso compatibilidade e protocolos. Tipo de dados: Int padrão: 1
minWriterVersion (Apenas Delta Lake )	A versão mínima necessária do gravador de protocolo para escrever nesta tabela. A Databricks não recomenda a configuração manual dessa propriedade. Consulte Delta Lake recurso compatibilidade e protocolos. Tipo de dados: Int padrão: 2
format-version (Apache Iceberg ) somente tabelas	Versão em formato de tabela Iceberg. A Databricks não recomenda a configuração manual dessa propriedade. Consulte Usar recurso Apache Iceberg v3. Tipo de dados: Int padrão: 2
randomizeFilePrefixes	true Gerar um prefixo aleatório para um caminho de arquivo em vez de informações de partição. Tipo de dados: Boolean padrão: false
targetFileSize	O tamanho de destino do arquivo em bytes ou unidades superiores para ajuste de arquivos. Por exemplo, 104857600 (bytes) ou 100mb. Consulte Tamanho do arquivo de dados de controle. Tipo de dados: String padrão: (nenhum)
parquet.compression.codec	O codec de compressão para uma tabela. Valores válidos: ZSTD, SNAPPY, GZIP, LZ4, BROTLI (o suporte varia conforme o formato) Esta propriedade garante que todas as gravações futuras 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 únicas do DataFrame .write.option("compression", "...") ainda têm precedência. Disponível no Databricks Runtime 16.0 e versões posteriores. Note que os arquivos existentes não são sobrescritos automaticamente. Para recomprimir dados existentes com o formato escolhido, use OPTIMIZE table_name FULL. Tipo de dados: String padrão: ZSTD
appendOnly	true Para tornar a tabela somente para acréscimo. Tabelas somente para anexação não permitem excluir registros existentes nem atualizar valores existentes. Tipo de dados: Boolean padrão: false
autoOptimize.autoCompact	Combina automaticamente arquivos pequenos dentro de partições de tabela para reduzir problemas com arquivos pequenos. Aceita auto (recomendado), true, legacy ou false. Veja Compactação automática. Tipo de dados: String padrão: (nenhum)
checkpoint.writeStatsAsJson	true para escrever estatísticas de arquivo em pontos de verificação no formato JSON para a coluna stats . Tipo de dados: Boolean padrão: false
checkpoint.writeStatsAsStruct	true para escrever estatísticas de arquivo em pontos de verificação no formato struct para a coluna stats_parsed e para escrever valores de partição como uma struct para partitionValues_parsed. Tipo de dados: Boolean padrão: true
checkpointPolicy	classic para pontos de controle clássicos. v2 para pontos de verificação v2. Consulte Compatibilidade para tabelas com clustering líquido. Tipo de dados: String padrão: classic
columnMapping.mode	Permite o mapeamento de colunas para colunas de tabela e as colunas Parquet correspondentes que usam nomes diferentes. Consulte Renomear e soltar colunas com o mapeamento de colunas do Delta Lake. Nota: Habilitar columnMapping.mode habilita automaticamente randomizeFilePrefixes. Tipo de dados: DeltaColumnMappingMode padrão: none
compatibility.symlinkFormatManifest.enabled (Apenas Delta Lake )	true Configurar a tabela Delta para que todas as operações de gravação na tabela atualizem automaticamente os manifestos. Tipo de dados: Boolean padrão: false
enableChangeDataFeed	true para ativar o feed de dados de alteração. Consulte Habilitar o feed de dados de alteração. Tipo de dados: Boolean padrão: false
enableTypeWidening	true para permitir a ampliação do tipo. Consulte Ampliação de tipos. Tipo de dados: Boolean padrão: false
isolationLevel	O grau em que uma transação deve ser isolada das modificações feitas por transações concorrentes. Os valores válidos são Serializable e WriteSerializable. Consulte Níveis de isolamento e conflitos de gravação em Databricks. Tipo de dados: String padrão: WriteSerializable
randomPrefixLength	O número de caracteres a serem gerados para prefixos aleatórios quando randomizeFilePrefixes é true. Tipo de dados: Int padrão: 2
setTransactionRetentionDuration	A duração mais curta dentro da qual um novo Snapshot retém identificadores de transação (por exemplo, SetTransactions). Os novos snapshots expiram e ignoram identificadores de transação mais antigos ou iguais à duração especificada por esta propriedade. O identificador SetTransaction é usado quando as escritas são idempotentes. Veja as escritas da tabela idempotente em foreachBatch para detalhes. Tipo de dados: CalendarInterval padrão: (nenhum)
tuneFileSizesForRewrites	true usar sempre tamanhos de arquivo menores para todos os dados, além de operações de otimização na tabela. false Impede o ajuste para tamanhos de arquivo menores e desativa a detecção automática. Consulte Tamanho do arquivo de dados de controle. Tipo de dados: Boolean padrão: (nenhum)