Gebruik gedeeltelijke schema-inferentie in Python Lakeflow-pijplijnen

Gedeeltelijke schema-inferentie stelt u in staat geselecteerde kolommen in een Python Lakeflow-pijplijn te definiëren en de resterende kolommen uit de query-uitvoer af te leiden. Gebruik het override_schema argument om typen, ondersteunde beperkingen of opmerkingen op te geven voor één of meer kolommen zonder elke outputkolom te declareren.

Important

Gedeeltelijke schema-inferentie is in Beta. In werkruimtes waar deze Beta beschikbaar is, gebruik override_schema in een Python-werkruimtepijplijn om je aan te melden voor een tabel.

Kies een schema-optie

De volgende opties regelen het uitvoerschema van een gematerialiseerde weergave, streamingtabel of beheerde tabel:

Option Behavior
Laat beide argumenten weg Leid het uitvoerschema af uit de query.
schema Declare het volledige outputschema.
override_schema Definieer geselecteerde kolomdefinities en leid de resterende query-uitvoerkolommen af.

Beide schema en override_schema accepteren een SQL DDL-string of een PySpark StructType. Specificeer slechts één van deze argumenten. Een DDL-string in override_schema definieert kolommen binnen de Python API. Het ondersteunt geen gedeeltelijke schemadeclaraties in SQL-instructies.

Gebruik override_schema met table, materialized_view of create_streaming_table. Gebruik voor beheerde tabellen create_table waar die API beschikbaar is. De bijbehorende functies in de dlt module accepteren dit argument ook. Gebruik voor nieuwe code pyspark.pipelines.

Geselecteerde kolommen definiëren

  1. Voeg toe override_schema aan de decorator- of doeltabeldefinitie.
  2. Declareer de kolommen waarvan u de definities wilt bepalen. De querytypes moeten compatibel zijn met de gedeclareerde types. Cast incompatibele waarden in de query voordat je ze wegschrijft.
  3. Geef de andere kolommen op die u in de query wilt opnemen. Gedeeltelijke schema-inferentie omvat query-uitvoerkolommen, niet bronkolommen die de query niet selecteert.

De volgende pijplijn creëert een materialized view met een expliciete NOT NULL constraint op id. Het leidt de definities van name en score uit de query af:

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

De output bevat id BIGINT NOT NULL, name STRING, en score BIGINT. Het toevoegen van een andere geselecteerde kolom aan de query neemt die kolom op zonder deze toe te voegen aan override_schema.

Om een StructTypete gebruiken, declareer alleen de geselecteerde velden. De volgende streamingtabel leest een toegankelijke, alleen als bijlage beschikbare Delta Lake-brontabel waarvan de kolommen id BIGINT, event_time TIMESTAMP, en payload STRINGzijn. De bron moet id-waarden die niet null zijn bevatten:

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

Geef voor een apart gedefinieerd doel override_schema door aan dp.create_streaming_table() of dp.create_table() en gebruik een appendflow om ernaar te schrijven. Elke niet-gegenereerde kolom die is gedeclareerd in override_schema moet verschijnen in de gecombineerde query-uitvoer van de stromen die het doel voeden. Het kan afwezig zijn in een individuele append-flow.

Kolomdefinities en restricties

U kunt kolomopmerkingen en ondersteunde tabelbeperkingen opnemen in een override_schema DDL-string. Bestaande eisen voor deze functies gelden; primaire en refererende sleutels blijven informatief.

Declareer een volledige complexe kolom, zoals een struct, array of map. Je kunt niet alleen enkele onderliggende velden van een geneste struct declareren en vervolgens de resterende onderliggende velden afleiden.

Schemawijzigingen tussen updates

Wanneer u de query of gedeeltelijke declaratie wijzigt, gelden de volgende regels voor updates zonder volledige vernieuwing:

  • Voor een herberekende gematerialiseerde weergave worden afgeleide kolommen die ontbreken in de nieuwe query-uitvoer verwijderd uit het uitvoerschema.
  • Voor een streamingtabel blijven eerder afgeleide kolommen in de tabel wanneer latere toevoegingen deze weglaten. Bestaande waarden worden behouden, en latere rijen hebben NULL in de weggelaten kolommen.
  • Het verwijderen van een kolom uit override_schema verwijdert ook de opgegeven NOT NULL vereiste. Als de query die kolom nog steeds teruggeeft, wordt de nulbaarheid ervan afgeleid.

Controleer downstream-queries voordat u een outputschema wijzigt. Een nieuwe declaratie-instructie valideert niet elk historisch bestand en herstelt niet automatisch eerder gecommitteerde gegevens.

Limitations

Deze Beta ondersteunt geen gedeeltelijke schema-declaraties in SQL of voor gematerialiseerde weergaven en streamingtabellen die buiten een werkruimtepipeline zijn aangemaakt, zoals in Databricks SQL.

De volgende onderdelen worden niet ondersteund door gedeeltelijke schema-inferentie:

  • Doeltabellen voor AUTO CDC of AUTO CDC FROM SNAPSHOT flows.
  • DEFAULT of IDENTITY kolomdefinities in override_schema.
  • Alleen een deel van een geneste struct declareren.

Bereid je voor op schemawijzigingen

Test declaratiewijzigingen op representatieve data en behoud de vorige pijplijncode. Voor streamingtabellen controleer je dat de brondata die nodig is om een update opnieuw af te spelen beschikbaar blijft voordat je een volledige verversing overweegt.

Voor een optionele aanvullende hersteloptie bereidt u pipeline rewind voor voordat u schema's wijzigt en behoudt u een bruikbaar rewind-punt van vóór de schemawijziging uit een geslaagde update. Rewind heeft aparte geschiktheids- en installatievereisten. Volg de richtlijnen voor retentie en replay bij het plannen van herstel. Gedeeltelijke schema-inferentie vereist geen terugspoelen.