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
Redacta una descripción de modelo en una frase.
Describe cada métrica con fórmula, rango y unidad.
Separa el origen de una columna de su transformación.
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.

Mapa de prácticaAntes 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:
- Crear o editar un archivo de modelo SQL (ej:
models/staging/users.sql) y añadir una descripción en un comentario especial. - Definir metadatos adicionales en un archivo YAML (ej:
models/staging/schema.yml) para columnas y tests. - Ejecutar
dbt docs generatepara compilar la documentación. - Usar
dbt docs serveo 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.usersDespué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.usersY 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
- ¿Puedes añadir una descripción a un modelo usando tanto la configuración en SQL como en archivos YAML?
- ¿Sabes generar y servir la documentación localmente y en dbt Cloud?
- ¿Entiendes cómo el lineage visual ayuda a depurar y optimizar pipelines?
- ¿Puedes documentar columnas individuales con descripciones claras y tests asociados?
- ¿Eres capaz de identificar y corregir documentación desactualizada en un proyecto existente?
- ¿Conoces la diferencia entre documentación para staging vs. marts models?
- ¿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:
- 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 - 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. - Crea o edita el archivo
models/staging/schema.ymlpara incluir metadatos del modeloorders. 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.
- Añade tests de
uniqueynot_nullpara la columnaorder_iden el YAML. - Ejecuta
dbt docs generatey luegodbt 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.