Prácticas recomendadas para los repositorios

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

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

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

Prácticas recomendadas para el tamaño de los repositorios

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

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

Dataform aplica cuotas y límites de API a los recursos de compilación. Si el tamaño de un repositorio es grande, puede superar estas cuotas y límites. Esto puede provocar que no se compilen ni se ejecuten los flujos de trabajo.

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

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

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

Prácticas recomendadas para la estructura de los repositorios

Te recomendamos que estructures los archivos del directorio definitions para que reflejen las fases 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 definitionssubdirectorios refleja las fases 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 de Dataform deben cumplir las directrices de nomenclatura de tablas de BigQuery. Te recomendamos que los nombres de los archivos del directorio definitions de un repositorio de Dataform reflejen la estructura de las subcarpetas.

Para obtener más información sobre las prácticas recomendadas para estructurar y nombrar archivos en un repositorio, consulta 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 gestionar el ciclo de vida del código en Dataform, puedes crear entornos de ejecución, como desarrollo, preproducción y producción.

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

Puedes 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 los de desarrollo, preproducción y producción, en un único repositorio de Dataform con sustituciones de compilación de espacio de trabajo y configuraciones de lanzamiento.

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

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

Después, puedes programar ejecuciones en entornos de staging y producción con configuraciones de flujo de trabajo. Te recomendamos que actives las ejecuciones manualmente en el entorno de desarrollo.

Para obtener más información sobre las prácticas recomendadas para gestionar el ciclo de vida de los flujos de trabajo en Dataform, consulta Prácticas recomendadas para el ciclo de vida de los flujos de trabajo.

Ciclo de vida del código en varios repositorios

Para adaptar los permisos de gestión de identidades y accesos a cada fase del ciclo de vida del código, puedes crear varias copias de un repositorio y almacenarlas en diferentes Google Cloud proyectos.

Cada Google Cloud proyecto sirve como entorno de ejecución que se corresponde con una fase del ciclo de vida del código, como el desarrollo y la producción.

En este enfoque, recomendamos que la base de código del repositorio sea la misma en todos los proyectos. Para personalizar la compilación y la ejecución en cada copia del repositorio, usa sustituciones de compilación del espacio de trabajo, configuraciones de lanzamiento y configuraciones de flujo de trabajo.

Información general sobre el tamaño del repositorio

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

Acerca del tamaño de los repositorios en Dataform

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

  • Colaboración. Varios colaboradores que trabajan en un repositorio grande pueden crear un número excesivo de solicitudes de extracción, lo que aumenta el riesgo de que se produzcan conflictos de combinación.

  • Legibilidad de la base de código. Si un flujo de trabajo está formado por un gran número de archivos en un solo repositorio, puede resultar difícil desplazarse por el repositorio.

  • Procesos de desarrollo. Es posible que algunas áreas de un flujo de trabajo grande en un solo repositorio requieran permisos o procesos personalizados, como la programación, que sean diferentes de los permisos y procesos aplicados al resto del flujo de trabajo. Si el tamaño del repositorio es grande, resulta difícil adaptar los procesos de desarrollo a áreas específicas del flujo de trabajo.

  • Compilación de flujos de trabajo. Dataform aplica límites de uso a los recursos de compilación. Si el tamaño del repositorio es grande, se pueden superar estos límites, lo que provoca que la compilación falle.

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

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

Acerca de los límites de recursos de compilación de repositorios

Durante el desarrollo, Dataform compila todo el código del repositorio en 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.

Tu repositorio puede superar los límites de uso por los siguientes motivos:

  • Un error de bucle infinito en el código del repositorio.
  • Un error de fuga de memoria en el código del repositorio.
  • Un repositorio de gran tamaño, aproximadamente más de 1000 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.

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

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

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

Para obtener una aproximación del uso actual del tiempo de CPU de compilación para la compilación de tu repositorio, puedes medir el tiempo de compilación de tu flujo de trabajo de Dataform en un equipo Linux o macOS local.

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

    time dataform compile

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

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

Puedes tratar el resultado de real como un indicador aproximado del uso del tiempo de CPU para compilar tu repositorio.

Para obtener una aproximación del tamaño total del gráfico de acciones generado en tu repositorio, puedes escribir la salida 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 la salida del gráfico compilado de tu flujo de trabajo en un archivo JSON, ejecuta el siguiente comando de la CLI de Dataform en tu repositorio:

    dataform compile --json > graph.json

Dividir repositorios

En esta sección se describen estrategias para dividir un repositorio de Dataform y gestionar las dependencias entre repositorios.

Los repositorios son las unidades principales de Dataform. Un repositorio almacena todos los archivos SQLX y JavaScript que componen 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 los límites de Dataform en el uso de recursos de compilación. Si divides un flujo de trabajo grande en varios repositorios más pequeños, se reduce el riesgo de superar los límites de Dataform en cuanto a recursos de compilación.
  • Procesos de granularidad fina. Puedes definir procesos, como reglas de integración continua (CI), de forma individual para cada fragmento dividido de tu flujo de trabajo y para el equipo que lo desarrolla.
  • Permisos pormenorizados. Puedes definir permisos individualmente para cada fragmento de tu flujo de trabajo y para el equipo que lo desarrolla para mejorar la seguridad general del flujo de trabajo.
  • Mejorar la colaboración minimizando el número de colaboradores que trabajan en cada fragmento 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 en comparación con la ejecución del flujo de trabajo completo.

Dividir un repositorio en Dataform tiene los siguientes inconvenientes:

  • Se requiere una configuración de integración continua y desarrollo continuo (CI/CD) personalizada 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 gestionar las dependencias entre los objetos de tu flujo de trabajo alojados en varios repositorios.
  • No se puede visualizar de forma completa el gráfico 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 independientes.

Puedes dividir un repositorio de una de las siguientes formas:

  • 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 fuente 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 independientes que contengan flujos de trabajo secundarios a un repositorio de Git de terceros específico.

Gestionar dependencias entre repositorios

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

Cuando no puedas evitar las dependencias entre repositorios, puedes gestionarlas 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 lo mejor posible 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 otro repositorio de Dataform 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 a uno en el orden de las dependencias entre repositorios.

Te recomendamos que no dividas 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.

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

Puede que quieras estructurar el código del flujo de trabajo en el directorio definitions por los siguientes motivos:

  • Mejorar la colaboración en la base de código asignando equipos a determinadas partes de tu flujo de trabajo.
  • Mejorar el mantenimiento del flujo de trabajo en caso de cambios en la organización.
  • Mejorar la navegación por tu base de código.
  • Mejorar la escalabilidad del código base.
  • Minimizar la sobrecarga administrativa de tu equipo.

El directorio raíz definitions de un repositorio de Dataform contiene el código que crea los elementos de tu flujo de trabajo. Puedes organizar los archivos de la carpeta 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 empresariales o analíticos.

Puedes distinguir tres fases clave de un flujo de trabajo:

  1. Declaración de las fuentes de datos.
  2. Transformación de los datos de origen.
  3. Definición de las tablas de salida a partir de los datos de origen transformados.

La siguiente estructura de subdirectorios del directorio definitions refleja las fases clave de un flujo de trabajo:

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 datos de sources y los transforman antes de que uses los datos transformados para definir tablas de outputs. Las tablas no suelen exponerse a procesos ni herramientas adicionales, como las herramientas de inteligencia empresarial (BI), después de que Dataform las ejecute en BigQuery.
outputs
Definiciones de las tablas que consumen los procesos o las herramientas, como la inteligencia empresarial, después de que Dataform las ejecute en BigQuery.
extra
Archivos que no forman parte de la canalización principal de tu flujo de trabajo. Por ejemplo, archivos que contienen datos de flujo de trabajo preparados para un uso adicional, como el aprendizaje automático. Un subdirectorio opcional y personalizado.

Prácticas recomendadas para sources

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

En el subdirectorio sources, almacena las declaraciones de fuentes de datos y las 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 tablas almacenadas en la subcarpeta intermediate.

Si declara fuentes de datos de varios grupos (por ejemplo, Google Ads o Google Analytics), asigne 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 declara varias tablas de fuentes de datos en el mismo esquema, puede consolidar sus declaraciones en un único archivo JavaScript.

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

En el siguiente ejemplo de código se muestran 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 frente a 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.

Después, cuando crees tablas intermediate o outputs, haz referencia a las vistas en lugar de a las tablas de origen sin procesar. Este método le permite probar las tablas de origen. Si cambia una tabla de origen, puede modificar su vista, por ejemplo, añadiendo filtros o cambiando el formato de los datos.

Prácticas recomendadas para intermediate

El subdirectorio intermediate contiene la segunda fase del 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 significativamente los datos de origen de una o varias fuentes del subdirectorio sources. Por ejemplo, las tablas que combinan datos. Las tablas del subdirectorio intermediate suelen consultar datos de tablas de origen u otras tablas intermediate.

Usa las tablas intermediate para crear tablas outputs. Normalmente, las intermediate tablas no se usan para otros fines, como las analíticas de datos, después de que Dataform las ejecute en BigQuery. Las tablas intermediatese pueden considerar como la lógica de transformación de datos que permite crear tablas de resultados.

Te recomendamos que documentes y pruebes todas las tablas intermediate.

Prácticas recomendadas para outputs

El subdirectorio outputs contiene la fase final del flujo de trabajo: la creación de tablas de resultados para sus fines empresariales a partir de los datos transformados.

En el directorio outputs, almacena las tablas que quieras usar en procesos o herramientas adicionales después de que Dataform las ejecute en BigQuery (por ejemplo, informes o paneles). Las tablas del directorio outputs suelen consultar datos de las tablas intermediate.

Agrupa las tablas outputs por la entidad de empresa a la que estén relacionadas (por ejemplo, marketing, pedidos o analíticas). Dedica un subdirectorio a cada entidad empresarial.

Para almacenar las tablas de salida por separado en BigQuery, puede configurar un esquema específico para las tablas de salida. Para obtener instrucciones sobre cómo configurar el esquema de la tabla, consulta Anular la configuración de la tabla.

En el siguiente ejemplo se muestra una estructura de subdirectorios de outputs con las entidades de empresa 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 nomenclatura

Los nombres de todos los archivos de Dataform deben cumplir las directrices de nomenclatura de tablas de BigQuery.

Te recomendamos que los nombres de los archivos del 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 con la que está relacionado el archivo. Añade el nombre de la fuente como prefijo a los nombres de los archivos. Por ejemplo, analytics_filtered.sqlx

En la subcarpeta intermediate, los nombres de los archivos deben identificar la subcarpeta 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 outputs tablas con el mismo nombre en subdirectorios de entidades diferentes, añade 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 archivo 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

Siguientes pasos