Cuando empezás a trabajar con herramientas de transformación como dbt, SQLMesh o Dataform, aparecen dos mecanismos para traer datos a tu proyecto que se confunden frecuentemente: los orígenes externos y los datos estáticos versionados. En dbt se llaman sources y seeds. En otras herramientas tienen nombres distintos, pero el concepto subyacente es el mismo.
Ambos terminan siendo tablas que podés referenciar en tus transformaciones. Pero la diferencia entre ellos es conceptual, no solo técnica.
Qué es un origen externo
Un origen externo (source en dbt) marca datos que vienen de afuera de tu proyecto de transformación. Son datos que otro proceso carga: una extracción de API, una réplica de base de datos, un archivo que llega de un sistema externo.
La característica central es que no los controlás. No están en tu repositorio. No los versionás. No sabés con certeza cuándo cambian ni cómo. Tu proyecto de transformación los consume, pero no los gestiona.
Declarar un origen externo tiene dos propósitos:
Hacer explícita la frontera del proyecto. Cuando marcás algo como origen externo, estás diciendo: "esto viene de afuera, no es responsabilidad de mi proyecto de transformación". Esa distinción es importante para gobierno. Sabés qué depende de qué, y sabés dónde termina tu ámbito de control.
Habilitar trazabilidad y validación. Una vez que declarás el origen, podés definir tests sobre esos datos, chequear qué tan actualizados están, y hacer que aparezcan en el grafo de linaje. Si bien no los gestionás, sí los referenciás de manera explícita.
En el grafo de dependencias, los orígenes externos aparecen siempre en el borde izquierdo. Son el punto de entrada al pipeline de transformación.
Qué es un dato estático versionado
Un dato estático versionado (seed en dbt) es un archivo que vive dentro de tu proyecto. Típicamente un CSV con pocos registros y datos que no cambian frecuentemente.
La característica central es que lo controlás completamente. Está en tu repositorio. Se versiona junto con el código. Cuando cambia, el cambio queda registrado en el historial de commits.
Ejemplos típicos: mapeos de códigos de país a nombres, listas de IDs de clientes para filtrar, configuraciones de negocio que no vienen de ningún sistema externo.
Hay dos premisas para usar datos estáticos versionados:
Pocos registros. No es un mecanismo para cargar datasets grandes. Si tenés miles de registros, probablemente debería ser un origen externo cargado por otro proceso.
Naturaleza estática. Datos que no cambian frecuentemente. Si cambian todos los días, no tiene sentido versionarlos en el repositorio.
La diferencia de fondo
Si bien ambos terminan siendo tablas que podés referenciar, la diferencia está en quién los controla y dónde viven.
| Aspecto | Origen externo | Dato estático versionado |
|---|---|---|
| Origen | Externo (otro proceso lo carga) | Interno (vive en tu repo) |
| Control | No lo controlás | Lo controlás completamente |
| Versionado | No está en tu repo | Está en tu repo |
| Volumen típico | Puede ser grande | Debería ser chico |
| Posición en linaje | Siempre al borde | Puede estar en cualquier parte |
La confusión viene porque ambos pueden usarse de forma similar en el código. Pero conceptualmente son cosas distintas.
Un origen externo es una fuente de datos que estás extrayendo de algún lugar que no controlás. Un dato estático versionado es parte de tu proyecto, como cualquier otro archivo de código.
Cuándo usar cada uno
Usá un origen externo cuando:
- Los datos vienen de otro sistema (base de datos, API, archivo externo).
- No controlás cuándo ni cómo se actualizan.
- El volumen puede ser grande.
- Querés marcar explícitamente que esos datos están fuera de tu ámbito de responsabilidad.
Usá un dato estático versionado cuando:
- Los datos son pocos registros (decenas, cientos, no miles).
- Los datos no cambian frecuentemente.
- Querés que los cambios queden registrados en el historial del repositorio.
- Los datos son configuraciones o mapeos que no vienen de ningún sistema externo.
El error común
El error más frecuente es usar datos estáticos versionados para cosas que deberían ser orígenes externos. Cargar un CSV de 50.000 registros que se actualiza semanalmente como seed es usar mal el mecanismo.
El otro error es no declarar los orígenes externos. Si tu transformación lee directamente de una tabla sin declararla como source, esa dependencia queda invisible en el grafo. Perdés trazabilidad y gobierno.
Más allá de dbt
Los mismos principios aplican a otras herramientas de transformación. SQLMesh tiene external models y seeds. Dataform tiene declarations y includes. Los nombres cambian, pero la distinción conceptual es la misma:
- Datos que vienen de afuera y no controlás.
- Datos que versionás con tu proyecto y controlás completamente.
Entender esa diferencia te permite elegir el mecanismo correcto independientemente de la herramienta que uses.
En resumen
Sources y seeds (o sus equivalentes en otras herramientas) resuelven problemas distintos. Uno marca la frontera entre tu proyecto y el mundo externo. El otro te permite versionar datos estáticos junto con tu código.
La diferencia parece menor hasta que tenés que gobernar un pipeline con decenas de transformaciones. Ahí, saber qué controlás y qué no controlás se vuelve fundamental para entender el alcance de un cambio y la responsabilidad de cada parte del sistema.