Atualização programática no Databricks SQL

Você pode refresh manualmente seu pipeline Databricks SQL (seja view materializada ou uma tabela de transmissão) quando souber que as tabelas de origem foram atualizadas. No entanto, você também pode definir um programa para atualização, seja por tempo, quando as tabelas de origem forem atualizadas, ou via orquestração. Esta página descreve como criar o programa para seu pipeline.

Você também pode criar notificações e definir o modo de desempenho para sua atualização agendada.

Crie um programador

Você pode configurar um pipeline Databricks SQL para refresh automaticamente com base em um programa definido ou para ser acionado quando os dados upstream forem alterados. A tabela a seguir mostra as diferentes opções para atualização programada.

Método	Descrição	Exemplo de caso de uso
Manual	refresh sob demanda usando uma instrução SQL REFRESH ou através da interface do usuário workspace .	Desenvolvimento, testes, atualizações pontuais.
TRIGGER ON UPDATE	Programar o pipeline para refresh automaticamente quando os dados upstream forem alterados.	Cargas de trabalho de produção com SLAs de atualização de dados ou períodos refresh imprevisíveis.
SCHEDULE	Programar o pipeline para refresh em intervalos de tempo definidos.	Requisitos refresh previsíveis e baseados no tempo.
Tarefa SQL em um Job	A atualização é orquestrada por meio de tarefasLakeFlow.	Pipeline complexo com dependências entre sistemas.

Mesmo ao programar a atualização, você pode executá- refresh manualmente a qualquer momento, caso precise de dados atualizados.

refreshmanual

Para refresh manualmente um pipeline, você pode chamar uma refresh a partir do Databricks SQL ou usar a interface do usuário workspace .

REFRESH statement

Para refresh um pipeline usando Databricks SQL:

1. No EditorSQL , execute a seguinte instrução:

   SQL

   REFRESH MATERIALIZED VIEW <table-name>;

   Para tabelas de transmissão, use REFRESH STREAMING TABLE.

Para obter mais informações, consulte REFRESH (MATERIALIZED VIEW ou STREAMING TABLE).

Workspace UI

Para refresh um pipeline na interface do usuário workspace :

1. No workspace Databricks , clique em Empregos e oportunidades .
2. Selecione na lista o pipeline que deseja refresh .
3. Clique no botão Iniciar .

À medida que o pipeline é atualizado, você verá as atualizações na interface do usuário.

Acionar na atualização

A cláusula TRIGGER ON UPDATE atualiza automaticamente um pipeline quando os dados de origem upstream são alterados. Isso elimina a necessidade de coordenar a programação em todo o pipeline. O dataset permanece atualizado sem exigir que o usuário saiba quando o Job upstream termina ou mantenha uma lógica de programação complexa.

Essa é a abordagem recomendada para cargas de trabalho de produção, especialmente quando as dependências upstream não executam programas de forma previsível. Após configurar o gatilho de atualização, o pipeline monitora suas tabelas de origem e as atualiza automaticamente quando são detectadas alterações em qualquer uma das fontes upstream.

Limitações

• Limites de dependência upstream: Um pipeline pode monitorar no máximo 10 tabelas upstream e 30 visualizações upstream. Para lidar com mais dependências, divida a lógica em vários pipelines.
• Limites do espaço de trabalho: Um máximo de 1.000 pipelines com TRIGGER ON UPDATE podem existir por workspace. Entre em contato com o suporte da Databricks se precisar de mais de 1.000 unidades.
• Intervalo mínimo: O intervalo mínimo de ativação é de 1 minuto.

Os exemplos a seguir mostram como configurar um gatilho de atualização ao definir um pipeline.

Crie um pipeline com gatilho na atualização.

Para criar um pipeline que se atualiza automaticamente quando os dados de origem mudam, inclua a cláusula TRIGGER ON UPDATE na instrução CREATE .

O exemplo a seguir cria uma tabela de transmissão que lê os pedidos dos clientes e é atualizada sempre que a tabela de origem orders é atualizada:

SQL

CREATE OR REFRESH STREAMING TABLE catalog.schema.customer_orders
  TRIGGER ON UPDATE
AS SELECT
    o.customer_id,
    o.name,
    o.order_id
FROM catalog.schema.orders o;

Frequência refresh do acelerador

Se os dados upstream forem atualizados com frequência, use AT MOST EVERY para limitar a frequência de atualização da view e limitar os custos compute . Isso é útil quando as tabelas de origem são atualizadas com frequência, mas os consumidores subsequentes não precisam de dados tempo-real. A palavra-chave INTERVAL é obrigatória antes do valor de tempo.

O exemplo a seguir limita a refresh da tabela de transmissão a, no máximo, cada 5 minutos, mesmo que os dados de origem mudem com mais frequência:

SQL

CREATE OR REFRESH STREAMING TABLE catalog.schema.customer_orders
  TRIGGER ON UPDATE AT MOST EVERY INTERVAL 5 MINUTES
AS SELECT
    o.customer_id,
    o.name,
    o.order_id
FROM catalog.schema.orders o;

refreshprogramada

O agendador de atualização pode ser definido diretamente na definição pipeline para refresh a view em intervalos de tempo fixos. Essa abordagem é útil quando a frequência de atualização dos dados é conhecida e se deseja um tempo refresh previsível.

Quando houver uma refresh programada, você ainda poderá executar uma refresh manual a qualquer momento, caso deseje dados atualizados.

Databricks suporta duas sintaxes de programação: SCHEDULE EVERY para intervalos simples e SCHEDULE CRON para programação precisa. As palavras-chave SCHEDULE e SCHEDULE REFRESH são semanticamente equivalentes.

Para obter detalhes sobre a sintaxe e o uso da cláusula SCHEDULE , consulte a cláusula de programaCREATE STREAMING TABLE ou a cláusula de programaCREATE MATERIALIZED VIEW.

Quando um programador é criado, um novo Job Databricks é configurado automaticamente para processar a atualização.

Para view o programa, faça um dos seguintes procedimentos:

• execute a instrução DESCRIBE EXTENDED a partir do editor SQL na interface do usuário Databricks . Consulte DESCRIBE TABLE.
• Utilize o Explorador de Catálogo para view o dataset. O programador está listado na tab Visão geral , em status de atualização . Consulte O que é o Catalog Explorer?.

Os exemplos a seguir mostram como criar uma view materializada com um programador:

programar a cada intervalo de tempo

Este exemplo programa uma refresh a cada 5 minutos:

SQL

CREATE OR REPLACE MATERIALIZED VIEW catalog.schema.hourly_metrics
  SCHEDULE EVERY 1 HOUR
AS SELECT
    date_trunc('hour', event_time) AS hour,
    count(*) AS events
FROM catalog.schema.raw_events
GROUP BY 1;

programar usando cron

Este exemplo de programa refresh a cada 15 minutos, no quarto de hora do fuso horário UTC:

SQL

CREATE OR REPLACE MATERIALIZED VIEW catalog.schema.regular_metrics
  SCHEDULE CRON '0 */15 * * * ?' AT TIME ZONE 'UTC'
AS SELECT
    date_trunc('minute', event_time) AS minute,
    count(*) AS events
FROM catalog.schema.raw_events
WHERE event_time > current_timestamp() - INTERVAL 1 HOUR
GROUP BY 1;

TarefaSQL em um Job

A atualização do pipeline pode ser orquestrada por meio de trabalhos LakeFlow , criando tarefas SQL que incluem o comando REFRESH . Essa abordagem integra a atualização pipeline na orquestração de fluxo de trabalho existente.

Existem duas maneiras de criar uma tarefa para atualizar as tabelas de transmissão:

• No Editor SQL : Digite o comando REFRESH e clique no botão do programador para criar um Job diretamente da consulta.
• Na interface de trabalho Jobs : Crie um novo Job, adicione um tipo de tarefa SQL e anexe uma consulta SQL ou Notebook com o comando REFRESHBLE .

O exemplo a seguir mostra a instrução SQL dentro de uma tarefa SQL que atualiza uma tabela de transmissão:

SQL

REFRESH STREAMING TABLE catalog.schema.sales;

Essa abordagem é apropriada quando:

• Um pipeline complexo com várias etapas possui dependências entre sistemas.
• É necessária integração com orquestração de Job existente.
• É necessário um sistema de alertas e monitoramento em nível Job .

A tarefa SQL utiliza tanto o SQL warehouse associado ao trabalho quanto o compute serverless que executa a refresh. Se o uso de programação baseada em definição de tabela de transmissão atender aos requisitos, a mudança para TRIGGER ON UPDATE ou SCHEDULE pode simplificar o fluxo de trabalho.

Adicionar um programador a um pipelineexistente

Para definir o programador após a criação, use a instrução ALTER STREAMING TABLE ou ALTER MATERIALIZED VIEW . Por exemplo:

SQL

-- Alters the schedule to refresh the streaming table when its upstream
-- data gets updated.
ALTER STREAMING TABLE sales
  ADD TRIGGER ON UPDATE;

Modificar um programador ou gatilho existente

Se um pipeline já tiver um programar ou gatilho associado, use ALTER SCHEDULE ou ALTER TRIGGER ON UPDATE para alterar a configuração refresh . Isso se aplica tanto à mudança de um programador para outro, de um gatilho para outro, quanto à troca entre um programador e um gatilho.

O exemplo a seguir altera um programa existente para refresh a cada 5 minutos:

SQL

ALTER STREAMING TABLE catalog.schema.my_table
  ALTER SCHEDULE EVERY 5 MINUTES;

Solte um programador ou gatilho

Para remover um programar, use ALTER ... DROP:

SQL

ALTER STREAMING TABLE catalog.schema.my_table
  DROP SCHEDULE;

Acompanhe o status de uma refresh

Você pode view o status de uma refresh visualizando o pipeline na interface do usuário do pipeline ou visualizando as informações de atualização retornadas pelo comando DESCRIBE EXTENDED para o dataset.

SQL

DESCRIBE TABLE EXTENDED <table-name>;

Alternativamente, você pode view o dataset no Explorador de Catálogo e verificar o status refresh lá:

1. Clique Catálogo na barra lateral.
2. Na árvore do Explorador de Catálogo à esquerda, abra o catálogo e selecione o esquema onde seu dataset está localizado.
3. Abra o item Tabelas no esquema selecionado e clique na tabela de transmissão ou view materializada.

A partir daqui, você pode usar a aba abaixo do nome dataset para view e editar informações sobre o dataset, incluindo:

• atualizar status e história
• O esquema da tabela
• Dados de exemplo (requer um compute ativo)
• Permissões
• Linhagem, incluindo tabelas e outros fluxos de dados dos quais este dataset depende.
• Introduzir ao uso
• Monitores que você criou para este dataset

Interrompa uma refreshativa.

Para interromper uma refresh ativa na interface Databricks , na página de detalhes do pipeline, clique em Parar para interromper a atualização pipeline . Você também pode interromper a refresh com a CLIDatabricks ou com o comando POST /api/2.0/pipeline/{pipeline_id}/stop. operações na API REST do pipeline.

veja a história de execução para uma refreshagendada

Se você abrir seu dataset no Catalog Explorer, o painel de detalhes no lado direito da workspace mostrará o programa de atualização . Clicar no link "programar" (por exemplo, "A cada 1 hora ") leva você à página da tarefa (gerenciamento de sistema) que executa o programa. Você pode ver a história da execução, incluindo um gráfico das últimas 48 horas de execução, incluindo sucesso ou fracasso e tempo gasto. Você pode clicar em uma execução específica para obter mais detalhes.

Você não pode editar esta tarefa de gerenciamento do sistema. Para fazer alterações no programar, edite a definição do pipeline com CREATE OR REFRESH ou com ALTER. Consulte Modificar um programador ou gatilho existente.

Tempo limite para atualização

A atualização do pipeline é uma execução com um tempo limite que restringe a duração de sua execução. Para pipelines Databricks SQL criados ou atualizados a partir de 14 de agosto de 2025, o tempo limite é capturado quando você atualiza executando CREATE OR REFRESH:

• Se um STATEMENT_TIMEOUT for definido, esse valor será usado. Consulte STATEMENT_TIMEOUT.
• Caso contrário, será utilizado o tempo limite do SQL warehouse usado para a execução do comando.
• Se o armazém não tiver um tempo limite configurado, será aplicado um default de 2 dias.

O tempo limite é utilizado na criação inicial, mas também nas atualizações agendadas subsequentes.

Para tabelas de transmissão cuja última atualização ocorreu antes de 14 de agosto de 2025, o tempo limite é definido para 2 dias.

Exemplo: Defina um tempo limite para uma refresh Você pode controlar explicitamente por quanto tempo uma refresh pode ser executada definindo um tempo limite no nível da instrução ao criar ou atualizar o dataset:

SQL

SET STATEMENT_TIMEOUT = '6h';

CREATE OR REFRESH MATERIALIZED VIEW my_catalog.my_schema.my_mv
  SCHEDULE EVERY 12 HOURS
AS SELECT * FROM large_source_table;

Isso configura a view materializada para ser atualizada a cada 12 horas e, se uma refresh demorar mais de 6 horas, ela expira e aguarda a próxima refresh agendada.

Como lidar com timeouts em atualizações agendadas

Os tempos limite são sincronizados apenas quando você executa explicitamente CREATE OR REFRESH.

• A atualização agendada continua usando o tempo limite capturado durante o último CREATE OR REFRESH.
• Alterar o tempo limite do repositório de dados por si só não afeta as atualizações agendadas existentes.

importante

Após alterar o tempo limite do armazém, execute CREATE OR REFRESH novamente para aplicar o novo tempo limite à atualização agendada futura.

Receba notificações para atualizações agendadas.

info

Beta

As notificações para atualização agendada de recursos DDL estão em versão Beta. Os administradores do espaço de trabalho podem controlar o acesso a este recurso na página de Pré-visualizações , ativando a opção " Job de gerenciamento do sistema para visualização materializada e tabelas de transmissão" . Veja as prévias do Gerenciador Databricks.

Ao criar um programa para seu pipeline, você pode editá-lo para receber notificações. Existem várias maneiras de programar um pipeline, e o recebimento de notificações depende do método escolhido:

• Agendado com uma tarefa : Para receber notificações de uma tarefa SQL no LakeFlow Jobs, edite a tarefa e adicione as notificações. Consulte a tarefaSQL para Job.

  Você tem uma ampla variedade de opções para as notificações que deseja receber e como recebê-las. Consulte Adicionar notificações a uma tarefa

• Agendado com uma cláusula SCHEDULE : Para receber notificações de um pipeline agendado por uma cláusula SCHEDULE na definição SQL, edite-o no Explorador de Catálogo:

  1. Abra o dataset no Explorador de Catálogo.

  2. Na tab Visão geral , em Atualizar programa , clique em Para editar o programa para o qual você deseja receber notificações.

  3. Em Mais opções , adicione ou modifique as notificações.

     Você tem a opção de receber notificações por email sobre o início, sucesso ou falha da refresh agendada. Por default, o proprietário é notificado apenas em caso de falha.

     O email inclui um link que leva você à história de execução do sistema de gerenciamento do Job que orquestra seu programar. Veja a história da execução para uma refreshagendada.

Selecione um modo de desempenho para atualização agendada

O compute serverless é utilizado pela execução do pipeline no modo otimizado para desempenho quando a execução é feita através da interface do usuário.

Para pipelines agendados na definição SQL , você pode selecionar o modo de desempenho compute serverless usando a configuração otimizada para desempenho no Explorador de Catálogo. Quando essa configuração está desativada (o default), o pipeline usa o modo de desempenho padrão. O modo de desempenho padrão foi projetado para reduzir custos em cargas de trabalho onde uma latência de inicialização ligeiramente maior é aceitável. As cargas de trabalho sem servidor que utilizam o modo de desempenho padrão normalmente iniciam dentro de quatro a seis minutos após serem acionadas, dependendo da disponibilidade compute e da programação otimizada.

Quando a otimização de desempenho está ativada, seu pipeline é otimizado para alto desempenho, resultando em startup e execução mais rápidas para cargas de trabalho sensíveis ao tempo.

Ambos os modos usam o mesmo SKU, mas o modo de desempenho padrão consome menos DBUs, refletindo um menor uso compute .

info

Beta

A modificação do modo de desempenho para atualização agendada está em versão Beta. Os administradores do espaço de trabalho podem controlar o acesso a este recurso na página de Pré-visualizações , ativando a opção " Job de gerenciamento do sistema para visualização materializada e tabelas de transmissão" . Veja as prévias do Gerenciador Databricks.

Por default, o pipeline usa o modo otimizado para desempenho quando executado interativamente na interface do usuário ou quando agendado com uma tarefaSQL, e usa o modo padrão quando agendado. Para definir o modo compute para o pipeline agendado por uma cláusula SCHEDULE na definição, edite o programa no Explorador de Catálogo:

1. Abra o dataset no Explorador de Catálogo.
2. Na tab Visão geral , em Atualizar programa , clique em Para editar o programa que você deseja modificar.
3. Verifique se o modo de desempenho otimizado foi ativado para usar o modo de desempenho otimizado em futuras atualizações agendadas.