Usare i parametri con le pipeline

I parametri della pipeline consentono di riutilizzare lo stesso codice sorgente della pipeline in ambienti o set di dati. Ad esempio, è possibile eseguire le stesse trasformazioni sui cataloghi dev e prod oppure acquisire dati da un percorso di origine diverso a ogni esecuzione. È possibile definire i parametri nella pipeline (o eseguirne l'override all'avvio di un aggiornamento) e farvi riferimento dal codice sorgente SQL.

Questa pagina descrive la funzionalità dei parametri della pipeline, disponibile per il codice sorgente SQL. Per parametrizzare il codice sorgente Python in una pipeline, continuare a utilizzare il campo Configuration come descritto in Fare riferimento ai parametri usando il campo di configurazione. La configurazione viene usata anche per impostare i valori di configurazione spark letti dalla pipeline in fase di esecuzione. Per informazioni sulle impostazioni di configurazione di Spark, consulta Riferimento alle proprietà della pipeline.

Cosa sono i parametri della pipeline?

I parametri della pipeline sono coppie chiave-valore che è possibile:

• Imposta come predefinite nelle impostazioni della pipeline.
• Eseguire l'override all'avvio di un aggiornamento dall'interfaccia utente della pipeline, dall'API Avvia aggiornamento o dalla finestra di dialogo Esegui con impostazioni diverse .
• Eseguire l'override dell'attività della pipeline in un processo, con il pushdown facoltativo dei parametri a livello di processo.
• Fare riferimento dal codice sorgente SQL usando la sintassi del parametro denominato.

I valori dei parametri sono sempre stringhe. Le chiavi possono contenere caratteri alfanumerici, caratteri di sottolineatura (_), trattini (-) e punti (.).

I parametri della pipeline e il campo Configurazione servono a scopi diversi:

Definire i parametri della pipeline

È possibile definire i valori dei parametri predefiniti nelle impostazioni della pipeline. Quando un aggiornamento viene eseguito senza override, la pipeline usa queste impostazioni predefinite.

Usa l'interfaccia utente della pipeline

1. Nell'area di lavoro fare clic Processi e pipeline nella barra laterale e selezionare la pipeline.
2. Fare clic su Impostazioni.
3. Nella barra laterale Impostazioni pipeline individuare la sezione Parametri e fare clic su Modifica.
4. Aggiungere voci chiave e valore , quindi fare clic su Salva.

Usare l'API JSON o REST

Aggiungere una parameters mappa alla definizione della pipeline:

{
  "name": "Sales pipeline",
  "parameters": {
    "source_catalog": "dev_catalog",
    "source_schema": "sales",
    "start_date": "2026-01-01"
  }
}

Per informazioni di riferimento su JSON della pipeline completa, vedere Configurazioni della pipeline.

Parametri di riferimento nel codice sorgente SQL

Fare riferimento a un parametro anteponendo alla chiave due punti. Azure Databricks associa il valore come stringa in fase di aggiornamento:

CREATE OR REFRESH MATERIALIZED VIEW transaction_summary AS
SELECT account_id,
  COUNT(txn_id) AS txn_count,
  SUM(txn_amount) AS account_revenue
FROM :source_catalog.sales.transactions
WHERE txn_date >= :start_date
GROUP BY account_id

Per usare un parametro in una posizione riservata a un identificatore, ad esempio come nome di catalogo, schema o tabella, racchiudilo in IDENTIFIER():

USE CATALOG IDENTIFIER(:source_catalog);
USE SCHEMA IDENTIFIER(:source_schema);

CREATE OR REFRESH MATERIALIZED VIEW daily_sales AS
SELECT date(timestamp) AS date,
  SUM(price) AS total_sales
FROM transactions
GROUP BY date;

Se il codice sorgente fa riferimento a un parametro senza valore in fase di aggiornamento, l'aggiornamento non riesce con un errore. La pipeline ignora parametri aggiuntivi a cui non fa riferimento il codice.

Sovrascrivere i parametri durante l'aggiornamento

È possibile eseguire l'override dei valori dei parametri per un singolo aggiornamento senza modificare le impostazioni predefinite salvate.

• Nell'interfaccia utente della pipeline fare clic su Esegui con impostazioni diverse e modificare la sezione Parametri .
• Da un'attività della pipeline in un processo, impostare gli override dei parametri nel campo Parametri dell'attività. Vedere Parametri.
• Dall'API, passa una parameters mappa nella richiesta Avvia aggiornamento.

Azure Databricks registra i parametri per un aggiornamento specifico nella cronologia degli aggiornamenti e li visualizza nella colonna Run parameters dell'elenco di esecuzioni della pipeline.

Precedenza dei parametri

Quando si definisce la stessa chiave in più posizioni, il valore con la precedenza più alta prevale. Dal più alto al più basso:

1. Parametri di esecuzione del processo: valori specificati per una singola esecuzione del processo (override).
2. Parametri del processo: valori predefiniti definiti nel processo padre.
3. Parametri dell'attività di pipeline: valori impostati nell'attività di pipeline.
4. Parametri della pipeline: valori predefiniti definiti nelle impostazioni della pipeline.

È conforme all'ordine di precedenza usato da altri tipi di attività dei parametri del processo.

Parametri della pipeline nei job di Lakeflow

Quando si pianifica una pipeline come attività della pipeline in un processo, l'attività può fornire parametri che eseguono l'override delle impostazioni predefinite della pipeline. I valori dei parametri possono usare riferimenti a valori dinamici per inserire valori di runtime del processo, {{job.trigger.time.iso_date}} ad esempio o {{job.parameters.region}}.

Lakeflow Jobs propaga automaticamente tutti i parametri del job ai task della pipeline, allo stesso modo in cui li propaga ai task notebook e SQL. Il codice sorgente della pipeline può fare riferimento a qualsiasi valore passato usando la sintassi dei parametri denominati. La dichiarazione di un parametro nelle impostazioni della pipeline è facoltativa e imposta solo un valore predefinito per le esecuzioni senza eseguire un override.

Avvertenze e limitazioni note

• Le pipeline eseguono un aggiornamento alla volta: una pipeline può eseguire un singolo aggiornamento alla volta. Per evitare che i job vadano in errore quando più aggiornamenti si sovrapporrebbero altrimenti, Azure Databricks limita la concorrenza a 1 in due scenari:

  • Un processo che contiene un'attività pipeline ed è configurato con più di un max_concurrent_runs.
  • Un'attività della pipeline racchiusa in un'attività for-each, indipendentemente dal numero di iterazioni.

  L'interfaccia utente del processo mostra una notifica quando questo limite diventa effettivo. Tenere conto del limite durante la progettazione di pipeline parametrizzate che si prevede di eseguire con molte combinazioni di parametri.

• I filtri di data possono attivare aggiornamenti completi: un caso d'uso comune per la parametrizzazione consiste nel filtrare i dati in base alla data. Prestare attenzione ai predicati: il filtro su entrambi i lati di un intervallo di date invalida l'elaborazione incrementale nelle viste materializzate e attiva un aggiornamento completo in ogni aggiornamento.

  -- Triggers a full refresh on each update
  CREATE OR REFRESH MATERIALIZED VIEW recent_orders AS
  SELECT * FROM orders
  WHERE order_date >= :start_date AND order_date < :end_date;
  

  -- Processes incrementally
  CREATE OR REFRESH MATERIALIZED VIEW recent_orders AS
  SELECT * FROM orders
  WHERE order_date >= :start_date;
  

• I parametri denominati sono solo SQL: in questa versione beta la sintassi dei parametri denominati può essere usata solo nel codice sorgente SQL. Per parametrizzare Python codice sorgente, continuare a usare il campo Configuration con spark.conf.get(). Vedere Parametri di riferimento usando il campo di configurazione.

Parametri di riferimento tramite il campo di configurazione

Il campo Configurazione in una pipeline accetta coppie chiave-valore arbitrarie esposte come valori di configurazione spark. Si tratta del meccanismo di parametrizzazione legacy e continua a funzionare insieme ai parametri della pipeline. Usalo per il codice sorgente Python e per le chiavi che vuoi leggere con spark.conf.get() anziché con la sintassi con parametri denominati.

Nell'esempio seguente viene usato un mypipeline.start_date valore di configurazione per limitare una pipeline di sviluppo a un subset di dati di input:

SQL

CREATE OR REFRESH MATERIALIZED VIEW customer_events
AS SELECT * FROM source_table WHERE date > '${mypipeline.start_date}';

Pitone

from pyspark import pipelines as dp
from pyspark.sql.functions import col

@dp.table
def customer_events():
  start_date = spark.conf.get("mypipeline.start_date")
  return spark.read.table("source_table").where(col("date") > start_date)

I valori di configurazione sono impostati nella sezione Configurazione delle impostazioni della pipeline o nel configuration campo del codice JSON della pipeline. Evitare chiavi in conflitto con la pipeline riservata o i valori di configurazione di Apache Spark.

Articoli correlati

• Configurare le pipeline
• Attività della pipeline per i processi
• Configurare i parametri dell'attività
• Che cos'è un riferimento di valore dinamico?