02 Planejamento e projeto

Ponto de partida

Módulo 01 concluído: o Snowflake está totalmente construído, o stream CDC e as duas tarefas agendadas estão em execução e, principalmente, o produtor de corridas continua gravando cerca de 60 corridas por minuto em TRIPS_RAW. Mantenha-o ativo; este módulo apenas lê o Snowflake. Reserve cerca de 90 minutos e aproximadamente 0,5 crédito do Snowflake.

Por quê

O motivo mais comum para migrações do ClickHouse terem desempenho ruim não é um problema de ajuste, mas de arquitetura. As equipes movem os dados primeiro e só depois pensam no projeto. Quando percebem que o mecanismo MergeTree incorreto produz silenciosamente resultados errados, ou que uma chave de ordenação copiada do esquema de origem ignora os verdadeiros padrões de consulta, a migração já está “concluída”. Este módulo força a ordem inversa: analise o que você realmente tem e então explicite, por escrito, cada decisão sobre mecanismo, chave de ordenação, mapeamento de tipos e sequenciamento, antes que o módulo 03 execute qualquer uma delas.

Este também é o módulo que os parceiros mais se sentem tentados a ignorar. O setup.sh do módulo 03 procura migration-plan.md e avisa se ele estiver ausente ou incompleto, mas nunca bloqueia; você pode seguir adiante sem ele. Nesse caso, executará no módulo 03 decisões que nunca tomou: verá fact_trips ser criada como ReplacingMergeTree sem saber por que esse mecanismo foi escolhido em vez de um MergeTree simples, verá uma chave ORDER BY sem saber como ela foi derivada da carga de consultas, encontrará delete_insert e FINAL nas configurações do dbt sem saber como derivá-los para outra carga e verá no módulo 04 ganhos de benchmark que não conseguirá explicar nem reproduzir para um cliente. Estes 90 minutos transformam o restante do workshop de uma cópia de comandos em compreensão de uma migração.

Conceitos — nos bastidores

Todas as decisões produzidas neste módulo pertencem a uma de cinco categorias, cada uma com uma planilha:

• Família do mecanismo — qual variante MergeTree corresponde ao padrão de gravação de cada tabela: MergeTree simples para dados somente acrescentados, ReplacingMergeTree para tabelas que recebem atualizações por CDC e AggregatingMergeTree para agregações pré-calculadas. Consulte Mecanismos MergeTree.
• Chave ORDER BY — o ClickHouse não tem índices que possam ser adicionados depois; a chave de ordenação é escolhida uma vez a partir da carga real de consultas, não da chave primária da origem.
• Mapeamento de tipos e diferenças de dialeto — VARIANT, LATERAL FLATTEN e MERGE INTO do Snowflake não têm equivalente direto no ClickHouse e precisam de uma forma traduzida. QUALIFY é a exceção: o ClickHouse tem uma cláusula QUALIFY nativa desde a v24.5, mas o laboratório ainda ensina a reescrita com subconsulta porque ela é portável para versões do ClickHouse e mecanismos SQL anteriores ou sem QUALIFY. Consulte Snowflake versus ClickHouse.
• Projeto dos modelos dbt — materialização, configuração do mecanismo, estratégia incremental e posição de FINAL em cada modelo. Consulte dbt no ClickHouse.
• Ordenação das ondas — quais objetos podem ser migrados primeiro porque nada depende deles ainda, e quais devem esperar.

Etapa 1 — analisar o perfil do ambiente Snowflake

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab/02-plan-and-design"
source ../01-setup-snowflake/.env
./scripts/01_profile_snowflake.sh

O script consulta a instância ativa do Snowflake criada no módulo 01 e grava profile_report.md com quatro seções: inventário de objetos (todas as tabelas, views, streams e tarefas, com número de linhas e grau de complexidade), as 10 consultas com maior tempo total de execução nos últimos 7 dias, estatísticas das tabelas (número de linhas, intervalos de datas, taxas de nulos e uso de VARIANT) e lacunas de compatibilidade do esquema detectadas automaticamente.

profile_report.md é ignorado pelo Git: ele é gerado novamente a partir da sua própria conta Snowflake em cada execução, portanto é específico da máquina e nunca deve entrar em um commit. Não espere encontrá-lo em um clone novo e não tente adicioná-lo ao repositório.

Se ACCOUNT_USAGE ainda não estiver disponível (é preciso aguardar de 1 a 3 horas pela propagação ou usar a função ACCOUNTADMIN), o script recorrerá a INFORMATION_SCHEMA e indicará o que não pôde medir. Você também pode executar scripts/02_query_history.sql manualmente na interface do Snowflake.

Etapa 2 — realizar as cinco planilhas

Faça as cinco planilhas em ordem. Cada uma ensina um conceito e depois apresenta exercícios de múltipla escolha para a carga real de táxis de NYC. Toda resposta é verificada assim que você a seleciona, e cada planilha tem um botão “Copy as markdown” que fornece a tabela preenchida para colar no plano de migração.

• Planilha 1: seleção do mecanismo MergeTree — família e mecanismo de cada tabela
• Planilha 2: projeto da chave de ordenação — ORDER BY derivado da carga de consultas
• Planilha 3: tradução do esquema — mapeamento de tipos e tradução de funções
• Planilha 4: plano de ondas da migração — ordem de dependências e atribuição de ondas
• Planilha 5: projeto dos modelos dbt — materialização, mecanismo, estratégia incremental e posição de FINAL

Suas respostas são salvas no armazenamento local do navegador, não no repositório. Elas não acompanham você em outra máquina e são perdidas se os dados do site forem apagados. Se trocar de notebook no meio do workshop, terá de refazer as planilhas nele.

Etapa 3 — preencher o plano de migração

Abra workshop_public/snowflake_migration_lab/02-plan-and-design/migration-plan.md e preencha cada seção com suas respostas das planilhas. O documento tem dez seções e uma lista de verificação de conclusão com cinco caixas na parte superior:

- [ ] Engine selection: completed
- [ ] Sort key design: completed
- [ ] Schema translation: completed
- [ ] Migration wave plan: completed
- [ ] dbt model design: completed

O setup.sh do módulo 03 verifica essa lista e avisa se ela estiver incompleta, mas não impede o avanço. Mesmo assim, concluí-la é o que torna as decisões do módulo 03 compreensíveis, em vez de arbitrárias.

Como verificar se você terminou

Você terminou quando todas as condições abaixo forem verdadeiras:

• As cinco planilhas exibem pontuação máxima; a linha de pontuação no rodapé de cada uma mostra N/N correct.
• Todas as caixas da lista de verificação de conclusão em workshop_public/snowflake_migration_lab/02-plan-and-design/migration-plan.md estão marcadas.
• profile_report.md existe no disco como resultado da etapa 1 (ele é ignorado pelo Git, por isso não aparecerá em git status).

Depois de escrever seu próprio plano, compare-o com o Exemplo completo: plano concluído, um plano inteiramente preenchido para a mesma carga. Use-o para validar a coerência do raciocínio e entender onde suas escolhas diferem, não como um modelo a preencher antes de pensar por conta própria.

Estado final

Um migration-plan.md preenchido no disco, com todas as caixas marcadas e respaldado por cinco planilhas concluídas. O produtor do Snowflake continua em execução: o módulo 03 migra os dados de uma origem ativa e em movimento, e a virada do módulo 05 mede a lacuna exata criada pelo produtor entre Snowflake e ClickHouse durante a migração. Não o interrompa agora.