Documentación, lineage y CI

Objetivo

Convertir el proyecto dbt en un artefacto mantenible.

Explicación

Descriptions, tests y lineage permiten entender impacto. En CI conviene construir sólo cambios y dependencias en un entorno aislado, pero siempre validar contratos clave. dbt aporta valor cuando las transformaciones dejan de ser consultas sueltas y pasan a formar un DAG versionado, testeable y documentado. En trabajo real tendrás que justificar dependencias, contratos de datos y cómo despliegas cambios sin romper modelos downstream. Para trabajar Documentación, lineage y CI de forma profesional, no te quedes con el ejemplo: identifica la entrada, ejecuta el caso base, provoca al menos un caso incorrecto y compara el resultado con un control independiente. En este laboratorio el criterio de salida es concreto: Otra persona puede entender modelos, columnas y dependencias sin leer todo el SQL. La verificación principal será: dbt build termina sin errores y la documentación refleja los modelos. Si no puedes explicar por qué pasa esa comprobación, vuelve al paso anterior antes de continuar.

Contexto profesional

dbt aporta valor cuando las transformaciones dejan de ser consultas sueltas y pasan a formar un DAG versionado, testeable y documentado. En trabajo real tendrás que justificar dependencias, contratos de datos y cómo despliegas cambios sin romper modelos downstream.

Ejemplo real

dbt build --select state:modified+

Archivos o datos de entrada

• dbt/dbt_project.yml
• dbt/models/staging/stg_orders.sql

Práctica guiada

Documenta dim_customers y fact_orders con descriptions.

Laboratorio paso a paso

• Prepara el entorno y localiza los datos/archivos de entrada: dbt/dbt_project.yml, dbt/models/staging/stg_orders.sql. Antes de modificar nada, anota el número de filas, columnas u objetos que esperas usar.
• Reproduce el ejemplo real de la lección y guarda la salida. No avances hasta poder explicar qué hace cada bloque relacionado con «Documentación, lineage y CI».
• Ejecuta la práctica guiada: Documenta dim_customers y fact_orders con descriptions. Documenta el comando, consulta o acción exacta y el resultado obtenido.
• Resuelve el reto sin mirar la solución: Diseña un PR que cambie una columna y enumera qué tests deberían ejecutarse. Si falla, registra el mensaje de error y formula una hipótesis antes de cambiar código.
• Compara tu resultado con el criterio esperado: Otra persona puede entender modelos, columnas y dependencias sin leer todo el SQL. Después ejecuta la comprobación: dbt build termina sin errores y la documentación refleja los modelos.
• Provoca deliberadamente un caso problemático relacionado con este error frecuente: Un proyecto con SQL correcto pero sin tests/documentación es difícil de operar.. Comprueba que sabes detectarlo y corregirlo.

Reto sin ayuda

Diseña un PR que cambie una columna y enumera qué tests deberían ejecutarse.

Resultado esperado

Otra persona puede entender modelos, columnas y dependencias sin leer todo el SQL.

Cómo verificarlo

dbt build termina sin errores y la documentación refleja los modelos.

Checklist de validación

• El resultado cumple: Otra persona puede entender modelos, columnas y dependencias sin leer todo el SQL.
• Has ejecutado esta verificación y puedes explicar el resultado: dbt build termina sin errores y la documentación refleja los modelos.
• Has probado al menos un caso límite o dato inválido y el comportamiento es explícito, no silencioso.
• Puedes repetir la práctica desde cero sin copiar la solución y dejar evidencia (consulta, commit, captura o salida de consola).

Errores frecuentes

• Un proyecto con SQL correcto pero sin tests/documentación es difícil de operar.

Qué debes recordar

dbt debe hacer explícitas dependencias, tests y documentación de tus transformaciones.

Preguntas de entrevista

• ¿Qué test o contrato añadirías a este modelo y por qué? Aplícalo concretamente a «Documentación, lineage y CI».
• ¿Cómo comprobarías que el cambio no rompe modelos downstream? Explica qué evidencia enseñarías al revisor.

Siguiente paso

Aplicarás dbt dentro de proyectos de portfolio.

Recursos de esta lección