Usa inferenza parziale di schema nelle pipeline di Lakeflow di Python

L'inferenza parziale dello schema consente di definire colonne selezionate in una pipeline Python Lakeflow e di inferire le colonne rimanenti dall'output della query. Usa l'argomento override_schema per specificare tipi, vincoli supportati o commenti per una o più colonne senza dichiarare ogni colonna di output.

Important

L'inferenza parziale dello schema è presente in Beta. Negli workspace dove questa Beta è disponibile, utilizza override_schema in una pipeline di workspace Python per ottenere una tabella.

Scegli un'opzione di schema

Le seguenti opzioni controllano lo schema di output di una vista materializzata, di una tabella di streaming o di una tabella gestita:

Option Behavior
Ometti entrambi gli argomenti Ricava lo schema di output dalla query.
schema Dichiara lo schema di output completo.
override_schema Dichiara le definizioni di colonne selezionate e deduci le restanti colonne di output della query.

Entrambi schema e override_schema accettano una stringa SQL DDL o un PySpark StructType. Specifica solo uno di questi argomenti. Una stringa DDL in override_schema definisce colonne all'interno dell'API Python. Non abilita dichiarazioni parziali di schema nelle istruzioni SQL.

Usa override_schema con table, materialized_view o create_streaming_table. Per le tabelle gestite, usa create_table dove quell'API è disponibile. Le funzioni corrispondenti nel dlt modulo accettano anch'esse questo argomento. Per il nuovo codice, usare pyspark.pipelines.

Definisci le colonne selezionate

  1. Aggiungi override_schema alla definizione del decoratore o della target-table.
  2. Dichiara le colonne le cui definizioni vuoi controllare. I tipi di query devono essere compatibili con i tipi dichiarati. Esegui il cast di valori incompatibili nella query prima di scriverli.
  3. Restituisci le altre colonne che desideri includere dalla query. L'inferenza parziale dello schema include le colonne di output della query, non le colonne sorgente che la query non seleziona.

La pipeline seguente crea una vista materializzata con un vincolo esplicito NOT NULL su id. Essa deduce le definizioni di name e score dalla query:

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

L'output contiene id BIGINT NOT NULL, name STRING, e score BIGINT. Se aggiungi un'altra colonna selezionata alla query, la query include quella colonna senza aggiungerla a override_schema.

Per usare un StructType, dichiara solo i campi selezionati. La seguente tabella streaming legge una tabella sorgente Delta Lake accessibile, solo ad appendi, le cui colonne sono id BIGINT, event_time TIMESTAMP, e payload STRING. La sorgente deve contenere valori non nulli 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"
    )

Per un target definito separatamente, passa override_schema a dp.create_streaming_table() o dp.create_table() e usa un flusso di append per scrivervi. Ogni colonna non generata dichiarata in override_schema deve apparire nell'output combinato delle query dei flussi che alimentano il target. Può essere assente in un singolo flusso di append.

Definizioni delle colonne e vincoli

Puoi includere commenti di colonna e vincoli di tabella supportati in una override_schema stringa DDL. Si applicano i requisiti esistenti per queste funzionalità; le chiavi primarie e esterne rimangono informative.

Dichiara una colonna complessa completa, come una struct, un array o una mappa. Non puoi dichiarare solo alcuni figli di una struttura annidata e inferire i figli rimasti.

Cambiamenti dello schema tra gli aggiornamenti

Quando modifichi la query o la dichiarazione parziale, le seguenti regole si applicano agli aggiornamenti senza un aggiornamento completo:

  • Per una vista materializzata ricalcolata, le colonne dedotte assenti dall'output della nuova query vengono rimosse dallo schema di output.
  • Per una tabella in streaming, le colonne precedentemente inferite rimangono nella tabella quando le aggiunte successive le omettono. I valori esistenti vengono mantenuti, mentre le righe successive hanno NULL nelle colonne omesse.
  • Rimuovere una colonna da override_schema elimina anche il requisito dichiarato NOT NULL . Se la query restituisce ancora quella colonna, viene inferita la sua nullabilità.

Esaminare le query a valle prima di modificare uno schema di output. Una nuova dichiarazione non convalida ogni file storico né ripara automaticamente i dati precedentemente salvati.

Limitations

Questa Beta non supporta dichiarazioni parziali di schema in SQL né per visualizzazioni materializzate e tabelle in streaming create al di fuori di una pipeline di workspace, come in Databricks SQL.

L'inferenza parziale dello schema non supporta quanto segue:

  • Tabelle di destinazione per i flussi AUTO CDC o AUTO CDC FROM SNAPSHOT.
  • DEFAULT oppure IDENTITY definizioni di colonne in override_schema.
  • Dichiarare solo una parte di una struttura annidata.

Prepararsi per le modifiche dello schema

Verificare le modifiche alle dichiarazioni sui dati rappresentativi e mantenere il codice della pipeline precedente. Per le tabelle in streaming, verifica che i dati sorgente necessari per riprodurre un aggiornamento siano disponibili prima di considerare un aggiornamento completo.

Per un'ulteriore opzione di ripristino facoltativa, prepara pipeline rewind prima di modificare gli schemi e, dopo un aggiornamento riuscito, conserva un punto di rewind pre-modifica utilizzabile. Rewind ha requisiti di idoneità e di configurazione separati. Segui le sue linee guida su conservazione e riesecuzione quando pianifichi il recupero. L'inferenza parziale dello schema non richiede riavvolgimento.