O que é uma referência de valor dinâmico?

As referências de valores dinâmicos descrevem um conjunto de variáveis disponíveis ao configurar o Job e a tarefa. Use referências de valores dinâmicos para configurar instruções condicionais para a tarefa ou para passar informações como parâmetros ou argumentos.

As referências de valores dinâmicos incluem informações como

• Valores configurados para o trabalho, incluindo o nome do trabalho, os nomes das tarefas e o tipo de acionador.
• Metadados gerados sobre o trabalho, incluindo o ID do trabalho, o ID de execução e o horário de início da execução do trabalho.
• informações sobre quantas tentativas de reparo um trabalho fez ou quantas tentativas de execução de uma tarefa foram feitas.
• O estado do resultado de uma tarefa especificada.
• Valores configurados usando parâmetros de trabalho, parâmetros de tarefa ou definidos usando valores de tarefa.

Use referências de valores dinâmicos

Use referências de valores dinâmicos ao configurar o Job ou a tarefa. O senhor não pode fazer referência direta a referências de valores dinâmicos do ativo configurado usando tarefas como Notebook, consultas ou JARs. As referências de valores dinâmicos devem ser definidas usando parâmetros ou campos que passam o contexto para a tarefa.

As referências de valores dinâmicos usam chaves duplas ({{ }}). Quando um Job ou tarefa é executado, um literal de cadeia de caracteres substitui a referência de valor dinâmico. Por exemplo, se o senhor configurar o seguinte parâmetro key-value como um parâmetro de tarefa:

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

Se o ID de execução for 550315892394120, o valor de job_run_id será avaliado como job_550315892394120.

nota

O conteúdo dos colchetes duplos não é avaliado como expressões. O senhor não pode executar operações ou funções entre chaves duplas.

Os identificadores de valores fornecidos pelo usuário suportam caracteres alfanuméricos e sublinhados. Escape a chave que contém caracteres especiais, cercando o identificador com pontos traseiros ( ).

Os erros de sintaxe, incluindo valores de referência dinâmica inexistentes e chaves ausentes, são silenciosamente ignorados e tratados como literais strings. Uma mensagem de erro será exibida se você fornecer uma referência inválida pertencente a um namespace conhecido, por exemplo, {{job.notebook_url}}.

Usar referências de valores dinâmicos na interface do usuário do trabalho

Os campos que aceitam referências de valores dinâmicos fornecem um atalho para inserir referências de valores dinâmicos disponíveis. Clique em {} para ver essa lista e inseri-la no campo fornecido.

nota

A interface do usuário não preenche automaticamente a chave para fazer referência aos valores de tarefa.

Muitos campos que aceitam referências de valores dinâmicos exigem formatação adicional para serem usados corretamente. Consulte Configurar parâmetros da tarefa.

Usar referências de valores dinâmicos em uma tarefa JSON

Use a sintaxe {{ }} para usar valores dinâmicos nas definições do Job JSON usadas pelos sites Databricks CLI e REST API.

Job e os parâmetros de tarefa têm sintaxe diferente, e a sintaxe dos parâmetros de tarefa varia de acordo com o tipo de tarefa.

O exemplo a seguir mostra a sintaxe parcial do site JSON para configurar os parâmetros do Job usando referências de valores dinâmicos:

JSON

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

O exemplo a seguir mostra a sintaxe parcial do site JSON para configurar os parâmetros de tarefa do Notebook usando uma referência de valor dinâmico:

JSON

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

Revisar parâmetros para a execução de um trabalho

Após a conclusão de uma tarefa, o senhor pode ver os valores dos parâmetros resolvidos em Parâmetros na página de detalhes da execução. Veja os detalhes da execução do trabalho.

Referências de valor suportadas

As seguintes referências de valores dinâmicos são suportadas:

Referência	Descrição
{{job.id}}	O identificador exclusivo atribuído ao trabalho.
{{job.name}}	O nome do trabalho no momento da execução do trabalho.
{{job.run_id}}	O identificador exclusivo atribuído à execução do trabalho.
{{job.repair_count}}	O número de tentativas de reparo na execução do trabalho atual.
{{job.start_time.<argument>}}	Um valor baseado na hora (no fuso horário UTC) em que a execução do trabalho começou. O valor de retorno é baseado na opção argument. Consulte Opções para valores de data e hora.
{{job.parameters.<name>}}	O valor do parâmetro Job-level com o endereço key <name>.
{{job.trigger.type}}	O tipo de acionador da execução do trabalho. Os valores possíveis são periodic, one_time, run_job_task, file_arrival, continuous e table.
{{job.trigger.file_arrival.location}}	Se um acionador de chegada de arquivo estiver configurado para esse trabalho, o valor do local de armazenamento.
{{job.trigger.time.<argument>}}	Um valor baseado na hora (no fuso horário UTC) em que a execução do trabalho foi acionada, arredondado para baixo até o minuto mais próximo para trabalhos com um cron programar. O valor de retorno é baseado na opção argument. Consulte Opções para valores de data e hora.
{{task.name}}	O nome da tarefa atual.
{{task.run_id}}	O identificador exclusivo da execução da tarefa atual.
{{task.execution_count}}	O número de vezes que a tarefa atual foi executada (incluindo novas tentativas e reparos).
{{task.notebook_path}}	O caminho do Notebook da tarefa atual do Notebook.
{{tasks.<task_name>.run_id}}	O identificador exclusivo atribuído à execução da tarefa para <task_name>.
{{tasks.<task_name>.result_state}}	O estado do resultado da tarefa <task_name>. Os valores possíveis são success, failed, excluded, canceled, evicted, timedout, upstream_canceled, upstream_evicted e upstream_failed.
{{tasks.<task_name>.error_code}}	O código de erro da tarefa <task_name> se ocorrer um erro na execução da tarefa. Exemplos de valores possíveis são RunExecutionError, ResourceNotFound e UnauthorizedError. Para uma tarefa bem-sucedida, isso é avaliado como uma cadeia de caracteres vazia.
{{tasks.<task_name>.execution_count}}	O número de vezes que a tarefa <task_name> foi executada (incluindo novas tentativas e reparos).
{{tasks.<task_name>.notebook_path}}	O caminho para o Notebook para a tarefa Notebook <task_name>.
{{tasks.<task_name>.values.<value_name>}}	O valor da tarefa com o key <value_name> que foi definido pela tarefa <task_name>.
{{tasks.<task_name>.output.rows}}	As linhas de saída de uma tarefa SQL upstream <task_name>. Se for passado como Inputs para uma tarefa For each, cada linha será enviada iterativamente para a tarefa aninhada. A saída SQL é limitada a 1.000 linhas e tem 48 KB de tamanho. Consulte as opções de saída do SQL.
{{tasks.<task_name>.output.first_row}}	A primeira linha da saída de uma tarefa SQL upstream <task_name>. A saída SQL é limitada a 1.000 linhas e 48 KB de tamanho.
{{tasks.<task_name>.output.first_row.<column_alias>}}	O valor da coluna <column_alias> na primeira linha da saída de uma tarefa SQL upstream <task_name>. A saída SQL é limitada a 1.000 linhas e 48 KB de tamanho.
{{tasks.<task_name>.output.alert_state}}	O estado de uma tarefa de alerta SQL upstream. O valor é UNKNOWN, OK ou TRIGGERED.
{{workspace.id}}	O identificador exclusivo atribuído ao site workspace.
{{workspace.url}}	O URL do site workspace.

O senhor pode definir essas referências com qualquer tarefa. Consulte Configurar parâmetros da tarefa.

O senhor também pode passar parâmetros entre tarefas em um trabalho com valores de tarefa . Consulte Usar valores de tarefa para passar informações entre tarefas.

Opções para valores de data e hora

Use os argumentos a seguir para especificar o valor de retorno das variáveis de parâmetros com base no tempo. Todos os valores de retorno são baseados em um carimbo de data/hora no fuso horário UTC.

Argumento	Descrição
iso_weekday	Retorna um dígito de 1 a 7, representando o dia da semana do timestamp.
is_weekday	Retorna true se o carimbo de data/hora for em um dia da semana.
iso_date	Retorna a data no formato ISO.
iso_datetime	Retorna a data e a hora no formato ISO.
year	Retorna a parte do ano do carimbo de data/hora.
month	Retorna a parte mensal do carimbo de data/hora.
day	Retorna a parte do dia do carimbo de data/hora.
hour	Retorna a parte da hora do carimbo de data/hora.
minute	Retorna a parte minuciosa do carimbo de data/hora.
second	Retorna a segunda parte do carimbo de data/hora.
timestamp_ms	Retorna o carimbo de data/hora em milissegundos.

Opções de saída SQL

O senhor pode acessar a saída de uma tarefa SQL upstream usando valores dinâmicos.

Por exemplo, se o senhor tiver uma tarefa SQL chamada sales_by_year com o seguinte SQL, ela criará a saída com base na instrução final 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;

O senhor pode fazer referência à saída em uma tarefa downstream criando uma configuração de tarefa usando um valor dinâmico {{tasks.<task_name>.output.<argument>}}.

Em For each tarefa, as linhas são enviadas iterativamente para a tarefa aninhada. Neste exemplo, se o senhor definir as entradas de uma tarefa For each como {{tasks.sales_by_year.output.rows}}, na tarefa aninhada, poderá usar a sintaxe {{input.<column_alias>}} para enviar iterativamente os valores de linha como parâmetros. Na configuração de tarefa aninhada, o senhor poderia criar dois parâmetros com o par key-value year:{{input.sales_year}}, e sales:{{input.num_sales}}. Supondo que a tarefa aninhada seja uma tarefa SQL, o senhor poderia fazer referência aos valores em seu código com uma consulta como a seguinte.

SQL

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

Para obter mais informações sobre For each tarefa e sua tarefa aninhada, consulte Usar uma For each tarefa para executar outra tarefa em um loop.

nota

A saída da consulta SQL é mantida por 7 dias. Se o trabalho for pausado (por exemplo, em caso de falha) e retomado mais de 7 dias depois, a saída da consulta SQL não estará disponível.

Referências de valores dinâmicos obsoletas

As seguintes referências de valores dinâmicos estão obsoletas. A referência de substituição recomendada está incluída na descrição de cada variável.

Variável	Descrição
{{job_id}}	O identificador exclusivo atribuído a um trabalho. Em vez disso, use job.id.
{{run_id}}	O identificador exclusivo atribuído a uma execução de tarefa. Em vez disso, use task.run_id.
{{start_date}}	A data em que a tarefa execução começar. O formato é YYYY-MM-DD no fuso horário UTC. Em vez disso, use job.start_time.<argument>.
{{start_time}}	O registro de data e hora do início da execução após o clustering ter sido criado e estar pronto. O formato é de milissegundos desde a época do UNIX no fuso horário UTC, conforme retornado por System.currentTimeMillis(). Em vez disso, use job.start_time.<format>.
{{task_retry_count}}	O número de novas tentativas de execução de uma tarefa se a primeira tentativa falhar. O valor é 0 para a primeira tentativa e aumenta a cada nova tentativa. Em vez disso, use task.execution_count.
{{parent_run_id}}	O identificador exclusivo atribuído à execução de um trabalho com várias tarefas. Em vez disso, use job.run_id.
{{task_key}}	O nome exclusivo atribuído a uma tarefa que faz parte de um trabalho com várias tarefas. Em vez disso, use task.name.