Concepto clave

El lineage (linaje) en dbt Cloud es la representación visual de cómo tus modelos de datos se conectan entre sí, mostrando las dependencias y el flujo de transformación. Piensa en esto como un mapa de carreteras para tus datos: cada modelo es una ciudad y las dependencias son las carreteras que conectan esas ciudades. Este mapa te permite entender rápidamente qué modelos dependen de otros, cómo se transforman los datos paso a paso y qué impacto tendría cambiar un modelo específico.

En el mundo real, imagina que estás construyendo un reporte de ventas. Tienes datos brutos de transacciones, luego los limpias, los agrupas por producto, los unes con información de clientes y finalmente creas un resumen ejecutivo. El lineage te muestra este flujo completo, desde los datos crudos hasta el reporte final, ayudándote a identificar cuellos de botella, errores de lógica o dependencias críticas que podrían romper todo tu pipeline si fallan.

Cómo funciona en la práctica

dbt Cloud genera automáticamente el lineage basándose en las referencias entre modelos en tus archivos SQL. Cuando defines un modelo que referencia a otro usando ref() o source(), dbt detecta esta relación y la incluye en el lineage. Para visualizarlo, accedes a la interfaz web de dbt Cloud, navegas a tu proyecto y seleccionas la opción "Lineage" en el menú principal.

Veamos un ejemplo paso a paso: Supongamos que tienes tres modelos: raw_orders (datos brutos), cleaned_orders (datos limpios) y monthly_sales (agregado mensual). En dbt Cloud, verías un gráfico con tres nodos conectados por flechas que van desde raw_orders a cleaned_orders y desde ahí a monthly_sales. Al hacer clic en cualquier nodo, puedes ver detalles como el código SQL, los tests asociados y la documentación. Esto te permite rastrear rápidamente cómo un cambio en raw_orders afectaría a monthly_sales sin necesidad de revisar manualmente cada archivo.

Codigo en accion

Aquí tienes un ejemplo funcional de cómo se definen modelos que generan lineage automáticamente en dbt. Primero, el modelo base:

-- models/staging/stg_orders.sql
{{ config(materialized='view') }}

SELECT 
    order_id,
    customer_id,
    order_date,
    amount,
    status
FROM {{ source('raw_data', 'orders') }}
WHERE status != 'cancelled'

Luego, un modelo intermedio que depende del anterior:

-- models/marts/fct_orders.sql
{{ config(materialized='table') }}

SELECT 
    o.order_id,
    o.customer_id,
    o.order_date,
    o.amount,
    c.customer_name,
    c.region
FROM {{ ref('stg_orders') }} o
LEFT JOIN {{ ref('dim_customers') }} c ON o.customer_id = c.customer_id

En dbt Cloud, estos modelos aparecerán conectados en el lineage, mostrando que fct_orders depende de stg_orders y dim_customers. Puedes copiar y pegar este código en tu proyecto para verlo en acción.

Errores comunes

No usar ref() o source() correctamente: Si escribes nombres de tablas directamente (ej: FROM orders en lugar de FROM {{ ref('stg_orders') }}), dbt no podrá detectar la dependencia y el lineage estará incompleto. Siempre usa las funciones de Jinja para referenciar modelos.
Ignorar el lineage al refactorizar: Al cambiar un modelo, no revisar el lineage puede llevar a romper dependencias inesperadas. Antes de modificar, siempre verifica qué modelos dependen del que vas a cambiar usando la vista de lineage.
No documentar modelos clave: El lineage muestra conexiones, pero sin documentación adjunta (ej: descripciones en archivos .yml), es difícil entender el propósito de cada modelo. Asegúrate de agregar documentación a modelos críticos para que el lineage sea más informativo.
Asumir que el lineage es estático: El lineage se actualiza automáticamente al ejecutar dbt run o dbt compile. Si no ves cambios recientes, verifica que hayas ejecutado estos comandos en dbt Cloud.

Checklist de dominio

Puedo acceder al lineage en dbt Cloud y navegar entre modelos conectados.
Sé cómo interpretar las flechas en el lineage para entender dependencias (ej: modelo A → modelo B significa que B depende de A).
He usado el lineage para identificar el impacto de un cambio propuesto en un modelo específico.
Puedo explicar por qué es crucial usar ref() y source() en lugar de nombres de tablas directos.
He agregado documentación a al menos un modelo y verificado que aparezca en el lineage al hacer clic en él.
Puedo rastrear un error desde un modelo final hasta sus fuentes usando el lineage.
Sé cómo actualizar el lineage después de hacer cambios en el código (ej: ejecutando dbt compile).

Analizar y Documentar Dependencias en un Proyecto Existente

En este ejercicio, practicarás usando el lineage en dbt Cloud para entender y documentar las dependencias en un proyecto analytics real. Sigue estos pasos:

Abre tu proyecto en dbt Cloud y navega a la sección "Lineage" en el menú principal.
Identifica un modelo central en tu proyecto (ej: un modelo de hechos como fct_sales). Haz clic en él para ver sus dependencias.
Traza todas las dependencias hacia atrás: anota qué modelos fuente y staging alimentan este modelo central. Usa la funcionalidad de zoom y paneo si es necesario.
Traza todas las dependencias hacia adelante: anota qué modelos (ej: reportes o marts) dependen de este modelo central.
Crea un documento breve (puede ser un archivo de texto o un comentario en el código) que resuma estas dependencias, incluyendo cuántos niveles hay y si hay dependencias circulares.
Agrega documentación a al menos un modelo en este flujo usando un archivo .yml, describiendo su propósito y relaciones clave.
Verifica que tu documentación aparezca en el lineage al hacer clic en el modelo.

Pistas

Si no tienes un proyecto propio, usa el proyecto de ejemplo "jaffle_shop" incluido en dbt Cloud para practicar.
Presta atencion a las flechas en el lineage: las que salen de un modelo indican dependencias hacia adelante, las que entran indican dependencias hacia atras.
Usa la busqueda en la interfaz de lineage para encontrar modelos especificos rapidamente.

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.

Visualizar Lineage y Dependencias entre Modelos