Adicionar condições SQL aos acionadores de trabalho

Use uma condição SQL para verificar os seus dados antes de começar uma execução de tarefa acionada. Quando o gatilho dispara, o Azure Databricks executa uma consulta SQL guardada num SQL warehouse que escolher. A execução só começa se o resultado da consulta cumprir a condição. Por exemplo, execute um trabalho apenas quando uma tabela a montante terminou de carregar ou quando uma verificação de qualidade dos dados é aprovada, sem adicionar uma tarefa de verificação separada ao trabalho.

Important

Este recurso está em versão Beta. Para o utilizar, um administrador de espaço de trabalho deve ativar as condições SQL para os acionadores a partir da página de Pré-visualizações. Ver Gerir as pré-visualizações de Azure Databricks.

Requirements

  • Tens de ter o CAN MANAGE na tarefa para configurar os seus triggers.
  • Precisas de uma consulta guardada que não use parâmetros de consulta. Deve ter acesso à consulta e ser capaz de a executar no armazém SQL que selecionar.
  • A identidade de execução do trabalho deve ser capaz de abrir a consulta guardada, ter CAN USE no SQL warehouse e ter acesso de leitura a todas as tabelas que a consulta lê. A consulta de condição executa-se como esta identidade.

Como funcionam as condições SQL

O acionador decide quando verificar. A condição SQL decide se deve iniciar uma execução. Depois do disparo do trigger, o Azure Databricks executa a consulta em modo apenas de leitura. Uma execução só começa quando tanto o gatilho como a condição SQL se verificarem.

Pode adicionar uma condição SQL a um gatilho de agendamento, atualização de tabela, chegada de ficheiro, atualização de modelo ou conclusão de tarefa. Os gatilhos contínuos não suportam condições SQL.

Escolha como o Azure Databricks avalia o resultado da consulta:

Tipo de condição Valor da API Começa uma execução quando Requisitos de consulta
A consulta devolve linhas QUERY_RETURNS_ROWS O resultado contém pelo menos uma linha. None. Zero linhas significam que a condição não é cumprida.
Alterações no valor do resultado RESULT_VALUE_CHANGES O resultado difere do valor na verificação anterior. Deve devolver exatamente uma linha e uma coluna. O valor deve ser 1 MiB ou menor.

Para alterações no valor do resultado, o Azure Databricks executa a consulta em segundo plano logo após guardar o acionador e armazena o resultado como linha de base. Esta verificação não inicia uma execução. Verificações posteriores iniciam uma execução quando o resultado difere do valor armazenado. Alterar a consulta, SQL warehouse ou tipo de condição no trigger reinicia a linha de base, e o Azure Databricks armazena uma nova da mesma forma. Pausar o acionador ou alterar outras definições do acionador também pode reiniciá-lo. Editar o texto da consulta guardada não a reinicia.

Cada verificação funciona da seguinte forma:

  • Uma verificação, incluindo o arranque do SQL Warehouse, expira ao fim de 5 minutos. Se uma verificação expirar, nenhuma execução começa e o acionador verifica novamente na avaliação seguinte.
  • Um gatilho executa no máximo um teste de cada vez. Se o gatilho estiver agendado para ocorrer enquanto a verificação ainda está a decorrer, o Azure Databricks ignora essa avaliação em vez de a colocar na fila.
  • Se a consulta tiver mais do que uma instrução, apenas o resultado da última instrução é utilizado.
  • As condições SQL aplicam-se apenas a execuções que o acionador inicia. Executar agora e outras execuções manuais não verificam a condição SQL.

Gorjeta

A consulta devolve linhas, certifique-se de que a consulta devolve zero linhas quando os dados não estiverem prontos. Uma consulta como SELECT count(*) > 100 FROM main.sales.orders devolve uma linha mesmo quando a contagem é 100 ou menos, por isso a condição é cumprida. Filtrar com WHERE ou HAVING em vez disso:

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

Adicionar uma condição SQL a um trigger

  1. Na barra lateral do espaço de trabalho, clica em Jobs & Pipelines e depois abre o job.
  2. Em Agendamentos & Acionadores, clique em Adicionar acionador ou edite um acionador existente.
  3. Selecione o tipo de Trigger e configure o Trigger.
  4. Expanda Avançado e, em seguida, clique em Adicionar condição SQL.
  5. Selecione a consulta SQL e o SQL warehouse.
  6. Em Acionar quando, selecione A consulta devolve linhas ou O valor do resultado muda.
  7. Clique em Salvar.

Acionador de teste verifica se o trabalho pode usar a consulta guardada. Confirma que a consulta existe, não está no lixo 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.

Configure com a API, CLI ou bundles

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, define-o em trigger, ao lado das definições do tipo de gatilho. Com a Beta de Gatilhos Múltiplos, defina-a em cada entrada em triggers.

API REST

Guarde este pedido como update-job.json e envie-o para POST /api/2.2/jobs/update na API de Jobs. Substitui os IDs pelos IDs da tua tarefa, da consulta guardada 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

Guarde o corpo do pedido a partir do separador da API REST como update-job.json, e depois execute:

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

Pacotes

Para Pacotes de Automação Declarativa, adicione as seguintes definições a um recurso de trabalho existente, juntamente com as 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

Bundles não conseguem criar consultas guardadas. Crie primeiro a consulta no espaço de trabalho e depois faça referência ao seu ID.

A sql_condition que envia para jobs/update substitui a atual por completo, por isso inclua todos os seus campos. Se deixares de fora sql_condition, a condição atual mantém-se. Para atualizar múltiplos gatilhos, veja Adicionar múltiplos gatilhos a uma tarefa.

Monitorizar verificações de condição SQL

  • Para gatilhos agendados, o estado 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 correu sem erro, invoque a API Get Job com include_trigger_state=true e leia trigger_state.sql_condition. O campo latest_condition_evaluation_satisfied mostra se essa verificação cumpriu a condição e latest_condition_evaluation_sql_statement_id identifica a sua instrução no histórico da consulta. Uma verificação falhada não altera estes campos. Com Vários Triggers, 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 etiqueta SQL . Clique nele e, em seguida, clique em Detalhes da execução da consulta para abrir a verificação dessa execução no histórico de consultas.
  • Se uma verificação falhar por algum motivo que possas corrigir, o erro aparece no estado do gatilho 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 email e destinos de webhooks. Recebes uma notificação quando uma condição de funcionamento começa a falhar, não uma para cada verificação falhada. O erro mantém-se até à próxima verificação bem-sucedida. Consulte Adicionar notificações numa tarefa.

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

Troubleshooting

Questão Action
A tarefa é executada sempre que o acionador dispara Para Query devolve linhas, altera a consulta para que devolva zero linhas quando os dados não estão prontos.
Alterações no valor do resultado nunca iniciam uma execução A base é o resultado da consulta no momento em que guardaste o acionador. Uma execução só começa depois de o resultado da consulta mudar desse valor para outro.
A verificação expira Torna a consulta mais rápida, ou usa um serverless SQL warehouse, que começa mais depressa.
Adicionar condição SQL não aparece Expandir Avançado. Se o botão ainda estiver em falta, pede a um administrador do espaço de trabalho para ativar as condições SQL para os gatilhos.

Limitations

  • Cada gatilho suporta uma condição SQL.
  • Os gatilhos contínuos não suportam condições SQL.
  • As consultas condicionais são executadas apenas em warehouses SQL, em modo apenas de leitura.
  • Uma verificação, incluindo o arranque do SQL Warehouse, atinge o tempo limite após 5 minutos.
  • Um gatilho mantém apenas o seu último controlo, não um histórico completo de cada verificação. Para ver verificações anteriores, use a tag SQL nas execuções iniciadas pela condição, ou o histórico de consultas.
  • As verificações são feitas no seu SQL Warehouse e são faturadas como utilização do SQL Warehouse. Uma verificação pode iniciar um armazém de dados parado.
  • Os gatilhos com condições SQL contam para o limite do espaço de trabalho de 12.000 gatilhos ativos.
  • Última atualização a