Visões materializadas

1. Criar uma tabela de destino com o nome do modelo
2. Criar uma visão materializada no ClickHouse com o nome <model_name>_mv

-- models/events_mv.sql
{{
    config(
        materialized='materialized_view',
        engine='SummingMergeTree()',
        order_by='(event_date, event_type)'
    )
}}

SELECT
    toStartOfDay(event_time) AS event_date,
    event_type,
    count() AS total
FROM {{ source('raw', 'events') }}
GROUP BY event_date, event_type

--mv1:begin
select a,b,c from {{ source('raw', 'table_1') }}
--mv1:end
union all
--mv2:begin
select a,b,c from {{ source('raw', 'table_2') }}
--mv2:end

{{config(
    materialized='materialized_view',
    engine='MergeTree()',
    order_by='(id)',
    on_schema_change='fail'  # esta configuração
)}}

{{config(
    materialized='materialized_view',
    engine='MergeTree()',
    order_by='(id)',
    catchup=False  # esta configuração
)}}

• Todos os recursos (tabela de destino + MVs) compartilham a mesma configuração. Se várias MVs apontarem para a mesma tabela de destino, elas deverão ser definidas em conjunto usando a sintaxe UNION ALL.
• Nenhum desses recursos pode ser tratado separadamente; todos precisam ser gerenciados usando o mesmo arquivo de modelo.
• Você não consegue controlar facilmente o nome de cada MV.
• Todas as configurações são compartilhadas entre a tabela de destino e as MVs, o que dificulta configurar cada recurso individualmente e entender qual configuração pertence a cada um.

• Recursos totalmente separados: Agora cada recurso pode ser definido separadamente, melhorando a legibilidade.
• Recursos 1:1 entre dbt e CH: Agora você pode usar as ferramentas do dbt para gerenciá-los e iterar sobre eles separadamente.
• Diferentes configurações agora disponíveis: Agora é possível aplicar uma configuração diferente a cada um deles.
• Não é mais necessário seguir convenções de nomenclatura: Agora todos os recursos são criados com o nome que você definir, e não com o nome personalizado adicionado com _mv para as MVs.

• A definição da tabela de destino não é algo natural no dbt: não é um SQL que vai ler de uma tabela de origem, então você perde as validações do dbt nesse ponto. O SQL da MV ainda será validado usando os utilitários do dbt, e a compatibilidade dele com as colunas da tabela de destino será validada no nível do CH.
• Encontramos alguns problemas relacionados às limitações da função ref(): precisamos usá-la para referenciar modelos entre si, mas ela só pode ser usada para referenciar modelos upstream, não downstream. Isso traz alguns problemas para esta implementação. Criamos uma issue no repositório dbt-core e, no momento, estamos conversando com eles para buscar possíveis soluções (dbt-labs/dbt-core#12319):
  • Quando ref() é chamada de dentro do bloco de configuração, ela retorna o modelo atual, e não o modelo compartilhado. Isso nos impede de defini-la na seção config(), obrigando-nos a usar um comentário para adicionar essa dependência. Estamos seguindo o mesmo padrão definido na documentação do dbt com a abordagem “—depends_on:”.
  • ref() funciona no nosso caso, pois força a criação da tabela de destino primeiro, mas, no gráfico de dependências da documentação gerada, a tabela de destino aparecerá como mais uma dependência upstream, e não downstream, o que dificulta um pouco o entendimento.
  • unit-test também nos obriga a definir alguns dados para a tabela de destino, mesmo quando a ideia não é ler dela. A solução alternativa é simplesmente deixar vazios os dados dessa tabela.

{{
    config(
        materialized='table',
        engine='SummingMergeTree()',
        order_by='(event_date, event_type)',
        partition_by='toYYYYMM(event_date)'
    )
}}

SELECT
    toDate(now()) AS event_date,
    '' AS event_type,
    toUInt64(0) AS total
WHERE 0  -- Cria tabela vazia com o schema correto

{{ config(materialized='materialized_view') }}
{{ materialization_target_table(ref('events_daily')) }}

SELECT
    toStartOfDay(event_time) AS event_date,
    event_type,
    count() AS total
FROM {{ source('raw', 'page_events') }}
GROUP BY event_date, event_type

{{ config(materialized='materialized_view') }}
{{ materialization_target_table(ref('events_daily')) }}

SELECT
    toStartOfDay(event_time) AS event_date,
    event_type,
    count() AS total
FROM {{ source('raw', 'mobile_events') }}
GROUP BY event_date, event_type

-- models/page_events_aggregator.sql
{{ config(
    materialized='materialized_view',
    catchup=True  -- este é o valor padrão, portanto não é necessário defini-lo explicitamente.
) }}
{{ materialization_target_table(ref('events_daily')) }}
...

1. Criar uma nova tabela temporária
2. Executar INSERT-SELECT usando o SQL de cada MV
3. Trocar as tabelas atomicamente

-- models/events_daily.sql
{{
    config(
        materialized='table',
        engine='SummingMergeTree()',
        order_by='(event_date, event_type)',
        repopulate_from_mvs_on_full_refresh=True
    )
}}
...

1. Atualize a chamada materialization_target_table()
2. Execute dbt run --full-refresh -s your_mv_model

• As visões materializadas podem estar configuradas com catchup=False ou a tabela de destino pode estar configurada com repopulate_from_mvs_on_full_refresh=False, portanto nenhuma carga retroativa é executada quando as visões materializadas são criadas ou quando a tabela de destino é recriada. Esse é o comportamento esperado. Portanto, se você quiser reinserir os dados usando o SQL das visões materializadas, defina catchup=True na visão materializada (esse é o valor padrão) ou repopulate_from_mvs_on_full_refresh=True na tabela de destino. Certifique-se de não ativar os dois ao mesmo tempo para evitar duplicatas. Consulte a seção de configuração para mais detalhes.
• Durante a execução de dbt run --full-refresh, se as visões materializadas usarem o padrão catchup=True, o destino será recriado e as MVs reinserirão os dados sequencialmente. Para evitar essa situação, consulte Atualização completa com destinos explícitos.

• Tanto catchup=True nas visões materializadas quanto repopulate_from_mvs_on_full_refresh=True na tabela de destino podem estar habilitados: mantenha apenas um deles, dependendo das operações que pretende executar. Consulte a seção de configuração para mais detalhes.
• A tabela de destino não foi definida com WHERE 0: a tabela de destino deve ser criada vazia, mas a consulta interna pode inserir dados se WHERE 0 não for incluído. Certifique-se de que a cláusula esteja incluída.

SELECT
    name as mv_name,
    replaceRegexpOne(
        create_table_query,
        '.*TO\\s+`?([^`\\s(]+)`?\\.`?([^`\\s(]+)`?.*',
        '\\1.\\2'
    ) AS target_table
FROM system.tables
WHERE database = 'your_schema'
  AND engine = 'MaterializedView'

A tabela <table_name> está sendo usada como tabela de destino por uma visão materializada gerenciada pelo dbt. Definindo mv_on_schema_change como “fail” por padrão para evitar perda de dados.

• O modelo da visão materializada define {{ materialization_target_table(ref('your_target')) }} corretamente
• O modelo da visão materializada tem materialized='materialized_view' na configuração
• Tanto a visão materializada quanto a tabela de destino foram executadas pelo menos uma vez

-- models/events_daily.sql
{{
    config(
        materialized='table',
        engine='MergeTree()',
        order_by='(event_date, event_type)'
    )
}}

SELECT
    toDate(now()) AS event_date,
    '' AS event_type,
    toUInt64(0) AS total
WHERE 0

• se apenas uma MV foi definida, ela terá o nome: <old_model_name>_mv
• se várias MVs foram definidas, cada uma terá o nome: <old_model_name>_mv_<name_in_comments>

--mv1:begin
select a, b, c from {{ source('raw', 'table_1') }}
--mv1:end
union all
--mv2:begin
select a, b, c from {{ source('raw', 'table_2') }}
--mv2:end

-- models/my_model_mv_mv1.sql
{{ config(materialized='materialized_view') }}
{{ materialization_target_table(ref('events_daily')) }}

select a, b, c from {{ source('raw', 'table_1') }}

-- models/my_model_mv_mv2.sql
{{ config(materialized='materialized_view') }}
{{ materialization_target_table(ref('events_daily')) }}

select a, b, c from {{ source('raw', 'table_2') }}

• Como as visões materializadas do ClickHouse atuam como gatilhos de inserção, elas só capturam dados enquanto existem. Se uma visão materializada for removida e recriada (por exemplo, durante um --full-refresh), quaisquer linhas inseridas na tabela de origem durante esse intervalo não serão processadas pela visão materializada. Isso é chamado de visão materializada “cega”.
• Os diferentes processos de catchup se baseiam em operações INSERT INTO ... SELECT que usam o SQL das visões materializadas e são independentes do funcionamento delas. Depois que o INSERT começa, os novos dados não são capturados por ele, mas serão capturados pela visão materializada anexada.

{{
    config(
        materialized='materialized_view',
        engine='MergeTree()',
        order_by='(event_date)',
        refreshable={
            "interval": "EVERY 5 MINUTE",
            "randomize": "1 MINUTE",
            "append": True,
            "depends_on": ['schema.depend_on_model'],
            "depends_on_validation": True
        }
    )
}}

SELECT
    toStartOfDay(event_time) AS event_date,
    count() AS total
FROM {{ source('raw', 'events') }}
GROUP BY event_date

{{
    config(
        materialized='materialized_view',
        refreshable={
            "interval": "EVERY 1 HOUR",
            "append": False
        }
    )
}}
{{ materialization_target_table(ref('events_daily')) }}

SELECT
    toStartOfDay(event_time) AS event_date,
    event_type,
    count() AS total
FROM {{ source('raw', 'events') }}
GROUP BY event_date, event_type

• Ao criar uma visão materializada atualizável (MV) no ClickHouse que tenha uma dependência, o ClickHouse não gera um erro se a dependência especificada não existir no momento da criação. Em vez disso, a MV atualizável permanece em estado inativo, aguardando que a dependência seja atendida antes de começar a processar atualizações ou ser atualizada. Esse comportamento é intencional, mas pode causar atrasos na disponibilidade dos dados se a dependência necessária não for resolvida rapidamente. Garanta que todas as dependências estejam corretamente definidas e existam antes de criar uma visão materializada atualizável.
• Até o momento, não há um “vínculo com o dbt” real entre a MV e suas dependências; portanto, a ordem de criação não é garantida.
• O recurso de atualização não foi testado com várias MVs apontando para o mesmo modelo de destino.