Vad är en referens för dynamiskt värde?

Referenser till dynamiskt värde beskriver en samling variabler som är tillgängliga när jobb och uppgifter konfigureras. Använd referenser för dynamiskt värde för att konfigurera villkorsstyrda instruktioner för aktiviteter eller för att skicka information som parametrar eller argument.

Referenser till dynamiskt värde innehåller information som:

• Konfigurerade värden för jobbet, inklusive jobbnamn, uppgiftsnamn och utlösartyp.
• Genererade metadata om jobbet, inklusive jobb-ID, körnings-ID och starttid för jobbkörningen.
• Information om hur många reparationsförsök ett jobb har gjort eller hur många gånger en uppgift har körts om.
• Resultattillståndet för en angiven aktivitet.
• Värden som konfigurerats med hjälp av jobbparametrar, aktivitetsparametrar eller som anges med hjälp av aktivitetsvärden.

Använda referenser för dynamiskt värde

Använd referenser för dynamiskt värde när du konfigurerar jobb eller uppgifter. Du kan inte direkt referera till dynamiska värdereferenser från tillgångar som konfigurerats med hjälp av uppgifter som notebook-filer, frågor eller JAR:er. Referenser för dynamiskt värde måste definieras med hjälp av parametrar eller fält som skickar kontexten till aktiviteter.

Dynamiska värdereferenser använder dubbla klammerparenteser ({{ }}). När ett jobb eller en aktivitet körs ersätter en strängliteral referensen för det dynamiska värdet. Om du till exempel konfigurerar följande nyckel/värde-par som en aktivitetsparameter:

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

Om ditt körnings-ID är 550315892394120, utvärderas värdet för job_run_id till job_550315892394120.

Anmärkning

Innehållet i de dubbla klammerparenteserna utvärderas inte som uttryck. Du kan inte använda åtgärder eller funktioner i dubbla klammerparenteser.

Värdeidentifierare som tillhandahålls av användaren stöder alfanumeriska tecken och understreckstecken. Escape-nycklar som innehåller specialtecken genom att omge identifieraren med backticks (` `).

Syntaxfel, inklusive icke-existerande dynamiska referensvärden och saknade klammerparenteser, ignoreras utan varning och behandlas som bokstavliga strängar. Ett felmeddelande visas om du anger en ogiltig referens som tillhör ett känt namnområde, till exempel {{job.notebook_url}}.

Använda referenser för dynamiskt värde i jobbgränssnittet

Fält som accepterar referenser för dynamiskt värde ger en genväg för att infoga tillgängliga referenser för dynamiskt värde. Klicka på { } för att se den här listan och infoga den i det angivna fältet.

Anmärkning

Användargränssnittet fyller inte automatiskt i nycklarna för att hänvisa till aktivitetsvärden.

Många fält som accepterar referenser för dynamiskt värde kräver ytterligare formatering för att använda dem korrekt. Se Konfigurera aktivitetsparametrar.

Använd referenser för dynamiska värden i ett jobb-JSON

Använd {{ }} syntax för att använda dynamiska värden i JSON-jobbdefinitioner som används av Databricks CLI och REST API.

Jobb- och aktivitetsparametrar har olika syntax, och syntaxen för aktivitetsparametern varierar beroende på aktivitetstyp.

I följande exempel visas den partiella JSON-syntaxen för att konfigurera jobbparametrar med hjälp av referenser för dynamiskt värde:

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

I följande exempel visas den partiella JSON-syntaxen för att konfigurera notebook-uppgiftsparametrar med hjälp av en referens för dynamiskt värde:

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

Granska parametrar för en jobbkörning

När en uppgift har slutförts kan du se lösta parametervärden under Parametrar på sidan med körningsinformation. Se Visa detaljer om jobbkörning.

Värdereferenser som stöds

Följande referenser för dynamiskt värde stöds:

Hänvisning	Beskrivning
{{job.id}}	Den unika identifierare som tilldelats jobbet.
{{job.name}}	Namnet på jobbet vid tidpunkten för jobbkörningen.
{{job.run_id}}	Den unika identifieraren som tilldelats jobbkörningen.
{{job.repair_count}}	Antalet reparationsförsök på den aktuella jobbkörningen.
{{job.start_time.<argument>}}	Ett värde baserat på den tid (i UTC-tidszonen) som jobbkörningen startade. Returvärdet baseras på argument alternativet . Se Alternativ för datum- och tidsvärden.
{{job.parameters.<name>}}	Värdet för jobbnivåparametern med nyckeln <name>.
{{job.trigger.type}}	Utlösartypen för jobbkörningen. Möjliga värden är periodic, one_time, run_job_task, file_arrival, continuousoch table.
{{job.trigger.file_arrival.location}}	Om en utlösare för filinleverans har konfigurerats för den här tjänsten, lagringsplatsens värde.
{{job.trigger.time.<argument>}}	Ett värde baserat på den tid (i UTC-tidszonen) jobbexekveringen utlöstes, avrundas nedåt till närmaste minut för jobb som använder ett cron-schema. Returvärdet baseras på argument alternativet . Se Alternativ för datum- och tidsvärden.
{{task.name}}	Namnet på den aktuella aktiviteten.
{{task.run_id}}	Den unika identifieraren för den aktuella aktivitetskörningen.
{{task.execution_count}}	Antalet gånger som den aktuella aktiviteten kördes (inklusive återförsök och reparationer).
{{task.notebook_path}}	Notebook-sökvägen för den aktuella notebook-uppgiften.
{{tasks.<task_name>.run_id}}	Den unika identifieraren som tilldelats aktivitetskörningen för <task_name>.
{{tasks.<task_name>.result_state}}	Resultattillståndet för uppgiften <task_name>. Möjliga värden är success, failed, excluded, canceled, evicted, timedout, upstream_canceled, upstream_evictedoch upstream_failed.
{{tasks.<task_name>.error_code}}	Felkoden för aktiviteten <task_name> om ett fel uppstod när aktiviteten kördes. Exempel på möjliga värden är RunExecutionError, ResourceNotFoundoch UnauthorizedError. För lyckade uppgifter resulterar detta i en tom sträng.
{{tasks.<task_name>.execution_count}}	Antalet gånger aktiviteten <task_name> kördes (inklusive återförsök och reparationer).
{{tasks.<task_name>.notebook_path}}	Sökvägen till notebook-filen för notebook-uppgiften <task_name>.
{{tasks.<task_name>.values.<value_name>}}	Värdet för uppgiften med nyckeln <value_name> som angavs av uppgiften <task_name>.
{{tasks.<task_name>.output.rows}}	Utdataraderna för en överordnad SQL-uppgift <task_name>. Om den skickas som indata för en For each aktivitet skickas varje rad iterativt till den kapslade aktiviteten. SQL-utdata är begränsade till 1 000 rader och 48 KB i storlek. Se SQL-utdataalternativ.
{{tasks.<task_name>.output.first_row}}	Den första raden i utdata från en överordnad SQL-uppgift <task_name>. SQL-utdata är begränsade till 1 000 rader och 48 KB i storlek.
{{tasks.<task_name>.output.first_row.<column_alias>}}	Värdet för kolumnen <column_alias> på den första raden i utdata från en överordnad SQL-uppgift <task_name>. SQL-utdata är begränsade till 1 000 rader och 48 KB i storlek.
{{tasks.<task_name>.output.alert_state}}	Tillståndet för en uppströms SQL-aviseringsaktivitet. Värdet är ett av UNKNOWN, OKeller TRIGGERED.
{{workspace.id}}	Den unika identifierare som tilldelats arbetsytan.
{{workspace.url}}	URL:en för arbetsytan.

Du kan ange dessa referenser med valfri uppgift. Se Konfigurera aktivitetsparametrar.

Du kan också skicka parametrar mellan aktiviteter i ett jobb med aktivitetsvärden. Se Använd aktivitetsvärden för att skicka information mellan aktiviteter.

Alternativ för datum- och tidsvärden

Använd följande argument för att ange returvärdet från tidsbaserade parametervariabler. Alla returvärden baseras på en tidsstämpel i UTC-tidszonen.

Argumentation	Beskrivning
iso_weekday	Returnerar en siffra från 1 till 7 som representerar tidsstämpelns dag i veckan.
is_weekday	Returnerar true om tidsstämpeln är på en veckodag.
iso_date	Returnerar datumet i ISO-format.
iso_datetime	Returnerar datum och tid i ISO-format.
year	Returnerar årsdelen av tidsstämpeln.
month	Returnerar månadsdelen av tidsstämpeln.
day	Returnerar dagdelen av tidsstämpeln.
hour	Returnerar timdelen av tidsstämpeln.
minute	Returnerar minutdelen av tidsstämpeln.
second	Returnerar den andra delen av tidsstämpeln.
timestamp_ms	Returnerar tidsstämpeln i millisekunder.

SQL-utdataalternativ

Du kan komma åt utdata från en överordnad SQL-uppgift med hjälp av dynamiska värden.

Om du till exempel har en SQL-uppgift som anropas sales_by_year med följande SQL skapar den utdata baserat på den slutliga SELECT instruktionen.

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

Du kan referera till utdata i en nedströmsaktivitet genom att skapa en aktivitetskonfiguration med ett {{tasks.<task_name>.output.<argument>}} dynamiskt värde.

I For each uppgifter skickas raderna iterativt till den kapslade uppgiften. Om du i det här exemplet skulle ange indata för en For each aktivitet till {{tasks.sales_by_year.output.rows}}, kan du i den kapslade aktiviteten använda syntaxen {{input.<column_alias>}} för att iterativt skicka radvärdena som parametrar. I den kapslade uppgiftskonfigurationen kan du skapa två parametrar med nyckel/värde-paren year:{{input.sales_year}}, och sales:{{input.num_sales}}. Förutsatt att den kapslade aktiviteten är en SQL-uppgift kan du referera till värdena i koden med en fråga som följande.

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

Mer information om For each aktiviteter och deras kapslade aktiviteter finns i Använd en For each aktivitet för att köra en annan uppgift i en loop.

Anmärkning

SQL-frågeutdata behålls i 7 dagar. Om jobbet pausas (till exempel vid fel) och sedan återupptas mer än 7 dagar senare kommer SQL-frågeutdata inte att vara tillgängliga.

Inaktuella referenser för dynamiskt värde

Följande dynamiska värdereferenser är inaktuella. Den rekommenderade ersättningsreferensen ingår i beskrivningen av varje variabel.

Variabel	Beskrivning
{{job_id}}	Den unika identifierare som tilldelats ett jobb. Använd job.id i stället.
{{run_id}}	Den unika identifierare som tilldelats en aktivitetskörning. Använd task.run_id i stället.
{{start_date}}	Datumet då en aktivitetskörning startade. Formatet är åå-MM-dd i UTC-tidszonen. Använd job.start_time.<argument> i stället.
{{start_time}}	Tidsstämpeln för körningens start efter att klustret har skapats och är klart. Formatet, som returneras av System.currentTimeMillis(), är millisekunder sedan UNIX-epoken i UTC-tidszon. Använd job.start_time.<format> i stället.
{{task_retry_count}}	Antalet återförsök som har gjorts för att köra en uppgift om det första försöket misslyckas. Värdet är 0 för det första försöket och ökar med varje nytt försök. Använd task.execution_count i stället.
{{parent_run_id}}	Den unika identifierare som tilldelas körningen av ett jobb som har flera uppgifter. Använd job.run_id i stället.
{{task_key}}	Det unika namn som tilldelats en aktivitet som ingår i ett jobb med flera aktiviteter. Använd task.name i stället.