Referencia de propiedades de tabla

Las tablas Delta Lake y Apache Iceberg usan propiedades de tabla para configurar el comportamiento y las características, incluido el diseño de datos, el tamaño de archivo, la omisión de datos, el nivel de aislamiento y la fuente de distribución de datos modificados.

Nota:

Todas las operaciones que establecen o actualizan las propiedades de la tabla entran en conflicto con otras operaciones de escritura simultáneas, lo que provoca un error. Databricks recomienda modificar una propiedad de una tabla solo cuando no haya ninguna operación de escritura simultánea en la tabla.

Modificar propiedades de la tabla

Para modificar las propiedades de tabla de las tablas existentes, use SET TBLPROPERTIES.

Prefijos de propiedades Delta y Iceberg

Las tablas delta Lake y Apache Iceberg comparten los mismos nombres de propiedad de tabla, pero requieren prefijos diferentes:

  • Tablas Delta Lake: Usa el delta. prefijo
  • Tablas de icebergs: Usa el iceberg. prefijo

Por ejemplo, para habilitar vectores de eliminación en una tabla:

Lago Delta

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

Iceberg

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

Propiedades y SparkSession propiedades de la tabla

Cada tabla tiene sus propias propiedades de tabla que controlan su comportamiento. Algunas SparkSession configuraciones siempre invalidan las propiedades de la tabla. Por ejemplo, autoCompact.enabled y optimizeWrite.enabled habilite la compactación automática y las escrituras optimizadas en el SparkSession nivel. Databricks recomienda usar configuraciones con ámbito de tabla para la mayoría de las cargas de trabajo.

Puede establecer valores predeterminados para las nuevas tablas mediante SparkSession configuraciones. Estos valores predeterminados solo se aplican a las nuevas tablas y no afectan a las propiedades de tabla existentes. SparkSession Las configuraciones usan un prefijo diferente al de las propiedades de la tabla, como se muestra en la siguiente tabla:

Propiedad de tabla SparkSession configuración
delta.<conf>
iceberg.<conf>
spark.databricks.delta.properties.defaults.<conf>
spark.databricks.iceberg.properties.defaults.<conf>

Por ejemplo, para establecer la appendOnly = true propiedad para todas las tablas nuevas creadas en una sesión, establezca lo siguiente:

Lago Delta

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

Iceberg

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

Propiedades de la tabla

La mayoría de las siguientes propiedades de tabla están disponibles para las tablas Delta Lake y Apache Iceberg, excepto donde se indica. Use el delta. prefijo para las tablas de Delta Lake y iceberg. el prefijo para las tablas de Iceberg.

Propiedad Description
appendOnly true para que la tabla sea solo para adicción. Las tablas de solo agregar no permiten eliminar registros existentes ni actualizar valores existentes.
Tipo de datos: Boolean
Opción predeterminada: false
autoOptimize.autoCompact Combina automáticamente archivos pequeños dentro de particiones de tabla para reducir problemas de archivos pequeños. Acepta auto (recomendado), true, legacy, o false.
Consulte Compactación automática.
Tipo de datos: String
Valor predeterminado: (ninguno)
autoOptimize.optimizeWrite true para optimizar automáticamente la disposición de los archivos de esta tabla durante las escrituras.
Consulte Escrituras optimizadas.
Tipo de datos: Boolean
Valor predeterminado: (ninguno)
checkpoint.writeStatsAsJson true para escribir estadísticas de archivo en puntos de control en formato JSON para la stats columna.
Tipo de datos: Boolean
Opción predeterminada: false
checkpoint.writeStatsAsStruct true para escribir estadísticas de archivo en puntos de control en formato struct para la stats_parsed columna y para escribir valores de partición como struct para partitionValues_parsed.
Tipo de datos: Boolean
Opción predeterminada: true
checkpointPolicy classic para los puntos de control clásicos. v2 Para los puntos de control V2.
Consulte Checkpoint V2 and Compatibility for tables with liquid clustering (Punto de comprobación V2 y compatibilidad para tablas con clústeres líquidos).
Tipo de datos: String
Opción predeterminada: classic
columnMapping.mode Permite la asignación de columnas para las columnas de tabla y las columnas Parquet correspondientes que usan nombres diferentes. Los valores válidos son none, namey id.
Consulte Renombrar y eliminar columnas con el mapeo de columnas de Delta Lake.
Nota: Habilitar columnMapping.mode automáticamente habilita randomizeFilePrefixes.
Tipo de datos: DeltaColumnMappingMode
Opción predeterminada: none
compatibility.symlinkFormatManifest.enabled (Solo Delta Lake) true para configurar la tabla Delta Lake de modo que todas las operaciones de escritura en la tabla actualicen automáticamente los manifiestos.
Tipo de datos: Boolean
Opción predeterminada: false
dataSkippingNumIndexedCols Número de columnas sobre las que se van a recopilar estadísticas sobre la omisión de datos. Un valor de -1 significa que se han recopilado estadísticas de todas las columnas.
Consulte Omisión de datos.
Tipo de datos: Int
Opción predeterminada: 32
dataSkippingStatsColumns Lista separada por comas de nombres de columna en los que se van a recopilar estadísticas para mejorar la funcionalidad de omisión de datos no relevantes. Este propiedad tiene prioridad sobre dataSkippingNumIndexedCols.
Consulte Omisión de datos.
Tipo de datos: String
Valor predeterminado: (ninguno)
deletedFileRetentionDuration La duración más corta para mantener los archivos de datos eliminados lógicamente antes de eliminarlos físicamente. Esto evita fallos en lectores obsoletos después de compactaciones o sobrescrituras de particiones.
Databricks recomienda el valor predeterminado de 7 días o superior. Si el período de retención es demasiado corto, es posible que los trabajos de ejecución prolongada tengan eliminados sus archivos no confirmados antes de que se complete el trabajo.
Vea Configuración de la retención de datos para las consultas de historial temporal.
Tipo de datos: CalendarInterval
Opción predeterminada: interval 1 week
enableChangeDataFeed true para habilitar el flujo de datos de cambios.
Consulte Uso de la fuente de distribución de datos modificados.
Tipo de datos: Boolean
Opción predeterminada: false
enableColumnUpdates-preview (Solo Delta Lake) Configura para true habilitar Actualizaciones Eficientes de Columnas (Beta). Las lecturas y escrituras requieren Databricks Runtime 19 o superior. La tabla también debe utilizar confirmaciones de catálogo, seguimiento de filas, vectores de eliminación y mapeo de columnas en id modo.
Consulta Actualizaciones eficientes de columnas en Delta Lake.
Tipo de datos: Boolean
Opción predeterminada: false
enableDeletionVectors true para habilitar vectores de eliminación y E/S predictiva para actualizaciones.
Consulte Vectores de eliminación en Databricks y Habilitación de vectores de eliminación.
Tipo de datos: Boolean
Valor predeterminado: depende de la configuración del administrador del área de trabajo y de la versión de Databricks Runtime. Vea Habilitación automática de vectores de eliminación.
enableIcebergCompatV2 (Solo Delta Lake) true para habilitar IcebergCompatV2, que escribe datos en un formato compatible con lectores Iceberg. Para habilitar lecturas de iceberg, se establece esta propiedad junto con universalFormat.enabledFormats.
Consulte Leer tablas de Delta Lake con clientes de Iceberg.
Tipo de datos: Boolean
Valor predeterminado: (ninguno)
enableRowTracking (Solo Delta Lake) true para habilitar el seguimiento de filas, que asigna IDs estables de fila y versiones de confirmación de fila a cada fila para el linaje a nivel de fila. Disponible en Databricks Runtime 14.0 y superiores. Las tablas Apache Iceberg v3 incluyen seguimiento automático de filas.
Consulte Seguimiento de filas en Azure Databricks.
Tipo de datos: Boolean
Opción predeterminada: false
enableTypeWidening true para habilitar el ensanchamiento de texto.
Consulte Ampliación de tipos.
Tipo de datos: Boolean
Opción predeterminada: false
format-version (Solo tablas gestionadas por Apache Iceberg) La versión de formato de tabla de Iceberg.
Databricks recomienda no configurar manualmente esta propiedad.
Consulte Uso de las características de Apache Iceberg v3.
Tipo de datos: Int
Opción predeterminada: 2
isolationLevel Es el nivel en el que debe aislarse una transacción de las modificaciones que realicen las transacciones simultáneas.
Los valores válidos son Serializable y WriteSerializable.
Consulte Niveles de aislamiento (WriteSerializable y Serializable).
Tipo de datos: String
Opción predeterminada: WriteSerializable
logRetentionDuration Cuánto tiempo se almacena el historial de una tabla.
Databricks limpia automáticamente las entradas de registro de más antigüedad que el intervalo de retención cada vez que se realiza un punto de control. Al establecer esta propiedad en un valor grande, se conservan muchas entradas de registro. Esto no afecta al rendimiento porque las operaciones en el log (bitácora) son de tiempo constante. Las operaciones en el historial son paralelas, pero se vuelven más costosas a medida que aumenta el tamaño del registro.
Vea Configuración de la retención de datos para las consultas de historial temporal.
Tipo de datos: CalendarInterval
Opción predeterminada: interval 30 days
minReaderVersion (Solo Delta Lake) La versión mínima requerida del lector de protocolos para leer esta tabla.
Databricks recomienda no configurar manualmente esta propiedad.
Consulte Compatibilidad y protocolos de características de Delta Lake.
Tipo de datos: Int
Opción predeterminada: 1
minWriterVersion (Solo Delta Lake) Versión mínima necesaria del escritor de protocolos para escribir en esta tabla.
Databricks recomienda no configurar manualmente esta propiedad.
Consulte Compatibilidad y protocolos de características de Delta Lake.
Tipo de datos: Int
Opción predeterminada: 2
parquet.compression.codec Códec de compresión de una tabla.
Valores válidos: ZSTD, SNAPPY, GZIP, LZ4, BROTLI (la compatibilidad varía según el formato)
Disponible en Databricks Runtime 16.0 y superiores, al establecer esta propiedad se aplica el códec elegido a todas las futuras escrituras de la tabla, sobrscribiendo el predeterminado por defecto del clúster o de la sesión (spark.sql.parquet.compression.codec). Puedes sobrescribir esta propiedad de tabla con un DataFrame .write.option("compression", "..."). Configurar la propiedad no reescribe archivos existentes. Para recomprimir datos existentes con el códec elegido, utiliza OPTIMIZE table_name FULL. Para las tablas Delta Lake gestionadas por Unity Catalog, Databricks escribe parquet.compression.codec explícitamente (ZSTD) al crear la tabla, por lo que el Delta por defecto spark.databricks.delta.properties.defaults.parquet.compression.codec separado no tiene efecto. Para nuevas tablas externas de Delta Lake, usa spark.databricks.delta.properties.defaults.parquet.compression.codec.
Tipo de datos: String
Opción predeterminada: ZSTD
parquet.format.version La versión de formato Parquet que se usa al escribir archivos de datos. 2.12.0 Esta opción permite codificaciones avanzadas, encabezados de página de datos v2 y INT64 marcas de tiempo, lo que puede mejorar el rendimiento de las consultas y reducir la superficie de almacenamiento.
Los valores válidos son 1.0.0 y 2.12.0, que corresponden a versiones del formato Apache Parquet.
Esta propiedad se puede establecer en tablas delta Lake y Apache Incremental. Es posible que algunos lectoresdes de (OSS) no admitan codificaciones Parquet v2. Consulte Limitaciones.
Consulte Parquet v2.
Tipo de datos: String
Opción predeterminada: 1.0.0
randomizeFilePrefixes true para generar un prefijo aleatorio para una ruta de archivo en lugar de información de partición.
Tipo de datos: Boolean
Opción predeterminada: false
randomPrefixLength Número de caracteres que se van a generar para prefijos aleatorios cuando randomizeFilePrefixes es true.
Tipo de datos: Int
Opción predeterminada: 2
setTransactionRetentionDuration La duración mínima en la que las nuevas instantáneas conservan los identificadores de transacción (por ejemplo, SetTransactions). Las instantáneas nuevas expiran y omiten los identificadores de transacción que son anteriores o iguales a la duración especificada por esta propiedad. Este SetTransaction identificador se usa al realizar escrituras idempotentes. Consulte Uso foreachBatch de escrituras de tabla idempotentes para obtener más información.
Tipo de datos: CalendarInterval
Valor predeterminado: (ninguno)
targetFileSize El tamaño de archivo objetivo en bytes o en unidades mayores para el ajuste de archivos. Por ejemplo, 104857600 (bytes) o 100mb.
Consulte Control del tamaño del archivo de datos.
Tipo de datos: String
Valor predeterminado: (ninguno)
tuneFileSizesForRewrites (Solo Delta Lake) true Para ajustar el tamaño de los archivos de modo que las operaciones que reescriben archivos, como MERGE, se ejecuten más rápido. Esto es útil para tablas que reescriben archivos con frecuencia. false para desactivar esta sintonización.
Cuando se desactiva, Databricks detecta automáticamente si la tabla requiere mucha reescritura y ajusta el tamaño de los archivos para operaciones de reescritura como MERGE y OPTIMIZE en consecuencia.
Consulte Control del tamaño del archivo de datos.
Tipo de datos: Boolean
Valor predeterminado: (ninguno)
universalFormat.enabledFormats (Solo Delta Lake) Una lista separada por comas de formatos para generar metadatos, de modo que los clientes externos puedan leer la tabla Delta Lake (UniForm). Configura para iceberg generar metadatos de Iceberg. La configuración iceberg requiere o enableIcebergCompatV2 = true bien enableIcebergCompatV3 = true. No puedes activar ambos. Consulte Uso de las características de Apache Iceberg v3.
Consulte Leer tablas de Delta Lake con clientes de Iceberg.
Tipo de datos: String
Valor predeterminado: (ninguno)