Usar tabelas de streaming no Databricks SQL

O Databricks recomenda usar tabelas de streaming para ingerir dados usando o Databricks SQL. Uma tabela de streaming é uma tabela registrada no Catálogo do Unity com suporte extra para streaming ou processamento de dados incrementais. Um pipeline é criado automaticamente para cada tabela de streaming. Você pode usar as tabelas de streaming para o carregamento incremental de dados do Kafka e do armazenamento de objetos na nuvem.

Requirements

Para usar tabelas de streaming, você deve atender aos seguintes requisitos.

Requisitos do espaço de trabalho:

As tabelas de streaming criadas no DATAbricks SQL são apoiadas por pipelines sem servidor. Seu workspace precisa dar suporte aos pipelines sem servidor para usar essa funcionalidade.

• Uma conta do Azure Databricks sem servidor habilitada. Para obter mais informações, consulte Habilitar os SQL Warehouses sem servidor.
• Um espaço de trabalho com o Catálogo do Unity habilitado. Para obter mais informações, consulte Introdução ao Catálogo do Unity.

Requisitos de computação:

Você deverá usar um dos seguintes:

• Um SQL Warehouse que usa o canal Current.
• Compute com o modo de acesso padrão (antigo modo de acesso compartilhado) no Databricks Runtime 13.3 LTS ou superior.

• Computação com o modo de acesso dedicado (antigo modo de acesso de usuário único) no Databricks Runtime 15.4 LTS ou superior.

  No Databricks Runtime 15.3 e abaixo, você não pode usar computação dedicada para consultar tabelas de streaming que pertencem a outros usuários. Você pode usar a computação dedicada no Databricks Runtime 15.3 e abaixo somente se você for o proprietário da tabela de streaming. O criador da tabela é o proprietário.

  O Databricks Runtime 15.4 LTS e acima dão suporte à consulta de tabelas geradas por pipeline na computação dedicada, mesmo que você não seja o proprietário da tabela. Você pode ser cobrado por recursos de computação sem servidor ao usar a computação dedicada para executar operações de filtragem de dados. Consulte o controle de acesso refinado na computação dedicada.

Requisitos de permissões:

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

Criar tabelas de streaming

Uma tabela de streaming é definida por uma consulta SQL no Databricks SQL. Quando você cria uma tabela de streaming, os dados atualmente nas tabelas de origem são usados para criar a tabela de streaming. Depois disso, você atualiza a tabela, geralmente de acordo com um cronograma, para extrair todos os dados adicionados nas tabelas de origem e acrescentá-los à tabela de streaming.

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

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

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

Nesse caso, a tabela de streaming sales é criada a partir de colunas específicas da tabela raw_data, programada para atualizar a cada hora. A consulta usada deve ser uma consulta de streaming . Use a palavra-chave STREAM para usar a semântica de streaming para leitura da origem.

Quando você cria uma tabela de streaming usando a CREATE OR REFRESH STREAMING TABLE instrução, a atualização de dados inicial e a população começam imediatamente. Essas operações não consomem computação de warehouse DBSQL. Em vez disso, a tabela de streaming depende de pipelines sem servidor para criação e atualização. Um pipeline dedicado sem servidor é criado e gerenciado automaticamente pelo sistema para cada tabela de streaming.

Carregar arquivos com o Carregador Automático

Para criar uma tabela de streaming com base em arquivos em um volume, use o Carregador Automático. Use o Carregador Automático para a maioria das tarefas de ingestão de dados do armazenamento de objetos na nuvem. O Carregador Automático e os pipelines são projetados para carregar dados cada vez maiores de forma incremental e idempotente à medida que chegam ao armazenamento em nuvem.

Para usar o Carregador Automático no SQL do Databricks, use a função read_files. Os exemplos a seguir mostram como usar o Carregador Automático para ler um volume de arquivos JSON em uma tabela de streaming:

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 em nuvem, você também pode usar o Carregador Automático:

CREATE OR REFRESH STREAMING TABLE sales
  SCHEDULE EVERY 1 hour
  AS SELECT *
  FROM STREAM read_files(
    'abfss://myContainer@myStorageAccount.dfs.core.windows.net/analysis/*/*/*.json',
    format => "json"
  );

Para saber mais sobre o Carregador Automático, confira o que é o Carregador Automático?. Para saber mais sobre como usar o Carregador Automático no SQL, com exemplos, consulte Carregar dados do armazenamento de objetos.

Ingestão de streaming de outras fontes

Um exemplo de ingestão a partir de outras fontes, incluindo o Kafka, pode ser visto em Carregar dados em pipelines.

Ingerir apenas novos dados

Por padrão, a função read_files lê todos os dados existentes no diretório de origem durante a criação da tabela e processa registros recém-chegados com cada atualização.

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 para false. Isso significa que somente os dados que chegam ao diretório após a criação da tabela são processados. Por exemplo:

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

Definir o canal do runtime

As tabelas de streaming criadas usando os sql warehouses são atualizadas automaticamente usando um pipeline. Os pipelines usam o runtime no canal current por padrão. Confira as notas de versão do Lakeflow Spark Declarative Pipelines e o processo de atualização de versão para saber mais sobre o processo de lançamento.

O Databricks recomenda usar o canal current nas cargas de trabalho de produção. Os novos recursos são lançados pela primeira vez no canal preview. Você pode definir um pipeline para o canal de visualização para testar novos recursos especificando preview como uma propriedade de tabela. Você pode especificar essa propriedade ao criar a tabela ou depois que a tabela 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:

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

Agendar atualizações da tabela de streaming

Você pode configurar uma tabela de streaming do Databricks SQL para atualizar automaticamente com base em um agendamento definido ou disparar quando os dados upstream forem alterados.

Para definir um agendamento ou gatilho, siga um destes procedimentos:

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

Quando você cria uma agenda, o Azure Databricks cria automaticamente um novo trabalho para processar a atualização.

Para exibir o agendamento, siga um destes procedimentos:

• Execute a DESCRIBE EXTENDED instrução do editor do SQL na interface do usuário do Azure Databricks. Consulte DESCRIBE TABLE.
• Use o Gerenciador de Catálogos para exibir a tabela de streaming. O agendamento está listado na guia Visão geral , em Status de atualização. Consulte O que é o Explorador de Catálogos?.

Mesmo com um agendamento de atualização, você pode executar uma atualização manual a qualquer momento se precisar de dados atualizados.

Ocultar dados confidenciais

Você pode usar tabelas de streaming para ocultar dados confidenciais de usuários que acessam a tabela. Uma abordagem é definir a consulta para que ela exclua totalmente 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 está consultando. Por exemplo, você pode ocultar a tax_id coluna 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 streaming. Para obter mais informações, consulte Filtros de linha e máscaras de coluna.

Atualizar uma tabela de streaming

As atualizações podem ser agendadas automaticamente quando você cria a tabela de streaming. Você também pode atualizar manualmente as tabelas de streaming. Mesmo se você tiver uma atualização agendada, poderá chamar uma atualização manual a qualquer momento. As atualizações são tratadas pelo mesmo pipeline que foi criado automaticamente junto com a tabela de streaming.

Para atualizar uma tabela de streaming:

REFRESH STREAMING TABLE sales;

Você pode verificar o status da atualização mais recente com DESCRIBE TABLE EXTENDED.

Como funciona a atualização

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

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

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

• A remoção de um filtro não processará novamente linhas filtradas anteriormente.
• A alteração das projeções de coluna não afetará a forma como os dados existentes foram processados.
• As junções com instantâneos estáticos usam o estado do instantâneo no momento do processamento inicial. Dados que chegam atrasados e que teriam correspondido ao instantâneo atualizado serão ignorados. Isso pode levar à remoção de fatos se as dimensões estiverem atrasadas.
• Modificar o CAST de uma coluna existente resultará em um erro.

Se os dados forem alterados de uma maneira que não tenha suporte na tabela de streaming existente, você poderá executar uma atualização completa.

Atualizar totalmente uma tabela de streaming

As atualizações completas reprocessam todos os dados disponíveis na origem com a definição mais recente. Não é recomendável chamar atualizações completas em fontes que não mantêm todo o histórico dos dados ou têm períodos de retenção curtos, como Kafka, porque a atualização completa trunca os dados existentes. É possível que você não precise recuperar dados antigos se os dados não estiverem mais disponíveis na origem.

Por exemplo:

REFRESH STREAMING TABLE sales FULL;

Alterar a agenda de uma tabela de streaming

Você pode modificar (ou definir) uma agenda de atualização automática para sua tabela de streaming. Os exemplos a seguir mostram como definir uma agenda usando ALTER STREAMING TABLE:

ALTER STREAMING TABLE sales
  ADD SCHEDULE EVERY 1 HOUR;

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

Para obter exemplos de consultas de atualização de agendamento, veja ALTER STREAMING TABLE.

Acompanhar o status de uma atualização

Você pode exibir o status de uma atualização de tabela de streaming exibindo o pipeline que gerencia a tabela de streaming na interface do usuário do Pipelines ou exibindo as Informações de Atualização retornadas pelo DESCRIBE EXTENDED comando da tabela de streaming.

DESCRIBE TABLE EXTENDED <table-name>;

Como alternativa, você pode exibir a tabela de streaming no Gerenciador de Catálogos e ver o status da atualização lá:

1. Clique no Catálogo na barra lateral.
2. Na árvore do Gerenciador de Catálogos à esquerda, abra o catálogo e selecione o esquema em que a tabela de streaming está localizada.
3. Abra o item Tabelas no esquema selecionado e clique na tabela de streaming.

A partir daqui, você pode usar as guias sob o nome da tabela de streaming para exibir e editar informações sobre a tabela de streaming, incluindo:

• Atualizar status e histórico
• O esquema de tabela
• Dados de exemplo (exigem uma computação ativa)
• Permissions
• Linhagem, incluindo tabelas e pipelines dos quais essa tabela de streaming depende
• Insights sobre o uso
• Monitores que você criou para esta tabela de streaming

Tempos limite para atualizações

Atualizações de execução longa podem ter tempo limite. As tabelas de streaming criadas ou atualizadas após 14 de agosto de 2025 usarão o tempo limite associado ao SQL Warehouse usado para executar a atualização. Se o armazém não tiver um tempo limite configurado, o padrão de 2 dias será aplicado.

Você pode definir explicitamente o tempo limite com uma STATEMENT_TIMEOUT configuração em seu SQL para a atualização. Consulte STATEMENT_TIMEOUT.

Controlar o acesso a tabelas de streaming

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

Você também pode modificar o proprietário de uma tabela de streaming.

Conceder privilégios a uma tabela de streaming

Para conceder acesso a uma tabela de streaming, use o GRANT comando:

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

Pode privilege_type ser:

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

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

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 a concessão de privilégios no Catálogo do Unity, consulte Privilégios e objetos protegíveis do Catálogo do Unity.

Revogar os privilégios de uma tabela de streaming

Para revogar o acesso a partir de uma tabela de streaming, use a REVOKE instrução:

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 streaming ou de qualquer outro usuário que tenha recebido privilégios MANAGE ou SELECT na tabela de streaming, ou a tabela de origem é excluída, o proprietário ou usuário concedido acesso ainda pode consultar a tabela de streaming. No entanto, ocorre o seguinte comportamento:

• O proprietário da tabela de streaming ou outras pessoas que perderam o acesso a uma tabela de streaming não podem mais REFRESH essa tabela de streaming e a tabela de streaming ficará obsoleta.
• Se automatizado com um agendamento, o próximo REFRESH agendado falhará ou não será executado.

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

REVOKE SELECT ON st_name FROM read_only_user;

Alterar o proprietário de uma tabela de streaming

Um usuário com MANAGE permissões em uma tabela de streaming definida no Databricks SQL pode definir um novo proprietário por meio do Gerenciador de Catálogos. O novo proprietário pode ser ele mesmo ou uma entidade de serviço na qual ele tem a função de Usuário da Entidade de Serviço .

1. No workspace do Azure Databricks, clique no Catálogo para abrir o Gerenciador de Catálogos.

2. Selecione a tabela de streaming que você deseja atualizar.

3. Na barra lateral direita, em Sobre essa tabela de streaming, localize o Proprietário e clique no para editar.

   Observação

   Se você receber uma mensagem informando para atualizar o proprietário alterando o usuário de Executar como nas configurações de pipeline, então a tabela de streaming é definida em Pipelines Declarativos do Lakeflow Spark, e não no Databricks SQL. A mensagem inclui um link para as configurações de pipeline, onde você pode alterar o usuário Executar como.

4. Selecione um novo proprietário para a tabela de streaming.

   Os proprietários têm privilégios MANAGE e SELECT automaticamente em tabelas de streaming que eles próprios possuem. Se você estiver definindo um principal de serviço como proprietário de uma tabela de streaming que você possui, e não tiver explicitamente os privilégios SELECT ou MANAGE na tabela de streaming, essa alteração fará com que você perca todo o acesso à tabela de streaming. Nesse caso, você será solicitado a fornecer explicitamente esses privilégios.

   Selecione os privilégios Grant MANAGE e Grant SELECT para fornecê-los no Save.

5. Clique em Salvar para alterar o proprietário.

O proprietário da tabela de streaming é atualizado. Todas as atualizações futuras são executadas usando a identidade do novo proprietário.

Quando o proprietário perde privilégios sobre as tabelas de origem

Se você alterar o proprietário e o novo proprietário não tiver acesso às tabelas de origem (ou SELECT os privilégios forem revogados nas tabelas de origem subjacentes), os usuários ainda poderão consultar a tabela de streaming. No entanto:

• Eles não podem acessar a tabela de streaming.
• A próxima atualização agendada da tabela de streaming falhará.

Perder o acesso aos dados de origem impede atualizações, mas não invalida imediatamente a leitura da tabela de streaming existente.

Excluir permanentemente registros de uma tabela de streaming

Para excluir fisicamente os registros do armazenamento subjacente de uma tabela de streaming com vetores de exclusão habilitados, como para conformidade com o GDPR, etapas adicionais devem ser tomadas para garantir que uma VACUUM operação seja executada nos dados da tabela de streaming.

Para excluir fisicamente os registros do armazenamento subjacente:

1. Atualize registros ou exclua registros da tabela de streaming.
2. Execute uma instrução REORG na tabela de streaming, especificando o parâmetro APPLY (PURGE). Por exemplo, REORG TABLE <streaming-table-name> APPLY (PURGE);.
3. Aguarde a passagem do período de retenção de dados da tabela de streaming. O período de retenção de dados padrão é de sete dias, mas pode ser configurado com a propriedade delta.deletedFileRetentionDuration tabela. Consulte Configurar retenção de dados para consultas de viagem no tempo.
4. REFRESH a tabela de streaming. Consulte Atualizar uma tabela de streaming. Dentro de 24 horas da operação, as REFRESH tarefas de manutenção do pipeline, incluindo a VACUUM operação necessária para garantir que os registros sejam excluídos permanentemente, são executadas automaticamente.

Monitorar as execuções usando o histórico de consultas

Você pode usar a página de histórico de consultas para acessar detalhes e perfis de consulta que podem ajudá-lo a identificar consultas com baixo desempenho e gargalos no pipeline utilizado para executar as atualizações da tabela de streaming. Para obter uma visão geral do tipo de informações disponíveis nos históricos de consulta e perfis de consulta, consulte Histórico de consultas e Perfil de consulta.

Todas as instruções relacionadas às tabelas de streaming aparecem no histórico de consultas. 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 modo assíncrono em um pipeline. Normalmente, as instruções REFRESH incluem planos de consulta detalhados que fornecem insights sobre como otimizar o desempenho.

Para acessar as declarações REFRESH na interface do usuário do histórico de consultas, siga os passos a seguir:

1. Clique no , na barra lateral esquerda para abrir a UI do histórico de consultas.
2. Selecione a caixa de seleção REFRESH do filtro suspenso Instrução.
3. Clique no nome da instrução de consulta para exibir os detalhes resumidos, como a duração da consulta e as métricas agregadas.
4. Clique em Ver o perfil de consulta para abrir o perfil de consulta. Consulte o Perfil de consulta para obter detalhes sobre como navegar no perfil de consulta.
5. Opcionalmente, você pode usar os links na seção Origem da Consulta para abrir a consulta ou o pipeline relacionado.

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

Acessar tabelas de transmissão de clientes externos

Para acessar tabelas de streaming de clientes externos do Delta Lake ou iceberg que não dão suporte a APIs abertas, você pode usar o Modo de Compatibilidade. O Modo de Compatibilidade cria uma versão somente leitura da tabela de streaming que pode ser acessada por qualquer cliente Delta Lake ou Iceberg.

Recursos adicionais

• Pipelines Declarativos Lakeflow Spark
• read_files Função com valor de tabela
• read_kafka Função com valor de tabela
• CREATE STREAMING TABLE
• ALTER STREAMING TABLE
• Usar exibições materializadas no DATAbricks SQL