Utiliser l’inférence partielle du schéma dans les pipelines Lakeflow Python

L’inférence partielle du schéma vous permet de définir des colonnes sélectionnées dans un pipeline Python Lakeflow et d’inférer les colonnes restantes à partir de la sortie de requête. Utilisez l’argument override_schema pour spécifier les types, contraintes prises en charge ou commentaires pour une ou plusieurs colonnes sans déclarer chaque colonne de sortie.

Important

L’inférence partielle du schéma est en Beta. Dans les espaces de travail où cette version bêta est disponible, utilisez override_schema dans un pipeline d’espace de travail Python pour activer l’utilisation d’une table.

Choisir une option de schéma

Les options suivantes contrôlent le schéma de sortie d’une vue matérialisée, d’une table de streaming ou d’une table gérée :

Option Behavior
Omettez les deux arguments Déduisez le schéma de sortie à partir de la requête.
schema Déclarez le schéma de sortie complet.
override_schema Déclarez les définitions de colonnes sélectionnées et inférez les colonnes de sortie restantes de requête.

schema et StructType acceptent tous deux une chaîne SQL DDL ou un PySpark override_schema. Spécifiez un seul de ces arguments. Une chaîne DDL override_schema définit des colonnes à l’intérieur de l’API Python. Il ne permet pas les déclarations partielles de schéma dans les instructions SQL.

Utilisez override_schema avec table, materialized_view ou create_streaming_table. Pour les tables gérées, utilisez create_table là où cette API est disponible. Les fonctions correspondantes du dlt module acceptent également cet argument. Pour le nouveau code, utilisez pyspark.pipelines.

Définir les colonnes sélectionnées

  1. Ajoutez override_schema à la définition de la table décoratrice ou de la table cible.
  2. Déclarez les colonnes dont vous souhaitez contrôler les définitions. Les types de requête doivent être compatibles avec les types déclarés. Convertissez des valeurs incompatibles dans la requête avant de les écrire.
  3. Retournez les autres colonnes que vous souhaitez inclure depuis la requête. L’inférence partielle du schéma inclut les colonnes de sortie de la requête, et non les colonnes source que la requête ne sélectionne pas.

Le pipeline suivant crée une vue matérialisée avec une contrainte explicite NOT NULL sur id. Elle déduit les définitions de name et score à partir de la requête :

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 sortie contient id BIGINT NOT NULL, name STRING, et score BIGINT. L’ajout d’une autre colonne sélectionnée à la requête inclut cette colonne sans l’ajouter à override_schema.

Pour utiliser un StructType, déclarez uniquement les champs sélectionnés. La table de flux suivante lit une table source Delta Lake accessible, uniquement annexe, dont les colonnes sont id BIGINT, event_time TIMESTAMP, et payload STRING. La source doit contenir des valeurs non nulles 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"
    )

Pour une cible définie séparément, passez override_schema vers dp.create_streaming_table() ou dp.create_table() et utilisez un flux d’ajout pour y écrire. Chaque colonne non générée déclarée dans override_schema doit apparaître dans la sortie combinée des requêtes des flux alimentant la cible. Elle peut être absente d’un flux d’ajout individuel.

Définitions de colonnes et contraintes

Vous pouvez inclure des commentaires de colonne et des contraintes de table prises en charge dans une override_schema chaîne DDL. Les exigences existantes pour ces fonctionnalités s’appliquent ; les clés primaire et étrangère restent informatives.

Déclarez une colonne complexe complète, telle qu’une structure, un tableau ou une map. On ne peut pas déclarer seulement quelques champs d’une structure imbriquée et en déduire ses champs restants.

Changements de schéma entre les mises à jour

Lorsque vous modifiez la requête ou la déclaration partielle, les règles suivantes s’appliquent aux mises à jour sans rafraîchissement complet :

  • Pour une vue matérialisée recalculée, les colonnes inférées absentes de la nouvelle sortie de requête sont retirées du schéma de sortie.
  • Pour une table en streaming, les colonnes précédemment inférées restent dans la table lorsque des ajouts ultérieurs les omettent. Les valeurs existantes sont conservées, et les lignes ultérieures comportent NULL dans les colonnes omises.
  • Supprimer une colonne de override_schema supprime également son exigence déclarée NOT NULL . Si la requête renvoie toujours cette colonne, sa nullabilité est déduite.

Examinez les requêtes en aval avant de modifier un schéma de sortie. Une nouvelle déclaration ne valide pas chaque fichier historique ni ne répare automatiquement les données précédemment enregistrées.

Limitations

Cette version bêta ne supporte pas les déclarations partielles de schéma en SQL ni pour les vues matérialisées et les tables en flux créées en dehors d’un pipeline d’espace de travail, comme dans Databricks SQL.

L’inférence partielle du schéma ne prend pas en charge les éléments suivants :

  • Tables cibles pour les flux AUTO CDC ou AUTO CDC FROM SNAPSHOT.
  • DEFAULT ou IDENTITY définitions de colonnes dans override_schema.
  • Déclaration d’une partie seulement d’une structure imbriquée.

Préparez-vous aux modifications du schéma

Testez les changements de déclaration sur des données représentatives et conservez le code de pipeline précédent. Pour les tables en streaming, vérifiez que les données source nécessaires pour rejouer une mise à jour restent disponibles avant d’envisager une mise à jour complète.

Pour une option de récupération supplémentaire optionnelle, préparez le rembobinage du pipeline avant de modifier les schémas et conservez un point de rembobinage utilisable avant le changement suite à une mise à jour réussie. Rewind a des critères d’éligibilité et des conditions de configuration distincts. Suivez ses recommandations de rétention et de rejeu lors de la planification de la récupération. L’inférence partielle du schéma ne nécessite pas de rembobinage.