Prácticas recomendadas para repositorios

En este documento, se presenta la siguiente información sobre los repositorios de Dataform:

Descripción general de las prácticas recomendadas para los repositorios en Dataform

En esta sección, se presenta una descripción general de las prácticas recomendadas para administrar el tamaño y la estructura del repositorio, y el ciclo de vida del código en Dataform.

Prácticas recomendadas para el tamaño del repositorio

El tamaño del repositorio afecta varios aspectos del desarrollo en Dataform, como los siguientes:

  • Colaboración
  • Legibilidad de la base de código
  • Procesos de desarrollo
  • Compilación del flujo de trabajo
  • Ejecución del flujo de trabajo

Dataform aplica cuotas y límites de la API en los recursos de compilación. Un tamaño grande del repositorio puede hacer que este supere estas cuotas y límites. Esto puede provocar errores en la compilación y ejecución de tu flujo de trabajo.

Para mitigar ese riesgo, te recomendamos que dividas los repositorios grandes. Cuando divides un repositorio grande, separas un flujo de trabajo grande en varios flujos de trabajo más pequeños que se encuentran en diferentes repositorios y están conectados por dependencias entre repositorios.

Este enfoque te permite cumplir con las cuotas y los límites de Dataform, implementar procesos y permisos detallados, y mejorar la legibilidad y la colaboración del código base. Sin embargo, administrar repositorios divididos puede ser más difícil que administrar un solo repositorio.

Para obtener más información sobre el impacto del tamaño del repositorio en Dataform, consulta la Descripción general del tamaño del repositorio. Para obtener más información sobre las prácticas recomendadas para dividir repositorios, consulta Cómo dividir repositorios.

Prácticas recomendadas para la estructura del repositorio

Te recomendamos que estructures los archivos en el directorio definitions para que reflejen las etapas de tu flujo de trabajo. Ten en cuenta que puedes adoptar una estructura personalizada que se adapte mejor a tus necesidades.

La siguiente estructura recomendada de subdirectorios de definitions refleja las etapas clave de la mayoría de los flujos de trabajo:

  • sources para almacenar declaraciones de fuentes de datos
  • intermediate para almacenar la lógica de transformación de datos
  • output para almacenar definiciones de tablas de salida
  • extras (opcional) para almacenar archivos adicionales

Los nombres de todos los archivos en Dataform deben cumplir con los lineamientos de nomenclatura 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.

Para obtener más información sobre las prácticas recomendadas para estructurar y nombrar archivos en un repositorio, consulta Cómo estructurar el código en un repositorio.

Prácticas recomendadas para el ciclo de vida del código

El ciclo de vida del código predeterminado en Dataform consta de las siguientes fases:

Para administrar el ciclo de vida del código en Dataform, puedes crear entornos de ejecución, como desarrollo, etapa de pruebas y producción.

Para obtener más información sobre el ciclo de vida del código en Dataform, consulta Introducción al ciclo de vida del código en Dataform.

Puedes optar por mantener tus entornos de ejecución en un solo repositorio o en varios.

Entornos de ejecución en un solo repositorio

Puedes crear entornos de ejecución aislados, como desarrollo, etapa de pruebas y producción, en un solo repositorio de Dataform con anulaciones de compilación de lugares de trabajo y configuraciones de lanzamiento.

Puedes crear entornos de ejecución aislados de las siguientes maneras:

  • Divide las tablas de desarrollo y producción por esquema.
  • Divide las tablas de desarrollo y producción por esquema y proyecto Google Cloud .
  • Divide las tablas de desarrollo, etapa de pruebas y producción por Google Cloud proyecto.

Luego, puedes programar ejecuciones en entornos de producción y de pruebas con configuraciones de flujo de trabajo. Te recomendamos que actives las ejecuciones de forma manual en el entorno de desarrollo.

Si deseas obtener más información sobre las prácticas recomendadas para administrar el ciclo de vida del flujo de trabajo en Dataform, consulta Prácticas recomendadas para el ciclo de vida del flujo de trabajo.

Ciclo de vida del código en varios repositorios

Para adaptar los permisos de Identity and Access Management a cada etapa del ciclo de vida del código, puedes crear varias copias de un repositorio y almacenarlas en diferentes proyectos de Google Cloud .

Cada proyecto Google Cloud sirve como un entorno de ejecución que corresponde a una etapa del ciclo de vida del código, por ejemplo, desarrollo y producción.

En este enfoque, recomendamos mantener la misma base de código del repositorio en todos los proyectos. Para personalizar la compilación y la ejecución en cada copia del repositorio, usa las anulaciones de compilación del espacio de trabajo, los parámetros de configuración de lanzamiento y los parámetros de configuración del flujo de trabajo.

Descripción general del tamaño del repositorio

En esta sección, se explica cómo el tamaño del repositorio afecta el desarrollo del flujo de trabajo y el uso de recursos de compilación de Dataform, y cómo estimar el uso de recursos de compilación de tu repositorio.

Acerca del tamaño del repositorio en Dataform

El tamaño de un repositorio afecta los siguientes aspectos del desarrollo en Dataform:

  • Colaboración. Varios colaboradores que trabajan en un repositorio grande pueden crear una cantidad excesiva de solicitudes de extracción, lo que aumenta el riesgo de conflictos de combinación.

  • Legibilidad de la base de código. Una mayor cantidad de archivos que componen un flujo de trabajo en un solo repositorio puede dificultar la navegación por el repositorio.

  • Procesos de desarrollo: Algunas áreas de un flujo de trabajo grande en un solo repositorio pueden requerir permisos o procesos personalizados, como la programación, que son diferentes de los permisos y procesos aplicados al resto del flujo de trabajo. Un repositorio grande dificulta la adaptación de los procesos de desarrollo a áreas específicas del flujo de trabajo.

  • Compilación del flujo de trabajo. Dataform aplica límites de uso en los recursos de compilación. Un tamaño de repositorio grande puede hacer que se superen estos límites, lo que provoca que falle la compilación.

  • Ejecución del flujo de trabajo. Durante la ejecución, Dataform ejecuta el código del repositorio dentro de tu espacio de trabajo y, luego, implementa los recursos en BigQuery. Cuanto más grande sea el repositorio, más tiempo tardará Dataform en ejecutarlo.

Si el gran tamaño de tu repositorio afecta negativamente tu desarrollo en Dataform, puedes dividirlo en varios repositorios más pequeños.

Acerca de los límites de recursos de compilación del repositorio

Durante el desarrollo, Dataform compila todo el código del repositorio dentro de tu espacio de trabajo para generar una representación del flujo de trabajo en tu repositorio. Esto se denomina resultado de compilación. Dataform aplica límites de uso a los recursos de compilación.

Es posible que tu repositorio supere los límites de uso por los siguientes motivos:

  • Un error de bucle infinito en el código del repositorio
  • Un error de pérdida de memoria en el código del repositorio
  • Un repositorio grande, con aproximadamente más de 1,000 acciones de flujo de trabajo

Para obtener más información sobre los límites de uso de los recursos de compilación, consulta Límites de los recursos de compilación de Dataform.

Estima el uso de recursos de compilación de tu repositorio

Puedes estimar el uso de los siguientes recursos de compilación para tu repositorio:

  • Uso del tiempo de CPU.
  • Tamaño máximo total de los datos serializados del gráfico de acciones generado que se define en tu repositorio.

Para obtener una aproximación aproximada del uso actual del tiempo de CPU de compilación para la compilación de tu repositorio, puedes cronometrar la compilación de tu flujo de trabajo de Dataform en una máquina local de Linux o macOS.

  • Para cronometrar la compilación de tu flujo de trabajo, dentro de tu repositorio, ejecuta el comando de la CLI de Dataform dataform compile con el siguiente formato:

    time dataform compile

    En el siguiente muestra de código, se muestra el resultado de ejecutar el comando time dataform compile:

    real    0m3.480s
user    0m1.828s
sys     0m0.260s

Puedes considerar el resultado de real como un indicador aproximado del uso del tiempo de CPU para la compilación de tu repositorio.

Para obtener una aproximación aproximada del tamaño total del gráfico de acciones generado en tu repositorio, puedes escribir el resultado del gráfico en un archivo JSON. Puedes considerar el tamaño del archivo JSON sin comprimir como un indicador aproximado del tamaño total del gráfico.

  • Para escribir el resultado del gráfico compilado de tu flujo de trabajo en un archivo JSON, ejecuta el siguiente comando de la CLI de Dataform dentro de tu repositorio:

    dataform compile --json > graph.json

Cómo dividir repositorios

En esta sección, se analizan las estrategias para dividir un repositorio de Dataform y administrar las dependencias entre repositorios.

Los repositorios son las unidades centrales de Dataform. Un repositorio almacena todos los archivos SQLX y JavaScript que conforman tu flujo de trabajo, así como los archivos de configuración y los paquetes de Dataform. Puedes almacenar un flujo de trabajo en un solo repositorio o dividirlo entre varios.

Dividir un repositorio en Dataform tiene las siguientes ventajas:

  • Cumplir con los límites de Dataform sobre el uso de recursos de compilación Dividir un flujo de trabajo grande en varios repositorios más pequeños reduce el riesgo de exceder los límites de Dataform en los recursos de compilación.
  • Procesos de ajuste detallado Puedes establecer procesos, como reglas de integración continua (CI), de forma individual para cada fragmento dividido de tu flujo de trabajo y el equipo que lo desarrolla.
  • Se detallaron los permisos. Puedes establecer permisos de forma individual para cada fragmento dividido de tu flujo de trabajo y el equipo que lo desarrolla para mejorar la seguridad general del flujo de trabajo.
  • Mejora la colaboración minimizando la cantidad de colaboradores que trabajan en cada fragmento dividido de tu flujo de trabajo.
  • Mejorar la legibilidad de la base de código Dividir los archivos que componen un flujo de trabajo grande en varios repositorios facilita la navegación por cada repositorio de forma individual en lugar de navegar por todo el flujo de trabajo a la vez.
  • Acelerar la ejecución del flujo de trabajo de cada fragmento dividido de tu flujo de trabajo en comparación con la ejecución del flujo de trabajo completo

Dividir un repositorio en Dataform tiene las siguientes desventajas:

  • Se requiere una configuración personalizada de integración continua y desarrollo continuo (CI/CD) para cada repositorio de Dataform y su repositorio de Git correspondiente.
  • Se requiere una configuración de programación personalizada para cada repositorio de Dataform y su repositorio de Git correspondiente.
  • Dificultad para administrar las dependencias entre los objetos de tu flujo de trabajo alojados en varios repositorios
  • Falta de visualización integral del grafo acíclico dirigido (DAG) del flujo de trabajo de SQL dividido entre varios repositorios. En cada repositorio, el DAG generado representa solo una parte del flujo de trabajo completo.

Estrategias para dividir un repositorio

Cuando divides un repositorio, separas los archivos que componen un flujo de trabajo de SQL principal en flujos de trabajo secundarios más pequeños alojados en repositorios de Dataform separados.

Puedes dividir un repositorio de una de las siguientes maneras:

  • Un repositorio por equipo de desarrollo
  • Un repositorio por dominio (por ejemplo, ventas, marketing o logística)
  • Un repositorio central y un repositorio por dominio que usa el contenido del repositorio central como fuentes de datos.

Para alojar el flujo de trabajo principal en una plataforma de alojamiento de Git de terceros, debes conectar individualmente cada uno de los repositorios separados que contienen flujos de trabajo secundarios a un repositorio de Git de terceros dedicado.

Administra dependencias entre repositorios

La forma más eficiente de dividir un repositorio es dividir el flujo de trabajo principal de SQL en flujos de trabajo secundarios independientes, lo que crea repositorios independientes. Un repositorio independiente no usa el contenido de otro repositorio como fuente de datos. Este enfoque no requiere la administración de dependencias entre repositorios.

Cuando no puedes evitar las dependencias entre repositorios, puedes administrarlas dividiendo un repositorio en una sucesión de repositorios, en la que un repositorio depende de su predecesor y es una fuente de datos para su sucesor. La sucesión de repositorios y sus dependencias debe reflejar mejor la estructura de tu flujo de trabajo principal.

Puedes crear dependencias entre repositorios con declaraciones de fuentes de datos de Dataform. Puedes declarar un tipo de tabla de BigQuery de un repositorio de Dataform diferente como fuente de datos en el repositorio que se está editando. Después de declarar una fuente de datos, puedes hacer referencia a ella como a cualquier otra acción de flujo de trabajo de Dataform y usarla para desarrollar tu flujo de trabajo.

Cuando programes la ejecución de un flujo de trabajo dividido entre repositorios con dependencias entre repositorios, debes ejecutar los repositorios uno por uno en el orden de las dependencias entre repositorios.

Te recomendamos que evites dividir un repositorio en un grupo de repositorios con dependencias bidireccionales. Se produce una dependencia bidireccional entre repositorios cuando un repositorio es una fuente de datos para otro repositorio y también usa ese repositorio como fuente de datos. Las dependencias bidireccionales entre repositorios complican la programación y la ejecución del flujo de trabajo principal, así como los procesos de desarrollo.

Cómo estructurar el código en un repositorio

En esta sección, se describen las prácticas recomendadas para estructurar y nombrar archivos de flujo de trabajo 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. Puedes adoptar cualquier estructura que se adapte a las necesidades de tu empresa.

Te recomendamos que estructures el código del flujo de trabajo en el directorio definitions por los siguientes motivos:

  • Mejora la colaboración en la base de código designando equipos para partes seleccionadas de tu flujo de trabajo.
  • Mejora el mantenimiento del flujo de trabajo en caso de cambios organizacionales.
  • Mejora 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 en un repositorio de Dataform contiene código que crea elementos de tu flujo de trabajo. 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, declaras 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:

  1. Declaración de fuentes de datos
  2. Transformación de los datos de origen
  3. Es la 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:

sources
Declaraciones de fuentes de datos y transformación básica de datos de origen (por ejemplo, filtrado)
intermediate
Tablas y acciones que leen datos de sources y los transforman antes de que uses los datos transformados 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 las tablas que consumen los procesos o las herramientas, como IE, después de que Dataform las ejecuta en BigQuery.
extra
Archivos fuera de la canalización principal de tu flujo de trabajo, por ejemplo, archivos que contienen datos del flujo de trabajo preparados para un uso adicional, como el aprendizaje automático. Es un subdirectorio personalizado y opcional.

Prácticas recomendadas para sources

El subdirectorio sources contiene la primera etapa de tu flujo de trabajo: la declaración y la transformación básica de los datos de origen.

En el subdirectorio sources, almacena declaraciones de fuentes de datos y tablas que filtran, categorizan, convierten 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), dedica un subdirectorio a cada grupo.

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.

Para obtener más información sobre cómo crear declaraciones de fuentes de datos con JavaScript, consulta Crea flujos de trabajo exclusivamente con JavaScript.

En el 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 contra los cambios en las fuentes de datos, puedes crear una vista para cada declaración de fuente de datos, por ejemplo, analytics_users_filtered.sqlx. La vista puede contener el filtrado y el formato 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 a las tablas de origen sin procesar. Este enfoque te permite probar las tablas de origen. En caso de que cambie una tabla fuente, puedes modificar su vista, por ejemplo, agregando filtros o recasteando datos.

Prácticas recomendadas para intermediate

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

En el subdirectorio intermediate, almacena los archivos que transforman de manera significativa los datos de origen de una o varias fuentes en el subdirectorio sources, por ejemplo, las 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 de 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 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 outputs contiene la etapa final de tu flujo de trabajo: 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 las tablas intermediate.

Agrupa las tablas de 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 Cómo anular la configuración 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 de outputs.

Estrategia de nombres

Los nombres de todos los archivos de Dataform deben cumplir con los lineamientos para la asignación de nombres a las 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, 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 los archivos 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 o ads_revenue.sqlx.

En el siguiente ejemplo, se muestra una estructura de subdirectorios dentro del directorio definitions con nombres de archivos que se ajustan a la estrategia de nomenclatura 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?