Configurar uma tabela incremental

Este documento mostra como usar o núcleo do Dataform para configurar uma tabela incremental.

Sobre uma tabela incremental

O Dataform atualiza as tabelas de maneira diferente com base no tipo delas. Durante cada execução de uma tabela ou visualização, o Dataform recria toda a tabela ou visualização do zero.

Quando você define uma tabela incremental, o Dataform cria a tabela incremental do zero apenas na primeira vez. Durante as execuções subsequentes, o Dataform só insere ou mescla novas linhas na tabela incremental de acordo com as condições configuradas.

O Dataform insere novas linhas apenas em colunas que já existem na tabela incremental. Se você fizer alterações na consulta de definição de tabela incremental, como adicionar uma nova coluna, será necessário recriar a tabela do zero. Para fazer isso, na próxima vez que você acionar uma execução da tabela, selecione a opção Executar com atualização completa.

Confira alguns casos de uso comuns para tabelas incrementais:

Otimização de desempenho
Para alguns tipos de dados, como registros da Web ou dados de análise, talvez seja melhor processar apenas novos registros em vez de repetir o processamento da tabela inteira.
Redução da latência
É possível usar tabelas incrementais para executar fluxos de trabalho rapidamente, mas com frequência, reduzindo a latência downstream das tabelas de saída.
Snapshots diários
É possível configurar uma tabela incremental para criar snapshots diários dos dados da tabela, por exemplo, para análise longitudinal das configurações do usuário armazenadas em um banco de dados de produção.

Antes de começar

  1. No Console do Google Cloud, acesse a página Dataform.

    Acesse a página do Dataform

  2. Selecione ou crie um repositório.

  3. Selecione ou crie um espaço de trabalho de desenvolvimento.

  4. Crie uma tabela do tipo incremental.

Funções exigidas

Para receber as permissões necessárias para configurar uma tabela incremental, peça ao administrador que conceda a você o papel do IAM Editor de formulário de dados (roles/dataform.editor) nos espaços de trabalho. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Processar um subconjunto de linhas em uma tabela incremental

Para determinar um subconjunto de linhas que o Dataform processará durante cada execução, adicione uma cláusula WHERE condicional ao arquivo de definição SQLX da tabela incremental. Na cláusula WHERE, é possível especificar uma condição incremental e uma não incremental. O Dataform aplica a condição incremental durante a execução da tabela sem uma atualização completa e a condição não incremental durante a execução com uma atualização completa.

Para configurar uma tabela incremental, siga estas etapas:

  1. Acesse seu espaço de trabalho de desenvolvimento.
  2. No painel Files, abra definitions/.
  3. Abra um arquivo SQLX de definição de tabela incremental.

  4. Insira uma cláusula WHERE no seguinte formato:

    config { type: "incremental" }

SELECT_STATEMENT

${when(incremental(), `WHERE INCREMENTAL_CONDITION`, `WHERE NON_INCREMENTAL_CONDITION`) }

    Substitua:

    • SELECT_STATEMENT: a instrução SELECT que define a tabela.

    • INCREMENTAL_CONDITION: a condição especificada na cláusula WHERE para selecionar linhas que o Dataform vai processar durante a execução da tabela sem uma atualização completa.

    • NON_INCREMENTAL_CONDITION: a condição especificada na cláusula WHERE para selecionar linhas que o Dataform vai processar durante a execução da tabela com uma atualização completa.

  5. Opcional: clique em Formato.

O exemplo de código a seguir mostra uma tabela incremental que processa de forma incremental as linhas da tabela productiondb.logs:

config { type: "incremental" }

SELECT timestamp, message FROM ${ref("productiondb", "logs")}

${when(incremental(),
   `WHERE date > (SELECT MAX(date) FROM ${self()}) AND country = "UK"`,
   `WHERE country = "UK"`)}

O exemplo de código abaixo mostra uma tabela incremental que cria um snapshot da tabela productiondb.customers:

config { type: "incremental" }

SELECT CURRENT_DATE() AS snapshot_date, customer_id, name, account_settings FROM ${ref("productiondb", "customers")}

${when(incremental(), `WHERE snapshot_date > (SELECT MAX(snapshot_date) FROM ${self()})`) }

Mesclar linhas em uma tabela incremental

Para garantir que uma tabela incremental contenha apenas uma linha correspondente a uma combinação selecionada de colunas, defina as colunas selecionadas como uniqueKey para mesclar linhas com o mesmo uniqueKey. Ao atualizar a tabela, o Dataform mescla linhas com uniqueKey em vez de anexá-las.

Para configurar a mesclagem em uma tabela incremental, siga estas etapas:

  1. Acesse seu espaço de trabalho de desenvolvimento.
  2. No painel Files, abra definitions/.
  3. Selecione um arquivo SQLX de definição de tabela incremental

  4. No bloco config, defina as colunas selecionadas como uniqueKey no seguinte formato:

    uniqueKey: ["COLUMN_NAME"]

    Substitua COLUMN_NAME pelo nome de uma coluna selecionada.

  5. Opcional: clique em Formato.

O exemplo de código a seguir mostra uma tabela incremental com a coluna transaction_id definida como uniqueKey para garantir que ela sempre contenha uma linha:

config {
  type: "incremental",
  uniqueKey: ["transaction_id"]
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

Filtrar linhas em uma tabela incremental

Em uma tabela particionada incremental, para evitar que o Dataform analise toda a tabela para encontrar linhas correspondentes, defina updatePartitionFilter para considerar apenas um subconjunto de registros.

O exemplo de código abaixo mostra uma tabela particionada incremental com mesclagem configurada definindo as propriedades uniqueKey e updatePartitionFilter:

config {
  type: "incremental",
  uniqueKey: ["transaction_id"],
  bigquery: {
    partitionBy: "DATE(timestamp)",
    updatePartitionFilter:
        "timestamp >= timestamp_sub(current_timestamp(), interval 24 hour)"
  }
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

Evite verificações de tabela completas ao fazer a ingestão de uma tabela particionada

Ao criar uma tabela incremental que faz referência a uma tabela particionada, recomendamos que você crie a consulta de tabela para evitar verificações completas da tabela particionada durante cada atualização incremental.

É possível limitar o número de partições que o BigQuery verifica para atualizar a tabela incremental usando uma expressão constante na consulta de tabela. Para transformar um valor da tabela particionada em uma expressão constante, use o script do BigQuery para declarar o valor como uma variável no bloco pre_operations. Em seguida, use a variável como uma expressão constante em uma cláusula WHERE na consulta SELECT.

Com essa configuração, o Dataform atualiza a tabela incremental com base nas partições mais recentes da tabela particionada referenciada, sem verificar a tabela inteira.

Para configurar uma tabela incremental que faz referência a uma tabela particionada e evita verificações completas de tabela, siga estas etapas:

  1. Acesse seu espaço de trabalho de desenvolvimento.
  2. No painel Files, abra definitions/.
  3. Selecione um arquivo SQLX de definição de tabela incremental
  4. No bloco pre_operations, declare uma variável com o script do BigQuery.
  5. Filtre a instrução SELECT que define a tabela com uma cláusula WHERE que faz referência à variável declarada.
  6. Opcional: clique em Formato.

O exemplo de código a seguir mostra uma tabela incremental em que a tabela raw_events referenciada é particionada por event_timestamp:

config {
  type: "incremental",
}

pre_operations {
  DECLARE event_timestamp_checkpoint DEFAULT (
    ${when(incremental(),
    `SELECT max(event_timestamp) FROM ${self()}`,
    `SELECT timestamp("2000-01-01")`)}
  )
}

SELECT
  *
FROM
  ${ref("raw_events")}
WHERE event_timestamp > event_timestamp_checkpoint

No exemplo de código anterior, a variável event_timestamp_checkpoint é definida no bloco pre_operations. A variável event_timestamp_checkpoint é usada como uma expressão constante na cláusula WHERE.

Reconstruir uma tabela incremental do zero com atualização completa

É possível forçar a reconstrução de uma tabela incremental do zero usando a interface de linha de comando com a opção --full-refresh ou com a opção Run with full refresh ao acionar uma execução de fluxo de trabalho.

Quando você seleciona a opção de atualização completa no seu espaço de trabalho de desenvolvimento ou usando a CLI do Dataform, o Dataform ignora o parâmetro ${when(incremental(), ... } durante a execução e recria a tabela com uma instrução CREATE OR REPLACE.

Proteger uma tabela incremental contra atualização completa

Para proteger uma tabela incremental contra a reconstrução do zero e a possível perda de dados, defina-a como protected. Talvez você queira impedir que uma tabela incremental seja recriada se a fonte de dados for temporária.

Para marcar uma tabela incremental como protected, siga estas etapas:

  1. Acesse seu espaço de trabalho de desenvolvimento.
  2. No painel Files, abra definitions/.
  3. Selecione um arquivo SQLX de definição de tabela incremental.
  4. No bloco config, digite protected: true.
  5. Opcional: clique em Formato.

O exemplo de código a seguir mostra uma tabela incremental marcada como protected:

config {
  type: "incremental",
  protected: true
}
SELECT ...

A seguir