Références de valeurs dynamiques

Les références de valeurs dynamiques décrivent une collection de variables disponibles lors de la configuration des Jobs et des tâches. Utilisez des références de valeur dynamiques pour configurer des instructions conditionnelles pour les tâches ou pour transmettre des informations en tant que paramètres ou arguments.

Les références de valeurs dynamiques incluent des informations telles que :

Valeurs configurées pour le job, y compris le nom du job, les noms des tâches et le type de trigger.
Métadonnées générées concernant le Job, y compris l’ID du Job, l’ID d’exécution et l’heure de start de l’exécution du Job.
Information sur le nombre de tentatives de réparation ou de relances d'une tâche de Job.
L'état du résultat pour une tâche spécifiée.
Valeurs configurées à l'aide de paramètres de Job, de paramètres de tâche ou définies à l'aide de valeurs de tâche.

Pour savoir comment chaque type de tâche récupère les valeurs de paramètre, consultez Accéder aux valeurs de paramètre à partir d'une tâche.

Utiliser les références de valeur dynamiques

Utilisez des références de valeur dynamiques lors de la configuration des Jobs ou des tâches. Vous ne pouvez pas référencer directement les références de valeur dynamiques à partir des assets configurés à l'aide de tâches telles que les Notebooks, les query ou les JAR. Les références de valeur dynamiques doivent être définies à l'aide de paramètres ou de champs qui transmettent le contexte aux tâches.

Les références de valeur dynamique utilisent des doubles accolades ({{ }}). Lorsqu'un Job ou une tâche s'exécute, un littéral de chaîne remplace la référence de valeur dynamique. Par exemple, si vous configurez la paire clé-valeur suivante comme parameter de tâche :

{"job_run_id": "job_{{job.run_id}}"}

Si votre ID d'exécution est 550315892394120, la valeur de job_run_id est évaluée à job_550315892394120.

remarque

Le contenu des doubles accolades n’est pas évalué comme des expressions. Vous ne pouvez pas exécuter d’opérations ou de fonctions dans des doubles accolades.

Les identifiants de valeur fournis par l'utilisateur acceptent les caractères alphanumériques et de soulignement. Échapper les clés qui contiennent des caractères spéciaux en encadrant l'identifiant avec des accents graves (` `).

Les erreurs de syntaxe, y compris les valeurs de référence dynamique inexistantes et les accolades manquantes, sont ignorées silencieusement et traitées comme des chaînes de caractères littérales. Cependant, si vous fournissez une référence qui appartient à un espace de noms connu mais qui n'est pas valide, par exemple, {{job.notebook_url}}, un message d'erreur s'affiche.

Utilisez les références de valeurs dynamiques dans l'interface utilisateur des Jobs.

Les champs qui acceptent les références de valeur dynamique fournissent un raccourci pour insérer les références de valeur dynamique disponibles. Cliquez sur { } pour voir cette liste et l'insérer dans le champ fourni.

remarque

L’interface utilisateur ne complète pas automatiquement les clés pour référencer les valeurs de tâche.

De nombreux champs qui acceptent des références de valeurs dynamiques nécessitent un formatage supplémentaire pour les utiliser correctement. Voir Configurer les paramètres de tâche.

Utilisez des références de valeur dynamique dans un JSON de job

Utilisez la syntaxe {{ }} pour utiliser des valeurs dynamiques dans les définitions JSON de Job utilisées par la CLI Databricks et l'API REST.

Les paramètres de Job et de tâche ont une syntaxe différente, et la syntaxe des paramètres de tâche varie selon le type de tâche.

L’exemple suivant montre la syntaxe JSON partielle pour configurer les paramètres de job à l’aide de références de valeurs dynamiques :

JSON
{
  "parameters": [
    {
      "name": "my_job_id",
      "default": "{{job.id}}"
    },
    {
      "name": "run_date",
      "default": "{{job.start_time.iso_date}}"
    }
  ]
}

L’exemple suivant montre la syntaxe JSON partielle pour configurer les parameters d’une tâche Notebook à l’aide d’une référence de valeur dynamique :

JSON
{
  "notebook_task": {
    "base_parameters": {
      "workspace_id": "workspace_{{workspace.id}}",
      "file_arrival_location": "{{job.trigger.file_arrival.location}}"
    }
  }
}

Examiner les paramètres d'une exécution de job

Une fois la tâche terminée, vous pouvez consulter les valeurs de paramètre résolues sous Paramètres sur la page des détails de l'exécution. Voir les détails d'exécution du Job.

Références de valeurs prises en charge

Les références de valeurs dynamiques suivantes sont prises en charge :

Référence	Description
`{{job.id}}`	L'identifiant unique attribué au Job.
`{{job.name}}`	Nom du Job au moment de son exécution.
`{{job.run_id}}`	L'identifiant unique attribué à l'exécution du Job.
`{{job.repair_count}}`	Le nombre de tentatives de réparation sur l'exécution de job en cours.
`{{job.start_time.<argument>}}`	Une valeur basée sur l'heure (dans le fuseau horaire UTC) à laquelle l'exécution du Job a démarré. La valeur renvoyée est basée sur l'option `argument`. Voir les options pour les valeurs de date et d'heure.
`{{job.parameters.<name>}}`	La valeur du paramètre au niveau du Job avec la clé `<name>`.
`{{job.trigger.type}}`	Le type de Trigger de l'exécution du Job. Les valeurs possibles sont `periodic`, `one_time`, `run_job_task`, `file_arrival`, `continuous`, `table` et `model`.
`{{job.trigger.file_arrival.location}}`	Si un trigger d'arrivée de fichier est configuré pour ce job, la valeur de l'emplacement de stockage.
`{{job.trigger.table_update.updated_tables}}`	Si un table update Trigger est configuré pour ce job, une liste JSON des tables mises à jour depuis la dernière exécution du job au format `<catalog>.<schema>.<table>`.
{{job.trigger.table_update.`<catalog.schema.table>`.commit_timestamp.iso_datetime}}	Si un Trigger de mise à jour de table est configuré pour ce job, le timestamp de commit le plus récent qui a déclenché l'exécution du job. Si une seule table est surveillée, vous pouvez omettre le nom de la table : `{{job.trigger.table_update.commit_timestamp.iso_datetime}}`.
{{job.trigger.table_update.`<catalog.schema.table>`.version}}	Si un trigger de mise à jour de table est configuré pour ce job, la version de commit la plus récente qui a déclenché l'exécution du job. Si une seule table est surveillée, vous pouvez omettre le nom de la table : `{{job.trigger.table_update.version}}`.
`{{job.trigger.model.updates}}`	Si un Trigger de mise à jour de modèle est configuré pour ce job, une liste JSON des mises à jour de modèle depuis la dernière exécution du job. Chaque entrée inclut le nom du modèle. Selon la condition du trigger, les entrées peuvent également inclure le nom de la version et de l'alias.
`{{job.trigger.time.<argument>}}`	Une valeur basée sur l'heure (dans le fuseau horaire UTC) à laquelle l'exécution du job a été déclenchée, arrondie à la minute la plus proche pour les jobs avec un calendrier cron. La valeur renvoyée est basée sur l'option `argument`. Voir les options pour les valeurs de date et d'heure.
`{{task.name}}`	Le nom de la tâche en cours.
`{{task.run_id}}`	L’identifiant unique de l’exécution de tâche actuelle.
`{{task.execution_count}}`	Nombre de fois où la tâche en cours a été exécutée (nouvelles tentatives et réparations comprises).
`{{task.notebook_path}}`	Le chemin du notebook de la tâche de notebook en cours.
`{{tasks.<task_name>.run_id}}`	L'identifiant unique attribué à l'exécution de la tâche pour `<task_name>`.
`{{tasks.<task_name>.output.catalog_name}}`	Le nom du catalogue de sortie pour une tâche de salle blanche en amont.
`{{tasks.<task_name>.output.schema_name}}`	Le nom du schéma de sortie pour une tâche de salle blanche en amont. Ce schéma stocke toutes les sorties de l'exécution de la tâche de salle blanche.
`{{tasks.<task_name>.result_state}}`	Le résultat de la tâche « `<task_name>` ». Les valeurs possibles sont `success`, `failed`, `excluded`, `canceled`, `evicted`, `timedout`, `upstream_canceled`, `upstream_evicted` et `upstream_failed`.
`{{tasks.<task_name>.error_code}}`	Le code d'erreur pour la tâche `<task_name>` si une erreur est survenue lors de l'exécution de la tâche. Des exemples de valeurs possibles sont `RunExecutionError`, `ResourceNotFound` et `UnauthorizedError`. Pour les tâches réussies, cela donne une chaîne vide.
`{{tasks.<task_name>.execution_count}}`	Le nombre de fois où la tâche `<task_name>` a été exécutée (y compris les nouvelles tentatives et les réparations).
`{{tasks.<task_name>.notebook_path}}`	Le chemin du Notebook pour la tâche de Notebook `<task_name>`.
`{{tasks.<task_name>.values.<value_name>}}`	La valeur de la tâche avec la clé `<value_name>` qui a été définie par la tâche `<task_name>`.
`{{tasks.<task_name>.output.rows}}`	Les lignes de sortie d’une tâche SQL en amont `<task_name>`. Si elles sont passées comme entrées pour une tâche `For each`, chaque ligne est envoyée itérativement à la tâche imbriquée. La sortie SQL est limitée à 1 000 lignes et à une taille de 48 Ko. Consultez les options de sortie SQL.
`{{tasks.<task_name>.output.first_row}}`	La première ligne de la sortie d'une tâche SQL en amont `<task_name>`. La sortie SQL est limitée à 1 000 lignes et 48 Ko.
`{{tasks.<task_name>.output.first_row.<column_alias>}}`	La valeur de la colonne `<column_alias>` dans la première ligne de la sortie d'une tâche SQL en amont `<task_name>`. La sortie SQL est limitée à 1 000 lignes et 48 Ko.
`{{tasks.<task_name>.output.alert_state}}`	L'état d'une tâche d'alerte SQL en amont. La valeur est l'une des suivantes : `UNKNOWN`, `OK` ou `TRIGGERED`.
`{{workspace.id}}`	L'identifiant unique attribué au Workspace.
`{{workspace.url}}`	L'URL du Workspace.
`{{backfill.day}}`	La partie jour du start de la plage horaire pour l'exécution spécifique du Job de rattrapage. Voir les jobs de backfill.
`{{backfill.is_weekday}}`	Retourne `true` si le start de la plage horaire pour l'exécution du Job de remplissage spécifique est un jour de semaine.
`{{backfill.iso_date}}`	La date ISO du start de la plage de temps pour l'exécution spécifique du Job de remplissage.
`{{backfill.iso_datetime}}`	La date et l'heure ISO du start de la plage horaire pour l'exécution du Job de remplissage spécifique.
`{{backfill.iso_weekday}}`	Renvoie un chiffre de 1 à 7, représentant le jour de la semaine du start de la plage horaire pour l'exécution du Job de remplissage spécifique.
`{{backfill.month}}`	La partie mois du start de la plage horaire pour l'exécution de job de remplissage spécifique.
`{{backfill.timestamp_ms}}`	Le timestamp du start de la plage horaire pour l'exécution du Job de remplissage spécifique.
`{{backfill.year}}`	La partie année du start de la plage horaire pour l'exécution du Job de remplissage spécifique.

Référence	Description
`{{job.id}}`	L'identifiant unique attribué au Job.
`{{job.name}}`	Nom du Job au moment de son exécution.
`{{job.run_id}}`	L'identifiant unique attribué à l'exécution du Job.
`{{job.repair_count}}`	Le nombre de tentatives de réparation sur l'exécution de job en cours.
`{{job.start_time.<argument>}}`	Une valeur basée sur l'heure (dans le fuseau horaire UTC) à laquelle l'exécution du Job a démarré. La valeur renvoyée est basée sur l'option `argument`. Voir les options pour les valeurs de date et d'heure.
`{{job.parameters.<name>}}`	La valeur du paramètre au niveau du Job avec la clé `<name>`.
`{{job.trigger.type}}`	Le type de Trigger de l'exécution du Job. Les valeurs possibles sont `periodic`, `one_time`, `run_job_task`, `file_arrival`, `continuous`, `table` et `model`.
`{{job.trigger.file_arrival.location}}`	Si un trigger d'arrivée de fichier est configuré pour ce job, la valeur de l'emplacement de stockage.
`{{job.trigger.table_update.updated_tables}}`	Si un table update Trigger est configuré pour ce job, une liste JSON des tables mises à jour depuis la dernière exécution du job au format `<catalog>.<schema>.<table>`.
{{job.trigger.table_update.`<catalog.schema.table>`.commit_timestamp.iso_datetime}}	Si un Trigger de mise à jour de table est configuré pour ce job, le timestamp de commit le plus récent qui a déclenché l'exécution du job. Si une seule table est surveillée, vous pouvez omettre le nom de la table : `{{job.trigger.table_update.commit_timestamp.iso_datetime}}`.
{{job.trigger.table_update.`<catalog.schema.table>`.version}}	Si un trigger de mise à jour de table est configuré pour ce job, la version de commit la plus récente qui a déclenché l'exécution du job. Si une seule table est surveillée, vous pouvez omettre le nom de la table : `{{job.trigger.table_update.version}}`.
`{{job.trigger.model.updates}}`	Si un Trigger de mise à jour de modèle est configuré pour ce job, une liste JSON des mises à jour de modèle depuis la dernière exécution du job. Chaque entrée inclut le nom du modèle. Selon la condition du trigger, les entrées peuvent également inclure le nom de la version et de l'alias.
`{{job.trigger.time.<argument>}}`	Une valeur basée sur l'heure (dans le fuseau horaire UTC) à laquelle l'exécution du job a été déclenchée, arrondie à la minute la plus proche pour les jobs avec un calendrier cron. La valeur renvoyée est basée sur l'option `argument`. Voir les options pour les valeurs de date et d'heure.
`{{task.name}}`	Le nom de la tâche en cours.
`{{task.run_id}}`	L’identifiant unique de l’exécution de tâche actuelle.
`{{task.execution_count}}`	Nombre de fois où la tâche en cours a été exécutée (nouvelles tentatives et réparations comprises).
`{{task.notebook_path}}`	Le chemin du notebook de la tâche de notebook en cours.
`{{tasks.<task_name>.run_id}}`	L'identifiant unique attribué à l'exécution de la tâche pour `<task_name>`.
`{{tasks.<task_name>.output.catalog_name}}`	Le nom du catalogue de sortie pour une tâche de salle blanche en amont.
`{{tasks.<task_name>.output.schema_name}}`	Le nom du schéma de sortie pour une tâche de salle blanche en amont. Ce schéma stocke toutes les sorties de l'exécution de la tâche de salle blanche.
`{{tasks.<task_name>.result_state}}`	Le résultat de la tâche « `<task_name>` ». Les valeurs possibles sont `success`, `failed`, `excluded`, `canceled`, `evicted`, `timedout`, `upstream_canceled`, `upstream_evicted` et `upstream_failed`.
`{{tasks.<task_name>.error_code}}`	Le code d'erreur pour la tâche `<task_name>` si une erreur est survenue lors de l'exécution de la tâche. Des exemples de valeurs possibles sont `RunExecutionError`, `ResourceNotFound` et `UnauthorizedError`. Pour les tâches réussies, cela donne une chaîne vide.
`{{tasks.<task_name>.execution_count}}`	Le nombre de fois où la tâche `<task_name>` a été exécutée (y compris les nouvelles tentatives et les réparations).
`{{tasks.<task_name>.notebook_path}}`	Le chemin du Notebook pour la tâche de Notebook `<task_name>`.
`{{tasks.<task_name>.values.<value_name>}}`	La valeur de la tâche avec la clé `<value_name>` qui a été définie par la tâche `<task_name>`.
`{{tasks.<task_name>.output.rows}}`	Les lignes de sortie d’une tâche SQL en amont `<task_name>`. Si elles sont passées comme entrées pour une tâche `For each`, chaque ligne est envoyée itérativement à la tâche imbriquée. La sortie SQL est limitée à 1 000 lignes et à une taille de 48 Ko. Consultez les options de sortie SQL.
`{{tasks.<task_name>.output.first_row}}`	La première ligne de la sortie d'une tâche SQL en amont `<task_name>`. La sortie SQL est limitée à 1 000 lignes et 48 Ko.
`{{tasks.<task_name>.output.first_row.<column_alias>}}`	La valeur de la colonne `<column_alias>` dans la première ligne de la sortie d'une tâche SQL en amont `<task_name>`. La sortie SQL est limitée à 1 000 lignes et 48 Ko.
`{{tasks.<task_name>.output.alert_state}}`	L'état d'une tâche d'alerte SQL en amont. La valeur est l'une des suivantes : `UNKNOWN`, `OK` ou `TRIGGERED`.
`{{workspace.id}}`	L'identifiant unique attribué au Workspace.
`{{workspace.url}}`	L'URL du Workspace.
`{{backfill.day}}`	La partie jour du start de la plage horaire pour l'exécution spécifique du Job de rattrapage. Voir les jobs de backfill.
`{{backfill.is_weekday}}`	Retourne `true` si le start de la plage horaire pour l'exécution du Job de remplissage spécifique est un jour de semaine.
`{{backfill.iso_date}}`	La date ISO du start de la plage de temps pour l'exécution spécifique du Job de remplissage.
`{{backfill.iso_datetime}}`	La date et l'heure ISO du start de la plage horaire pour l'exécution du Job de remplissage spécifique.
`{{backfill.iso_weekday}}`	Renvoie un chiffre de 1 à 7, représentant le jour de la semaine du start de la plage horaire pour l'exécution du Job de remplissage spécifique.
`{{backfill.month}}`	La partie mois du start de la plage horaire pour l'exécution de job de remplissage spécifique.
`{{backfill.timestamp_ms}}`	Le timestamp du start de la plage horaire pour l'exécution du Job de remplissage spécifique.
`{{backfill.year}}`	La partie année du start de la plage horaire pour l'exécution du Job de remplissage spécifique.

Vous pouvez définir ces références avec n'importe quelle tâche. Consultez Configurer les paramètres de tâche. Les paramètres de remplissage ne sont disponibles que lors de la création d'un Job de remplissage.

Vous pouvez également transmettre des paramètres entre les tâches d'un Job avec des valeurs de tâche . Consultez Utiliser les valeurs de tâche pour transmettre des informations entre les tâches.

Options pour les valeurs de date et d'heure

Utilisez les arguments suivants pour spécifier la valeur de retour des variables de paramètre basées sur le temps. Toutes les valeurs de retour sont basées sur un timestamp dans le fuseau horaire UTC.

Argument	Description
`iso_weekday`	Renvoie un chiffre de 1 à 7, représentant le jour de la semaine du Timestamp.
`is_weekday`	Renvoie `true` si le Timestamp est un jour de semaine.
`iso_date`	Renvoie la date au format ISO.
`iso_datetime`	Retourne la date et l’heure au format ISO.
`year`	Renvoie la partie année du Timestamp.
`month`	Renvoie la partie mois du timestamp.
`day`	Renvoie la partie jour du Timestamp.
`hour`	Renvoie la partie heure du timestamp.
`minute`	Renvoie la partie minutes de l'Timestamp.
`second`	Renvoie la seconde partie du timestamp.
`timestamp_ms`	Renvoie le timestamp en millisecondes.

Argument	Description
`iso_weekday`	Renvoie un chiffre de 1 à 7, représentant le jour de la semaine du Timestamp.
`is_weekday`	Renvoie `true` si le Timestamp est un jour de semaine.
`iso_date`	Renvoie la date au format ISO.
`iso_datetime`	Retourne la date et l’heure au format ISO.
`year`	Renvoie la partie année du Timestamp.
`month`	Renvoie la partie mois du timestamp.
`day`	Renvoie la partie jour du Timestamp.
`hour`	Renvoie la partie heure du timestamp.
`minute`	Renvoie la partie minutes de l'Timestamp.
`second`	Renvoie la seconde partie du timestamp.
`timestamp_ms`	Renvoie le timestamp en millisecondes.

Options de sortie SQL

Vous pouvez accéder à la sortie d'une tâche SQL en amont à l'aide de valeurs dynamiques.

Par exemple, si vous avez une tâche SQL appelée sales_by_year avec le SQL suivant, elle génère une sortie basée sur la dernière instruction SELECT.

SQL
-- Generate example data
CREATE OR REPLACE TEMP VIEW example_sales AS
SELECT * FROM VALUES
  (2020, 12),
  (2021, 23),
  (2022, 47),
  (2023, 15),
  (2024, 22)
AS example_sales(sales_year, num_sales);

-- Query example data
SELECT sales_year, num_sales FROM example_sales;

Vous pouvez référencer la sortie dans une tâche en aval en créant une configuration de tâche à l'aide d'une valeur dynamique {{tasks.<task_name>.output.<argument>}}.

Dans les tâches For each, les lignes sont envoyées de manière itérative à la tâche imbriquée. Dans cet exemple, si vous définissiez les Inputs d'une tâche For each sur {{tasks.sales_by_year.output.rows}}, vous pourriez alors, dans la tâche imbriquée, utiliser la syntaxe {{input.<column_alias>}} pour envoyer itérativement les valeurs de ligne comme parameters. Dans la configuration de la tâche imbriquée, vous pouvez créer deux parameters avec les paires clé-valeur year:{{input.sales_year}} et sales:{{input.num_sales}}. En supposant que la tâche imbriquée soit une tâche SQL, vous pourriez référencer les valeurs de votre code avec une query telle que la suivante.

SQL
-- Example: access data from previous query:
SELECT concat('In ', :year, ' we had ', :sales, ' sales.')

Pour plus d'information sur les tâches For each et leurs tâches imbriquées, voir Utiliser une tâche For each pour exécuter une autre tâche en boucle.

remarque

Le résultat de la query SQL est conservé pendant 7 jours. Si le Job est mis en pause (par exemple, en cas d'échec), puis reprise plus de 7 jours plus tard, la sortie de la requête SQL n'est pas disponible.