Estructuración de código en un repositorio

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. Puedes adoptar cualquier estructura que se adapte a las necesidades de tu empresa.

Te recomendamos estructurar el código del 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 partes seleccionadas de tu flujo de trabajo.
  • Mejora la capacidad de mantenimiento del flujo de trabajo de SQL en caso de cambios organizativos.
  • Mejorar la navegación a través de tu base de código
  • Mejora la escalabilidad de la base de código.
  • Minimiza la sobrecarga administrativa de tu equipo.

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 en el directorio definitions en una estructura de directorios que refleje la estructura del flujo de trabajo.

Cuando desarrollas un flujo de trabajo de SQL, declaras las tablas de origen y las transformas para crear tablas de salida que puedes usar con fines comerciales o analíticos.

Puedes distinguir tres etapas clave de un flujo de trabajo de SQL:

  1. Declaración de fuentes de datos
  2. Transformación de datos de origen
  3. Definición de las tablas de salida a partir 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 los datos de origen, por ejemplo, filtrado.
intermediate
Tablas y acciones que leen de sources y transforman datos antes de que los uses para definir tablas outputs. Por lo general, las tablas no se exponen a procesos o herramientas adicionales, como las herramientas de inteligencia empresarial (IE), después de que Dataform las ejecuta en BigQuery.
outputs
Definiciones de tablas que consumen procesos o herramientas, como la BI, después de 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 de flujo de trabajo preparados para un uso adicional, como el aprendizaje automático. Es un subdirectorio opcional y personalizado.

Prácticas recomendadas para sources

El subdirectorio 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 y las tablas de fuentes de datos que filtran, categorizan, transmiten o cambian el nombre de las columnas.

Evita almacenar tablas que combinen datos de varias fuentes.

Transforma los datos de sources en las tablas almacenadas en el subdirectorio intermediate.

Si declaras fuentes de datos de varios grupos, por ejemplo, Google Ads o Google Analytics, asigna un subdirectorio a cada uno.

En el siguiente ejemplo, se muestra una estructura de subdirectorios de sources con dos grupos de fuentes:

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 fuentes de datos dentro del mismo esquema, puedes consolidar sus declaraciones en un solo archivo JavaScript. a Para obtener más información sobre cómo crear declaraciones de fuentes de datos con JavaScript, consulta Cómo crear flujos de trabajo 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 JavaScript:

[
  "source_table_1",
  "source_table_2",
  "source_table_3"
].forEach((name) =>
  declare({
    database: "gcp_project",
    schema: "source_dataset",
    name,
  })
);

Para proteger tu flujo de trabajo de SQL contra los 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 filtros y formatos básicos de los datos de origen. Almacena las vistas en el subdirectorio sources.

Luego, cuando crees tablas intermediate o outputs, haz referencia a las vistas en lugar de las tablas de origen sin procesar. Este enfoque te permite probar las tablas de origen. En caso de que cambie una tabla de origen, puedes modificar su vista, por ejemplo, agregando filtros o cambiando los datos.

Prácticas recomendadas para intermediate

El subdirectorio intermediate contiene la segunda etapa de tu flujo de trabajo de SQL: la transformación y 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 unen 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 para fines adicionales, por ejemplo, análisis de datos, después de que Dataform las ejecuta en BigQuery. Puedes considerar las tablas intermediate como la lógica de transformación de datos que habilita la creación de tablas de salida.

Te recomendamos que documentes y pruebes todas las tablas intermediate.

Prácticas recomendadas para outputs

El subdirectorio outputs contiene la etapa final de tu flujo de trabajo de SQL: la creación de tablas de resultados para tus fines comerciales a partir de 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 las tablas intermediate.

Agrupa las tablas outputs según la entidad comercial con la que se relacionan, por ejemplo, marketing, pedidos o estadísticas. Dedica un subdirectorio a cada entidad comercial.

Para almacenar las 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 Configura parámetros de configuración adicionales de la tabla.

En el siguiente ejemplo, se muestra una estructura de subdirectorios de outputs con entidades comerciales sales y marketing:

definitions/
    outputs/
        orders/
            orders.sqlx
            returns.sqlx
        sales/
            sales.sqlx
            revenue.sqlx
        marketing/
            campaigns.sqlx

Te recomendamos que documentes y pruebes todas las tablas outputs.

Estrategia de nombres

Los nombres de todos los archivos de Dataform deben cumplir con los lineamientos de nombres de tablas de BigQuery.

Te recomendamos que los nombres de los archivos del directorio definitions en un repositorio de Dataform reflejen la estructura de subdirectorios.

En el subdirectorio sources, los nombres de archivo deben apuntar a la fuente con la que se relaciona el archivo. Agrega el nombre de la fuente como 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 claramente 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 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 la entidad, por ejemplo, sales_revenue.sqlx y ads_revenue.sqlx.

En el siguiente ejemplo, se muestra una estructura de subdirectorios 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?