Utilizar inferencia parcial de esquema en las canalizaciones de Lakeflow de Python

La inferencia parcial del esquema te permite definir columnas seleccionadas en una canalización de Python Lakeflow e inferir las columnas restantes a partir de la salida de la consulta. Utilice el override_schema argumento para especificar tipos, restricciones soportadas o comentarios para una o más columnas sin declarar todas las columnas de salida.

Importante

La inferencia parcial del esquema está en Beta. En espacios de trabajo donde esta Beta esté disponible, utilice override_schema en una canalización de espacio de trabajo de Python para optar por una tabla.

Elige una opción de esquema

Las siguientes opciones controlan el esquema de salida de una vista materializada, una tabla de streaming o una tabla gestionada:

Option Behavior
Omitir ambos argumentos Inferir el esquema de salida a partir de la consulta.
schema Declare el esquema de salida completo.
override_schema Declara las definiciones de columnas seleccionadas e infiere las columnas de salida de consulta restantes.

Ambos schema y override_schema aceptan una cadena SQL DDL o un PySpark StructType. Especifique solo uno de estos argumentos. Una cadena DDL en override_schema define columnas dentro de la API de Python. No habilita declaraciones parciales de esquema en sentencias SQL.

Úsalo override_schema con table, materialized_view o create_streaming_table. Para tablas gestionadas, utilice create_table donde esa API esté disponible. Las funciones correspondientes en el dlt módulo también aceptan este argumento. Para el nuevo código, use pyspark.pipelines.

Definir columnas seleccionadas

  1. Añade override_schema a la definición del decorador o de la tabla de destino.
  2. Declara las columnas cuyas definiciones quieres controlar. Los tipos de consulta deben ser compatibles con los tipos declarados. Convierte valores incompatibles en la consulta antes de escribirlos.
  3. Devuelve las otras columnas que quieras incluir desde la consulta. La inferencia parcial del esquema incluye columnas de salida de consulta, no columnas de origen que la consulta no selecciona.

La siguiente pipeline crea una vista materializada con una restricción explícita NOT NULL en id. Infiere las definiciones de name y score a partir de la consulta:

from pyspark import pipelines as dp

@dp.materialized_view(override_schema="id BIGINT NOT NULL")
def customers():
    return spark.range(3).selectExpr(
        "id",
        "concat('customer-', CAST(id AS STRING)) AS name",
        "id * 10 AS score",
    )

La salida contiene id BIGINT NOT NULL, name STRING, y score BIGINT. Añadir otra columna seleccionada a la consulta incluye esa columna sin añadirla a override_schema.

Para usar un StructType, declare solo los campos seleccionados. La siguiente tabla de flujo lee una tabla fuente de Delta Lake accesible, solo de inserción, cuyas columnas son id BIGINT, event_time TIMESTAMP y payload STRING. La fuente debe contener valores no nulos id :

from pyspark import pipelines as dp
from pyspark.sql.types import LongType, StructField, StructType

@dp.table(
    override_schema=StructType([StructField("id", LongType(), nullable=False)])
)
def events():
    return spark.readStream.table("catalog.schema.raw_events").select(
        "id", "event_time", "payload"
    )

Para un destino definido por separado, pasa override_schema a dp.create_streaming_table() o dp.create_table() y utiliza un flujo de añade para escribir en él. Cada columna no generada declarada en override_schema debe aparecer en la salida combinada de la consulta de los flujos que alimentan el destino. Puede estar ausente en un flujo append individual.

Definiciones y restricciones de columnas

Puedes incluir comentarios de columna y restricciones de tabla compatibles en una override_schema cadena DDL. Se aplican los requisitos existentes para estas características; las claves primaria y foránea siguen siendo informativas.

Declara una columna compleja completa, como una estructura, array o mapa. No puedes declarar solo algunos campos de una estructura anidada e inferir sus campos restantes.

Cambios de esquema entre actualizaciones

Cuando cambias la consulta o declaración parcial, las siguientes reglas se aplican a las actualizaciones sin una actualización completa:

  • Para una vista materializada recalculada, las columnas inferidas que faltan en la nueva salida de la consulta se eliminan del esquema de salida.
  • Para una tabla en streaming, las columnas previamente inferidas permanecen en la tabla cuando las incorporaciones posteriores las omiten. Se conservan los valores existentes, y las filas posteriores tienen NULL en las columnas omitidas.
  • Eliminar una columna de override_schema también elimina su requisito declarado de NOT NULL. Si la consulta sigue devolviendo esa columna, se infiere su nulabilidad.

Revise las consultas posteriores antes de cambiar un esquema de salida. Una nueva declaración no valida todos los archivos históricos ni repara automáticamente los datos previamente confirmados.

Limitations

Esta Beta no admite declaraciones parciales de esquema en SQL ni para vistas materializadas y tablas de transmisión creadas fuera de una canalización del espacio de trabajo, como en SQL de Databricks.

La inferencia parcial del esquema no admite lo siguiente:

  • Tablas de destino para flujos AUTO CDC o AUTO CDC FROM SNAPSHOT.
  • DEFAULT o IDENTITY definiciones de columnas en override_schema.
  • Declarar solo parte de una estructura anidada.

Prepárate para cambios en el esquema

Pruebe los cambios en la declaración con datos representativos y conserve el código de la tubería anterior. Para tablas de streaming, confirme que los datos fuente necesarios para reproducir una actualización siguen disponibles antes de considerar una actualización completa.

Para una opción adicional de recuperación opcional, prepare el rebobinado de la tubería antes de cambiar los esquemas y conserve un punto de rebobinado previo al cambio utilizable tras una actualización exitosa. Rewind tiene requisitos de elegibilidad y configuración separados. Sigue sus indicaciones de retención y reproducción al planificar la recuperación. La inferencia parcial de esquemas no requiere rebobinado.