01 Ambiente de origem

Provisione um ambiente Snowflake que reproduz uma implantação real de cliente — 50 milhões de linhas, um pipeline Medallion no dbt, um produtor de corridas em tempo real e três dashboards do Superset.

Ponto de partida

Módulo 00 concluído: a cadeia de ferramentas está instalada, as duas contas de avaliação na nuvem estão ativas, o repositório foi clonado e o ambiente virtual dbt-snowflake está configurado. Este módulo leva cerca de 45 minutos e consome aproximadamente 2 a 4 créditos do Snowflake.

Por quê

Não é possível planejar uma migração a partir de uma origem de brinquedo. Uma única tabela plana com poucas linhas permitiria ignorar todas as decisões que tornam uma migração real difícil. Este módulo cria o formato de uma implantação real de cliente: uma coluna VARIANT contendo JSON semiestruturado, um stream CDC, tarefas agendadas, um pipeline incremental com MERGE e uma camada de BI que lê tudo isso. Cada elemento se torna uma decisão específica de migração no módulo 02. Este módulo existe para que você tenha um caso real ao qual se referir quando a decisão aparecer, e não uma abstração.

Conceitos — nos bastidores

Infraestrutura (Terraform). A execução de setup.sh provisiona:

Warehouses — TRANSFORM_WH (SMALL, para ELT) e ANALYTICS_WH (MEDIUM, para BI), além de um monitor de recursos (ANALYTICS_WH_MONITOR) limitado a 50 créditos por mês.
Banco de dados — NYC_TAXI_DB, com três esquemas: RAW, STAGING, ANALYTICS.
Funções — TRANSFORMER_ROLE, ANALYST_ROLE, DBT_ROLE, LOADER_ROLE.

Ambiente Snowflake de origem: um gerador sintético de execução única e um produtor contínuo de corridas em Docker inserem dados em NYC_TAXI_DB, que é consultado por três dashboards do Superset por meio do warehouse analítico

O formato Medallion. Os dados percorrem três camadas dentro de NYC_TAXI_DB:

RAW — TRIPS_RAW (50 milhões de corridas sintéticas, incluindo uma coluna VARIANT TRIP_METADATA que simula a telemetria do aplicativo — este é o desafio de migração do JSON), além das tabelas de dimensões (DIM_TAXI_ZONES, DIM_PAYMENT_TYPE, DIM_VENDOR).
STAGING — views do dbt que limpam os tipos e achatam a coluna VARIANT.
ANALYTICS — tabelas e modelos incrementais do dbt: fact_trips (50 milhões de linhas, estratégia MERGE), quatro tabelas de dimensões e agg_hourly_zone_trips (um agregado incremental).

Dois objetos do Snowflake mantêm esse pipeline em movimento por conta própria, independentemente do dbt:

TRIPS_CDC_STREAM — stream de captura de dados alterados em TRIPS_RAW.
CDC_CONSUME_TASK — lê esse stream a cada 5 minutos (é executada em RAW e retomada durante a configuração) — e HOURLY_AGG_TASK, que atualiza o agregado por hora a cada hora (é executada em STAGING e retomada depois que o dbt termina a construção).

Dentro de NYC_TAXI_DB: TRIPS_RAW, com uma coluna VARIANT de metadados, alimenta um stream CDC e uma tarefa agendada de consumo, enquanto o dbt cria views de preparação e depois as tabelas de fatos, dimensões e agregados por hora

Superset. Os três dashboards leem o esquema ANALYTICS por meio de ANALYTICS_WH; nenhum deles acessa RAW ou STAGING diretamente. Esse é o caminho de leitura que você reproduzirá no lado do ClickHouse mais adiante no workshop.

Etapa 1 — configurar as credenciais

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab/01-setup-snowflake"

cp .env.example .env
# Edit .env with your Snowflake credentials

cp dbt/nyc_taxi_dbt/profiles.yml.example ~/.dbt/profiles.yml
# Edit ~/.dbt/profiles.yml with your account details

Tanto .env quanto ~/.dbt/profiles.yml são ignorados pelo Git e contêm a conta, o usuário e a senha do Snowflake. Nunca faça commit de nenhum desses arquivos.

Etapa 2 — executar a configuração

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab/01-setup-snowflake"
source .env && ./setup.sh

Espere 5 a 10 minutos, usados principalmente para gerar 50 milhões de corridas sintéticas com TABLE(GENERATOR). Em uma única passagem, setup.sh provisiona a infraestrutura do Terraform, carrega TRIPS_RAW, executa a construção do dbt e inicia o Docker Compose (produtor de corridas e Superset).

Etapa 3 — iniciar o produtor e o Superset

setup.sh inicia o Docker Compose com o ambiente correto, registra a conexão do Snowflake no Superset e importa automaticamente os três dashboards.

Nos ZIPs de dashboard versionados em superset/dashboards/, o sqlalchemy_uri foi ocultado com valores fictícios (LAB_USER, MYORG-MYACCOUNT). A importação automática recria a URI a partir do seu .env, portanto tudo acontece de forma transparente durante setup.sh. Se você importar um ZIP manualmente pela interface do Superset, a conexão criada usará os valores fictícios e não funcionará; edite-a depois para apontar para sua conta real do Snowflake.

Se precisar reiniciar o Superset manualmente:

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab/01-setup-snowflake/superset"
docker-compose --env-file ../.env up -d

A opção --env-file ../.env carrega as variáveis de ambiente do diretório pai.

Fontes de dados dos dashboards do Superset: três dashboards operacionais leem o esquema analítico por meio do warehouse analítico

Os três dashboards são Operations Command Center, Executive Weekly Report e Driver & Quality Analytics (intencionalmente lento, pois será o alvo do benchmark do ClickHouse mais adiante). Para ver a construção completa — fontes de dados, gráficos e filtros —, consulte Superset no Snowflake.

Etapa 4 — manter o dbt atualizado

O produtor de corridas insere continuamente cerca de 60 corridas por minuto em TRIPS_RAW. Para manter fact_trips e agg_hourly_zone_trips atualizadas durante o trabalho, execute o ciclo de atualização do dbt em outro terminal:

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab/01-setup-snowflake"

# Default: refresh every 5 minutes (auto-sources .env)
./scripts/run_dbt.sh

# Custom interval
./scripts/run_dbt.sh --interval 15m

# Run once and exit
./scripts/run_dbt.sh --once

# Include dbt tests after each run
./scripts/run_dbt.sh --test

Opção	Efeito
`--interval <n>`	Tempo entre execuções: `30s`, `5m`, `1h` ou segundos sem sufixo (padrão: `5m`)
`--once`	Executa uma única atualização e encerra
`--test`	Executa `dbt test` depois de cada `dbt run`

O script sempre é executado de forma incremental; ele nunca faz --full-refresh, portanto as linhas inseridas pelo produtor são preservadas. Pressione Ctrl-C a qualquer momento para interrompê-lo. Deixe-o ativo em seu próprio terminal durante o restante do laboratório, pois o módulo 03 ainda depende dele.

Etapa 5 — explorar a biblioteca de consultas

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab/01-setup-snowflake"

O diretório de consultas (workshop_public/snowflake_migration_lab/01-setup-snowflake/queries/) contém sete arquivos SQL comentados. Cada um é executado no ambiente Snowflake que você acabou de criar e traz um desafio deliberado de migração que o módulo 02 traduzirá para o ClickHouse:

Consulta	Construção	Desafio de migração
Q1	`DATE_TRUNC`, `DATEADD`	Pequena diferença de sintaxe
Q2	Janela `ROWS BETWEEN`	Quase idêntica no ClickHouse
Q3	`QUALIFY`	Nativo no ClickHouse desde a v24.5; ainda é reescrito aqui como subconsulta, por portabilidade
Q4	`LATERAL FLATTEN`	Sem equivalente; use `JSONExtract` ou faça o pré-achatamento
Q5	Caminho com dois-pontos em `VARIANT`	Substitua por `JSONExtractFloat`/`JSONExtractString`
Q6	`MERGE INTO`	Sem equivalente; use `ReplacingMergeTree`
Q7	Streams do Snowflake	Removidos na virada; as gravações em tempo real vão diretamente ao ClickHouse pelo produtor

Abra cada arquivo e execute-o no ambiente Snowflake antes de continuar. O bloco de comentários de cada consulta já esboça o equivalente no ClickHouse; no módulo 02, você escreverá e executará esse lado de verdade.

Como verificar se você terminou

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab/01-setup-snowflake"
source .env && ./scripts/verify_environment.sh

O script verifica:

Banco de dados e esquemas — NYC_TAXI_DB existe com RAW, STAGING, ANALYTICS.
Tabelas e dados — TRIPS_RAW tem aproximadamente 50 milhões de linhas, FACT_TRIPS está preenchida e as dimensões existem.
Stream CDC — TRIPS_CDC_STREAM existe sobre TRIPS_RAW.
Tarefas agendadas — CDC_CONSUME_TASK e HOURLY_AGG_TASK estão no estado started.
Atividade de CDC — as tarefas foram executadas recentemente.
Feed do produtor — o produtor de corridas está inserindo dados continuamente.
Superset — os dashboards de BI podem ser acessados em http://localhost:8088.

Se preferir verificar manualmente, execute SHOW TASKS LIKE '%TASK' IN DATABASE NYC_TAXI_DB; com a função ACCOUNTADMIN (proprietária das tarefas) para confirmar que ambas estão em execução.

Encerramento

Você voltará a este ambiente várias vezes nos próximos módulos, e uma execução completa de ./setup.sh custa de 5 a 10 minutos que você não deseja repetir a cada ajuste em um arquivo Terraform ou modelo dbt. setup.sh aceita opções para evitar isso:

Opção	Quando usar
(nenhuma)	Primeira execução. Provisiona tudo e gera 50 milhões de linhas sintéticas (cerca de 12 min no total).
`--skip-seed`	A infraestrutura já existe e `TRIPS_RAW` já contém dados. Ignora a geração de dados sintéticos (economiza cerca de 8 min).
`--skip-dbt`	Os objetos Snowflake existem, mas não é preciso executar novamente as transformações do dbt (por exemplo, ao testar alterações do Terraform).
`--skip-superset`	O Docker não está ativo ou você ainda não precisa da camada de BI.
`--full-refresh`	Força o dbt a reconstruir todos os modelos incrementais do zero (por exemplo, após uma alteração de esquema).

As opções podem ser combinadas. Duas combinações comuns:

# Re-run after a Terraform or SQL change — skip the ~10 min data load
./setup.sh --skip-seed

# Iterate on dbt models only — skip everything else
./setup.sh --skip-seed --skip-superset

Observação sobre custos. A carga inicial leva cerca de 12 minutos e consome 2 créditos (aproximadamente US$ 6), enquanto uma construção completa do dbt leva cerca de 8 minutos e consome 1,5 crédito (aproximadamente US$ 5). Uma sessão de laboratório de 8 horas acrescenta aproximadamente 12 créditos (cerca de US$ 36). Os warehouses são suspensos automaticamente quando ociosos, portanto o custo deixa de se acumular entre as sessões. O total diário por parceiro é de aproximadamente 16 créditos, ou US$ 47.

Estado final

O Snowflake está ativo: NYC_TAXI_DB está totalmente construído, o stream CDC e as duas tarefas agendadas estão em execução, o produtor grava aproximadamente 60 corridas por minuto em TRIPS_RAW e os três dashboards do Superset estão disponíveis em http://localhost:8088.

Mantenha o produtor ativo. Não interrompa a pilha do Docker Compose e não execute ./teardown.sh: os módulos de 02 a 05 dependem da continuidade deste ambiente, e a virada do módulo 05 mede a lacuna exata criada pelo produtor entre Snowflake e ClickHouse durante a migração. Desmontar agora faria o restante do workshop falhar de uma forma difícil de relacionar a esta etapa. A desmontagem é abordada no final do módulo 05, não aqui.