En este documento, se describen las prácticas recomendadas para estructurar y nombrar archivos de flujo de trabajo de SQL en el directorio raíz definitions de un repositorio de Dataform. La estructura recomendada del directorio definitions refleja las etapas de un flujo de trabajo de SQL. Puede adoptar cualquier estructura que se adapte a las necesidades de su empresa.
Recomendamos estructurar el código de flujo de trabajo de SQL en el directorio definitions por los siguientes motivos:
- Mejora la colaboración en la base de código designando equipos a las partes seleccionadas del flujo de trabajo.
- Mejorar el mantenimiento del flujo de trabajo de SQL en caso de cambios organizacionales
- Mejoras la navegación por la base de código.
- Mejorar la escalabilidad de la base de código.
- Minimizar la sobrecarga administrativa de su equipo.
Estructura recomendada del directorio definitions
El directorio raíz definitions en un repositorio de Dataform contiene código que crea elementos de tu flujo de trabajo de SQL. Puedes organizar los archivos del directorio definitions en una estructura de directorios que refleje la estructura del flujo de trabajo.
Cuando desarrollas un flujo de trabajo de SQL, declaras tablas de origen y las transformas para crear tablas de salida que puedas usar con fines comerciales o de estadísticas.
Puede distinguir tres etapas clave de un flujo de trabajo de SQL:
- Declaración de fuentes de datos
- Transformación de los datos de origen
- Definición de tablas de salida de los datos de origen transformados
La siguiente estructura de subdirectorios en el directorio definitions refleja las etapas clave de un flujo de trabajo de SQL:
sources- Declaraciones de fuentes de datos y transformación básica de datos fuente, por ejemplo, filtros.
intermediate- Tablas y acciones que leen de
sourcesy transforman los datos antes de usar los datos transformados para definir tablas deoutputs. Por lo general, las tablas no se exponen a procesos o herramientas adicionales, como herramientas de inteligencia empresarial (IE), después de que Dataform las ejecute en BigQuery. outputs- Definiciones de tablas que consumen los procesos o las herramientas, como IE, una vez que Dataform las ejecuta en BigQuery.
extra- Archivos fuera de la canalización principal de tu flujo de trabajo de SQL, por ejemplo, archivos que contienen datos del flujo de trabajo preparados para uso adicional, como el aprendizaje automático. Un subdirectorio opcional y personalizado
Prácticas recomendadas para sources
El subdirectorio de sources contiene la primera etapa de tu flujo de trabajo de SQL: la declaración y la transformación básica de los datos de origen.
En el subdirectorio sources, almacena las declaraciones de la fuente de datos y las tablas que filtran, categorizan, transforman o renombran columnas.
Evite almacenar tablas que combinen datos de varias fuentes.
Transforma los datos de sources en tablas almacenadas en el subdirectorio intermediate.
Si declaras fuentes de datos de varios grupos, por ejemplo, Google Ads o Google Analytics, dedica un subdirectorio a cada grupo.
En el siguiente ejemplo, se muestra una estructura de subdirectorio de sources con dos grupos de origen:
definitions/
sources/
google_ads/
google_ads_filtered.sqlx
google_ads_criteria_metrics.sqlx
google_ads_criteria_metrics_filtered.sqlx
google_ads_labels.sqlx
google_ads_labels_filtered.sqlx
google_analytics/
google_analytics_users.sqlx
google_analytics_users_filtered.sqlx
google_analytics_sessions.sqlx
Si declaras varias tablas de fuente de datos dentro del mismo esquema, puedes consolidar sus declaraciones en un solo archivo JavaScript. En un archivo de JavaScript, puedes almacenar varias declaraciones de fuentes de datos. Para obtener más información sobre cómo crear declaraciones de fuente de datos con JavaScript, consulta Crea flujos de trabajo de SQL de Dataform con JavaScript.
En la siguiente muestra de código, se muestran varias fuentes de datos dentro de un esquema, declaradas en un solo archivo de JavaScript:
[
"source_table_1",
"source_table_2",
"source_table_3"
].forEach((name) =>
declare({
database: "gcp_project",
schema: "source_dataset",
name,
})
);
A fin de proteger tu flujo de trabajo de SQL contra cambios en la fuente de datos, puedes crear una vista para cada declaración de fuente de datos, por ejemplo, analytics_users_filtered.sqlx.
La vista puede contener filtrado y formato básicos de datos fuente.
Almacena las vistas en el subdirectorio sources.
Luego, cuando crees tablas intermediate o outputs, haz referencia a las vistas en lugar de tablas sin procesar de origen. Este enfoque te permite probar las tablas fuente.
En el caso de que una tabla de origen cambie, puedes modificar su vista, por ejemplo, agregando filtros o volviendo a transmitir los datos.
Prácticas recomendadas para intermediate
El subdirectorio de intermediate contiene la segunda etapa de tu flujo de trabajo de SQL: la transformación y la agregación de datos de origen de una o varias fuentes.
En el subdirectorio intermediate, almacena archivos que transformen de forma significativa los datos de origen de una o varias fuentes en el subdirectorio sources, por ejemplo, tablas que unan datos. Por lo general, las tablas del subdirectorio intermediate consultan datos de tablas de origen o de otras tablas intermediate.
Usa tablas intermediate para crear tablas outputs.
Por lo general, las tablas intermediate no se usan con fines adicionales, por ejemplo, estadísticas de datos, después de que Dataform las ejecuta en BigQuery.
Puedes pensar en las tablas intermediate como la lógica de transformación de datos que permite la creación de tablas de salida.
Te recomendamos que documentes y pruebes todas las tablas de intermediate.
Prácticas recomendadas para outputs
El subdirectorio de outputs contiene la etapa final de tu flujo de trabajo de SQL: la creación de tablas de salida para tus fines comerciales a partir de los datos transformados.
En el directorio outputs, almacena las tablas que planeas usar en procesos o herramientas adicionales después de que Dataform las ejecute en BigQuery, por ejemplo, informes o paneles. Por lo general, las tablas del directorio outputs consultan datos de tablas intermediate.
Agrupar tablas outputs por la entidad comercial con la que están relacionados, por ejemplo, marketing, pedidos o estadísticas Dedicar un subdirectorio a cada entidad comercial
A fin de almacenar tablas de salida por separado en BigQuery, puedes configurar un esquema dedicado para las tablas de salida. Si deseas obtener instrucciones para configurar el esquema de la tabla, consulta Establece la configuración adicional de la tabla.
En el siguiente ejemplo, se muestra una estructura de subdirectorio de outputs con dos entidades comerciales:
definitions/
outputs/
orders/
orders.sqlx
returns.sqlx
sales/
sales.sqlx
revenue.sqlx
marketing/
campaigns.sqlx
Te recomendamos que documentes y pruebes todas las tablas de outputs.
Estrategia de asignación de nombres
Los nombres de todos los archivos en Dataform deben cumplir con los lineamientos para nombrar tablas de BigQuery.
Recomendamos que los nombres de los archivos que se encuentran en el directorio definitions de un repositorio de Dataform reflejen la estructura de subdirectorios.
En el subdirectorio sources, los nombres de archivo deben apuntar a la fuente a la que está relacionado el archivo. Agrega el nombre de la fuente como un prefijo a los nombres de archivo, por ejemplo, analytics_filtered.sqlx.
En el subdirectorio intermediate, los nombres de archivo deben identificar el subdirectorio para que los colaboradores puedan distinguir con claridad los archivos intermediate.
Selecciona un prefijo único y aplícalo solo a los archivos del directorio intermediate. Por ejemplo, stg_ads_concept.sqlx.
En el subdirectorio de outputs, los nombres de archivo deben ser concisos, por ejemplo, orders.sqlx. Si tienes tablas outputs con los mismos nombres en diferentes subdirectorios de entidades, agrega un prefijo que identifique a la entidad, por ejemplo, sales_revenue.sqlx y ads_revenue.sqlx.
En el siguiente ejemplo, se muestra una estructura de subdirectorio dentro del directorio definitions con nombres de archivo que cumplen con la estrategia de nombres recomendada:
definitions/
sources/
google_analytics.sqlx
google_analytics_filtered.sqlx
intermediate/
stg_analytics_concept.sqlx
outputs/
customers.sqlx
sales/
sales.sqlx
sales_revenue.sqlx
ads/
campaigns.sqlx
ads_revenue.sqlx
¿Qué sigue?
- Para obtener más información sobre los flujos de trabajo de SQL en Dataform, consulta Introducción a los flujos de trabajo de SQL.
- Para obtener más información sobre los repositorios de Dataform, consulta Introducción a los repositorios.
- Para obtener más información sobre cómo dividir repositorios, consulta Introducción a la división de repositorios.