Utiliser des paramètres avec des pipelines

Les parameters de pipeline vous permettent de réutiliser le même code source de pipeline dans différents environnements ou datasets. Par exemple, vous pouvez exécuter les mêmes transformations sur les catalogues dev et prod, ou ingérer des données à partir d'un chemin source différent à chaque exécution. Vous définissez des parameters sur le pipeline (ou les annulez lors du démarrage d'une mise à jour) et les référencez à partir de votre code source SQL.

info

Bêta

Cette fonctionnalité est en Bêta. Les administrateurs du Workspace peuvent contrôler l'accès à cette fonctionnalité à partir de la page Previews . Consultez Gérer les aperçus Databricks.

Les parameters de pipeline sont disponibles uniquement pour le code source SQL. Pour paramétrer le code source Python dans un pipeline, utilisez le champ Configuration tel que décrit dans Référencer les parameters à l'aide du champ de configuration. La configuration est également utilisée pour définir les valeurs de configuration Spark que les pipelines lisent au moment de l'exécution. Pour plus de détails sur les paramètres de configuration Spark, consultez Référence des propriétés du pipeline.

Qu’est-ce que les paramètres de pipeline ?

Les parameters de pipeline sont des paires clé-valeur que vous pouvez :

Déclarer comme default dans les paramètres du pipeline.
Ignorer lors du démarrage d'une mise à jour depuis l'interface utilisateur du pipeline, l'API Start update, ou la boîte de dialogue **Exécuter avec des paramètres différents**.
Remplacement sur la tâche du pipeline dans un Job, avec pushdown facultatif des paramètres au niveau du Job.
Référence provenant du code source SQL utilisant la syntaxe du paramètre nommé.

Les valeurs des paramètres sont toujours des chaînes de caractères. Les clés peuvent contenir des caractères alphanumériques, des traits de soulignement (_), des tirets (-) et des points (.).

Les parameters de pipeline et le champ Configuration servent à des fins différentes :

Use parameter for...	Utilisez configuration pour...
Valeurs qui changent entre les mises à jour (catalogue cible, chemin source, plage de dates).	Configuration Spark qui contrôle le comportement du pipeline (`pipelines.enzyme.enabled`, `pipelines.clusterLabelsV2Enabled`).
Valeurs que vous souhaitez transférer depuis un Job ou une tâche.	Propriétés de pipeline statiques et structurelles.
Valeurs que vous référencez dans SQL avec la syntaxe de parameter nommé.	Valeurs que vous référencez avec la syntaxe `${key}` en SQL ou `spark.conf.get("key")` en Python.

Use parameter for...	Utilisez configuration pour...
Valeurs qui changent entre les mises à jour (catalogue cible, chemin source, plage de dates).	Configuration Spark qui contrôle le comportement du pipeline (`pipelines.enzyme.enabled`, `pipelines.clusterLabelsV2Enabled`).
Valeurs que vous souhaitez transférer depuis un Job ou une tâche.	Propriétés de pipeline statiques et structurelles.
Valeurs que vous référencez dans SQL avec la syntaxe de parameter nommé.	Valeurs que vous référencez avec la syntaxe `${key}` en SQL ou `spark.conf.get("key")` en Python.

Définir les parameters du pipeline

Vous pouvez définir des valeurs de parameter par default dans les paramètres du pipeline. Lorsqu'une mise à jour s'exécute sans remplacements, le pipeline utilise ces valeurs par default.

Utiliser l'interface utilisateur du pipeline

Dans votre Workspace, cliquez sur Jobs et Pipelines dans la barre latérale et sélectionnez votre pipeline.
Cliquez sur Paramètres .
Dans la barre latérale **Paramètres du pipeline**, recherchez la section **Paramètres** et cliquez sur **Modifier**.
Ajoutez les entrées Clé et Valeur , puis cliquez sur Enregistrer .

Utilisez l'API JSON ou REST

Ajoutez un mappage parameters à la définition JSON du pipeline, soit dans les paramètres du pipeline, soit lors de l'utilisation de l'API REST :

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

Pour la référence JSON complète du pipeline, consultez Configurations de pipeline.

Utilisez YAML ou les Declarative Automation Bundles

Définissez les parameters dans le mappage parameters de la définition YAML du pipeline, soit dans les paramètres du pipeline, soit dans des Declarative Automation Bundles (Qu'est-ce qu'un Declarative Automation Bundles ?) :

YAML
resources:
  pipelines:
    my_pipeline:
      name: Sales pipeline
      parameters:
        source_catalog: dev_catalog
        source_schema: sales
        start_date: '2026-01-01'

Référencez les parameters dans le code source SQL

Référencez un paramètre en préfixant la clé avec un deux-points. Databricks lie la valeur sous forme de chaîne au moment de la mise à jour :

SQL
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

Pour utiliser un paramètre dans une position d'identificateur, tel qu'un nom de catalogue, de schéma ou de table, encapsulez-le dans IDENTIFIER():

SQL
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;

Si votre code source référence un parameter qui n'a aucune valeur au moment de la mise à jour, la mise à jour échoue avec une erreur. Le pipeline ignore les paramètres supplémentaires que le code ne référence pas.

Remplacer les paramètres au moment de la mise à jour

Vous pouvez remplacer les valeurs des paramètres pour une seule mise à jour sans modifier les default enregistrées.

Depuis l’interface utilisateur du pipeline, cliquez sur Exécuter avec différents paramètres et modifiez la section Paramètres .
À partir d'une tâche de pipeline dans un Job, définissez les remplacements de parameter dans le champ **Paramètres** de la tâche. See parameter.
Depuis l'API, transmettez une carte parameters dans la requête de start update.

Databricks enregistre les paramètres d'une mise à jour spécifique dans l'historique des mises à jour et les affiche dans la colonne Paramètres d'exécution de la liste des exécutions de pipeline.

Préférence des parameter

Lorsque vous définissez la même clé à plusieurs endroits, la valeur ayant la priorité la plus élevée l'emporte. Du plus élevé au plus bas :

Job run parameters : valeurs fournies pour une seule exécution de Job (remplacements).
Job parameters : valeurs par default définies sur le job parent.
Paramètres de tâche de pipeline : valeurs définies sur la tâche de pipeline.
Paramètres du pipeline : defaults définis dans les paramètres du pipeline.

Ceci correspond à la précédence utilisée par d'autres types de tâches de Job parameter.

Paramètres de pipeline dans les Lakeflow Jobs

Lorsque vous planifiez un pipeline en tant que tâche de pipeline dans un Job, la tâche peut fournir des paramètres qui remplacent les default du pipeline. Les valeurs des paramètres peuvent utiliser des références de valeur dynamique pour injecter des valeurs d'exécution de job telles que {{job.trigger.time.iso_date}} ou {{job.parameters.region}}. Pour référencer une valeur définie par une tâche en amont, utilisez {{tasks.<task_name>.values.<value_name>}}. Consultez Utiliser les valeurs de tâche pour transmettre des informations entre les tâches.

Lakeflow Jobs transfère également automatiquement tous les paramètres de job aux tâches de pipeline, de la même manière qu'il les transfère aux tâches de Notebook et SQL. Le code source du pipeline peut faire référence à toute valeur transférée avec la syntaxe de parameter nommé. La déclaration d'un parameter dans les paramètres de pipeline est facultative et ne définit une default que pour les exécutions sans substitution.

Mises en garde et limites connues

Les pipelines exécutent une seule mise à jour à la fois : Un pipeline ne peut exécuter qu'une seule mise à jour à la fois. Pour éviter que les jobs n’échouent lorsque plusieurs mises à jour se chevaucheraient, Databricks limite les exécutions simultanées à 1 dans deux scénarios :
- Un Job qui contient une tâche de pipeline et est configuré avec max_concurrent_runs, ce qui est plus d'un.
- Une tâche de pipeline encapsulée dans une tâche for-each, quel que soit le nombre d’itérations.
L'interface utilisateur du Job affiche une notification lorsque cette limite prend effet. Planifiez en fonction de la limite lors de la conception de pipelines paramétrés que vous avez l'intention d'exécuter avec de nombreuses combinaisons de paramètres.
Les filtres de date peuvent trigger des full refreshes : un cas d'utilisation courant de paramétrisation est de filtrer les données par date. Faites attention aux prédicats : le filtrage sur les deux côtés d'une plage de dates invalide le traitement incremental sur les vues matérialisées et Trigger un refresh complet à chaque mise à jour.
SQL
```
-- 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;
```
SQL
```
-- Processes incrementally
CREATE OR REFRESH MATERIALIZED VIEW recent_orders AS
SELECT * FROM orders
WHERE order_date >= :start_date;
```
Les paramètres nommés sont uniquement SQL : dans cette version bêta, la syntaxe des paramètres nommés ne peut être utilisée que dans le code source SQL. Pour paramétrer le code source Python, continuez d'utiliser le champ Configuration avec spark.conf.get(). Voir Référencer les paramètres à l'aide du champ de configuration.

Référencer les parameters à l'aide du champ de configuration

Le champ **Configuration** d'un pipeline accepte des paires clé-valeur arbitraires qui sont exposées comme des valeurs de configuration Spark. Il s’agit du mécanisme de paramétrisation hérité et il continue de fonctionner avec les parameters du pipeline. Utilisez-le pour le code source Python et pour les clés que vous souhaitez lire avec spark.conf.get() plutôt qu'avec la syntaxe des paramètres nommés.

L'exemple suivant utilise une valeur de configuration mypipeline.start_date pour limiter un pipeline de développement à un sous-ensemble de données d'entrée :

SQL
Python

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

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

Vous définissez les valeurs de configuration dans la section **Configuration** des paramètres du pipeline ou dans le configuration champ du JSON du pipeline. Évitez les clés qui entrent en conflit avec les valeurs de configuration réservées du pipeline ou d'Apache Spark.

Qu’est-ce que les paramètres de pipeline ?​

Définir les parameters du pipeline​

Utiliser l'interface utilisateur du pipeline​

Utilisez l'API JSON ou REST​

Utilisez YAML ou les Declarative Automation Bundles​

Référencez les parameters dans le code source SQL​

Remplacer les paramètres au moment de la mise à jour​

Préférence des parameter​

Paramètres de pipeline dans les Lakeflow Jobs​

Mises en garde et limites connues​

Référencer les parameters à l'aide du champ de configuration​

Ressources supplémentaires​