Configurar uma consulta recorrente com suporte de preenchimento usando LakeFlow Jobs

Um cenário comum é uma consulta que é executada em um programa regular com um Job orquestrando-a. Por exemplo, no final de cada dia, uma consulta é executada para atualizar o sistema com base nas alterações daquele dia no conjunto de dados de origem. Este tutorial explica como criar uma consulta com parâmetros que identificam o período para importar dados e, em seguida, criar um Job para programar essa consulta para execução diária.

A consulta e os parâmetros criados neste tutorial correspondem às melhores práticas e são configurados para permitir que você execute um Job de preenchimento posteriormente, se necessário.

Pré-requisito

Para concluir este tutorial, você precisa ter acesso às tabelas do sistema no Databricks.

o passo 1: Criar uma consulta

Neste tutorial, você criará uma consulta que usa parâmetros para descrever quais dados extrair. Por exemplo, este tutorial usa dados de cobrança das tabelas do sistema para calcular os custos diários do Databricks.

A consulta usa dois parâmetros:

Parâmetro	Uso
data_interval_end	A data em que o Job é executado (para o programador recorrente), que é o fim do intervalo de tempo que deve ser processado. Ou, para o trabalho de preenchimento, a data final para a qual os dados serão preenchidos.
lookback_days	Quantos dias de dados consultar. A consulta olha para trás a partir do data_interval_end, que normalmente é a hora ou data em que a consulta é executada, então você deve olhar para trás, em vez de para frente.

Siga estes passos para criar uma consulta:

1. No seu workspace, clique em Novo , então Notebook para criar um novo Notebook.

2. O nome padrão é Untitled Notebook <date-time>. Clique no nome na parte superior do Notebook e dê a ele um nome descritivo, como Query billing with parameters tutorial.

3. Na parte superior do editor do Notebook, escolha SQL no seletor de idiomas.

4. Na primeira célula, adicione o seguinte código. Substitua <catalog> e <schema> por um catálogo e esquema que você deseja usar e aos quais você tem acesso.

   SQL

   USE CATALOG <catalog>;
   USE SCHEMA <schema>;
   
   CREATE TABLE IF NOT EXISTS tutorial_databricks_product_spend (billing_origin_product STRING, usage_date DATE, total_dollar_cost DECIMAL(12, 2));
   
   -- Process the last N days specified by :lookback_days ending on :data_interval_end
   INSERT INTO TABLE tutorial_databricks_product_spend
     REPLACE WHERE
       usage_date >= date_add(:data_interval_end, - CAST(:lookback_days AS INT)) AND usage_date < :data_interval_end
     SELECT
       usage.billing_origin_product,
       usage.usage_date,
       SUM(usage.usage_quantity * list_prices.pricing.effective_list.default) AS total_dollar_cost
     FROM
       system.billing.usage AS usage
         JOIN system.billing.list_prices AS list_prices
           ON usage.sku_name = list_prices.sku_name
           AND usage.usage_end_time >= list_prices.price_start_time
           AND (
             list_prices.price_end_time IS NULL
             OR usage.usage_end_time < list_prices.price_end_time
           )
     WHERE
       usage.usage_date >=
         date_add(:data_interval_end, -CAST(:lookback_days AS INT))
       AND usage.usage_date <
         :data_interval_end
     GROUP BY
       usage.billing_origin_product,
       usage.usage_date

5. Adicione os dois parâmetros clicando em Editar , Adicionar parâmetro . Os parâmetros devem ter os seguintes nomes e valores default :

Nome	Valor padrão
lookback_days	1
data_interval_end	< nenhum >. Este parâmetro é sempre necessário.

Para saber mais sobre parâmetros e como acessá-los em diferentes tipos de tarefas ou no Python, consulte Acessar valores de parâmetros de uma tarefa.

Sua consulta agora está pronta. A consulta lê os dados de um dia inteiro das tabelas do sistema e, em seguida, substitui os dados existentes na tabela de destino usando REPLACE WHERE. Ao substituir dados em vez de inseri-los, a consulta não causa danos se um dia for executado uma segunda vez. Na verdade, isso permite que você execute novamente um dia em caso de erro no processamento ou atraso na chegada dos dados.

Você pode testar a consulta seguindo estes passos:

1. Forneça um valor para data_interval_end acima das células do Notebook, no formato yyyy-mm-dd, por exemplo, 2025-10-02.
2. Opcionalmente, clique em Conecte-se e escolha um recurso compute para usar.
3. Clique executar tudo .
4. Após a conclusão da execução, você pode view a tabela que foi criada abrindo o Catálogo no menu à esquerda e, em seguida, escolha o catálogo e o esquema que você definiu na consulta.

Em seguida, crie um programa recorrente para a consulta.

o passo 2: Crie um Job para programar a consulta

1. No seu workspace, clique em Empregos e pipeline na barra lateral.

2. Clique em Criar e depois Job . A tab de tarefas é exibida com o painel de tarefas vazio.

nota

Se a interface do usuárioLakeFlow Jobs estiver LIGADA , clique no bloco Notebook para configurar a primeira tarefa. Se o bloco Notebook não estiver disponível, clique em Adicionar outro tipo de tarefa e pesquise por Notebook .

3. (Opcional) Substitua o nome do trabalho, que é definido por padrão como New Job <date-time>, pelo nome do seu trabalho.

4. No campo nome da tarefa , insira um nome para a tarefa; por exemplo, tutorial-databricks-spend.

5. Se necessário, selecione Notebook no menu suspenso Tipo .

6. No menu suspenso Fonte , selecione área de trabalho , que permite que você use um Bloco de anotações salvo anteriormente.

7. Para Caminho , use o navegador de arquivos para encontrar o primeiro Notebook que você criou, clique no nome do Notebook e clique em Confirmar .

8. Clique Adicione na seção Parâmetros . Adicione o parâmetro lookback_days , com um valor de 1.

9. Clique Adicione na seção Parâmetros . Adicione o parâmetro data_interval_end . Clique em { } ao lado de Valor para ver uma lista de valores parametrizados. Selecione {{job.trigger.time.iso_date}} na lista para inseri-lo como valor.

   Isso passa a data em que a execução do Job foi acionada como parâmetro.

nota

Você também pode usar {{job.trigger.time.iso_datetime}} para passar o tempo, se tiver uma consulta que analise um período de tempo menor, como uma hora em vez de um dia. Nesse caso, qualquer opção funciona em nossa consulta, mas iso_date mostra a intenção do parâmetro.

10. Clique em Criar tarefa .

11. No painel de detalhes à direita da tarefa, em Programar & Gatilhos , clique em Adicionar gatilho .

12. Em Tipo de gatilho, escolha Agendado .

13. Mantenha o padrão de um gatilho ativo que seja executado uma vez por dia.

14. Clique em Salvar .

Seu trabalho agora executa sua consulta diariamente. Por default, isso é executado no mesmo horário do dia em que você criou o gatilho. Você pode editar o gatilho e selecionar o tipo de gatilho Avançado para definir um horário específico.

nota

Caso não queira arcar com os custos de execução diária deste tutorial , você pode clicar pausa no programa que você acabou de criar. Isso mantém o programa, mas ele não será executado até que você o despause. Você sempre pode executá-lo manualmente a qualquer momento.

Em seguida, execute um backfill para carregar dados mais antigos na tabela.

o passo 3: execução de preenchimento para dados mais antigos

Você pode executar um backfill para preencher dados mais antigos. Por exemplo, se você quiser que os dados da semana passada sejam preenchidos em sua tabela. As instruções a seguir criam 7 execuções de preenchimento para processar cada um dos dados dos últimos 7 dias.

1. Clique na seta para baixo (re:[ícone de seta para baixo]) ao lado de execução agora no topo da página.

2. Selecione execução backfill no menu suspenso que aparece. Isso abre a caixa de diálogo preenchimento de execução .

3. Altere o intervalo de datas para o intervalo que você deseja preencher. Escolha o início como 7 dias antes, às 00:00, e o Fim como hoje, também às 00:00. Por exemplo, você pode escolher 09/14/2025, 12:00 AM como seu horário de início e 09/21/2025, 12:00 AM como seu horário de término.

4. Selecione A cada 1 Day para o intervalo de tempo de cada preenchimento.

5. Em ParâmetrosJob , seus parâmetros existentes são exibidos com chave e valores. Confirme se o parâmetro data_interval_end está definido como {{backfill.iso_datetime}} e lookback_days é 1.

6. Clique em execução para iniciar a execução do preenchimento. Isso aciona 7 execuções para preenchimento, uma para cada dia.

Os preenchimentos podem ser executados em paralelo ou sequencialmente, dependendo da configuração do seu trabalho. Para mais detalhes sobre preenchimentos, consulte Trabalho de preenchimento.