Compartilhar via

CREATE STREAMING TABLE (pipelines)

Uma tabela de streaming é uma tabela com suporte para streaming ou processamento de dados incremental. As tabelas de streaming são suportadas por pipelines. Cada vez que uma tabela de streaming é atualizada, os dados adicionados às tabelas de origem são anexados à tabela de streaming. Você pode atualizar as tabelas de streaming manualmente ou mediante programação.

Para saber mais sobre como executar ou agendar atualizações, consulte Executar uma atualização de pipeline.

Sintaxe

CREATE [OR REFRESH] [PRIVATE] STREAMING TABLE
  table_name
  [ table_specification ]
  [ table_clauses ]
  [ AS query ]

table_specification
  ( { column_identifier column_type [column_properties] } [, ...]
    [ column_constraint ] [, ...]
    [ , table_constraint ] [...] )

   column_properties
      { NOT NULL | COMMENT column_comment | column_constraint | MASK clause } [ ... ]

table_clauses
  { USING DELTA
    PARTITIONED BY (col [, ...]) |
    CLUSTER BY clause |
    LOCATION path |
    COMMENT view_comment |
    TBLPROPERTIES clause |
    WITH { ROW FILTER clause } } [ ... ]

Parâmetros

  • REFRESH

    Se especificado, criará a tabela ou atualizará uma tabela existente e seu conteúdo.

  • PRIVADO

    Cria uma tabela de streaming privada.

    • Eles não são adicionados ao catálogo e só são acessíveis dentro do pipeline de definição
    • Eles podem ter o mesmo nome de um objeto existente no catálogo. Dentro do pipeline, se uma tabela de streaming privada e um objeto no catálogo tiverem o mesmo nome, as referências ao nome serão resolvidas para a tabela de streaming privada.
    • As tabelas de streaming privadas são mantidas somente durante toda a vida útil do pipeline, não apenas durante uma única atualização.

    Tabelas de streaming privadas foram criadas anteriormente com o parâmetro TEMPORARY.

  • table_name

    O nome da tabela recém-criada. O nome da tabela totalmente qualificado deve ser exclusivo.

  • especificação_da_tabela

    Esta cláusula opcional define a lista de colunas e os tipos, as propriedades, as descrições e as restrições de coluna associados.

  • restrição_de_tabela

    Importante

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

    Ao especificar um esquema, você pode definir as chaves primárias e estrangeiras. As restrições são informativas e não são impostas. Consulte a cláusula CONSTRAINT na referência da linguagem SQL.

    Observação

    Para definir restrições de tabela, seu pipeline deve ser um pipeline habilitado para o Unity Catalog.

  • tabela_cláusulas

    Opcionalmente, especifique particionamento, comentários e propriedades definidas pelo usuário para a tabela. Cada subcláusula só pode ser especificada uma vez.

    • USANDO DELTA

      Especifica o formato dos dados. A única opção é DELTA.

      Essa cláusula é opcional e o padrão é DELTA.

    • PARTICIONADO POR

      Uma lista opcional de uma ou mais colunas a serem usadas para particionamento na tabela. Mutuamente exclusivo com CLUSTER BY.

      O agrupamento líquido oferece uma solução flexível e otimizada para agrupamento. Considere usar CLUSTER BY em vez de PARTITIONED BY para pipelines.

    • CLUSTER BY

      Habilite o agrupamento líquido na tabela e defina as colunas a serem usadas como chaves de agrupamento. Use o agrupamento automático de líquidos com CLUSTER BY AUTO, e o Databricks escolhe de forma inteligente as chaves de agrupamento para otimizar o desempenho da consulta. Mutuamente exclusivo com PARTITIONED BY.

      Consulte Usar clustering líquido para tabelas.

    • LOCALIZAÇÃO

      Um local de armazenamento opcional para os dados da tabela. Se ele não estiver definido, o sistema usará como padrão o local de armazenamento do pipeline.

    • COMENTÁRIO

      Um literal STRING opcional para descrever a tabela.

    • TBLPROPERTIES

      Uma lista opcional de propriedades da tabela para a tabela.

    • COM ROW FILTER

    Importante

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

    Adiciona uma função de filtro de linha à tabela. Consultas futuras para essa tabela recebem um subconjunto das linhas para as quais a função é avaliada como TRUE. Isso pode ser útil para fins de controle de acesso refinado, em que a função pode inspecionar a identidade e/ou as associações de grupo do usuário que a invocou para decidir se deseja filtrar algumas linhas.

    Consulte a cláusula ROW FILTER.

  • consulta

    Essa cláusula preenche a tabela usando os dados de query. Essa consulta deve ser uma consulta de streaming. Use a palavra-chave STREAM para usar a semântica de streaming para ler a fonte. Se a leitura encontrar uma alteração ou exclusão em um registro existente, um erro será gerado. É mais seguro ler de fontes estáticas ou somente de acréscimos. Para ingerir dados que tenham confirmações de alterações, você pode usar Python e a opção SkipChangeCommits para lidar com erros.

    Quando você especifica um query e um table_specification juntos, o esquema de tabela especificado em table_specification deve conter todas as colunas retornadas pelo query, caso contrário, você receberá um erro. Todas as colunas especificadas em table_specification, mas não retornadas por query retornam valores null, quando consultadas.

    Para obter mais informações sobre dados de fluxo, consulte Transformar dados com pipelines.

Permissões necessárias

O usuário run-as de um pipeline deve ter as seguintes permissões:

  • SELECT privilégio sobre as tabelas base referenciadas pela tabela de streaming.
  • USE CATALOG privilégio no catálogo pai e o privilégio USE SCHEMA no esquema pai.
  • CREATE MATERIALIZED VIEW privilégio no esquema da tabela de streaming.

Para que um usuário possa atualizar o pipeline no qual a tabela de streaming está definida, ele precisa:

  • USE CATALOG privilégio no catálogo pai e o privilégio USE SCHEMA no esquema pai.
  • Propriedade da tabela de streaming ou REFRESH privilégio na tabela de streaming.
  • O proprietário da tabela de streaming deve ter o privilégio SELECT sobre as tabelas base referenciadas pela tabela de streaming.

Para que um usuário possa consultar a tabela de streaming resultante, ele precisa:

  • USE CATALOG privilégio no catálogo pai e o privilégio USE SCHEMA no esquema pai.
  • SELECT privilégio sobre a tabela de streaming.

Limitações

  • Somente os proprietários de tabelas podem atualizar tabelas de streaming para obter os dados mais recentes.
  • ALTER TABLE os comandos não são permitidos em tabelas de streaming. A definição e as propriedades da tabela devem ser alteradas por meio da instrução CREATE OR REFRESH ou ALTER STREAMING TABLE.
  • Não há suporte para a evolução do esquema de tabela por meio de comandos DML como INSERT INTO e MERGE.
  • Não há suporte para os seguintes comandos em tabelas de streaming:
    • CREATE TABLE ... CLONE <streaming_table>
    • COPY INTO
    • ANALYZE TABLE
    • RESTORE
    • TRUNCATE
    • GENERATE MANIFEST
    • [CREATE OR] REPLACE TABLE
  • Não há suporte para renomear a tabela ou alterar o proprietário.
  • Não há suporte para colunas geradas, colunas de identidade e colunas padrão.

Exemplos

-- Define a streaming table from a volume of files:
CREATE OR REFRESH STREAMING TABLE customers_bronze
AS SELECT * FROM STREAM read_files("/databricks-datasets/retail-org/customers/*", format => "csv")

-- Define a streaming table from a streaming source table:
CREATE OR REFRESH STREAMING TABLE customers_silver
AS SELECT * FROM STREAM(customers_bronze)

-- Define a table with a row filter and column mask:
CREATE OR REFRESH STREAMING TABLE customers_silver (
  id int COMMENT 'This is the customer ID',
  name string,
  region string,
  ssn string MASK catalog.schema.ssn_mask_fn COMMENT 'SSN masked for privacy'
)
WITH ROW FILTER catalog.schema.us_filter_fn ON (region)
AS SELECT * FROM STREAM(customers_bronze)

-- Define a streaming table that you can add flows into:
CREATE OR REFRESH STREAMING TABLE orders;
  • Last updated on