Ajouter des conditions SQL aux déclencheurs de tâches

Utilisez une condition SQL pour vérifier vos données avant qu’une exécution de tâche déclenchée ne commence. Lorsque le déclencheur se déclenche, Azure Databricks exécute une requête SQL sauvegardée sur un entrepôt SQL que vous choisissez. L'exécution ne commence que si le résultat de la requête remplit la condition. Par exemple, exécutez un travail seulement lorsqu’une table en amont a terminé de charger ou qu’un contrôle de qualité des données est passé, sans ajouter une tâche de vérification distincte au travail.

Important

Cette fonctionnalité est en version bêta. Pour l’utiliser, un administrateur d’espace de travail doit activer les conditions SQL pour les déclencheurs depuis la page Previews. Consultez Gérer les préversions d’Azure Databricks.

Requirements

  • Vous devez disposer de l’autorisation `CAN MANAGE` sur le travail pour configurer ses déclencheurs.
  • Vous avez besoin d’une requête sauvegardée qui n’utilise pas de paramètres de requête. Vous devez avoir accès à la requête et pouvoir l’exécuter sur l’entrepôt SQL que vous sélectionnez.
  • L’identité Run as du job doit pouvoir ouvrir la requête sauvegardée, avoir CAN USE sur l’entrepôt SQL, et avoir accès à la lecture de chaque table que la requête lit. La requête de condition s’exécute sous cette identité.

Comment fonctionnent les conditions SQL

Le déclencheur décide quand vérifier. La condition SQL décide si une exécution doit être lancée. Après le déclenchement, Azure Databricks exécute la requête en mode lecture seule. Une exécution ne commence que lorsque le déclencheur et la condition SQL sont satisfaits.

Vous pouvez ajouter une condition SQL à un déclencheur planifié, de mise à jour de table, d’arrivée de fichiers, de mise à jour de modèle ou de fin de tâche. Les déclencheurs continus ne supportent pas les conditions SQL.

Choisissez comment Azure Databricks évalue le résultat de la requête :

Type de condition Valeur de l’API Commence une exécution quand Exigences liées aux requêtes
La requête renvoie des lignes QUERY_RETURNS_ROWS Le résultat contient au moins une ligne. None. Aucune ligne signifie que la condition n’est pas remplie.
Changements de la valeur du résultat RESULT_VALUE_CHANGES Le résultat diffère de la valeur lors du contrôle précédent. Il faut retourner exactement une ligne et une colonne. La valeur doit être de 1 Mio ou moins.

Pour les changements de valeur de résultat, Azure Databricks exécute la requête en arrière-plan juste après que vous ayez sauvegardé le déclencheur et stocke le résultat comme référence. Cette vérification ne lance pas une exécution. Les vérifications ultérieures lancent une exécution lorsque le résultat diffère de la valeur stockée. La modification de la requête, de l’entrepôt SQL ou du type de condition du déclencheur réinitialise la valeur de référence, et Azure Databricks en enregistre une nouvelle de la même manière. Mettre le déclencheur en pause ou modifier d’autres réglages peut aussi le réinitialiser. Modifier le texte de la requête sauvegardée ne la réinitialise pas.

Chaque vérification fonctionne comme suit :

  • Une vérification, y compris le démarrage de l’entrepôt SQL, expire au bout de 5 minutes. Si une vérification expire, aucune exécution ne démarre et le déclencheur effectue une nouvelle vérification lors de sa prochaine évaluation.
  • Un déclencheur exécute au maximum une vérification à la fois. Si le déclencheur doit se déclencher alors qu’une vérification est encore en cours, Azure Databricks ignore cette évaluation au lieu de la mettre en file d’attente.
  • Si la requête contient plus d’une instruction, seul le résultat de la dernière instruction est utilisé.
  • Les conditions SQL ne s’appliquent qu’aux exécutions que le déclencheur lance. Exécutez maintenant et les autres exécutions manuelles ne vérifient pas la condition SQL.

Tip

Pour la requête qui retourne des lignes, assurez-vous que la requête ne renvoie aucune ligne lorsque les données ne sont pas prêtes. Une requête comme SELECT count(*) > 100 FROM main.sales.orders renvoie une ligne même lorsque le nombre est de 100 ou moins, donc la condition est remplie. Filtrez avec WHERE ou HAVING à la place :

SELECT 1
FROM main.sales.orders
WHERE order_date = current_date()
HAVING count(*) > 100

Ajouter une condition SQL à un déclencheur

  1. Dans la barre latérale de l’espace de travail, cliquez sur Jobs & Pipelines, puis ouvrez le job.
  2. Dans Planifications & déclencheurs, cliquez sur Ajouter un déclencheur, ou modifiez un déclencheur existant.
  3. Sélectionnez le type de déclenchement et configurez le déclencheur.
  4. Développez Avancé, puis cliquez sur Ajouter une condition SQL.
  5. Sélectionnez la requête SQL et l’entrepôt de données SQL.
  6. Dans la section Déclencher quand, sélectionnez La requête renvoie des lignes ou La valeur du résultat change.
  7. Cliquez sur Enregistrer.

Tester le déclencheur vérifie que le travail peut utiliser la requête enregistrée. Il confirme que la requête existe, n’est pas dans la corbeille, n’a pas de paramètres, mais il ne lance pas la requête. Pour voir le résultat de la requête, exécutez la requête dans l’éditeur SQL.

Pour supprimer une condition, modifiez le déclencheur, développez Avancé, puis cliquez sur Supprimer la condition SQL.

Configurez avec l’API, la CLI ou les bundles

Posez sql_condition avec sql_query_id, warehouse_id, et trigger_mode. Pour un déclencheur planifié utilisant une expression cron, définissez-la dans le champ schedule. Pour les autres types de déclencheur, définissez-la sur trigger, à côté des paramètres du type de déclencheur. Avec la fonctionnalité Déclencheurs multiples (bêta), définissez-la pour chaque entrée de triggers.

REST API

Enregistrez cette requête sous update-job.json et envoyez-la à POST /api/2.2/jobs/update dans l’API Jobs. Remplacez les identifiants par ceux de votre travail, de votre requête enregistrée et de votre entrepôt SQL.

{
  "job_id": 9001,
  "new_settings": {
    "trigger": {
      "pause_status": "UNPAUSED",
      "table_update": {
        "table_names": ["main.sales.orders"],
        "condition": "ANY_UPDATED"
      },
      "sql_condition": {
        "sql_query_id": "fe25e731-92f2-4838-9fb2-1ca364320a3d",
        "warehouse_id": "5d409943fcd32c6f",
        "trigger_mode": "QUERY_RETURNS_ROWS"
      }
    }
  }
}

CLI

Enregistrez le corps de la requête depuis l’onglet API REST sous le nom update-job.json, puis exécutez :

databricks api post /api/2.2/jobs/update --json @update-job.json

Offres groupées

Pour les bundles d’automatisation déclarative, ajoutez les paramètres suivants à une ressource de travail existante, au même niveau que ses tâches :

resources:
  jobs:
    orders_report:
      trigger:
        pause_status: UNPAUSED
        periodic:
          interval: 1
          unit: DAYS
        sql_condition:
          sql_query_id: fe25e731-92f2-4838-9fb2-1ca364320a3d
          warehouse_id: 5d409943fcd32c6f
          trigger_mode: RESULT_VALUE_CHANGES

Les bundles ne peuvent pas créer de requêtes enregistrées. Créez d’abord la requête dans l’espace de travail, puis faites référence à son ID.

Un sql_condition que vous envoyez à jobs/update remplace l’élément actuel dans son ensemble, donc incluez tous ses champs. Si vous laissez de côté sql_condition, la condition actuelle reste. Pour mettre à jour plusieurs déclencheurs, voir Ajouter plusieurs déclencheurs à une tâche.

Surveiller les vérifications des conditions SQL

  • Pour les déclencheurs planifiés, le statut du déclencheur sur la page du job indique si la dernière vérification de condition SQL a été satisfaite. Cliquez sur Détails d’exécution de la requête pour ouvrir l’instruction dans l’historique de la requête.
  • Pour lire la dernière vérification qui a fonctionné sans erreur, appelez l’API Get Job avec include_trigger_state=true et lisez trigger_state.sql_condition. Le latest_condition_evaluation_satisfied champ indique si cette vérification remplit la condition et latest_condition_evaluation_sql_statement_id identifie son instruction dans l’historique des requêtes. Une vérification ayant échoué ne modifie pas ces champs. Avec plusieurs déclencheurs, lisez trigger_details[].state.sql_condition.
  • Pour chaque exécution qu’une condition SQL a lancée, le champ Lancé dans la liste des exécutions et sur la page des détails de l’exécution affiche une balise SQL . Cliquez dessus, puis cliquez sur Détails d’exécution de la requête pour ouvrir la vérification de cette exécution dans l’historique des requêtes.
  • Si un test échoue pour une raison que vous pouvez corriger, l’erreur apparaît dans le statut du déclencheur sur la page de la tâche. Azure Databricks envoie également l'erreur aux notifications d'échec du travail, y compris les destinataires des emails et les destinations webhook. Vous recevez une notification lorsqu’une condition de fonctionnement commence à échouer, pas une pour chaque vérification ratée. L’erreur reste jusqu’à la prochaine vérification réussie. Voir Ajouter des notifications dans une tâche.

Chaque vérification s’exécute sous forme d’instruction SQL sur votre entrepôt SQL. Pour examiner les vérifications au fil du temps, interrogez la table système d’historique des requêtes pour l’entrepôt.

Troubleshooting

Problème Action
La tâche s’exécute à chaque déclenchement Pour La requête renvoie des lignes, modifiez la requête afin qu’elle ne renvoie aucune ligne lorsque les données ne sont pas prêtes.
La valeur du résultat change ne lance jamais une exécution La valeur de référence correspond au résultat de la requête au moment où vous avez enregistré le déclencheur. Une exécution ne commence qu’après que le résultat de la requête a changé par rapport à cette valeur.
La vérification expire Rendez la requête plus rapide, ou utilisez un entrepôt SQL serverless, qui démarre plus vite.
Ajouter une condition SQL n’apparaît pas Développez Avancé. Si le bouton manque toujours, demandez à un administrateur d’espace de travail d’activer Conditions SQL pour les déclencheurs.

Limitations

  • Chaque déclencheur prend en charge une condition SQL.
  • Les déclencheurs continus ne supportent pas les conditions SQL.
  • Les requêtes de condition s’exécutent uniquement sur des entrepôts SQL, en mode lecture seule.
  • Une vérification, y compris le démarrage de l’entrepôt SQL, expire au bout de 5 minutes.
  • Un déclencheur ne conserve que son dernier test, pas l’historique complet de chaque test. Pour voir les vérifications antérieures, utilisez la balise SQL des exécutions démarrées par la condition, ou l’historique des requêtes.
  • Les vérifications s’exécutent sur votre entrepôt SQL et sont facturées comme utilisation de l’entrepôt SQL. Une vérification peut démarrer un entrepôt arrêté.
  • Les déclencheurs avec des conditions SQL comptent dans la limite de l’espace de travail de 12 000 déclencheurs actifs.