Carregar dados usando tabelas de streaming no Databricks SQL

Artigo
11/16/2024

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 incremental. Um pipeline Delta Live Tables é criado automaticamente para cada tabela de streaming. Você pode usar tabelas de streaming para carregamento incremental de dados do Kafka e do armazenamento de objetos de nuvem.

Este artigo demonstra o uso de tabelas de streaming para carregar dados do armazenamento de objetos de nuvem configurados como um volume do Catálogo do Unity (recomendado) ou local externo.

Observação

Para saber como usar as tabelas do Delta Lake como fontes e coletores de streaming, consulte Leituras e gravações de streaming da tabela do Delta.

Importante

As tabelas de streaming criadas no Databricks SQL são apoiadas por um pipeline Delta Live Tables sem servidor. Seu workspace deve dar suporte a pipelines sem servidor para usar essa funcionalidade.

Antes de começar

Antes de começar, você precisará atender aos seguintes requisitos.

Requisitos do espaço de trabalho:

Uma conta do Azure Databricks sem servidor habilitada. Para obter mais informações, consulte Habilitar SQL warehouses sem servidor.
Um workspace com o Catálogo do Unity habilitado. Para obter mais informações, confira Configurar e gerenciar o 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 compartilhado no Databricks Runtime 13.3 LTS ou superior.
Compute com o modo de acesso de usuário único no Databricks Runtime 15.4 LTS ou superior.

No Databricks Runtime 15.3 e inferior, você não pode usar a computação de usuário único para consultar tabelas de streaming que pertencem a outros usuários. Você pode usar a computação de usuário único no Databricks Runtime 15.3 e inferior 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 superior dá suporte a consultas em tabelas geradas por Delta Live Tables na computação de usuário único, independentemente da propriedade da tabela. Para aproveitar a filtragem de dados fornecida no Databricks Runtime 15.4 LTS e superior, garanta que o seu espaço de trabalho está habilitado para computação sem servidor, porque a funcionalidade de filtragem de dados que dá suporte às tabelas geradas pelo Delta Live Tables é executada na computação sem servidor. Você pode ser cobrado por recursos de computação sem servidor ao usar a computação de usuário único para executar operações de filtragem de dados. Consulte Controle de acesso refinado na computação de usuário único.

Requisitos de permissões:

O privilégio READ FILES em um local externo do Catálogo do Unity. Para obter informações, confira Criar um local externo para conectar o armazenamento em nuvem ao Azure Databricks.
O privilégio USE CATALOG no catálogo no qual você cria a tabela de streaming.
O privilégio USE SCHEMA no esquema no qual você cria a tabela de streaming.
O privilégio CREATE TABLE no esquema no qual você cria a tabela de streaming.

Outros requisitos:

O caminho para os dados de origem.

Exemplo de caminho de volume: /Volumes/<catalog>/<schema>/<volume>/<path>/<file-name>

Exemplo de caminho de local externo: abfss://myContainer@myStorageAccount.dfs.core.windows.net/analysis

Observação

Este artigo pressupõe que os dados que você deseja carregar estão em um local de armazenamento em nuvem que corresponde a um volume do Catálogo do Unity ou ao local externo ao qual você tem acesso.

Descobrir e visualizar dados de origem

Na barra lateral do workspace, clique em Consultas e clique em Criar consulta.
No editor de consultas, selecione um SQL warehouse que usa o canal Current na lista suspensa.
Cole o seguinte no editor, substituindo valores em colchetes angulares (<>) pelas informações que identificam seus dados de origem e clique em Executar.

Observação

Você poderá encontrar erros de inferência de esquema ao executar a função read_files com valor de tabela se os padrões para a função não puderem analisar seus dados. Por exemplo, talvez seja necessário configurar o modo de várias linhas para arquivos CSV ou JSON de várias linhas. Para obter uma lista de opções de analisador, consulte Função com valor de tabela read_files.
```
/* Discover your data in a volume */
LIST "/Volumes/<catalog>/<schema>/<volume>/<path>/<folder>"

/* Preview your data in a volume */
SELECT * FROM read_files("/Volumes/<catalog>/<schema>/<volume>/<path>/<folder>") LIMIT 10

/* Discover your data in an external location */
LIST "abfss://<container>@<storage-account>.dfs.core.windows.net/<path>/<folder>"

/* Preview your data */
SELECT * FROM read_files("abfss://<container>@<storage-account>.dfs.core.windows.net/<path>/<folder>") LIMIT 10
```

Carregar dados em uma tabela de streaming

Para criar uma tabela de streaming com base em dados no armazenamento de objetos de nuvem, cole o seguinte no editor de consultas e clique em Executar:

/* Load data from a volume */
CREATE OR REFRESH STREAMING TABLE <table-name> AS
SELECT * FROM STREAM read_files('/Volumes/<catalog>/<schema>/<volume>/<path>/<folder>')

/* Load data from an external location */
CREATE OR REFRESH STREAMING TABLE <table-name> AS
SELECT * FROM STREAM read_files('abfss://<container>@<storage-account>.dfs.core.windows.net/<path>/<folder>')

Definir o canal de tempo de execução

As tabelas de streaming criadas usando SQL warehouses são atualizadas automaticamente usando um pipeline do Delta Live Tables. Os pipelines do Delta Live Tables usam o runtime no current canal por padrão. Consulte as notas de versão do Delta Live Tables e o processo de atualização de versão para saber mais sobre o processo de lançamento.

O Databricks recomenda usar o current canal para cargas de trabalho de produção. Novos recursos são lançados primeiro no preview canal. Você pode definir um pipeline para o canal de visualização do Delta Live Tables 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 REPLACE MATERIALIZED VIEW foo.default.bar
TBLPROPERTIES ('pipelines.channel' = 'preview') as
SELECT
  *
FROM
  range(5)

## <a id="refresh"></a> Refresh a <st> using a DLT pipeline

This section describes patterns for refreshing a <st> with the latest data available from the sources defined in the query.

When you `CREATE` or `REFRESH` a <st>, the update processes using a serverless <DLT> pipeline. Each <st> you define has an associated <DLT> pipeline.

After you run the `REFRESH` command, the DLT pipeline link is returned. You can use the DLT pipeline link to check the status of the refresh.

.. note:: Only the table owner can refresh a <st> to get the latest data. The user that creates the table is the owner, and the owner can't be changed. You might need to refresh your <st> before using [time travel](/delta/history.md#time-travel) queries.

See [_](/delta-live-tables/index.md).

### Ingest new data only

By default, the `read_files` function reads all existing data in the source directory during table creation, and then processes newly arriving records with each refresh.

To avoid ingesting data that already exists in the source directory at the time of table creation, set the `includeExistingFiles` option to `false`. This means that only data that arrives in the directory after table creation is processed. For example:

.. azure::

  ```sql
  CREATE OR REFRESH STREAMING TABLE my_bronze_table
  AS SELECT *
  FROM STREAM read_files(
    'abfss://myContainer@myStorageAccount.dfs.core.windows.net/analysis/*/*/*.json',
    includeExistingFiles => false)

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 origens que não mantêm todo o histórico dos dados ou têm períodos de retenção curtos, como Kafka, pois a atualização completa trunca os dados existentes. Talvez não seja possível recuperar dados antigos se os dados não estiverem mais disponíveis na origem.

Por exemplo:

REFRESH STREAMING TABLE my_bronze_table FULL

Agendar uma tabela de streaming para atualização automática

Para configurar uma tabela de streaming para atualizar automaticamente com base em um agendamento definido, cole o seguinte no editor de consultas e clique em Executar:

ALTER STREAMING TABLE
[[<catalog>.]<database>.]<name>
ADD [SCHEDULE [REFRESH]
        CRON '<cron-string>'
                [ AT TIME ZONE '<timezone-id>' ]];

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

Acompanhar o status de uma atualização

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

DESCRIBE EXTENDED <table-name>

Ingestão de streaming do Kafka

Para obter um exemplo de ingestão de streaming do Kafka, consulte read_kafka.

Conceder aos usuários acesso a uma tabela de streaming

Para conceder aos usuários o privilégio SELECT na tabela de streaming para que eles possam consultá-la, cole o seguinte no editor de consultas e clique em Executar:

GRANT SELECT ON TABLE <catalog>.<schema>.<table> TO <user-or-group>

Para obter mais informações sobre concessão de privilégios no Catálogo do Unity, confira Privilégios e objetos protegíveis do Catálogo do Unity.

Monitorar 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 de baixo desempenho e gargalos no pipeline do Delta Live Tables usado para executar suas atualizações de tabela de streaming. Para obter uma visão geral do tipo de informação disponível em históricos de consulta e perfis de consulta, consulte Histórico de consultas e Perfil de consulta.

Importante

Esse recurso está em uma versão prévia. Os administradores do workspace podem habilitar esse recurso na página Visualizações. Consulte Gerenciar Versões Prévias do Azure Databricks.

Todas as instruções relacionadas a 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 CREATE instruções são seguidas por uma REFRESH instrução que é executada de forma assíncrona em um pipeline do Delta Live Tables. As REFRESH instruções geralmente incluem planos de consulta detalhados que fornecem insights sobre como otimizar o desempenho.

Para acessar REFRESH instruções na interface do usuário do histórico de consultas, use as seguintes etapas:

Clique em na barra lateral esquerda para abrir a interface do usuário do histórico de consultas.
Marque a caixa de seleção REFRESH no filtro suspenso Instrução .
Clique no nome da instrução de consulta para exibir detalhes resumidos, como a duração da consulta e as métricas agregadas.
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.
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 os detalhes da consulta usando links no editor SQL ou de um notebook anexado a um SQL warehouse.