Concepto clave

La estructura de proyectos en dbt Cloud es el esqueleto organizativo que determina cómo se gestionan tus transformaciones de datos. Imagina que estás construyendo una casa: los archivos de configuración son los planos, los modelos son las habitaciones, y las dependencias entre ellos son las tuberías y cables que conectan todo. Un proyecto bien estructurado te permite escalar de transformaciones simples a pipelines complejos manteniendo la claridad.

En dbt, todo gira alrededor del archivo dbt_project.yml, que actúa como el punto de entrada principal. Este archivo define el nombre de tu proyecto, la versión de dbt, y cómo se organizan los diferentes componentes. La estructura típica incluye carpetas para modelos (transformaciones SQL), tests (validaciones de calidad), documentación (explicaciones de negocio), y macros (funciones reutilizables). La clave está en mantener esta estructura consistente desde el primer día.

Cómo funciona en la práctica

Cuando inicias un proyecto en dbt Cloud, lo primero que haces es configurar tu conexión al data warehouse (como Snowflake, BigQuery o Redshift). Luego, creas la estructura básica de carpetas. Un flujo típico sería:

Crear el archivo dbt_project.yml con la configuración básica
Organizar modelos por dominio de negocio (ej: marketing, ventas, finanzas)
Definir sources.yml para mapear tus tablas fuente
Configurar profiles.yml para las credenciales de conexión
Establecer tests básicos para validar datos críticos

Por ejemplo, si estás modelando datos de e-commerce, podrías tener una carpeta 'staging' para limpieza inicial, otra 'marts' para tablas finales de negocio, y dentro de estas, subcarpetas por departamento. Esta organización refleja cómo tu equipo analiza los datos, no solo cómo están almacenados técnicamente.

Codigo en accion

Veamos un ejemplo real de configuración inicial. Primero, el archivo dbt_project.yml básico:

# dbt_project.yml
name: 'ecommerce_analytics'
version: '1.0.0'
config-version: 2

profile: 'ecommerce_profile'

model-paths: ["models"]
test-paths: ["tests"]
analysis-paths: ["analyses"]
macro-paths: ["macros"]
seed-paths: ["data"]

models:
  ecommerce_analytics:
    staging:
      materialized: view
    marts:
      materialized: table
      marketing:
        materialized: incremental
        unique_key: campaign_id

Ahora, un modelo SQL simple en models/staging/stg_orders.sql:

-- models/staging/stg_orders.sql
{{ config(materialized='view') }}

with source as (
    select * from {{ source('raw_data', 'orders') }}
),

transformed as (
    select
        order_id,
        customer_id,
        order_date,
        amount,
        status,
        -- Limpieza y estandarización
        lower(trim(status)) as status_clean,
        amount * 1.16 as amount_with_tax  -- Ejemplo de transformación
    from source
)

select * from transformed

Errores comunes

1. Estructura plana sin organización: Poner todos los modelos en una sola carpeta. Solución: Organizar por capas (staging, intermediate, marts) desde el inicio.

2. Configuración inconsistente entre entornos: Usar diferentes configuraciones en desarrollo vs producción. Solución: Usar variables de entorno y perfiles específicos para cada ambiente.

3. Falta de documentación inicial: Posponer la documentación hasta el final. Solución: Documentar cada modelo con comentarios y un archivo .yml desde el primer commit.

4. Dependencias circulares: Crear referencias que forman ciclos entre modelos. Solución: Usar el comando 'dbt compile' para detectarlas temprano y diseñar un DAG claro.

5. Ignorar los tests básicos: No configurar tests de nulos o unicidad en columnas clave. Solución: Incluir tests mínimos en el schema.yml de cada modelo nuevo.

Checklist de dominio

✓ Tengo un dbt_project.yml configurado con nombre, versión y paths definidos
✓ Mis modelos están organizados en carpetas lógicas (staging, marts, etc.)
✓ Configure correctamente el archivo profiles.yml para mi data warehouse
✓ Defini sources.yml para mapear mis tablas fuente originales
✓ Establecí al menos un test básico por modelo importante
✓ Documenté cada modelo en su correspondiente archivo .yml
✓ Verifiqué que no hay dependencias circulares con dbt compile

Configura tu primer proyecto dbt Cloud desde cero

En este ejercicio, configurarás un proyecto dbt Cloud básico para analítica de ventas. Sigue estos pasos:

Crea un nuevo proyecto en dbt Cloud conectado a tu data warehouse (usa Snowflake, BigQuery o Redshift según tu configuración).
Configura el archivo dbt_project.yml con:
- Nombre: 'sales_analytics'
- Versión: '1.0.0'
- Define model-paths, test-paths, y macro-paths
- Configura materializaciones: staging como views, marts como tables
Crea la estructura de carpetas:
- models/staging/
- models/marts/
- tests/
- macros/
Implementa tu primer modelo: En models/staging/, crea stg_customers.sql que:
- Seleccione de una tabla fuente 'raw_customers'
- Limpie el campo email (trim y lowercase)
- Convierta fecha de registro a formato estándar
Agrega documentación: Crea models/staging/schema.yml documentando stg_customers con:
- Descripción del modelo
- Descripción de cada columna
- Un test de not_null en customer_id
Ejecuta dbt run para compilar y verificar que todo funciona.

Pistas

Recuerda que en dbt_project.yml, la indentación en YAML es crucial. Usa 2 espacios, no tabs.
Para referenciar una tabla fuente en SQL, usa {{ source('nombre_schema', 'nombre_tabla') }}
Puedes verificar tu estructura con 'dbt debug' antes de ejecutar el primer run completo.

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.

Estructura de Proyectos y Configuración Básica