Use tabelas de transmissão no Databricks SQL

Databricks recomenda usar tabelas de transmissão para ingerir uso de dados Databricks SQL. Uma tabela de transmissão é uma tabela registrada no Unity Catalog com suporte extra para transmissão ou processamento incremental de dados. Um pipeline é criado automaticamente para cada tabela de transmissão. Você pode usar tabelas de transmissão para carregamento incremental de dados do Kafka e armazenamento de objetos cloud .

nota

Para aprender como usar tabelas Delta Lake como fontes e coletores de transmissão, consulte Leituras e gravações de transmissão de tabelasDelta.

Requisitos

Para usar tabelas de transmissão, você deve atender aos seguintes requisitos.

requisitos do espaço de trabalho :

As tabelas de transmissão criadas no Databricks SQL são apoiadas pelo pipeline declarativo LakeFlow serverless . Seu workspace deve oferecer suporte ao pipeline serverless para usar essa funcionalidade.

• Uma account Databricks com serverless habilitado. Para obter mais informações, consulte Habilitar warehouse SQL serverless.
• Um workspace com Unity Catalog habilitado. Para obter mais informações, consulte Começar com Unity Catalog.

requisitos de computação :

Você deve usar um dos seguintes:

• Um SQL warehouse que usa o canal Current .

• calcular com modo de acesso padrão (antigo modo de acesso compartilhado) no Databricks Runtime 13.3 LTS ou acima.

• calcular com modo de acesso dedicado (antigo modo de acesso de usuário único) no Databricks Runtime 15.4 LTS ou acima.

  No Databricks Runtime 15.3 e abaixo, você não pode usar compute dedicada para consultar tabelas de transmissão que são de propriedade de outros usuários . Você pode usar compute dedicada no Databricks Runtime 15.3 e abaixo somente se você possuir a tabela de transmissão. O criador da tabela é o proprietário.

  Databricks Runtime 15.4 LTS e acima oferecem suporte à consulta de tabelas geradas pelo pipeline declarativo LakeFlow em compute dedicada, mesmo que você não seja o proprietário da tabela. Você pode ser cobrado por recursos compute serverless ao usar compute dedicada para executar operações de filtragem de dados. Veja Controle de acesso refinado em computededicada.

Requisitos de permissão :

• USE CATALOG e privilégios USE SCHEMA no catálogo e esquema nos quais você cria a tabela de transmissão.
• O privilégio CREATE TABLE no esquema no qual você cria a tabela de transmissão.
• Privilégios para acessar as tabelas ou locais que fornecem os dados de origem para sua tabela de transmissão.

Criar tabelas de transmissão

Uma tabela de transmissão é definida por uma consulta SQL no Databricks SQL. Quando você cria uma tabela de transmissão, os dados atualmente nas tabelas de origem são usados para construir a tabela de transmissão. Depois disso, você refresh a tabela, geralmente em um programa, para extrair quaisquer dados adicionados nas tabelas de origem para anexar à tabela de transmissão.

Ao criar uma tabela de transmissão, você é considerado o proprietário da tabela.

Para criar uma tabela de transmissão a partir de uma tabela existente, use a instruçãoCREATE STREAMING TABLE, como no exemplo a seguir:

SQL

CREATE OR REFRESH STREAMING TABLE sales
  SCHEDULE EVERY 1 hour
  AS SELECT product, price FROM STREAM raw_data;

Neste caso, a tabela de transmissão sales é criada a partir de colunas específicas da tabela raw_data , com um programa para refresh a cada hora. A consulta utilizada deve ser uma consulta de transmissão . Use a palavra-chave STREAM para usar a semântica de transmissão para ler a fonte.

Quando você cria uma tabela de transmissão usando a instrução CREATE OR REFRESH STREAMING TABLE , a refresh inicial dos dados e o preenchimento começam imediatamente. Essas operações não consomem compute do armazém DBSQL. Em vez disso, a tabela de transmissão depende do pipeline declarativo LakeFlow serverless para criação e refresh. Um pipeline serverless dedicado é criado e gerenciado automaticamente pelo sistema para cada tabela de transmissão.

Carregar arquivos com o Auto Loader

Para criar uma tabela de transmissão a partir de arquivos em um volume, use Auto Loader. Use Auto Loader com o pipeline declarativo LakeFlow para a maioria das tarefas de aquisição de dados do armazenamento de objetos cloud . Auto Loader e o pipeline declarativo LakeFlow foram projetados para carregar de forma incremental e idempotente dados cada vez maiores conforme eles chegam ao armazenamento cloud .

Para usar o Auto Loader no Databricks SQL, use a função read_files . Os exemplos a seguir mostram o uso do Auto Loader para ler um volume de arquivos JSON em uma tabela de transmissão:

SQL

CREATE OR REFRESH STREAMING TABLE sales
  SCHEDULE EVERY 1 hour
  AS SELECT * FROM STREAM read_files(
    "/Volumes/my_catalog/my_schema/my_volume/path/to/data",
    format => "json"
  );

Para ler dados do armazenamento cloud , você também pode usar Auto Loader:

SQL

CREATE OR REFRESH STREAMING TABLE sales
  SCHEDULE EVERY 1 hour
  AS SELECT *
  FROM STREAM read_files(
  's3://mybucket/analysis/*/*/*.json',
    format => "json"
  );

Para saber mais sobre o Auto Loader, veja O que é o Auto Loader?. Para saber mais sobre como usar Auto Loader no SQL, com exemplos, consulte Carregar dados do armazenamento de objetos.

ingestão de transmissão de outras fontes

Para obter um exemplo de ingestão de outras fontes, incluindo Kafka, consulte Carregar dados com o pipeline declarativo LakeFlow.

Ingerir apenas novos dados

Por default, a função read_files lê todos os dados existentes no diretório de origem durante a criação da tabela e, em seguida, processa os novos registros que chegam a cada refresh.

Para evitar a ingestão de dados que já existem no diretório de origem no momento da criação da tabela, defina a opção includeExistingFiles como false. Isso significa que somente os dados que chegam ao diretório após a criação da tabela são processados. Por exemplo:

SQL

CREATE OR REFRESH STREAMING TABLE sales
  SCHEDULE EVERY 1 hour
  AS SELECT *
  FROM STREAM read_files(
    '/path/to/files',
    includeExistingFiles => false
  );

Definir o canal de tempo de execução

As tabelas de transmissão criadas usando SQL Warehouse são atualizadas automaticamente usando um pipeline. O pipeline declarativo LakeFlow usa o tempo de execução no canal current por default. Consulte Notas sobre a versão do pipeline declarativoLakeFlow e o processo de atualização da versão para saber mais sobre o processo de versão.

A Databricks recomenda usar o canal current para cargas de trabalho de produção. Novos recursos são lançados primeiro no canal preview . Você pode definir um pipeline para o canal de pipeline declarativo LakeFlow de visualização para testar um novo recurso especificando preview como uma propriedade de tabela. Você pode especificar essa propriedade ao criar a tabela ou depois que ela for criada usando uma instrução ALTER.

O exemplo de código a seguir mostra como definir o canal para visualização em uma instrução CREATE:

SQL

CREATE OR REFRESH STREAMING TABLE sales
  TBLPROPERTIES ('pipelines.channel' = 'preview')
  SCHEDULE EVERY 1 hour
  AS SELECT *
  FROM STREAM raw_data;

programar transmissão atualização de tabela

Você pode configurar uma tabela de transmissão Databricks SQL para refresh automaticamente com base em um programa definido ou para disparar quando os dados upstream forem alterados.

info

Beta

O recurso TRIGGER ON UPDATE está em Beta. Para habilitar esse recurso no seu workspace, entre em contato com seu representante Databricks .

Para definir um programa ou gatilho, faça um dos seguintes:

• Configure o programa com a cláusula SCHEDULE ao criar a tabela de transmissão.
• Configure um gatilho com a cláusula TRIGGER ON UPDATE ao criar a tabela.
• Adicione ou modifique programas ou gatilhos com a instrução ALTER STREAMING TABLE .

nota

Como alternativa, crie uma tarefa em um Job que inclua a instrução CREATE OR REFRESH STREAMING TABLE ou REFRESH e orquestre-a como faria com qualquer outro Job. Veja empregosLakeFlow.

Quando você cria um programa, Databricks cria automaticamente um novo Job para processar a atualização.

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

• execute a instrução DESCRIBE EXTENDED do editor SQL na interface do usuário Databricks . Veja DESCRIBE TABLE.
• Use o Catalog Explorer para view a tabela de transmissão. O programa está listado na tab Visão geral , em status de atualização . Veja O que é o Catalog Explorer?.

Mesmo com um programa de refresh , você pode executar uma refresh manual a qualquer momento se precisar atualizar dados.

Ocultar dados confidenciais

info

Visualização

Este recurso está em Visualização Pública.

Você pode usar tabelas de transmissão para ocultar dados confidenciais de usuários que acessam a tabela. Uma abordagem é definir a consulta de modo que ela exclua completamente colunas ou linhas confidenciais. Como alternativa, você pode aplicar máscaras de coluna ou filtros de linha com base nas permissões do usuário que faz a consulta. Por exemplo, você pode ocultar a coluna tax_id para usuários que não estão no grupo HumanResourcesDept. Para fazer isso, use a sintaxe ROW FILTER e MASK durante a criação da tabela de transmissão. Para mais informações, consulte Filtros de linha e máscaras de coluna.

atualizar uma tabela de transmissão

a atualização pode ser agendada automaticamente quando você cria a tabela de transmissão. Você também pode refresh manualmente as tabelas de transmissão. Mesmo que você tenha uma refresh agendada, você pode chamar uma refresh manual a qualquer momento. as atualizações são manipuladas pelo mesmo pipeline que foi criado automaticamente junto com a tabela de transmissão.

Para refresh uma tabela de transmissão:

SQL

REFRESH STREAMING TABLE sales;

Você pode verificar o status da refresh mais recente com DESCRIBE TABLE EXTENDED.

nota

Somente o proprietário da tabela pode refresh uma tabela de transmissão para obter os dados mais recentes. O usuário que cria a tabela é o proprietário, e o proprietário não pode ser alterado. Talvez seja necessário refresh sua tabela de transmissão antes de usar consultas de viagem do tempo .

Como funciona refresh

Uma refresh de tabela de transmissão avalia apenas as novas linhas que chegaram desde a última atualização e acrescenta apenas os novos dados.

Cada refresh usa a definição atual da tabela de transmissão para processar esses novos dados. Modificar uma definição de tabela de transmissão não recalcula automaticamente os dados existentes. Se uma modificação for incompatível com os dados existentes (por exemplo, alteração de um tipo de dado), a próxima refresh falhará com um erro.

Os exemplos a seguir explicam como as alterações em uma definição de tabela de transmissão afetam o comportamento refresh :

• Remover um filtro não reprocessará linhas filtradas anteriormente.
• Alterar as projeções das colunas não afetará o modo como os dados existentes foram processados.
• junte-se ao Snapshot estático e use o estado do Snapshot no momento do processamento inicial. Dados recebidos tardiamente que corresponderiam ao Snapshot atualizado serão ignorados. Isso pode levar à perda de fatos caso as dimensões sejam atrasadas.
• Modificar o CAST de uma coluna existente resultará em um erro.

Se seus dados forem alterados de uma forma que não possa ser suportada na tabela de transmissão existente, você poderá executar uma refresh completa.

refresh totalmente uma tabela de transmissão

Atualização completa reprocessa todos os dados disponíveis na fonte com a definição mais recente. Não é recomendado chamar a atualização completa em fontes que não mantêm o histórico completo dos dados ou têm períodos de retenção curtos, como Kafka, porque a refresh completa trunca os dados existentes. Talvez você não consiga recuperar dados antigos se eles não estiverem mais disponíveis na fonte.

Por exemplo:

SQL

REFRESH STREAMING TABLE sales FULL;

Alterar o programar para uma tabela de transmissão

Você pode modificar (ou definir) um programa refresh automática para sua tabela de transmissão. Os exemplos a seguir mostram como definir um programa usando ALTER STREAMING TABLE:

SQL

ALTER STREAMING TABLE sales
  ADD SCHEDULE every 1 hour;

Por exemplo, refresh consultas de programa, consulte ALTER STREAMING TABLE.

Acompanhe o status de uma refresh

Você pode view o status de uma refresh da tabela de transmissão visualizando o pipeline que gerencia a tabela de transmissão na interface do pipeline declarativa LakeFlow ou visualizando as informações de atualização retornadas pelo comando DESCRIBE EXTENDED para a tabela de transmissão.

SQL

DESCRIBE TABLE EXTENDED <table-name>;

Como alternativa, você pode view a tabela de transmissão no Catalog Explorer e ver o status refresh lá:

1. Clique Catálogo na barra lateral.
2. Na árvore do Catalog Explorer à esquerda, abra o catálogo e selecione o esquema onde sua tabela de transmissão está localizada.
3. Abra o item Tabelas no esquema selecionado e clique na tabela de transmissão.

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

• atualizar status e histórico
• O esquema da tabela
• Dados de amostra (requer um compute ativo)
• Permissões
• Linhagem, incluindo tabelas e pipeline dos quais esta tabela de transmissão depende
• percepções sobre o uso
• Monitores que você criou para esta tabela de transmissão

Tempo limite para atualização

Uma atualização de longa duração pode expirar. As tabelas de transmissão criadas ou atualizadas após 14 de agosto de 2025 usarão o tempo limite associado ao SQL warehouse usado para executar a refresh. Se o depósito não tiver um tempo limite definido, o default de 2 dias será usado.

nota

A tabela de transmissão só sincroniza o tempo limite quando você executa manualmente uma instrução CREATE OR REFRESH . As atualizações agendadas mantêm o tempo limite do CREATE OR REFRESH mais recente.

Você pode definir explicitamente o tempo limite com uma configuração STATEMENT_TIMEOUT no seu SQL para a refresh. Veja STATEMENT_TIMEOUT.

Controlar o acesso às tabelas de transmissão

As tabelas de transmissão oferecem suporte a controles de acesso avançados para dar suporte ao compartilhamento de dados, evitando a exposição de dados potencialmente privados. Um proprietário de tabela de transmissão ou um usuário com o privilégio MANAGE pode conceder privilégios SELECT a outros usuários. Usuários com acesso SELECT à tabela de transmissão não precisam de acesso SELECT às tabelas referenciadas pela tabela de transmissão. Esse controle de acesso permite o compartilhamento de dados enquanto controla o acesso aos dados subjacentes.

Conceder privilégios a uma tabela de transmissão

Para conceder acesso a uma tabela de transmissão, use a instruçãoGRANT:

SQL

GRANT <privilege_type> ON <st_name> TO <principal>;

O privilege_type pode ser:

• SELECT - o usuário pode SELECT a tabela de transmissão.
• REFRESH - o usuário pode REFRESH a tabela de transmissão. atualização são executadas usando as permissões do proprietário.

O exemplo a seguir cria uma tabela de transmissão e concede privilégios de seleção e refresh aos usuários:

SQL

CREATE MATERIALIZED VIEW st_name AS SELECT * FROM source_table;

-- Grant read-only access:
GRANT SELECT ON st_name TO read_only_user;

-- Grand read and refresh access:
GRANT SELECT ON st_name TO refresh_user;
GRANT REFRESH ON st_name TO refresh_user;

Para obter mais informações sobre como conceder privilégios em objetos protegíveis Unity Catalog , consulte Privilégios e objetos protegíveisUnity Catalog.

Revogar privilégios de uma tabela de transmissão

Para revogar o acesso de uma tabela de transmissão, use a instruçãoREVOKE:

SQL

REVOKE privilege_type ON <st_name> FROM principal;

Quando os privilégios SELECT em uma tabela de origem são revogados do proprietário da tabela de transmissão ou de qualquer outro usuário que tenha recebido privilégios MANAGE ou SELECT na tabela de transmissão, ou a tabela de origem é descartada, o proprietário da tabela de transmissão ou o usuário que recebeu acesso ainda pode consultar a tabela de transmissão. Entretanto, ocorre o seguinte comportamento:

• O proprietário da tabela de transmissão ou outros que perderam o acesso a uma tabela de transmissão não poderão mais REFRESH essa tabela de transmissão, e a tabela de transmissão ficará obsoleta.
• Se automatizado com um programador, o próximo REFRESH agendado falha ou não é executado.

O exemplo a seguir revoga o privilégio SELECT de read_only_user:

SQL

REVOKE SELECT ON st_name FROM read_only_user;

Excluir permanentemente registros de uma tabela de transmissão

info

Visualização

O suporte para a instrução REORG com tabelas de transmissão está em Visualização Pública.

nota

• Usar uma instrução REORG com uma tabela de transmissão requer Databricks Runtime 15.4 e acima.
• Embora você possa usar a instrução REORG com qualquer tabela de transmissão, ela só é necessária ao excluir registros de uma tabela de transmissão com vetores de exclusão habilitados. O comando não tem efeito quando usado com uma tabela de transmissão sem vetores de exclusão habilitados.

Para excluir fisicamente registros do armazenamento subjacente para uma tabela de transmissão com vetores de exclusão habilitados, como para compliance GDPR , etapas adicionais devem ser tomadas para garantir que uma execução de operações vacuum nos dados da tabela de transmissão.

Para excluir fisicamente registros do armazenamento subjacente:

1. Atualizar registros ou excluir registros da tabela de transmissão.
2. executar uma instrução REORG na tabela de transmissão, especificando o parâmetro APPLY (PURGE) . Por exemplo REORG TABLE <streaming-table-name> APPLY (PURGE);.
3. Aguarde o período de retenção de dados da tabela de transmissão passar. O período default de retenção de dados é de sete dias, mas pode ser configurado com a propriedade da tabela delta.deletedFileRetentionDuration . Consulte Configurar retenção de dados para consultas de viagem do tempo.
4. REFRESH a tabela de transmissão. Veja atualizar uma tabela de transmissão. Dentro de 24 horas das operações REFRESH , a tarefa de manutenção do pipeline declarativo LakeFlow , incluindo as operações VACUUM necessárias para garantir que os registros sejam excluídos permanentemente, são executadas automaticamente.

Monitore a execução usando query história

Você pode usar a página de histórico de consultas para acessar detalhes e perfis de consultas que podem ajudar a identificar consultas com baixo desempenho e gargalos no pipeline declarativo LakeFlow usado para executar suas atualizações de tabela de transmissão. Para uma visão geral do tipo de informação disponível na consulta história e nos perfis de consulta, consulte Consulta história e Consulta perfil.

info

Visualização

Este recurso está em Visualização Pública. Os administradores do espaço de trabalho podem controlar o acesso a este recurso na página Visualizações . Veja as prévias do gerenciar Databricks.

Todas as declarações relacionadas às tabelas de transmissão aparecem na consulta história. Você pode usar o filtro suspenso Instrução para selecionar qualquer comando e inspecionar as consultas relacionadas. Todas as instruções CREATE são seguidas por uma instrução REFRESH que é executada de forma assíncrona em um pipeline. As instruções REFRESH normalmente incluem planos de consulta detalhados que fornecem percepções para otimizar o desempenho.

Para acessar instruções REFRESH na interface de usuário do histórico de consulta, use os seguintes passos:

1. Clique na barra lateral esquerda para abrir a interface do usuário Query History .
2. Selecione a caixa de seleção REFRESH no filtro suspenso Declaração .
3. Clique no nome da instrução de consulta para view detalhes resumidos, como a duração da consulta e métricas agregadas.
4. Clique em Ver perfil de consulta para abrir o perfil de consulta. Consulte Perfil de consulta para obter detalhes sobre como navegar no perfil de consulta.
5. Opcionalmente, você pode usar os links na seção Fonte da consulta para abrir a consulta ou o pipeline relacionado.

Você também pode acessar detalhes da consulta usando links no editor SQL ou em um Notebook anexado a um SQL warehouse.

Recurso adicional

• Pipelines Declarativos do LakeFlow
• read_files função com valor de tabela
• read_kafka função com valor de tabela
• CREATE STREAMING TABLE
• ALTER STREAMING TABLE
• Usar visualizações materializadas no Databricks SQL