Utiliser des paramètres avec des pipelines

Les paramètres de pipeline vous permettent de réutiliser le même code source de pipeline entre les environnements ou les jeux de données. Par exemple, vous pouvez exécuter les mêmes transformations sur les catalogues dev et prod, ou importer depuis un chemin source différent à chaque exécution. Vous définissez des paramètres sur le pipeline (ou remplacez-les lors du démarrage d’une mise à jour) et référencez-les à partir de votre code source SQL.

Important

Cette fonctionnalité est en version bêta. Les administrateurs d’espace de travail peuvent contrôler l’accès à cette fonctionnalité à partir de la page Aperçus . Consultez Gérer les préversions d’Azure Databricks.

Cette page décrit la fonctionnalité de paramètres de pipeline, disponible pour le code source SQL. Pour paramétrer le code source Python dans un pipeline, continuez à utiliser le champ Configuration comme décrit dans Référencer des paramètres à 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 d’informations sur les paramètres de configuration Spark, consultez la référence des propriétés du pipeline.

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

Les paramètres de pipeline sont des paires clé-valeur que vous pouvez :

Déclarez comme valeurs par défaut dans les paramètres du pipeline.
Remplacez les valeurs lors du démarrage d’une mise à jour à partir de l’interface utilisateur du pipeline, de l’API Start update ou de la boîte de dialogue Exécuter avec des paramètres différents.
Remplacez la tâche de pipeline dans un travail, avec un pushdown facultatif des paramètres au niveau du travail.
Référence depuis le code source SQL à l’aide de la syntaxe de paramètre nommé.

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

Les paramètres de pipeline et le champ Configuration ont des objectifs différents :

Utiliser les paramètres pour...	Utiliser Configuration pour...
Valeurs qui changent entre les mises à jour (catalogue cible, chemin d’accès source, plage de dates).	Configuration Spark qui contrôle le comportement du pipeline (`pipelines.enzyme.enabled`, `pipelines.clusterLabelsV2Enabled`).
Valeurs que vous souhaitez propager depuis un travail ou une tâche.	Propriétés statiques et structurelles du pipeline.
Valeurs que vous référencez dans SQL avec une syntaxe de paramètre nommée.	Valeurs que vous référencez avec la syntaxe `${key}` dans SQL ou `spark.conf.get("key")` dans Python.

Définir des paramètres de pipeline

Vous pouvez définir des valeurs de paramètre par défaut dans les paramètres du pipeline. Lorsqu’une mise à jour s’exécute sans remplacement, le pipeline utilise ces valeurs par défaut.

Utiliser l’interface utilisateur du pipeline

Dans votre espace de travail, cliquez sur Travaux et pipelines dans la barre latérale, puis sélectionnez votre pipeline.
Cliquez sur Paramètres.
Dans la barre latérale des paramètres du pipeline , recherchez la section Paramètres , puis cliquez sur Modifier.
Ajoutez des entrées clé et valeur , puis cliquez sur Enregistrer.

Utiliser l’API JSON ou REST

Ajoutez une parameters carte à la définition de pipeline :

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

Pour obtenir la référence JSON de pipeline complète, consultez configurations de pipeline.

Paramètres de référence dans le code source SQL

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

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 catalogue, un schéma ou un nom de table, encapsulez-le :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;

Si votre code source fait référence à un paramètre 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 de paramètre pour une seule mise à jour sans modifier les valeurs par défaut enregistrées.

Dans 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 travail, définissez les remplacements de paramètre dans le champ Paramètres de la tâche. Voir Paramètres.
À partir de l’API, transmettez une parameters carte dans la demande de mise à jour de démarrage .

Azure Databricks enregistre les paramètres d’une mise à jour spécifique dans l’historique des mises à jour et les affiche dans les paramètres Exécuter colonne de la liste des exécutions du pipeline.

Priorité des paramètres

Lorsque vous définissez la même clé à plusieurs endroits, la valeur avec la priorité la plus élevée gagne. De la plus élevée au plus bas :

Paramètres d’exécution du travail : valeurs fournies pour une seule exécution de travail (remplacements).
Paramètres de travail : valeurs par défaut définies sur le travail parent.
Paramètres de la tâche de pipeline : valeurs définies pour la tâche de pipeline.
Paramètres de pipeline : valeurs par défaut définies dans les paramètres du pipeline.

Cela correspond à la priorité utilisée par d’autres types de tâches de paramètre de travail.

Paramètres de pipeline dans les jobs Lakeflow

Lorsque vous planifiez un pipeline en tant que tâche de pipeline dans un travail, la tâche peut fournir des paramètres qui remplacent les valeurs par défaut du pipeline. Les valeurs de paramètre peuvent utiliser des références de valeurs dynamiques pour injecter des valeurs d’exécution de travail telles que {{job.trigger.time.iso_date}} ou {{job.parameters.region}}.

Lakeflow Jobs transmet également automatiquement tous les paramètres des jobs aux tâches du pipeline, de la même manière qu’à celles de notebook et SQL. Le code source du pipeline peut faire référence à toute valeur transmise à l’aide d’une syntaxe de paramètres nommés. La déclaration d’un paramètre dans les paramètres de pipeline est facultative et définit uniquement une valeur par défaut pour les exécutions sans remplacement.

Mises en garde et limitations connues

Les pipelines exécutent une mise à jour à la fois : un pipeline ne peut exécuter qu’une seule mise à jour à la fois. Pour empêcher les travaux d’échouer lorsque plusieurs mises à jour se chevauchent autrement, Azure Databricks limite la concurrence à 1 dans deux scénarios :
- Un travail qui contient une tâche de pipeline et qui est configuré avec plus de max_concurrent_runs un.
- Tâche de pipeline encapsulée dans une tâche for-each, quel que soit le nombre d’itérations.
L’interface utilisateur du travail affiche une notification lorsque cette limite prend effet. Tenez compte de cette limite lors de la conception de pipelines paramétrés destinés à être exécutés avec un grand nombre de combinaisons de paramètres.
Les filtres de date peuvent déclencher des actualisations complètes : un cas d’usage de paramétrage courant consiste à filtrer les données par date. Prenez soin des prédicats : le filtrage des deux côtés d’une plage de dates invalide le traitement incrémentiel sur les vues matérialisées et déclenche une actualisation complète sur chaque mise à jour.
```
-- 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;
```
Les paramètres nommés sont SQL uniquement : 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 Python code source, continuez à utiliser le champ Configuration avec spark.conf.get(). Consultez les paramètres de référence à l’aide du champ de configuration.

Paramètres de référence à l’aide du champ de configuration

Le champ Configuration d’un pipeline accepte des paires clé-valeur arbitraires qui sont exposées en tant que valeurs de configuration Spark. Il s’agit du mécanisme de paramétrage hérité et continue de fonctionner en même temps que les paramètres de 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 à paramètres nommés.

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

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 des valeurs de configuration dans la section Configuration des paramètres de pipeline ou dans le configuration champ du code JSON du pipeline. Évitez les clés qui entrent en conflit avec les valeurs de configuration du pipeline réservé ou Apache Spark.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-06-01