Was ist eine dynamische Wertreferenz?

Dynamische Wertverweise beschreiben eine Sammlung von Variablen, die beim Konfigurieren von Aufträgen und Aufgaben verfügbar sind. Verwenden Sie dynamische Wertverweise, um bedingte Anweisungen für Vorgänge zu konfigurieren oder Informationen als Parameter oder Argumente zu übergeben.

Dynamische Wertverweise enthalten Informationen wie:

• Konfigurierte Werte für den Auftrag, einschließlich Auftragsname, Aufgabennamen und Triggertyp.
• Generierte Metadaten über den Auftrag, einschließlich der Auftragskennung, der Laufkennung und der Startzeit des Auftragslaufs.
• Informationen darüber, wie viele Reparaturversuche ein Auftrag unternommen hat oder wie viele Wiederholungsversuche für eine Aufgabe durchgeführt wurden.
• Der Ergebnisstatus für einen angegebenen Vorgang.
• Werte, die mithilfe von Auftragsparametern, Vorgangsparametern oder Vorgangswerten konfiguriert wurden.

Dynamische Wertverweise verwenden

Verwenden Sie dynamische Wertverweise beim Konfigurieren von Aufträgen oder Aufgaben. Sie können nicht direkt auf dynamische Wertverweise von Ressourcen verweisen, die mit Aufgaben wie Notebooks, Abfragen oder JARs konfiguriert sind. Dynamische Wertverweise müssen mit Hilfe von Parametern oder Feldern definiert werden, die den Kontext an die Aufgaben weitergeben.

Dynamische Wertverweise verwenden doppelte geschweifte Klammern ({{ }}). Wenn ein Auftrag oder eine Aufgabe ausgeführt wird, ersetzt ein Zeichenfolgenliteral den dynamischen Wertverweis. Wenn Sie beispielsweise das folgende Schlüssel-Wert-Paar als Aufgabenparameter konfigurieren:

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

Wenn Ihre Lauf-ID 550315892394120 ist, wird der Wert für job_run_id als job_550315892394120 ausgewertet.

Hinweis

Inhalte in doppelten geschweiften Klammern werden nicht als Ausdrücke ausgewertet. Sie können keine Vorgänge oder Funktionen innerhalb von geschweiften Klammern ausführen.

Vom Benutzer bereitgestellte Wertbezeichner unterstützen alphanumerische Zeichen und Unterstriche. Escapetasten, die Sonderzeichen enthalten, indem sie den Bezeichner mit Backticks (` `) umgeben.

Syntaxfehler, einschließlich nicht vorhandener dynamischer Referenzwerte und fehlender geschweifter Klammern, werden stillschweigend ignoriert und als literale Zeichenfolgen behandelt. Eine Fehlermeldung wird angezeigt, wenn Sie einen ungültigen Verweis angeben, der zu einem bekannten Namespace gehört, z. B. {{job.notebook_url}}.

Verwendung dynamischer Wertverweise in der Benutzeroberfläche von Jobs

Felder, die dynamische Wertreferenzen akzeptieren, bieten eine Abkürzung zum Einfügen verfügbarer dynamischer Wertreferenzen. Klicken Sie auf { }, um diese Liste anzuzeigen und in das angegebene Feld einzufügen.

Hinweis

Die Benutzeroberfläche vervollständigt die Schlüssel nicht automatisch, um auf Aufgabenwerte zu verweisen.

Viele Felder, die dynamische Wertverweise akzeptieren, erfordern zusätzliche Formatierungen, um sie richtig zu verwenden. Weitere Informationen finden Sie unter Konfigurieren von Aufgabenparametern.

Verwendung von dynamischen Wertverweisen in einem Job-JSON

Verwenden Sie die {{ }}-Syntax, um dynamische Werte in den JSON-Definitionen von Databricks CLI und REST API zu verwenden.

Auftrags- und Aufgabenparameter haben eine unterschiedliche Syntax, und die Syntax der Aufgabenparameter variiert je nach Aufgabentyp.

Das folgende Beispiel zeigt die partielle JSON-Syntax zum Konfigurieren von Auftragsparametern mithilfe dynamischer Wertverweise:

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

Das folgende Beispiel zeigt die partielle JSON-Syntax zum Konfigurieren von Notebook-Aufgaben mithilfe dynamischer Wertverweise:

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

Überprüfen von Parametern für eine Auftragsausführung

Nach Abschluss einer Aufgabe können Sie aufgelöste Werte für Parameter unter Parameter auf der Seite „Ausführungsdetails“ anzeigen. Siehe Anzeigen von Details zur Auftragsausführung.

Unterstützte Wertverweise

Die folgenden dynamischen Wertverweise werden unterstützt:

Verweis	Beschreibung
{{job.id}}	Der eindeutige Bezeichner, der einem Auftrag zugewiesen ist.
{{job.name}}	Der Name des Auftrags zum Zeitpunkt der Ausführung des Auftrags.
{{job.run_id}}	Der eindeutige Bezeichner, der der Auftragsausführung zugewiesen ist.
{{job.repair_count}}	Die Anzahl der Reparaturversuche für die aktuelle Auftragsausführung.
{{job.start_time.<argument>}}	Ein Wert basierend auf der Zeit (in UTC-Zeitzone), zu der die Auftragsausführung begonnen hat. Der Rückgabewert basiert auf der argument-Option. Siehe Optionen für Datums- und Uhrzeitwerte.
{{job.parameters.<name>}}	Der Wert des Parameters auf Auftragsebene mit dem Schlüssel <name>.
{{job.trigger.type}}	Der Triggertyp des Auftragsausführung. Die möglichen Werte sind periodic, one_time , run_job_task, file_arrival, continuous, und table.
{{job.trigger.file_arrival.location}}	Wenn ein Dateiankunftstrigger für diesen Auftrag konfiguriert ist, der Wert des Speicherorts.
{{job.trigger.time.<argument>}}	Ein Wert basierend auf dem Zeitpunkt (in UTC-Zeitzone), zu dem der Auftrag ausgelöst wurde, abgerundet auf die nächstgelegene Minute für Aufträge mit einem Cron-Zeitplan. Der Rückgabewert basiert auf der argument-Option. Siehe Optionen für Datums- und Uhrzeitwerte.
{{task.name}}	Der Name der aktuellen Aufgabe.
{{task.run_id}}	Der eindeutige Bezeichner der aktuellen Aufgabenausführung.
{{task.execution_count}}	Die Häufigkeit, mit der die aktuelle Aufgabe ausgeführt wurde (einschließlich Wiederholungen und Reparaturen).
{{task.notebook_path}}	Der Notizbuchpfad der aktuellen Notizbuchaufgabe.
{{tasks.<task_name>.run_id}}	Der eindeutige Bezeichner, der der Aufgabenausführung für <task_name> zugewiesen wurde.
{{tasks.<task_name>.output.catalog_name}}	Der Name des Ausgabekatalogs für eine vorgelagerte Reinraumaufgabe.
{{tasks.<task_name>.output.schema_name}}	Der Name des Ausgabeschemas für eine vorgelagerte Reinraumaufgabe. Dieses Schema speichert alle Ergebnisse des Clean-Room-Vorgangs ab.
{{tasks.<task_name>.result_state}}	Der Ergebniszustand einer Ausführung <task_name>. Die möglichen Werte sind success, failed, excluded, canceled, evicted, timedout, upstream_canceled, upstream_evicted und upstream_failed.
{{tasks.<task_name>.error_code}}	Der Fehlercode für die Aufgabe <task_name>, wenn beim Ausführen der Aufgabe ein Fehler aufgetreten ist. Beispiele für mögliche Werte sind RunExecutionError, ResourceNotFound und UnauthorizedError. Bei erfolgreichen Vorgängen wird dies als leere Zeichenfolge ausgewertet.
{{tasks.<task_name>.execution_count}}	Die Häufigkeit, mit der die Aufgabe <task_name> ausgeführt wurde (einschließlich Wiederholungen und Reparaturen).
{{tasks.<task_name>.notebook_path}}	Der Pfad zum Notizbuch für die Notebookaufgabe <task_name>.
{{tasks.<task_name>.values.<value_name>}}	Der Aufgabenwert mit dem Schlüssel <value_name>, der von Aufgabe <task_name> festgelegt wurde.
{{tasks.<task_name>.output.rows}}	Die Ausgabezeilen eines vorgelagerten SQL-Vorgangs <task_name>. Wenn sie als Eingaben für einen For each Vorgang übergeben wird, wird jede Zeile iterativ an den geschachtelten Vorgang gesendet. Die SQL-Ausgabe ist auf 1.000 Zeilen und eine Größe von 48 KB begrenzt. Siehe SQL-Ausgabeoptionen.
{{tasks.<task_name>.output.first_row}}	Die erste Zeile der Ausgabe eines vorgelagerten SQL-Vorgangs <task_name>. Die SQL-Ausgabe ist auf 1.000 Zeilen und 48 KB Größe begrenzt.
{{tasks.<task_name>.output.first_row.<column_alias>}}	Der Wert der Spalte <column_alias> in der ersten Zeile der Ausgabe eines vorgelagerten SQL-Vorgangs <task_name>. Die SQL-Ausgabe ist auf 1.000 Zeilen und 48 KB Größe begrenzt.
{{tasks.<task_name>.output.alert_state}}	Der Status einer vorgelagerten SQL-Warnungsaufgabe. Der Wert ist einer von UNKNOWN, OK, oder TRIGGERED.
{{workspace.id}}	Der eindeutige Bezeichner, der dem Arbeitsbereich zugewiesen ist.
{{workspace.url}}	Die URL des Arbeitsbereichs.
{{backfill.day}}	Der Tagesteil des Anfangs des Zeitraums für den spezifischen Nachfüllauftrag. Siehe Backfill-Aufträge.
{{backfill.is_weekday}}	Gibt zurück true , wenn der Anfang des Zeitraums für die Ausführung des spezifischen Backfill-Auftrags ein Wochentag ist.
{{backfill.iso_date}}	Das ISO-Datum des Anfangs des Zeitraums für den spezifischen Nachfüllauftragslauf.
{{backfill.iso_datetime}}	Die ISO-Datumszeit des Anfangs des Zeitraums für den spezifischen Nachfüllauftrag.
{{backfill.iso_weekday}}	Gibt eine Ziffer von 1 bis 7 zurück, die den Wochentag des Anfangs des Zeitraums für den spezifischen Nachfüllauftragslauf darstellt.
{{backfill.month}}	Der Monatsteil des Anfangs des Zeitraums für den spezifischen Nachfüllauftragslauf.
{{backfill.timestamp_ms}}	Der Zeitstempel des Beginns des Zeitbereichs für die spezifische Backfill-Auftragsausführung.
{{backfill.year}}	Der Jahresteil des Anfangs des Zeitraums für den spezifischen Nachfüllauftragslauf.

Sie können diese Referenzen bei jeder Aufgabe festlegen. Weitere Informationen finden Sie unter Konfigurieren von Aufgabenparametern. Backfill-Parameter sind nur beim Erstellen eines Backfill-Auftrags verfügbar.

Sie können auch Parameter zwischen Aufgaben in einem Auftrag mithilfe von Aufgabenwerten übergeben. Siehe Verwenden von Aufgabenwerten zur Weitergabe von Informationen zwischen Aufgaben..

Optionen für Datums- und Uhrzeitwerte

Verwenden Sie die folgenden Argumente, um den Rückgabewert aus zeitbasierten Parametervariablen anzugeben. Alle Rückgabewerte basieren auf einem Zeitstempel in der UTC-Zeitzone.

Streitpunkt	Beschreibung
iso_weekday	Gibt eine Ziffer von 1 bis 7 zurück, die den Wochentag des Zeitstempels darstellt.
is_weekday	Gibt true zurück, wenn der Zeitstempel an einem Wochentag liegt.
iso_date	Gibt das Datum im ISO-Format zurück.
iso_datetime	Gibt das Datum und die Uhrzeit im ISO-Format zurück.
year	Gibt den Jahresteil des Zeitstempels zurück.
month	Gibt den Monatsteil des Zeitstempels zurück.
day	Gibt den Tagesteil des Zeitstempels zurück.
hour	Gibt den Stundenteil des Zeitstempels zurück.
minute	Gibt den Minutenteil des Zeitstempels zurück.
second	Gibt den Sekundenteil des Zeitstempels zurück.
timestamp_ms	Gibt den Zeitstempel in Millisekunden zurück.

SQL-Ausgabeoptionen

Sie können mithilfe dynamischer Werte auf die Ausgabe einer vorgelagerten SQL-Aufgabe zugreifen.

Wenn Sie beispielsweise über eine SQL-Aufgabe verfügen, die mit der folgenden SQL aufgerufen wird sales_by_year , wird die Ausgabe basierend auf der endgültigen SELECT Anweisung erstellt.

-- 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;

Sie können auf die Ausgabe in einer nachgeschalteten Aufgabe verweisen, indem Sie eine Aufgabenkonfiguration mithilfe eines {{tasks.<task_name>.output.<argument>}} dynamischen Werts erstellen.

In For each Vorgängen werden die Zeilen iterativ an die geschachtelte Aufgabe gesendet. Wenn Sie in diesem Beispiel die Eingaben einer For each Aufgabe auf {{tasks.sales_by_year.output.rows}} festlegen würden, können Sie in der geschachtelten Aufgabe die Syntax {{input.<column_alias>}} verwenden, um iterativ die Zeilenwerte als Parameter zu senden. In der geschachtelten Aufgabenkonfiguration können Sie zwei Parameter mit den Schlüssel-Wert-Paaren year:{{input.sales_year}}, und sales:{{input.num_sales}}erstellen. Wenn es sich bei der geschachtelten Aufgabe um eine SQL-Aufgabe handelt, können Sie mit einer Abfrage wie der folgenden auf die Werte in Ihrem Code verweisen.

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

Weitere Informationen zu For each Aufgaben und deren geschachtelten Aufgaben finden Sie unter Verwenden einer Aufgabe zum Ausführen einer For each anderen Aufgabe in einer Schleife.

Hinweis

Die SQL-Abfrageausgabe wird 7 Tage lang aufbewahrt. Wenn der Auftrag angehalten wird (z. B. bei einem Fehler) und erst mehr als 7 Tage später fortgesetzt wird, ist die SQL-Abfrageausgabe nicht mehr verfügbar.

Veraltete Verweise auf dynamische Werte

Die folgenden dynamischen Wertverweise sind veraltet. Der empfohlene Ersatzverweis ist in der Beschreibung jeder Variablen enthalten.

Variable	Beschreibung
{{job_id}}	Der eindeutige Bezeichner, der einem Auftrag zugewiesen ist. Verwenden Sie stattdessen job.id.
{{run_id}}	Der eindeutige Bezeichner, der einer Aufgabenausführung zugewiesen wurde. Verwenden Sie stattdessen task.run_id.
{{start_date}}	Das Datum, an dem eine Aufgabenausführung gestartet wird. Das Format ist YYYY-MM-DD in der UTC-Zeitzone. Verwenden Sie stattdessen job.start_time.<argument>.
{{start_time}}	Der Zeitstempel des Ausführungsbeginns, nachdem der Cluster erstellt und bereit ist. Als Format wird die UNIX-Zeit in der UTC-Zeitzone verwendet, wie zurückgegeben durch System.currentTimeMillis(). Verwenden Sie stattdessen job.start_time.<format>.
{{task_retry_count}}	Die Anzahl der Wiederholungen, die unternommen werden, um eine Aufgabe auszuführen, wenn der erste Versuch fehlschlägt. Der Wert lautet beim ersten Versuch 0 und erhöht sich bei jedem weiteren Versuch. Verwenden Sie stattdessen task.execution_count.
{{parent_run_id}}	Der eindeutige Bezeichner, der der Ausführung eines Auftrags mit mehreren Aufgaben zugeordnet ist. Verwenden Sie stattdessen job.run_id.
{{task_key}}	Der eindeutige Name, der einem Vorgang zugeordnet ist, der Teil eines Auftrags mit mehreren Vorgängen ist. Verwenden Sie stattdessen task.name.