DBT: Documentación

Introducción

• Documentar un proyecto de DBT es fundamental para que cualquier miembro del equipo pueda entender el significado de cada modelo, tabla y campo.
• La documentación se realiza en ficheros .yml, que acompañan a los modelos y permiten añadir:
  • Descripciones de modelos.
  • Descripciones de columnas.
  • Tests de calidad de datos.

Formas de reutilizar descripciones

En proyectos grandes, muchos campos se repiten a lo largo de las capas (BRONZE → SILVER → GOLD). Por ello, conviene evitar escribir las descripciones manualmente una y otra vez.

Opción 1: Anchors (YAML anchors & aliases)

• Permiten definir una descripción una vez y reutilizarla en el mismo fichero .yml.
• Limitación: solo funcionan dentro del mismo fichero.
• Ejemplo:

columns:
  - name: customer_id
    description: &customer_id "Identificador único del cliente"
  - name: id_cliente
    description: *customer_id

Opción 2: Ficheros Markdown

• Permiten centralizar descripciones y reutilizarlas en distintos ficheros .yml.
• Ventaja: ideales cuando un mismo campo atraviesa varias capas (BRONZE, SILVER y GOLD).
• Se puede mantener un fichero único con todas las descripciones y referenciarlo desde cualquier modelo.
• Ejemplo:

columns:
  - name: customer_id
    description: "{{ doc('customer_id') }}"

Buenas prácticas

• Mantener un catálogo único de descripciones accesible desde toda la organización.
• Documentar en BRONZE y heredar esas descripciones en SILVER y GOLD para asegurar consistencia.
• Aprovechar los tests en YAML para validar calidad de datos junto a la documentación (ejemplo: unique, not_null, relationships).

Herramientas de apoyo

• La documentación puede escribirse manualmente en los ficheros .yml.
• Alternativamente, se puede utilizar la extensión Power DBT Utils en VSCode, que facilita la generación y edición de documentación directamente sobre los modelos.