Saltar al contenido

Lección 12 de 20 · Lectura y práctica

Añadir Descripciones y Metadatos a Modelos

Tipo de lección: VideoConcepto claveEn dbt, la documentación no es solo un complemento opcional, es una parte fundamental del modelado de datos que transforma tu proyecto de un conjunto de scripts a un sistema de conocimiento.

Del concepto a la práctica

Taller de esta lección

Una descripción de calidad responde qué representa el dato, cómo se calcula y qué no debe inferirse. Los metadatos complementan esa explicación con información operativa, como propietario o dominio, siempre que sea verdadera y mantenible.

Ejemplo resuelto

Para conversion_rate, escribe “sesiones con al menos un pedido pagado divididas por sesiones elegibles, expresado como proporción entre 0 y 1”. No lo describas como porcentaje si el valor almacenado es 0.25. Para revenue, indica que se suma line_total y que la moneda proviene de la fuente.

Pruébalo

  1. Redacta una descripción de modelo en una frase.

  2. Describe cada métrica con fórmula, rango y unidad.

  3. Separa el origen de una columna de su transformación.

  4. Revisa que el YAML nombre exactamente los modelos y columnas.

Comprueba tu resultado

Error frecuente: usar “25%” para un valor almacenado como 0.25 sin aclarar la conversión. Corrígelo diciendo proporción o multiplicando por 100 de forma explícita.

Ejercicio: documenta tres sesiones y una compra; la tasa es 1/3. Resultado esperado: la descripción permite reproducir 0.3333... como proporción y no confunde ese valor con 33.33 puntos porcentuales ni con importe monetario.

Cuenta cada sesión convertida una sola vez: pedidos/sesiones puede superar 1 si una sesión contiene varios pedidos. Para revenue, agrupa por moneda o declara una conversión con tasa y fecha antes de sumar; sumar importes de monedas diferentes no produce un total monetario comparable.

Flujo de datos: dos formatos de la misma fecha se normalizan y un vacío queda marcado antes de comprobar tipos, duplicados y unidades.
CursaloMapa de práctica
Antes del gráfico, revisa los datos

Antes de analizar, comprueba los tipos, valores vacíos, duplicados y unidades. Decide cómo tratar cada problema según el contexto y conserva la trazabilidad del cambio. Un gráfico solo es útil si los datos de entrada son coherentes.

Ver la infografía en tamaño completo ↗

Tipo de lección: Video

Concepto clave

En dbt, la documentación no es solo un complemento opcional, es una parte fundamental del modelado de datos que transforma tu proyecto de un conjunto de scripts a un sistema de conocimiento compartido. Imagina que estás construyendo un mapa de una ciudad: los modelos son los edificios, pero sin nombres de calles, señales o leyendas, nadie puede navegar eficientemente. Añadir descripciones y metadatos es como poner esos nombres y señales, permitiendo que tu equipo entienda qué representa cada tabla, de dónde viene la data y cómo usarla correctamente.

En el contexto de dbt Cloud, esta documentación se integra directamente en la interfaz, creando un lineage visual que muestra las dependencias entre modelos. Esto es crucial para roles como Analytics Engineer, donde la claridad en los pipelines de datos impacta directamente en la toma de decisiones empresariales. No documentar es como dejar un proyecto de construcción sin planos: eventualmente, alguien se perderá o cometerá errores costosos.

Cómo funciona en la práctica

Para añadir documentación en dbt, sigues un flujo estructurado que comienza en los archivos de modelo. Primero, defines descripciones directamente en los archivos SQL o YAML usando sintaxis específica. Luego, generas y sirves la documentación a través de comandos de dbt, que compilan esta información en una interfaz web navegable. Veamos un ejemplo paso a paso:

  1. Crear o editar un archivo de modelo SQL (ej: models/staging/users.sql) y añadir una descripción en un comentario especial.
  2. Definir metadatos adicionales en un archivo YAML (ej: models/staging/schema.yml) para columnas y tests.
  3. Ejecutar dbt docs generate para compilar la documentación.
  4. Usar dbt docs serve o la funcionalidad integrada en dbt Cloud para visualizar el resultado.

Este proceso asegura que cada cambio en el código vaya acompañado de su correspondiente actualización en la documentación, manteniendo todo sincronizado.

Codigo en accion

Antes de añadir documentación, un modelo podría verse así:

-- models/staging/users.sql
SELECT
    user_id,
    email,
    created_at
FROM raw.users

Después de añadir descripciones y metadatos:

-- models/staging/users.sql
{{ config(
    description="Tabla de usuarios extraída desde la fuente raw, con limpieza básica de datos."
) }}
SELECT
    user_id,
    email,
    created_at
FROM raw.users

Y en el archivo YAML correspondiente:

# models/staging/schema.yml
version: 2

models:
  - name: users
    description: "Modelo de staging para usuarios. Contiene datos crudos transformados para uso en modelos marts."
    columns:
      - name: user_id
        description: "Identificador único del usuario, generado por el sistema."
        tests:
          - unique
          - not_null
      - name: email
        description: "Correo electrónico del usuario, validado con formato estándar."
      - name: created_at
        description: "Fecha y hora de creación del registro en la fuente original."

Errores comunes

  • Documentación desactualizada: Añadir descripciones una vez y olvidarlas. Cuando cambias un modelo, actualiza también su documentación para evitar confusiones.
  • Descripciones vagas: Usar términos como "datos de usuario" sin contexto. En su lugar, sé específico: "Usuarios registrados en la plataforma web, excluyendo cuentas inactivas".
  • Ignorar el lineage: No revisar el gráfico de dependencias en dbt Cloud. Úsalo para identificar impactos de cambios y optimizar flujos de datos.
  • No documentar columnas clave: Solo describir la tabla general. Cada columna importante debe tener su propia descripción, especialmente si usa lógica compleja.
  • Confiar solo en comentarios en SQL: Los comentarios en SQL no se capturan automáticamente en la documentación de dbt. Usa los métodos oficiales (config o YAML).

Checklist de dominio

  1. ¿Puedes añadir una descripción a un modelo usando tanto la configuración en SQL como en archivos YAML?
  2. ¿Sabes generar y servir la documentación localmente y en dbt Cloud?
  3. ¿Entiendes cómo el lineage visual ayuda a depurar y optimizar pipelines?
  4. ¿Puedes documentar columnas individuales con descripciones claras y tests asociados?
  5. ¿Eres capaz de identificar y corregir documentación desactualizada en un proyecto existente?
  6. ¿Conoces la diferencia entre documentación para staging vs. marts models?
  7. ¿Puedes explicar por qué la documentación es crítica para la colaboración en equipos analytics?

Documentar un modelo de staging para pedidos

En este ejercicio, practicarás añadir descripciones y metadatos a un modelo existente en dbt. Sigue estos pasos:

  1. Abre tu proyecto dbt Cloud o local y localiza el modelo models/staging/orders.sql. Si no existe, créalo con este contenido básico:
    SELECT
        order_id,
        customer_id,
        order_date,
        total_amount
    FROM raw.orders
  2. Añade una descripción al modelo usando la función {{ config() }} en el archivo SQL. La descripción debe explicar que este es un modelo de staging para pedidos, con limpieza de datos básica.
  3. Crea o edita el archivo models/staging/schema.yml para incluir metadatos del modelo orders. Define descripciones para cada columna:
    • order_id: Identificador único del pedido.
    • customer_id: ID del cliente asociado al pedido.
    • order_date: Fecha en que se realizó el pedido.
    • total_amount: Monto total del pedido en USD.
  4. Añade tests de unique y not_null para la columna order_id en el YAML.
  5. Ejecuta dbt docs generate y luego dbt docs serve (o usa la interfaz de dbt Cloud) para verificar que la documentación se muestra correctamente, incluyendo el lineage.
Pistas
  • Recuerda que la sintaxis de config en SQL usa dobles llaves: {{ config(description="...") }}.
  • En el archivo YAML, la estructura jerárquica es clave: models -> name -> columns -> name, description, tests.
  • Si no ves los cambios en la documentación, asegúrate de haber guardado los archivos y regenerado la docs con dbt docs generate.

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.

Sigue con Modelado de Datos en dbt Cloud: Tests, Documentación y Práctica

Esta lección forma parte de un curso de Cursalo. Revisa su programa y elige entre la compra individual o el acceso a toda la escuela.

Si ya tenías acceso a este curso, entra con tu cuenta: tus derechos y tu progreso se conservan. No necesitas comprarlo de nuevo.

01 / ELEGIR UNA RUTA

El próximo paso

Aprende IA mientras construyes algo que sí necesitas.

Empieza por el curso inicial o explora el catálogo para encontrar una práctica alineada con tu trabajo.