Usar valores de tarefa para transmitir informações entre tarefas.

Os valores de tarefa referem-se ao subutilitário Databricks Utilities taskValues, que permite passar valores arbitrários entre tarefas em um trabalho do Databricks. Consulte o subutilitário taskValues (dbutils.jobs.taskValues).

Você especifica um par chave-valor usando dbutils.jobs.taskValues.set() em uma tarefa e, em seguida, pode usar o nome da tarefa e a chave para fazer referência ao valor em tarefas subsequentes.

Observação

Como dbutils.jobs.taskValues.set() e dbutils.jobs.taskValues.get() na subutilidade dbutils.jobs.taskValues são funções do Python, elas só podem ser usadas em notebooks com Python selecionado como o idioma. No entanto, você pode referenciar valores de tarefa usando referências de valor dinâmico para todas as tarefas que dão suporte a parâmetros. Consulte Valores de tarefa de referência.

Definir valores de tarefa

Defina valores de tarefa em notebooks Python usando dbutils.jobs.taskValues.set().

Chaves de valores de tarefa devem ser cadeias de caracteres. Cada chave deve ser exclusiva se você tiver vários valores de tarefa definidos em um notebook.

Você pode atribuir valores de tarefa manualmente ou programaticamente a chaves. Apenas valores que podem ser expressos como JSON válido são permitidos. O tamanho da representação JSON do valor não pode exceder 48 KiB.

Por exemplo, o exemplo a seguir define uma cadeia de caracteres estática para a chave fave_food:

dbutils.jobs.taskValues.set(key = "fave_food", value = "beans")

O exemplo a seguir usa um parâmetro de tarefa de notebook para consultar todos os registros de atualização de um determinado registro e retornar o status atual do registro e a contagem total de registros:

from pyspark.sql.functions import col

dbutils.widgets.text("booking_id", "51567", "Booking ID")
booking_id = dbutils.widgets.get("booking_id")

query = (spark.read.table("samples.wanderbricks.booking_updates")
  .orderBy(col("updated_at"), ascending=False)
  .where(col("booking_id") == booking_id)
  .select(col("status"))
)

dbutils.jobs.taskValues.set(key = "record_count", value = query.count())
dbutils.jobs.taskValues.set(key = "booking_status", value = query.take(1)[0][0])

Você pode passar listas de valores usando esse padrão e depois usá-los para coordenar a lógica downstream, como For each tarefas. Consulte Usar uma tarefa For each para executar outra tarefa em um loop.

O exemplo a seguir extrai os valores distintos para o ID de destino para uma lista Python e define isso como valor de tarefa:

dest_list = list(spark.read.table("samples.wanderbricks.properties").select("destination_id").distinct().toPandas()["destination_id"])

dbutils.jobs.taskValues.set(key = "dest_list", value = dest_list)

Valores de tarefa de referência

O Databricks recomenda referenciar valores de tarefa como parâmetros de tarefa configurados usando o padrão {{tasks.<task_name>.values.<value_name>}} de referência de valor dinâmico.

Por exemplo, para referenciar o valor da tarefa com a chave dest_list definida pela tarefa chamada destination_lookup, utilize a sintaxe {{tasks.destination_lookup.values.dest_list}}.

Consulte Configurar parâmetros de tarefa e referências de valor dinâmico.

Use dbutils.jobs.taskValues.get.

A sintaxe dbutils.jobs.taskValues.get() requer a especificação do nome da tarefa upstream. Essa sintaxe não é recomendada, pois você pode usar valores de tarefa em várias tarefas downstream, o que significa que são necessárias várias atualizações se o nome de uma tarefa for alterado.

Usando essa sintaxe, você pode especificar opcionalmente um valor default e um debugValue. O valor padrão será usado se a chave não puder ser encontrada. O debugValue permite que você defina um valor estático a ser usado durante o desenvolvimento e teste manual de código em notebooks antes de agendar o notebook como uma tarefa.

O exemplo a seguir obtém o valor da chave booking_status definido em um nome de tarefa booking_lookup. O valor confirmed é retornado somente ao executar o notebook interativamente.

booking_status = dbutils.jobs.taskValues.get(taskKey = "booking_lookup", key = "booking_status", debugValue = "confirmed")

Observação

O Databricks não recomenda definir valores padrão, pois eles podem ser difíceis de solucionar problemas e evitar mensagens de erro esperadas devido a chaves ausentes ou tarefas nomeadas incorretamente.

Leia valores das iterações de uma For each tarefa

Uma tarefa que roda dentro de um Para cada tarefa é executada uma vez por iteração, e cada iteração pode definir um valor de tarefa com dbutils.jobs.taskValues.set() como em qualquer tarefa. Uma tarefa a jusante pode ler o valor de cada iteração de uma única lista retornada, ordenada pelo índice de iteração.

Importante

A leitura das saídas de iteração agregadas de uma tarefa For each está em versão Beta. Ele é ativado por padrão e requer Databricks Runtime 15.4 LTS ou superior na computação clássica.

Na computação serverless, dbutils.jobs.taskValues.get requer versão 5 do ambiente ou superior. Nas versões de ambiente 1 a 4, ele retorna apenas o valor da primeira iteração em vez da lista, e pode gerar um TypeError. Referências de valores dinâmicos retornam a lista completa em qualquer processamento.

Em qualquer superfície de leitura, use a chave da tarefa aninhada que é executada dentro da tarefa For each e não a chave da própria tarefa For each. Sua chave retorna os valores de cada iteração como uma única lista ordenada por índice de iteração. Por exemplo, se três iterações de uma tarefa aninhada chamada process definirem result:

results = dbutils.jobs.taskValues.get(taskKey = "process", key = "result")
# results == [1, 2, 3]

A referência de valor dinâmico {{tasks.process.values.result}} é resolvida para o mesmo array.

Uma iteração que não definiu a chave mantém sua posição no resultado: ela aparece como None (JSON null) a partir de dbutils.jobs.taskValues.get, e como a null em uma referência de valor dinâmica. Por exemplo, se a segunda de três iterações não definiu result, results é [1, None, 3].

Referências agregadas têm dois limites: um array montado não pode exceder aproximadamente 48 KB (49.344 caracteres) para um único valor de parâmetro, e um único valor de parâmetro pode conter no máximo três referências agregadas de valor de tarefa.

Exibir valores de tarefa

O valor retornado de um valor da tarefa para cada execução é exibido no painel Saída de Detalhes da execução da tarefa. Consulte Ver o histórico de execução da tarefa.