Saltar al contenido

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

Generar Documentación Automatizada con dbt Docs

Concepto claveLa documentación automatizada en dbt Docs es como tener un arquitecto que dibuja planos actualizados de tu edificio de datos cada vez que construyes algo nuevo. En lugar de mantener manualmente diagramas y.

Del concepto a la práctica

Taller de esta lección

La documentación automatizada reúne metadatos del proyecto, modelos, columnas y tests en una representación navegable. Su utilidad depende de que las descripciones expliquen significado y límites, no de que exista una página generada.

Ejemplo resuelto

Para fct_orders, una descripción útil dice: tabla a nivel de línea de pedido, excluye cancelaciones y expresa line_total en la moneda de origen. La columna order_id se describe como identificador de la orden, no como “ID”.

Pruébalo

  1. Añade descripción al modelo y a tres columnas importantes.

  2. Indica granularidad, filtros y unidad monetaria.

  3. Asocia los tests definidos al modelo.

  4. Genera la documentación y busca el modelo por su nombre.

Comprueba tu resultado

Error frecuente: documentar una tabla agregada como si conservara una fila por transacción. Corrígelo escribiendo la granularidad en la primera frase y revisando el SQL.

Ejercicio: documenta un modelo con dos columnas, order_id y line_total, usando los registros A,10 y B,15. Resultado esperado: la documentación identifica la granularidad, la moneda o ausencia de moneda, el cálculo de line_total y los tests visibles; una consulta de control verifica aparte dos filas y suma 25; no afirma una suma por cliente que el modelo no contiene.

Ejecuta dbt docs generate para producir los artefactos documentales; dbt docs serve permite revisarlos localmente cuando tu entorno lo admite. El conteo de filas depende del catálogo y del adaptador: generar documentación no sustituye reconciliar la tabla con una consulta explícita.

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 ↗
Fuentes para profundizar

Concepto clave

La documentación automatizada en dbt Docs es como tener un arquitecto que dibuja planos actualizados de tu edificio de datos cada vez que construyes algo nuevo. En lugar de mantener manualmente diagramas y descripciones, dbt genera automáticamente un sitio web interactivo que muestra cómo se relacionan tus modelos, qué columnas contienen y qué pruebas están asociadas.

Imagina que trabajas en un equipo de analytics donde diferentes personas crean modelos SQL. Sin documentación automatizada, tendrías que preguntar constantemente: "¿Qué hace esta tabla?" o "¿De dónde viene esta columna?". Con dbt Docs, cada modelo, fuente y semilla queda documentado a través de comentarios en código YAML, creando un single source of truth que siempre está sincronizado con tu código.

Cómo funciona en la práctica

El proceso sigue estos pasos:

  1. Escribes documentación en archivos YAML (schema.yml) o usando comentarios en modelos SQL
  2. Ejecutas dbt docs generate para compilar la documentación
  3. Ejecutas dbt docs serve o usas dbt Cloud para visualizar el sitio web
  4. Compartes el enlace con tu equipo para colaboración

Por ejemplo, cuando documentas un modelo de customer_lifetime_value, defines su propósito, describe cada columna (como customer_id, total_purchases, avg_order_value) y especificas las pruebas aplicadas. dbt Docs luego muestra esto junto con un gráfico de lineage que traza las dependencias desde las fuentes hasta los modelos finales.

Codigo en accion

ANTES: Modelo sin documentación

-- models/marts/customer_lifetime_value.sql
SELECT 
    customer_id,
    COUNT(order_id) as total_orders,
    SUM(amount) as total_spent
FROM {{ ref('stg_orders') }}
GROUP BY 1

DESPUES: Modelo con documentación en schema.yml

# models/marts/schema.yml
version: 2

models:
  - name: customer_lifetime_value
    description: "Calcula el valor de vida del cliente basado en historial de pedidos"
    columns:
      - name: customer_id
        description: "Identificador único del cliente, enlaza con dimensiones de cliente"
        tests:
          - not_null
          - unique
      - name: total_orders
        description: "Número total de pedidos realizados por el cliente"
      - name: total_spent
        description: "Suma total gastada por el cliente en todos los pedidos"
        tests:
          - accepted_values:
              values: ['>0']

Errores comunes

  • Documentación desactualizada: Modificar modelos sin actualizar YAML. Solución: Integra revisiones de documentación en tu proceso de PR.
  • Descripciones vagas: Usar "ID del cliente" en lugar de "Identificador único, enlaza con tabla dim_customers". Solución: Sigue un template de documentación.
  • Falta de contexto empresarial: No explicar por qué existe el modelo. Solución: Incluye sección business_logic en descripciones.
  • Ignorar lineage: No documentar fuentes o semillas. Solución: Documenta todo el pipeline, no solo modelos finales.
  • No usar tags: Perder capacidad de filtrar documentación. Solución: Aplica tags como finance, marketing, sales a modelos.

Checklist de dominio

  • Puedo generar y servir dbt Docs localmente con CLI
  • Documenté al menos 3 modelos con descripciones y columnas en YAML
  • Agregué pruebas (tests) a columnas documentadas
  • Verifiqué que el lineage muestra correctamente las dependencias
  • Compartí el enlace de dbt Cloud Docs con un compañero
  • Usé tags para organizar modelos en la documentación
  • Actualicé documentación después de un cambio en un modelo

Documentar un modelo de funnel de conversión

En este ejercicio, documentarás un modelo existente de funnel de conversión para hacerlo comprensible para el equipo de marketing.

  1. Abre tu proyecto dbt y localiza el modelo marketing_funnel en models/marts/
  2. Crea o edita el archivo schema.yml en la misma carpeta
  3. Documenta el modelo con:
    • Descripción clara del propósito empresarial
    • Documentación de al menos 5 columnas clave
    • Aplica 2-3 pruebas a columnas importantes
    • Añade tags marketing y conversion
  4. Genera la documentación con dbt docs generate
  5. Verifica en dbt Docs que:
    • La descripción aparece correctamente
    • El lineage muestra fuentes correctas
    • Las columnas documentadas tienen tooltips
Pistas
  • Usa el bloque models: en YAML, no confundas con sources:
  • Para pruebas en columnas, revisa la sintaxis de accepted_values o relationships
  • Si no tienes un modelo marketing_funnel, crea uno simple con 3-4 columnas primero

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.