Adicionar condições SQL aos gatilhos de tarefa

Use uma condição SQL para verificar seus dados antes que uma execução de um job acionado comece. Quando o gatilho dispara, o Azure Databricks executa uma consulta SQL salva em um SQL warehouse que você seleciona. A execução começa somente se o resultado da consulta atender à condição. Por exemplo, execute um trabalho apenas quando uma tabela a montante terminar de carregar ou quando uma verificação de qualidade de dados for aprovada, sem adicionar uma tarefa de verificação separada ao trabalho.

Requirements

• Você precisa ter o CAN MANAGE na tarefa para configurar seus gatilhos.
• Você precisa de uma consulta salva que não use parâmetros de consulta. Você deve ter acesso à consulta e ser capaz de executá-la no SQL warehouse que selecionar.
• A Run as identity do trabalho deve ser capaz de abrir a consulta salva, ter CAN USE no SQL warehouse e ter acesso de leitura a todas as tabelas que a consulta lê. A consulta de condição é executada como essa identidade.

Como funcionam as condições SQL

O acionador decide quando verificar. A condição SQL decide se iniciar uma execução. Após o disparo do gatilho, o Azure Databricks executa a consulta no modo somente leitura. Uma execução começa apenas quando tanto o gatilho quanto a condição SQL são satisfeitas.

Você pode adicionar uma condição SQL a um gatilho de agendamento, atualização de tabela, chegada de arquivo, atualização de modelo ou conclusão de tarefa. Gatilhos contínuos não suportam condições SQL.

Escolha como o Azure Databricks avalia o resultado da consulta:

Para mudanças no valor do resultado, o Azure Databricks executa a consulta em segundo plano logo após você salvar o gatilho e armazena o resultado como base. Essa verificação não inicia uma execução. Verificações posteriores iniciam uma execução quando o resultado difere do valor armazenado. Mudar a consulta, o SQL warehouse ou o tipo de condição no gatilho reinicia a linha base, e o Azure Databricks armazena uma nova da mesma forma. Pausar o gatilho ou mudar outras configurações do gatilho também pode resetá-lo. Editar o texto da consulta salva não a reseta.

Cada verificação funciona da seguinte forma:

• Uma verificação, incluindo a inicialização do SQL Warehouse, expira após 5 minutos. Se uma verificação atinge o tempo limite, nenhuma execução começa, e o acionador verifica novamente na próxima avaliação.
• Um gatilho executa no máximo um checagem por vez. Se o gatilho estiver previsto enquanto a verificação ainda está rodando, o Azure Databricks pula essa avaliação em vez de colocá-la na fila.
• Se a consulta tiver mais de uma instrução, apenas o resultado da última instrução é usado.
• Condições SQL se aplicam apenas às execuções que o disparador inicia. Execute agora e outras execuções manuais não verificam a condição SQL.

SELECT 1
FROM main.sales.orders
WHERE order_date = current_date()
HAVING count(*) > 100

Adicionar uma condição SQL a um gatilho

1. Na barra lateral do workspace, clique em Jobs & Pipelines e depois abra o job.
2. Em Agendamentos e Gatilhos, clique em Adicionar gatilho ou edite um gatilho existente.
3. Selecione o tipo de gatilho e configure o gatilho.
4. Expanda Avançado, depois clique em Adicionar condição SQL.
5. Selecione a consulta SQL e o SQL warehouse.
6. Em Disparar quando, selecione Consulta retorna linhas ou Valor do resultado muda.
7. Clique em Salvar.

Acionador de teste verifica se o trabalho pode usar a consulta salva. Ele confirma que a consulta existe, não está na lixeira e não tem parâmetros, mas não executa a consulta. Para ver o resultado da consulta, execute a consulta no editor SQL.

Para remover uma condição, edite o gatilho, expanda Avançado e clique em Remover condição SQL.

Configurar usando a API, a CLI ou os pacotes

Defina sql_condition com sql_query_id, warehouse_id, e trigger_mode. Para um gatilho agendado que usa uma expressão cron, defina-o em schedule. Para outros tipos de gatilho, configure em trigger, ao lado das configurações de tipo de gatilho. Com o Multiple Triggers Beta, defina-o em cada entrada em triggers.

API REST

Salve essa solicitação como update-job.json e envie para POST /api/2.2/jobs/update na API Jobs. Substitua os IDs pelos IDs do job, da consulta salva e do SQL Warehouse.

{
  "job_id": 9001,
  "new_settings": {
    "trigger": {
      "pause_status": "UNPAUSED",
      "table_update": {
        "table_names": ["main.sales.orders"],
        "condition": "ANY_UPDATED"
      },
      "sql_condition": {
        "sql_query_id": "fe25e731-92f2-4838-9fb2-1ca364320a3d",
        "warehouse_id": "5d409943fcd32c6f",
        "trigger_mode": "QUERY_RETURNS_ROWS"
      }
    }
  }
}

CLI

Salve o corpo da requisição da aba REST API como update-job.json, e então execute:

databricks api post /api/2.2/jobs/update --json @update-job.json

Pacotes

Para Pacotes de Automação Declarativa, adicione as seguintes configurações a um recurso de trabalho existente, junto com suas tarefas:

resources:
  jobs:
    orders_report:
      trigger:
        pause_status: UNPAUSED
        periodic:
          interval: 1
          unit: DAYS
        sql_condition:
          sql_query_id: fe25e731-92f2-4838-9fb2-1ca364320a3d
          warehouse_id: 5d409943fcd32c6f
          trigger_mode: RESULT_VALUE_CHANGES

Consultas salvas não conseguem criar bundles. Crie a consulta primeiro no workspace e depois faça referência ao ID dela.

A sql_condition que você envia para jobs/update substitui o atual como um todo, então inclua todos os seus campos. Se você deixar de fora sql_condition, a condição atual permanece. Para atualizar múltiplos gatilhos, veja Adicionar múltiplos gatilhos a um job.

Monitorar verificações de condição SQL

• Para gatilhos agendados, o status do gatilho na página do trabalho mostra se a última verificação de condição SQL foi cumprida. Clique em Detalhes da execução da consulta para abrir a instrução no histórico da consulta.
• Para ler a verificação mais recente que rodou sem erro, chame a API Get Job com include_trigger_state=true e leia trigger_state.sql_condition. O latest_condition_evaluation_satisfied campo mostra se essa verificação atendeu à condição e latest_condition_evaluation_sql_statement_id identifica sua declaração no histórico da consulta. Uma verificação falhada não altera esses campos. Com Múltiplos Acionadores, leia trigger_details[].state.sql_condition.
• Para cada execução iniciada por uma condição SQL, o campo Lançado na lista de execuções e na página de detalhes da execução mostra uma tag SQL . Clique nele, depois clique em Detalhes da execução da consulta para abrir a verificação daquela execução no histórico de consultas.
• Se uma verificação falhar por algum motivo que você possa corrigir, o erro aparece no status do trigger na página da tarefa. O Azure Databricks também envia o erro para as notificações de falha do trabalho, incluindo destinatários de e-mail e destinos de webhooks. Você recebe uma notificação quando uma condição de trabalho começa a falhar, não uma para cada verificação com falha. O erro permanece até a próxima verificação bem-sucedida. Confira Adicionar notificações sobre um trabalho.

Cada verificação é executada como uma instrução SQL no seu SQL Warehouse. Para revisar as verificações ao longo do tempo, consulte a tabela do sistema de histórico de consultas do warehouse.

Troubleshooting

Limitations

• Cada gatilho suporta uma condição SQL.
• Gatilhos contínuos não suportam condições SQL.
• As consultas de condição rodam apenas em warehouses SQL, em modo somente leitura.
• Uma verificação, incluindo a inicialização do SQL Warehouse, expira após 5 minutos.
• Um gatilho mantém apenas sua última verificação, não um histórico completo de cada verificação. Para ver verificações anteriores, use a tag SQL nas execuções em que a condição começou, ou o histórico de consultas.
• As verificações são feitas no seu SQL Warehouse e são cobradas como uso do SQL Warehouse. Uma verificação pode iniciar um warehouse parado.
• Gatilhos com condições SQL contam para o limite do workspace de 12.000 gatilhos ativos.