Estructura 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.

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 mediante la designación de equipos para partes seleccionadas del flujo de trabajo.
  • Mejorar la capacidad de mantenimiento del flujo de trabajo de SQL en caso de cambios organizativos.
  • Mejorar la navegación por tu base de código
  • Mejorar la escalabilidad de la base de código
  • Minimizar la sobrecarga administrativa de tu equipo.

El directorio raíz definitions de un repositorio de Dataform contiene código que crea elementos del 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 puedes usar con fines comerciales o estadísticos.

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
Las declaraciones de fuentes de datos y la transformación básica de los datos de origen; por ejemplo, el filtrado
intermediate
Tablas y acciones que leen desde sources y transforman datos antes de usar los datos transformados para definir tablas outputs. Por lo general, las tablas no están expuestas 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 los procesos o herramientas, como la IE, después de que Dataform las ejecuta en BigQuery.
extra
Archivos fuera de la canalización principal del flujo de trabajo de SQL, por ejemplo, archivos que contienen datos de flujo de trabajo preparados para su uso adicional, como aprendizaje automático. Un subdirectorio opcional y personalizado.

Prácticas recomendadas para sources

El subdirectorio de sources contiene la primera etapa del 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 tablas de fuente de datos que filtran, categorizan, transmiten o renombran columnas.

Evita 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 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 en el mismo esquema, puedes consolidar sus declaraciones en un solo archivo JavaScript. En un archivo JavaScript, puedes almacenar varias declaraciones de fuente 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 incluyen varias fuentes de datos en 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 básicos y formato de 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 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, si agregas filtros o vuelves a convertir los datos.

Prácticas recomendadas para intermediate

El subdirectorio de intermediate contiene la segunda etapa del flujo de trabajo de SQL: la transformación y la agregación de los datos de origen desde una o varias fuentes.

En el subdirectorio intermediate, almacena los archivos que transforman de forma significativa los datos de origen a partir de una o varias fuentes en el subdirectorio sources, por ejemplo, tablas que unen datos. Las tablas del subdirectorio intermediate suelen consultar datos de tablas fuente o, también, de otras tablas intermediate.

Usa tablas intermediate para crear tablas outputs. Por lo general, las tablas intermediate no se usan con fines adicionales, como el análisis 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 documentar y probar todas las tablas intermediate.

Prácticas recomendadas para outputs

El subdirectorio outputs contiene la etapa final del flujo de trabajo de SQL: creación de tablas de salida para 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 tablas intermediate.

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

A fin de almacenar las tablas de salida por separado en BigQuery, puedes configurar un esquema dedicado para las tablas de salida. Si quieres obtener instrucciones para configurar el esquema de la tabla, consulta Establece parámetros de configuración adicionales 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 documentar y probar todas las tablas outputs.

Estrategia de asignación de nombres

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

Recomendamos que los nombres de los archivos del directorio definitions en un repositorio de Dataform reflejen la estructura del subdirectorio.

En el subdirectorio sources, los nombres de archivo deben apuntar a la fuente con 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, de modo 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 entidad, 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 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?