Compartir a través de

Ampliación de tipos

Importante

Esta característica está en versión preliminar pública en Databricks Runtime 15.4 LTS y versiones posteriores.

Las tablas con la ampliación de tipos habilitada permiten cambiar los tipos de datos de columna a un tipo más amplio sin volver a escribir archivos de datos subyacentes. Puede cambiar manualmente los tipos de columna o usar la evolución del esquema para evolucionar los tipos de columna.

Importante

La ampliación de tipos está disponible en Databricks Runtime 15.4 LTS y versiones posteriores. Las tablas con ampliación de tipos habilitadas solo se pueden leer en Databricks Runtime 15.4 LTS y versiones posteriores.

La ampliación de tipos requiere Delta Lake. Todas las tablas administradas por Unity Catalog usan Delta Lake de forma predeterminada.

Cambios de tipo admitidos

Puede ampliar los tipos según las siguientes reglas:

Tipo de origen Tipos más amplios admitidos
byte short, int, long, , decimal, double
short int, long, , decimal, double
int long, , decimal, double
long decimal
float double
decimal decimal con mayor precisión y escala
date timestampNTZ

Para evitar la promoción accidental de valores enteros a decimales, debe confirmar manualmente los cambios de tipo de byte, short, int o long a decimal o double. Al promover un tipo entero a decimal o double, si alguna ingesta descendente devuelve este valor a una columna de enteros, Spark truncará la parte fraccionaria de los valores por defecto.

Nota:

Al cambiar cualquier tipo numérico a decimal, la precisión total debe ser igual o mayor que la precisión inicial. Si también aumenta la escala, la precisión total debe aumentar en una cantidad correspondiente.

El destino mínimo para los tipos de byte, short y int es decimal(10,0). El objetivo mínimo para long es decimal(20,0).

Si desea agregar dos posiciones decimales a un campo con decimal(10,1), el destino mínimo es decimal(12,3).

Los cambios de tipo se admiten para columnas y campos de nivel superior anidados dentro de estructuras, mapas y matrices.

Habilitación de la ampliación de tipos

Puede habilitar la ampliación de tipos en una tabla existente estableciendo la propiedad de tabla delta.enableTypeWidening en true:

  ALTER TABLE <table_name> SET TBLPROPERTIES ('delta.enableTypeWidening' = 'true')

También puede habilitar el ampliación de tipos durante la creación de la tabla:

  CREATE TABLE T(c1 INT) TBLPROPERTIES('delta.enableTypeWidening' = 'true')

Importante

Al habilitar la ampliación de tipos, se establece la característica de tabla typeWidening, que actualiza los protocolos de lector y escritor. Debe usar Databricks Runtime 15.4 o superior para que interactúe con tablas con la ampliación de tipos habilitada. Si los clientes externos también interactúan con la tabla, compruebe que admiten esta característica de tabla. Consulte Compatibilidad y protocolos de características de Delta Lake.

Aplicación manual de un cambio de tipo

Use el comando ALTER COLUMN para cambiar manualmente los tipos:

ALTER TABLE <table_name> ALTER COLUMN <col_name> TYPE <new_type>

Esta operación actualiza el esquema de tabla sin volver a escribir los archivos de datos subyacentes.

Tipos anchos con evolución automática del esquema

La evolución del esquema funciona con la ampliación de tipos para actualizar los tipos de datos de las tablas de destino para que coincidan con el tipo de datos entrantes.

Nota:

Sin la ampliación del tipo habilitada, la evolución del esquema siempre intenta reducir el tipo de datos para que coincidan con los tipos de columna en la tabla objetivo. Si no desea ampliar automáticamente los tipos de datos en las tablas de destino, deshabilite el ancho de tipos antes de ejecutar cargas de trabajo con la evolución del esquema habilitada.

Para usar la evolución del esquema para ampliar el tipo de datos de una columna durante la ingestión, debe cumplir con las siguientes condiciones:

  • El comando write se ejecuta con la evolución automática del esquema habilitada.
  • La tabla de destino tiene habilitada la ampliación de tipos.
  • El tipo de columna de origen es más amplio que el tipo de columna de destino.
  • La ampliación de tipos admite el cambio de tipo.
  • El cambio de tipo no es uno de byte, short, into long a decimal o double. Estos cambios de tipo solo se pueden aplicar manualmente usando ALTER TABLE para evitar la promoción accidental de enteros a decimales.

Los desajustes de tipo que no cumplen todas estas condiciones siguen las reglas normales de aplicación de esquemas. Consulte Aplicación de esquemas.

Deshabilitar la función de tabla de ampliación de tipos

Puede evitar la ampliación accidental de tipos en tablas habilitadas estableciendo la propiedad en false:

  ALTER TABLE <table_name> SET TBLPROPERTIES ('delta.enableTypeWidening' = 'false')

Esta configuración evita cambios futuros de tipo en la tabla, pero no quita la función de ampliación de tipos en la tabla ni deshace los tipos que se han cambiado.

Si necesita quitar completamente las características de la tabla de ampliación de tipos, puede usar el comando DROP FEATURE como se muestra en el siguiente ejemplo:

 ALTER TABLE <table-name> DROP FEATURE 'typeWidening' [TRUNCATE HISTORY]

Nota:

Las tablas que habilitan la ampliación de tipos mediante Databricks Runtime 15.4 LTS requieren quitar la característica typeWidening-preview en su lugar.

Cuando se elimina la ampliación del tipo, se reescriben todos los archivos de datos que no se ajustan al esquema de tabla actual. Consulte Eliminar una característica de tabla de Delta Lake y degradar el protocolo de tabla.

Streaming desde una tabla Delta

Nota:

La compatibilidad con la ampliación de tipos en Structured Streaming está disponible en Databricks Runtime 16.3 y versiones posteriores.

Cuando se realiza streaming desde una tabla Delta, los cambios de tipo se tratan como cambios de esquema no aditivos, similares a renombrar o eliminar una columna con Asignación de Columnas.

Puede proporcionar una ubicación para el seguimiento del esquema que permita el streaming desde tablas de Delta Lake a las que se haya aplicado un cambio de tipo.

Cada lectura de streaming en un origen de datos debe tener su propia schemaTrackingLocation especificada. El schemaTrackingLocation especificado debe estar contenido en el directorio especificado para la checkpointLocation de la tabla de destino para la escritura en streaming.

Nota:

Para cargas de trabajo de streaming que combinan datos de varias tablas Delta de origen, debe especificar directorios únicos en el checkpointLocation para cada tabla de origen.

La opción schemaTrackingLocation se usa para especificar la ruta de acceso para el seguimiento de esquemas, como se muestra en el ejemplo de código siguiente:

Pitón

checkpoint_path = "/path/to/checkpointLocation"

(spark.readStream
  .option("schemaTrackingLocation", checkpoint_path)
  .table("delta_source_table")
  .writeStream
  .option("checkpointLocation", checkpoint_path)
  .toTable("output_table")
)

Scala

val checkpointPath = "/path/to/checkpointLocation"

spark.readStream
  .option("schemaTrackingLocation", checkpointPath)
  .table("delta_source_table")
  .writeStream
  .option("checkpointLocation", checkpointPath)
  .toTable("output_table")

Después de proporcionar una ubicación de seguimiento de esquemas, la secuencia actualizará su esquema de seguimiento cada vez que se detecte un cambio de tipo y entonces se detendrá. En ese momento, puede realizar cualquier acción necesaria para gestionar el cambio de tipo, como habilitar la ampliación de tipos en la tabla de destino o actualizar la consulta de streaming.

Para reanudar el procesamiento, establezca la configuración spark.databricks.delta.streaming.allowSourceColumnTypeChange de Spark o la opción allowSourceColumnTypeChange de lector de DataFrame:

Pitón

checkpoint_path = "/path/to/checkpointLocation"

(spark.readStream
  .option("schemaTrackingLocation", checkpoint_path)
  .option("allowSourceColumnTypeChange", "<delta_source_table_version>")
  # alternatively to allow all future type changes for this stream:
  # .option("allowSourceColumnTypeChange", "always")
  .table("delta_source_table")
  .writeStream
  .option("checkpointLocation", checkpoint_path)
  .toTable("output_table")
)

Scala

val checkpointPath = "/path/to/checkpointLocation"

spark.readStream
  .option("schemaTrackingLocation", checkpointPath)
  .option("allowSourceColumnTypeChange", "<delta_source_table_version>")
  // alternatively to allow all future type changes for this stream:
  // .option("allowSourceColumnTypeChange", "always")
  .table("delta_source_table")
  .writeStream
  .option("checkpointLocation", checkpointPath)
  .toTable("output_table")

SQL

  -- To unblock for this particular stream just for this series of schema change(s):
  SET spark.databricks.delta.streaming.allowSourceColumnTypeChange.ckpt_<checkpoint_id> = "<delta_source_table_version>"
  -- To unblock for this particular stream:
  SET spark.databricks.delta.streaming.allowSourceColumnTypeChange = "<delta_source_table_version>"
  -- To unblock for all streams:
  SET spark.databricks.delta.streaming.allowSourceColumnTypeChange = "always"

El identificador de punto de control <checkpoint_id> y la versión de la tabla de origen de Delta Lake <delta_source_table_version> se muestran en el mensaje de error cuando la secuencia se detiene.

Uso compartido delta

Nota:

La compatibilidad con la ampliación de tipos en Delta Sharing está disponible en Databricks Runtime 16.1 y en versiones posteriores.

El uso compartido de una tabla de Delta Lake con la ampliación de tipo habilitada se admite en el uso compartido de Delta de Databricks a Databricks. El proveedor y el destinatario deben estar en Databricks Runtime 16.1 o superior.

Para leer el flujo de datos de cambios de una tabla de Delta Lake con la ampliación de tipos habilitada utilizando Delta Sharing, debe establecer el formato de respuesta en delta:

spark.read
  .format("deltaSharing")
  .option("responseFormat", "delta")
  .option("readChangeFeed", "true")
  .option("startingVersion", "<start version>")
  .option("endingVersion", "<end version>")
  .load("<table>")

No se admite la lectura del flujo de cambios de datos a través de cambios de tipo. En su lugar, debe dividir la operación en dos lecturas independientes, una que termina en la versión de la tabla que contiene el cambio de tipo y la otra a partir de la versión que contiene el cambio de tipo.

Limitaciones

Compatibilidad de Apache Iceberg

Apache Iceberg no admite todos los cambios de tipo cubiertos por la ampliación de tipos, consulte Evolución del esquema de Iceberg. En concreto, Azure Databricks no admite los siguientes cambios de tipo:

  • byte, short, int, long a decimal o double
  • aumento de la escala decimal
  • date a timestampNTZ

Cuando la compatibilidad de UniForm con Iceberg está habilitada en una tabla de Delta Lake, la aplicación de uno de estos cambios de tipo produce un error.

Si aplica uno de estos cambios de tipo no admitidos en una tabla de Delta Lake, la habilitación de la compatibilidad Uniform con Iceberg en la tabla produce un error. Para resolver el error, debe quitar la característica de tabla de ampliación de tipos.

Otras limitaciones

  • No se admite proporcionar una ubicación de seguimiento de esquema mediante SQL al hacer streaming desde una tabla de Delta Lake cuando hay un cambio de tipo.
  • No se admite compartir una tabla usando Delta Sharing con la ampliación de tipo habilitada para consumidores que no son de Databricks.
  • Last updated on