Utiliser une table de contrôles pour piloter un For each travail

Lorsque vous effectuez le même traitement sur de nombreuses entrées, telles que des marchés, des tables sources, des clients ou des partitions de dates, le fait de coder cette liste en dur dans votre travail vous oblige à modifier le code et à redéployer chaque fois que la liste change. À la place, stockez la liste dans une table de contrôle que le job lit à l’exécution. Pour ajouter ou retirer du travail, vous mettez à jour une ligne dans la table, et la prochaine exécution du travail reprend le changement sans modifications apportées au travail lui-même. C’est un schéma piloté par les métadonnées : ce sont les données, et non le code, qui contrôlent ce que la tâche traite.

Ce tutoriel construit une tâche qui utilise ce motif sur le jeu de données d’échantillons Wanderbricks préinstallé, afin que vous puissiez l’exécuter de bout en bout sans créer de données sources. Le scénario concerne une plateforme de location de vacances qui exécute la même analyse des prix pour chaque segment de biens (tel que Ski Resort ou Urban Year-Round). Une table de contrôle liste les segments à analyser, une tâche SQL lit cette table, et une For each tâche exécute l’analyse une fois par segment, en parallèle.

Comment fonctionne la tâche de la table de contrôle

Le job enchaîne trois tâches en séquence :

Tâche Type Qu’est-ce que cela fait ?
read_segments SQL Lit la table de contrôle et capture les lignes comme un tableau JSON
process_segments Pour chaque Itère sur le tableau de lignes, lançant la tâche imbriquée une fois par ligne
run_segment_analysis Notebook ou SQL (imbriqué dans For each) S’exécute une fois par ligne, en utilisant les valeurs de cette ligne pour analyser un segment de propriété

Le flux est read_segments → process_segments → run_segment_analysis (une fois par ligne). La sortie de la tâche SQL, un tableau JSON d’objets de ligne, est transmise dans le champ Inputs de la tâche For each via la référence de valeur dynamique {{tasks.read_segments.output.rows}}. La For each tâche transmet ensuite les champs de chaque ligne à la tâche imbriquée sous forme de paramètres, disponibles en tant que {{input.property_type}} et {{input.min_price}}.

Prerequisites

  • Un espace de travail Azure Databricks avec l’autorisation de créer des tâches et des notebooks.
  • Permission de créer des tables dans Unity Catalog, et permission de créer un schéma dans un catalogue (les privilèges USE CATALOG et CREATE SCHEMA) pour contenir la table de contrôle.
  • Un entrepôt SQL pour exécuter les tâches SQL. Si vous n’en avez pas, voir Créer un entrepôt SQL.
  • Le catalogue samples, disponible dans chaque espace de travail où Unity Catalog est activé. Le tutoriel lit depuis samples.wanderbricks.properties, donc il n’y a pas de données sources à configurer.

Étape 1 : Créer la table de contrôle

La table de contrôle constitue la source de référence pour la liste des segments traités par votre travail. Pour changer ce que fait le job, vous mettez à jour ce tableau, pas le job.

Exécutez le SQL suivant dans un notebook Azure Databricks ou dans l’éditeur SQL. La première instruction crée un schéma pour contenir la table de contrôle, et la seconde crée la table avec une ligne par segment de propriété et le prix minimum de listage à inclure dans l’analyse de ce segment :

USE CATALOG <catalog-name>;

CREATE SCHEMA IF NOT EXISTS config;

CREATE OR REPLACE TABLE config.property_segments AS
SELECT * FROM VALUES
  ('Urban Year-Round', 150),
  ('Summer Getaway', 200),
  ('Ski Resort', 250)
AS t(property_type, min_price);

Remplacez <catalog-name> par un catalogue dans lequel vous pouvez créer des schémas, par exemple le catalogue de votre espace de travail. Utilisez le même catalogue partout où le tutoriel fait référence à config.property_segments, y compris la requête de recherche à l’étape 3.

Après cette étape, config.property_segments contient trois lignes, une par segment. Chaque ligne contient les deux valeurs que le travail transmet à chaque itération : le property_type à analyser et la valeur minimale min_price à utiliser pour le filtrage.

Étape 2 : Écrire la logique d’analyse

La tâche imbriquée à l’intérieur de la tâche For each s’exécute une fois par ligne de la table de contrôle, recevant le property_type et le min_price de cette ligne comme paramètres. Vous pouvez écrire cette logique comme une tâche notebook ou SQL. Choisissez en fonction de votre logique métier :

  • Utilisez une tâche de notebook lorsque la logique par itération nécessite du code procédural, plusieurs langages ou des bibliothèques (par exemple, une étape de data science ou d’apprentissage automatique).
  • Utilisez une tâche SQL lorsque la logique est une requête ou une transformation unique que vous pouvez exprimer de manière déclarative. Une tâche SQL nécessite un entrepôt SQL.

Les deux variantes ci-dessous produisent le même résultat : pour le segment en cours de traitement, le nombre d’annonces dont le prix est supérieur ou égal au prix minimal, ainsi que leur prix moyen.

Tâche de notebook

Créez un notebook dans un chemin d’accès tel que /Workspace/Users/<username>/run_segment_analysis. Ce notebook s’exécute une fois pour chaque itération de la tâche For each et reçoit un segment différent à chaque fois.

Ajoutez le code suivant au notebook :

# Set default values so you can run the notebook on its own while developing.
# When the notebook runs inside a For each task, the job overrides these defaults.
dbutils.widgets.text("property_type", "Ski Resort", "Property type")
dbutils.widgets.text("min_price", "250", "Minimum price")

# Read the parameters passed by the For each task.
property_type = dbutils.widgets.get("property_type")
min_price = dbutils.widgets.get("min_price")

result = spark.sql(
    """
    SELECT :property_type AS property_type,
           COUNT(*) AS property_count,
           ROUND(AVG(base_price), 2) AS avg_price
    FROM samples.wanderbricks.properties
    WHERE property_type = :property_type
      AND base_price >= :min_price
    """,
    args={"property_type": property_type, "min_price": min_price},
)
display(result)

Note

Appelez dbutils.widgets.text() avant dbutils.widgets.get(). Si vous appelez get en premier, faire tourner le notebook en dehors d’un job génère une erreur InputWidgetNotDefined.

Tâche SQL

Une tâche SQL exécute une requête enregistrée, donc créez et enregistrez la requête d’analyse dans l’éditeur SQL dès maintenant. Vous l’attachez à la tâche imbriquée lorsque vous configurez la For each tâche à l’étape 4.

  1. Dans votre espace de travail Azure Databricks, cliquez sur Icône plus.Nouveau>Icône de requête.Requête pour ouvrir l’éditeur SQL.

  2. Entrez la requête suivante. Les tâches SQL font référence aux paramètres avec la syntaxe :param_name, donc la requête lit son segment et son plancher de prix à partir des paramètres :property_type et :min_price :

    SELECT :property_type AS property_type,
           COUNT(*) AS property_count,
           ROUND(AVG(base_price), 2) AS avg_price
    FROM samples.wanderbricks.properties
    WHERE property_type = :property_type
      AND base_price >= :min_price;
    
  3. Cliquez sur le titre New Query <date> dans l’en-tête de l’onglet de votre fichier SQL, et donnez-lui le nom run_segment_analysis. Ensuite, cliquez sur Enregistrer pour le déplacer dans un dossier où vous souhaitez le stocker.

La tâche For each transmet les valeurs de chaque itération aux paramètres nommés :property_type et :min_price à l’exécution. Contrairement aux widgets de carnet, les paramètres nommés SQL ne prennent pas en charge les valeurs par défaut : si un paramètre n’est pas passé, la requête échoue avec une erreur de résolution de paramètre.

Étape 3 : Créer la requête de recherche

La tâche de recherche lit la table de contrôle via une requête enregistrée. Comme à l’étape 2, créez et enregistrez maintenant la requête dans l’éditeur SQL, puis associez-la à la tâche de recherche à l’étape 4.

  1. Dans votre espace de travail Azure Databricks, cliquez sur Icône plus.Nouveau>Icône de requête.Requête pour ouvrir l’éditeur SQL.

  2. Entrez ce qui suit, en utilisant le même catalogue que vous avez choisi à l’étape 1 :

    SELECT property_type, min_price FROM <catalog-name>.config.property_segments;
    

    Le nom est entièrement qualifié, car l’entrepôt SQL qui exécute cette requête peut utiliser par défaut un catalogue différent de celui dans lequel vous avez créé la table.

  3. Cliquez sur le titre New Query <date> dans l’en-tête de l’onglet de votre fichier SQL, et donnez-lui le nom read_segments. Ensuite, cliquez sur Enregistrer pour le déplacer dans un dossier où vous souhaitez le stocker.

Étape 4 : Créer et configurer la tâche

Avec les deux requêtes sauvegardées, créez le travail et ajoutez ses deux tâches : la tâche de recherche SQL qui lit la table de contrôle, et la For each tâche qui exécute l’analyse pour chaque ligne.

Créez la tâche

Dans votre espace de travail Azure Databricks, dans la barre latérale, cliquez sur l’icône Plus., puis sur Nouveau>l’icône Workflows.Job. Donnez à la tâche un nom descriptif, comme Segment Analysis.

Configurez la tâche de recherche SQL

Cette tâche lit la table de contrôle et rend ses lignes accessibles à la For each tâche en exécutant la read_segments requête que vous avez enregistrée à l’étape 3.

  1. Cliquez sur la tuile de requête SQL pour configurer la première tâche. Si la vignette Requête SQL n’est pas disponible, cliquez sur Ajouter un autre type de tâche puis recherchez Requête SQL.
  2. Définissez le nom de la tâche sur read_segments.
  3. Si nécessaire, sélectionnez requête SQL dans le menu déroulant Type .
  4. Dans le champ requête SQL , sélectionnez la read_segments requête que vous avez enregistrée à l’étape 3.
  5. Définissez SQL warehouse comme un entrepôt dans votre espace de travail.
  6. Cliquez sur Create task.

Lorsque cette tâche s’exécute, Azure Databricks capture le résultat sous forme de tableau JSON dans tasks.read_segments.output.rows. La sortie de tâche SQL est toujours renvoyée sous forme de tableau JSON, donc vous n’avez pas besoin de configuration supplémentaire. La forme générale de la référence est tasks.<task-name>.output.rows, où <task-name> correspond au nom de la tâche que vous avez définie. Le résultat se présente ainsi :

[
  { "property_type": "Urban Year-Round", "min_price": 150 },
  { "property_type": "Summer Getaway", "min_price": 200 },
  { "property_type": "Ski Resort", "min_price": 250 }
]

Configurer la tâche For each

La For each tâche lit la sortie SQL et lance une tâche imbriquée exécutée par ligne.

  1. Cliquez sur Icône plus.Ajouter une tâche puis sélectionnez Pour chaque.

  2. Définissez le nom de la tâche sur process_segments.

  3. Vérifiez que Dépend de est défini à read_segments.

  4. Dans le champ Inputs, entrez le tableau de lignes capturé par la tâche SQL :

    {{tasks.read_segments.output.rows}}
    
  5. Réglez Concurrency sur 2 pour exécuter deux itérations en parallèle. Augmentez cette valeur lorsque votre tâche imbriquée prend en charge un parallélisme plus élevé.

  6. Pour accomplir cette tâche, cliquez sur Ajouter une tâche sur laquelle boucler et configurez la tâche imbriquée qui s’exécute sur chaque itération.

La For each tâche et sa tâche imbriquée sont créées ensemble comme une seule tâche. Configurez la tâche imbriquée selon le type que vous avez choisi à l’étape 2 :

Tâche de notebook

  1. Définissez le nom de la tâche sur run_segment_analysis.

  2. Définissez Type sur Notebook.

  3. Définissez Chemin sur le notebook que vous avez créé à l’étape 2.

  4. Cliquez sur Paramètres, puis cliquez sur Ajouter pour ajouter chaque paramètre :

    • Clé : property_type, Valeur : {{input.property_type}}
    • Clé : min_price, Valeur : {{input.min_price}}

    Chaque référence {{input.<key>}} est résolue en utilisant le champ correspondant de la ligne de l’itération actuelle.

  5. Cliquez sur Créer une tâche pour créer la For each tâche et sa tâche imbriquée ensemble.

Tâche SQL

Cette tâche exécute la run_segment_analysis requête que vous avez enregistrée à l’étape 2.

  1. Définissez le nom de la tâche sur run_segment_analysis.

  2. Définissez Type sur SQL, puis définissez la tâche SQL sur Requête.

  3. Dans le champ de requête SQL , sélectionnez la run_segment_analysis requête que vous avez enregistrée à l’étape 2.

  4. Définissez SQL warehouse comme un entrepôt dans votre espace de travail.

  5. Cliquez sur Paramètres, puis cliquez sur Ajouter pour ajouter chaque paramètre :

    • Clé : property_type, Valeur : {{input.property_type}}
    • Clé : min_price, Valeur : {{input.min_price}}

    Chaque référence {{input.<key>}} est résolue en utilisant le champ correspondant de la ligne de l’itération actuelle.

  6. Cliquez sur Créer une tâche pour créer la For each tâche et sa tâche imbriquée ensemble.

Votre graphe de tâches affiche désormais read_segments menant à process_segments, avec la tâche imbriquée à l’intérieur du nœud For each.

Étape 5 : Exécutez la tâche et vérifiez

  1. Cliquez sur Exécuter maintenant pour déclencher le travail.
  2. Sélectionnez l’onglet Exécutions pour afficher l’exécution. La première exécution d’un travail prend quelques minutes pour commencer le calcul ; Une fois terminé, il apparaît dans la liste.
  3. Cliquez sur le nœud process_segments pour développer la tâche For each.
  4. La page d’exécution montre un tableau d’itérations, une ligne par segment, chacune avec son statut, son heure de début et sa durée.
  5. Cliquez sur n’importe quelle ligne d’itération pour ouvrir sa sortie et confirmer qu’elle a analysé le segment attendu.

Vous pouvez voir les résultats de chaque itération indépendamment. Si une itération spécifique échoue, vous pouvez relancer uniquement cette itération depuis la page d’exécution de la tâche sans relancer toute la tâche.

Étendre le modèle

Pour ajouter un segment à l’analyse, insérez une ligne dans la table de contrôle :

INSERT INTO <catalog-name>.config.property_segments VALUES ('Historical Place', 100);

La prochaine exécution du travail inclut le nouveau segment, sans aucun changement de configuration du travail ni modification du notebook.

Ce même schéma fonctionne dans tous les cas où vous souhaitez que les données pilotent l’itération :

  • Traitement par client : une ligne par ID client. La tâche imbriquée applique des transformations spécifiques au client ou livre à des destinations spécifiques à chaque client.
  • Ingestion de table : une ligne par nom de table source. La tâche imbriquée lit et ingère chaque table.
  • Traitement de renvoi : une ligne pour chaque partition de date. La tâche imbriquée retraite à nouveau les données historiques de cette partition.
  • Exécution pilotée par indicateur de fonctionnalité : une ligne par fonctionnalité ou expérience activée. La tâche imbriquée active la logique correspondante.

Pour arrêter de traiter une ligne sans la supprimer, ajoutez votre propre colonne à la table de contrôle (comme un active drapeau) et filtrez dessus dans la tâche de recherche SQL. Il s’agit d’une colonne ordinaire que vous définissez et renseignez. La tâche For each n’en a aucune notion intégrée. Commencez par ajouter la colonne, puis définissez les lignes existantes sur TRUE :

ALTER TABLE <catalog-name>.config.property_segments ADD COLUMN active BOOLEAN;
UPDATE <catalog-name>.config.property_segments SET active = TRUE;

Ensuite, filtrez dessus dans la read_segments requête pour que seules les lignes actives guident l’itération :

SELECT property_type, min_price FROM <catalog-name>.config.property_segments WHERE active = TRUE;

Ressources supplémentaires