02 Planificación y diseño

Punto de partida

Has completado el módulo 01: Snowflake está totalmente construido, el stream de CDC y las dos tareas programadas están en ejecución y, lo más importante, el productor de viajes sigue escribiendo unas 60 filas por minuto en TRIPS_RAW. Déjalo activo; este módulo solo lee de Snowflake. Reserva unos 90 minutos y aproximadamente 0,5 créditos de Snowflake.

Por qué

La causa más frecuente de que una migración a ClickHouse rinda menos de lo esperado no es un problema de ajuste, sino de arquitectura. Los equipos mueven primero los datos y piensan en el diseño después. Cuando descubren que una elección incorrecta de motor MergeTree produce silenciosamente resultados erróneos, o que una clave de ordenación copiada del esquema de origen ignora los patrones reales de consulta, la migración ya está «terminada». Este módulo fuerza el orden contrario: perfila lo que existe de verdad y deja por escrito cada decisión de motor, clave de ordenación, mapeo de tipos y secuencia antes de que el módulo 03 ejecute ninguna de ellas.

También es el módulo que los participantes se sienten más tentados de omitir. setup.sh del módulo 03 comprueba si existe migration-plan.md y avisa cuando falta o está incompleto, pero nunca impide continuar: puedes lanzarte a la migración sin él. Si lo haces, ejecutarás en el módulo 03 decisiones que nunca llegaste a tomar: verás que fact_trips se crea como ReplacingMergeTree sin saber por qué se escogió ese motor en vez de MergeTree; encontrarás una clave ORDER BY sin saber cómo se dedujo de la carga de consultas; verás delete_insert y FINAL en la configuración de dbt sin saber derivarlos para otra carga; y obtendrás en el módulo 04 mejoras de rendimiento que no podrás explicar ni reproducir para un cliente. Estos 90 minutos convierten el resto del taller de una sucesión de comandos copiados en la comprensión real de una migración.

Conceptos internos

Cada decisión que produce este módulo pertenece a una de cinco categorías, cada una con su propia hoja de trabajo:

• Familia de motor: qué variante de MergeTree encaja con el patrón de escritura de cada tabla: MergeTree para tablas de solo inserción, ReplacingMergeTree para las que reciben actualizaciones mediante CDC y AggregatingMergeTree para agregados precalculados. Consulta Motores MergeTree.
• Clave ORDER BY: ClickHouse no dispone de índices que se puedan añadir a posteriori. La clave de ordenación se elige una vez a partir de la carga real de consultas, no de la clave primaria de la tabla de origen.
• Mapeo de tipos y diferencias de dialecto: VARIANT, LATERAL FLATTEN y MERGE INTO de Snowflake no tienen un equivalente directo en ClickHouse y requieren una forma traducida. QUALIFY es la excepción: ClickHouse incluye una cláusula QUALIFY nativa desde la versión 24.5, pero el laboratorio sigue enseñando la reescritura como subconsulta porque es compatible con versiones de ClickHouse y motores SQL anteriores o que no admiten QUALIFY. Consulta Snowflake frente a ClickHouse.
• Diseño de modelos dbt: materialización, configuración del motor, estrategia incremental y ubicación de FINAL en cada modelo. Consulta dbt en ClickHouse.
• Orden de las oleadas: qué objetos pueden trasladarse primero porque todavía nada depende de ellos y cuáles deben esperar.

Paso 1 — Perfila 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

El script se ejecuta contra la instancia activa de Snowflake del módulo 01 y escribe profile_report.md con cuatro secciones: un inventario de objetos —todas las tablas, vistas, streams y tareas, junto con el recuento de filas y un nivel de complejidad—; las 10 consultas con mayor tiempo total de ejecución durante los últimos 7 días; estadísticas de tablas —recuentos, intervalos de fechas, tasas de valores nulos y uso de VARIANT—; y las incompatibilidades de esquema detectadas automáticamente.

profile_report.md se ignora en Git: en cada ejecución se genera de nuevo a partir de tu propia cuenta de Snowflake, por lo que es específico de tu máquina y nunca se incorpora al repositorio. No esperes encontrarlo en un clon nuevo ni intentes añadirlo tú mismo.

Si ACCOUNT_USAGE todavía no está disponible —requiere entre 1 y 3 horas de propagación o el rol ACCOUNTADMIN—, el script recurre a INFORMATION_SCHEMA y anota lo que no ha podido medir. También puedes ejecutar manualmente scripts/02_query_history.sql en la interfaz de Snowflake.

Paso 2 — Completa las cinco hojas

Completa las cinco hojas en orden. Cada una enseña un concepto y después plantea ejercicios de opción múltiple aplicados a la carga real de NYC Taxi. Cada respuesta se comprueba en cuanto la seleccionas, y todas las hojas ofrecen un botón «Copy as markdown» que genera la tabla cumplimentada para pegarla en el plan de migración.

• Hoja 1: selección de motor MergeTree: familia y motor para cada tabla.
• Hoja 2: diseño de clave: ORDER BY derivado de la carga de consultas.
• Hoja 3: traducción de esquema: mapeo de tipos y traducción de funciones.
• Hoja 4: oleadas: orden de dependencias y asignación a oleadas.
• Hoja 5: modelos dbt: materialización, motor, estrategia incremental y ubicación de FINAL.

Las respuestas se guardan en el almacenamiento local del navegador, no en el repositorio. No te acompañarán si cambias de máquina y desaparecerán si borras los datos del sitio. Si cambias de portátil a mitad del taller, tendrás que volver a completar allí las hojas de trabajo.

Paso 3 — Completa el plan

Abre workshop_public/snowflake_migration_lab/02-plan-and-design/migration-plan.md y rellena cada sección con las respuestas de tus hojas. El documento contiene diez secciones y, en la parte superior, una lista de finalización con cinco casillas:

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

setup.sh del módulo 03 comprueba esta lista y avisa si está incompleta, pero no impide continuar. Terminarla de todos modos es lo que hace que las decisiones del módulo 03 tengan sentido en vez de parecer arbitrarias.

Cómo verificar la finalización

Has terminado cuando se cumplen todas estas condiciones:

• Las cinco hojas muestran la puntuación máxima; la línea de puntuación al final de cada una indica N/N correct.
• workshop_public/snowflake_migration_lab/02-plan-and-design/migration-plan.md tiene marcadas todas las casillas de su lista de finalización.
• profile_report.md existe en el disco desde el Paso 1. Como se ignora en Git, no aparecerá en git status.

Una vez redactado tu propio plan, compáralo con el ejemplo resuelto, un plan completamente cumplimentado para esta misma carga. Utilízalo para comprobar la coherencia de tu razonamiento y entender los puntos en los que elegiste algo distinto, no como una plantilla que rellenar antes de haber pensado por tu cuenta.

Estado final

Tienes en el disco un migration-plan.md cumplimentado, con todas las casillas marcadas y respaldado por cinco hojas de trabajo completas. El productor de Snowflake sigue activo: el módulo 03 migra datos desde un origen vivo y en movimiento, y la transición del módulo 05 mide el desfase exacto que crea el productor entre Snowflake y ClickHouse durante la migración. No lo detengas ahora.