DBT: Copilot para la documentación

Introducción

La documentación es clave para la calidad de un proyecto DBT, pero puede resultar una tarea repetitiva y costosa.
Hoy en día, contamos con asistentes inteligentes como GitHub Copilot o ChatGPT que nos ayudan a generar descripciones iniciales de modelos y campos.

Cómo utilizar Copilot en DBT

Copilot puede analizar el nombre de una tabla o columna y proponer automáticamente una descripción base.
Ejemplo:

columns:
  - name: customer_id
    description: # Copilot sugiere: "Identificador único del cliente en la tabla."
  - name: invoice_date
    description: # Copilot sugiere: "Fecha en la que se emitió la factura."

Estas sugerencias se pueden revisar y ajustar según el contexto de negocio.

Ventajas de usar IA en documentación

Ahorro de tiempo: genera borradores automáticos en segundos.
Consistencia inicial: asegura que todas las columnas tengan al menos una descripción.
Enfoque del equipo: los data engineers dedican menos tiempo a escribir documentación y más a validar que sea correcta.

Buenas prácticas

Usar Copilot como punto de partida, nunca como fuente definitiva.
Revisar siempre las descripciones para asegurar que reflejen el significado real en el negocio.
Centralizar las descripciones finales en Markdown o un catálogo maestro, de forma que se puedan reutilizar en BRONZE, SILVER y GOLD.

Uso de Copilot para acelerar la documentación en DBT

Más allá de documentar manualmente, podemos instalar la extensión de Copilot y aprovecharla para generar la documentación y añadir los tests básicos automáticamente.

Con una serie de prompts, es posible pedirle a la IA que realice tareas como:

Generar descripciones

Crear descripciones para cada tabla y campo de los modelos en la capa BRONZE.

Aplicar tests básicos

Validar claves subrogadas y business keys con los tests de DBT.

Extraer y centralizar documentación

Extraer las descripciones de los modelos y guardarlas en ficheros docs en bloques docs en formato Markdown.
Actualizar los modelos para que referencien estas variables de documentación.

Documentar capas posteriores

Añadir descripciones a la capa SILVER y vincularlas a las variables de docs.
Repetir el mismo proceso con la capa GOLD.

Ejemplo:

Ahora voy a ir modelo por modelo para sincronizar las columnas.
Una vez realizada esta sincronización, empezaré a utilizar Copilot para generar y mantener la documentación.

Se puede solicitar a Copilot que realice todas las tareas descritas anteriormente: generar descripciones de tablas y campos, aplicar tests básicos, extraer documentación en Markdown y actualizar referencias en los modelos.

Es importante tener en cuenta que este proceso puede ser tedioso y requiere pruebas y ajustes manuales, ya que la IA no sustituye completamente la revisión humana.

Una vez completado todo el proceso, se puede visualizar la documentación ejecutando el siguiente comando:
- dbt docs serve

A continuación se muestran capturas del servidor web que DBT levanta, el cual permite explorar la documentación generada de los modelos, columnas y tests.