Concepto clave

La documentación y el lineage en dbt Cloud son como el manual de instrucciones y el mapa de ruta de un proyecto analytics. La documentación explica qué hace cada modelo, qué columnas contiene y cómo se relaciona con el negocio, mientras que el lineage muestra visualmente cómo los datos fluyen desde las fuentes crudas hasta los modelos finales, permitiendo rastrear el impacto de cambios.

Imagina que estás construyendo un automóvil: la documentación sería el manual que describe cada pieza (motor, transmisión, frenos) y su función, y el lineage sería el diagrama que muestra cómo la energía del motor se transmite a las ruedas. En analytics, esto significa que cualquier miembro del equipo puede entender rápidamente qué datos están disponibles, cómo se transformaron y qué dependencias existen.

Cómo funciona en la práctica

En dbt Cloud, la documentación se crea principalmente en archivos YAML (como schema.yml) y mediante comentarios en los modelos SQL. El lineage se genera automáticamente cuando ejecutas dbt docs generate y dbt docs serve, creando un sitio web interactivo.

Paso a paso: 1) Define tus modelos en SQL con nombres descriptivos. 2) Crea un archivo schema.yml para documentar cada modelo, sus columnas y tests. 3) Ejecuta dbt docs generate para compilar la documentación. 4) Usa dbt docs serve o la interfaz de dbt Cloud para visualizar el lineage. Por ejemplo, si tienes un modelo orders_cleaned que depende de raw_orders, el lineage mostrará una flecha desde raw_orders hacia orders_cleaned.

Codigo en accion

Antes: Modelo SQL sin documentación.

-- models/staging/stg_orders.sql
SELECT 
    order_id,
    customer_id,
    amount
FROM raw.orders
WHERE status = 'completed'

Después: Modelo SQL con documentación en YAML.

# models/staging/schema.yml
version: 2

models:
  - name: stg_orders
    description: "Modelo de staging para órdenes completadas, limpia datos crudos"
    columns:
      - name: order_id
        description: "Identificador único de la orden"
        tests:
          - unique
          - not_null
      - name: customer_id
        description: "ID del cliente que realizó la orden"
      - name: amount
        description: "Monto total de la orden en USD"
        tests:
          - accepted_values:
              values: [0, 1000]

Ejecuta esto para generar documentación:

dbt docs generate
dbt docs serve

Errores comunes

Documentación desactualizada: Actualizar modelos SQL sin modificar los archivos YAML, llevando a inconsistencias. Solución: Revisa la documentación en cada cambio y usa herramientas como dbt test para validar.
Falta de descripciones claras: Usar descripciones genéricas como "modelo de datos" que no ayudan al usuario. Solución: Describe el propósito del modelo en términos de negocio, por ejemplo, "Calcula el ingreso mensual por cliente".
Ignorar el lineage en refactorizaciones: Cambiar dependencias sin verificar el impacto en otros modelos. Solución: Siempre consulta el lineage gráfico antes de modificar dependencias para evitar romper flujos de datos.
No documentar columnas críticas: Dejar columnas sin descripción, especialmente aquellas usadas en métricas clave. Solución: Documenta todas las columnas, enfocándote en las que se usan en reports o dashboards.

Checklist de dominio

¿Puedes generar y visualizar el sitio de documentación de dbt localmente o en dbt Cloud?
¿Documentas cada modelo y columna con descripciones que un analista no técnico pueda entender?
¿Usas el lineage para identificar dependencias antes de modificar un modelo?
¿Incluyes ejemplos de uso o notas en la documentación para contextos complejos?
¿Actualizas la documentación sincrónicamente con cambios en los modelos SQL?
¿Aplicas tests directamente desde los archivos YAML de documentación?
¿Compartes el lineage con stakeholders para explicar flujos de datos?

Documenta y visualiza el lineage de un modelo de analytics

En este ejercicio, mejorarás la documentación de un proyecto dbt existente y usarás el lineage para analizar dependencias.

Prepara tu entorno: Abre dbt Cloud o tu terminal local con un proyecto dbt que tenga al menos 3 modelos interconectados (ej: raw → staging → marts). Si no tienes uno, crea modelos simples como raw_sales.sql, stg_sales.sql, y sales_report.sql con dependencias usando {{ ref() }}.
Documenta un modelo: Elige un modelo, por ejemplo stg_sales.sql. Crea o edita su archivo schema.yml para incluir: una descripción del modelo, descripciones para cada columna, y al menos un test por columna (como not_null o unique). Usa el ejemplo de código de la lección como guía.
Genera la documentación: Ejecuta dbt docs generate seguido de dbt docs serve en tu terminal, o usa la función de documentación en dbt Cloud. Abre el sitio web generado (generalmente en http://localhost:8080).
Analiza el lineage: En el sitio de documentación, navega al modelo que documentaste. Haz clic en el gráfico de lineage para ver sus dependencias ascendentes (fuentes) y descendentes (modelos que lo usan). Toma una captura de pantalla o anota qué otros modelos están conectados.
Propón una mejora: Basado en el lineage, identifica un modelo que podría refactorizarse para reducir dependencias o mejorar la claridad. Escribe una breve explicación de cómo lo harías (ej: dividir un modelo grande en dos más pequeños).

Pistas

Si no tienes un proyecto dbt, usa el ejemplo rápido: crea archivos SQL con SELECT simples y referencias usando {{ ref('model_name') }}.
En dbt Cloud, la documentación se genera automáticamente al ejecutar jobs; busca la pestaña 'Documentation' en la interfaz.

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.

Quiz: Documentación y Lineage

Quiz Interactivo