Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Utiliser une table de contrôles pour piloter un
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 CATALOGetCREATE 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 depuissamples.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.
Dans votre espace de travail Azure Databricks, cliquez sur
Nouveau>
Requête pour ouvrir l’éditeur SQL.
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_typeet: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;Cliquez sur le titre
New Query <date>dans l’en-tête de l’onglet de votre fichier SQL, et donnez-lui le nomrun_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.
Dans votre espace de travail Azure Databricks, cliquez sur
Nouveau>
Requête pour ouvrir l’éditeur SQL.
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.
Cliquez sur le titre
New Query <date>dans l’en-tête de l’onglet de votre fichier SQL, et donnez-lui le nomread_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 , puis sur Nouveau>
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.
- 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.
- Définissez le nom de la tâche sur
read_segments. - Si nécessaire, sélectionnez requête SQL dans le menu déroulant Type .
- Dans le champ requête SQL , sélectionnez la
read_segmentsrequête que vous avez enregistrée à l’étape 3. - Définissez SQL warehouse comme un entrepôt dans votre espace de travail.
- 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.
Cliquez sur
Ajouter une tâche puis sélectionnez Pour chaque.
Définissez le nom de la tâche sur
process_segments.Vérifiez que Dépend de est défini à
read_segments.Dans le champ Inputs, entrez le tableau de lignes capturé par la tâche SQL :
{{tasks.read_segments.output.rows}}Réglez Concurrency sur
2pour 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é.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
Définissez le nom de la tâche sur
run_segment_analysis.Définissez Type sur Notebook.
Définissez Chemin sur le notebook que vous avez créé à l’étape 2.
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.-
Clé :
Cliquez sur Créer une tâche pour créer la
For eachtâ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.
Définissez le nom de la tâche sur
run_segment_analysis.Définissez Type sur SQL, puis définissez la tâche SQL sur Requête.
Dans le champ de requête SQL , sélectionnez la
run_segment_analysisrequête que vous avez enregistrée à l’étape 2.Définissez SQL warehouse comme un entrepôt dans votre espace de travail.
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.-
Clé :
Cliquez sur Créer une tâche pour créer la
For eachtâ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
- Cliquez sur Exécuter maintenant pour déclencher le travail.
- 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.
- Cliquez sur le nœud
process_segmentspour développer la tâcheFor each. - 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.
- 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
-
Utiliser une tâche pour exécuter une
For eachautre tâche dans une boucle : référence complète pour la configurationFor eachdes tâches, y compris les types de paramètres et les options d’accès concurrentiel -
Utiliser une table de recherche pour les tableaux de paramètres volumineux d’une
For eachtâche : comment gérer des tableaux de paramètres volumineux qui dépassent la limite de valeur de tâche de 48 Ko - Accéder aux valeurs des paramètres à partir d’une tâche : toutes les méthodes d’accès aux valeurs de paramètres dans les notebooks, les scripts Python et les tâches SQL
- Jeu de données Wanderbricks : L’échantillon de jeu utilisé dans ce tutoriel