Teilweise Schema-Inferenz in Python Lakeflow-Pipelines verwenden

Teilweise Schema-Inferenz ermöglicht es Ihnen, ausgewählte Spalten in einer Python Lakeflow-Pipeline zu definieren und die verbleibenden Spalten aus der Abfrageausgabe abzuleiten. Verwenden Sie das Argument override_schema , um Typen, unterstützte Einschränkungen oder Kommentare für eine oder mehrere Spalten anzugeben, ohne jede Ausgabespalte zu deklarieren.

Important

Die partielle Schema-Inferenz befindet sich in der Beta. In Arbeitsbereichen, in denen diese Beta verfügbar ist, verwenden Sie override_schema in einer Python-Workspace-Pipeline, um eine Tabelle zu aktivieren.

Wählen Sie eine Schema-Option

Die folgenden Optionen steuern das Ausgabeschema einer materialisierten Ansicht, einer Streaming-Tabelle oder einer verwalteten Tabelle:

Auswahl Behavior
Beide Argumente weglassen Leite das Ausgabeschema aus der Abfrage ab.
schema Deklarieren Sie das vollständige Ausgabeschema.
override_schema Deklarieren Sie ausgewählte Spaltendefinitionen und leiten Sie die verbleibenden Abfrageausgabespalten ab.

Beides schema und override_schema akzeptieren einen SQL-DDL-String oder einen PySpark StructType. Geben Sie nur eines dieser Argumente an. Eine DDL-Zeichenkette in override_schema definiert Spalten innerhalb der Python-API. Es aktiviert keine Teilschema-Deklarationen in SQL-Anweisungen.

Verwenden Sie override_schema mit table, materialized_view oder create_streaming_table. Für verwaltete Tabellen verwenden Sie create_table , wo diese API verfügbar ist. Die entsprechenden Funktionen im Modul dlt akzeptieren dieses Argument ebenfalls. Verwenden Sie pyspark.pipelines für neuen Code.

Ausgewählte Spalten definieren

  1. Fügen Sie override_schema zur Definition des Dekorators oder Zieltisches hinzu.
  2. Deklarieren Sie die Spalten, deren Definitionen Sie steuern möchten. Die Abfragetypen müssen mit den deklarierten Typen kompatibel sein. Konvertieren Sie inkompatible Werte in der Abfrage, bevor Sie sie schreiben.
  3. Geben Sie die anderen Spalten zurück, die Sie aus der Abfrage einbeziehen möchten. Die teilweise Schema-Inferenz umfasst Abfrage-Ausgabespalten, nicht Quellspalten, die die Abfrage nicht auswählt.

Die folgende Pipeline erstellt eine materialisierte Ansicht mit einer expliziten NOT NULL Einschränkung auf id. Es leitet die Definitionen von name und score aus der Abfrage ab:

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",
    )

Die Ausgabe enthält id BIGINT NOT NULL, name STRING, und score BIGINT. Das Hinzufügen einer weiteren ausgewählten Spalte zur Abfrage umfasst diese Spalte, ohne sie override_schema hinzuzufügen.

Um ein StructTypezu verwenden, deklarieren Sie nur die ausgewählten Felder. Die folgende Streaming-Tabelle liest eine zugängliche, nur anfügbare Delta-Lake-Quelltabelle, deren Spalten event_time TIMESTAMP, payload STRING und id BIGINT sind. Die Quelle muss nicht-nullgültige id Werte enthalten:

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"
    )

Für ein separat definiertes Ziel übergeben Sie override_schema an dp.create_streaming_table() oder dp.create_table() und verwenden einen Append-Flow, um darauf zu schreiben. Jede nicht generierte Spalte, die in override_schema deklariert wird, muss im kombinierten Abfrageergebnis der Flows erscheinen, die das Ziel versorgen. Sie kann in einem einzelnen Append-Flow fehlen.

Spaltendefinitionen und Constraints

Sie können Spaltenkommentare und unterstützte Tabellenbeschränkungen in eine override_schema DDL-Zeichenkette einbinden. Bestehende Anforderungen an diese Funktionen gelten; Primär- und Fremdschlüssel bleiben informativ.

Deklarieren Sie eine vollständige komplexe Spalte, wie etwa eine Struktur, ein Array oder eine Abbildung. Sie können nicht nur einige untergeordnete Elemente einer verschachtelten Struktur deklarieren und deren verbleibende untergeordnete Elemente ableiten.

Schemaänderungen zwischen Updates

Wenn Sie die Abfrage oder Teildeklaration ändern, gelten die folgenden Regeln für Updates ohne vollständige Aktualisierung:

  • Für eine neu berechnete materialisierte Ansicht werden abgeleitete Spalten, die in der neuen Abfrageausgabe fehlen, aus dem Ausgabeschema entfernt.
  • Bei einer Streaming-Tabelle bleiben zuvor abgeleitete Spalten in der Tabelle zurück, wenn spätere Anfügungen sie weglassen. Bestehende Werte werden beibehalten, und spätere Zeilen haben NULL in den ausgelassenen Spalten.
  • Das Entfernen einer Spalte aus override_schema entfernt auch deren deklarierte NOT NULL Anforderung. Wenn die Abfrage diese Spalte weiterhin zurückgibt, wird ihre Nullbarkeit abgeleitet.

Überprüfen Sie nachgelagerte Abfragen, bevor Sie ein Ausgabeschema ändern. Eine neue Deklaration validiert nicht jede historische Datei und repariert nicht automatisch zuvor festgeschriebene Daten.

Limitations

Diese Beta unterstützt keine Teilschema-Deklarationen in SQL oder für materialisierte Ansichten und Streaming-Tabellen, die außerhalb einer Arbeitsraumpipeline erstellt werden, wie zum Beispiel in Databricks SQL.

Teilweise Schema-Inferenz unterstützt Folgendes nicht:

  • Zieltabellen für AUTO CDC oder AUTO CDC FROM SNAPSHOT Flows.
  • DEFAULT oder IDENTITY Spaltendefinitionen in override_schema.
  • Nur einen Teil einer verschachtelten Struktur deklarieren.

Auf Schemaänderungen vorbereiten

Änderungen der Deklaration auf repräsentativen Daten testen und den vorherigen Pipeline-Code beibehalten. Für Streaming-Tabellen stellen Sie sicher, dass die Quelldaten, die zum erneuten Abspielen eines Updates benötigt werden, weiterhin verfügbar sind, bevor eine vollständige Aktualisierung in Betracht gezogen wird.

Für eine optionale zusätzliche Wiederherstellungsoption bereiten Sie die Pipeline-Rückspulung vor, bevor Sie die Schemata ändern, und behalten Sie einen nutzbaren Rückspulpunkt vor der Änderung nach einem erfolgreichen Update bei. Rewind hat eigene Berechtigungs- und Setup-Anforderungen. Befolgen Sie deren Aufbewahrungs- und Wiedergaberichtlinien bei der Planung der Wiederherstellung. Partielle Schema-Inferenz erfordert kein Zurücksetzen.