Reutiliza variables y funciones con inclusiones en Dataform

En este documento, se muestra cómo crear JavaScript para reutilizar código en Dataform.

En la carpeta includes/ de tu repositorio, puedes definir las inclusiones de JavaScript. Las inclusiones son constantes o funciones globales que puedes volver a usar en todo tu repositorio.

Antes de comenzar

  1. En Google Cloud Console, ve a la página Dataform.

    Ir a Dataform

  2. Selecciona o crea un repositorio de Dataform.

  3. Selecciona o crea un lugar de trabajo de desarrollo de Dataform.

Roles obligatorios

Si quieres obtener los permisos que necesitas para volver a usar el código con JavaScript, pídele al administrador que te otorgue el rol de IAM Editor de formularios de datos (roles/dataform.editor) en los lugares de trabajo. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Cómo crear un archivo JavaScript para el objeto include en Dataform

Para crear un nuevo archivo JavaScript en el directorio includes/, sigue estos pasos:

  1. En el panel Archivos, junto a includes/, haz clic en el menú Más.

  2. Haga clic en Crear archivo.

  3. En el panel Crear archivo nuevo, haz lo siguiente:

    1. En el campo Add a file path, después de includes/, ingresa el nombre del archivo, seguido de .js. Por ejemplo, includes/constants.js.

      Los nombres de archivo solo pueden incluir números, letras, guiones y guiones bajos.

    2. Haga clic en Crear archivo.

Cómo crear una constante de JavaScript

Para crear una constante que puedas volver a usar en tu proyecto, sigue estos pasos:

  1. Ve al lugar de trabajo de desarrollo.

  2. En el panel Archivos, expande includes/.

  3. Crea o selecciona un archivo JavaScript con la extensión .js.

  4. En el archivo, ingresa el siguiente fragmento de código:

     const CONSTANT_NAME = CONSTANT_VALUE;
 module.exports = { CONSTANT_NAME };

    1. Reemplaza CONSTANT_NAME por el nombre de la constante.

    2. Reemplaza CONSTANT_VALUE por el valor de la constante.

En la siguiente muestra de código, se define la constante PROJECT_ID en el archivo includes/constants.js:

  // filename is includes/constants.js
  const PROJECT_ID = "my_project_name";
  module.exports = { PROJECT_ID };

En la siguiente muestra de código, se hace referencia a la constante PROJECT_ID en una consulta de definición de tablas en un archivo SQLX:

  config { type: "table" }
  SELECT * FROM ${constants.PROJECT_ID}.my_schema_name.my_table_name

La siguiente muestra de código muestra la consulta de definición de la tabla Dataform core anterior compilada en SQL:

  SELECT * FROM my_project_name.my_schema_name.my_table_name

Crea una función de JavaScript personalizada

Para crear una función de JavaScript personalizada que puedas volver a usar en tu proyecto, sigue estos pasos:

  1. Ve al lugar de trabajo de desarrollo.

  2. En el panel Archivos, expande includes/.

  3. Crea o selecciona un archivo JavaScript con la extensión .js.

  4. En el archivo, escribe tu función de JavaScript personalizada.

  5. En el archivo, ingresa el siguiente fragmento de código:

     module.exports = { FUNCTION_NAME }

    Reemplaza FUNCTION_NAME por el nombre de tu función.

En la siguiente muestra de código, se muestra una función de JavaScript personalizada, llamada renderScript, en el archivo includes/functions.js, que genera una secuencia de comandos de SQL:

  function renderScript(table, dimensions, metrics) {
    return `
        select
        ${dimensions.map(field => `${field} as ${field}`).join(",")},
        ${metrics.map(field => `sum(${field}) as ${field}`).join(",\n")}
        from ${table}
        group by ${dimensions.map((field, i) => `${i + 1}`).join(", ")}
      `;
  }

  module.exports = { renderScript };

En la siguiente muestra de código, se muestra el uso de la función renderScript personalizada de JavaScript en una consulta de definición de una tabla principal de Dataform:

  config {
      type: "table",
      tags: ["advanced", "hourly"],
      disabled: true
  }

  ${functions.renderScript(ref("source_table"),
                                ["country", "device_type"],
                                ["revenue", "pageviews", "sessions"]
                                )}

En la siguiente muestra de código, se muestra la consulta de definición de la tabla principal de Dataform compilada en SQL:

  select
    country as country,
    device_type as device_type,
    sum(revenue) as revenue,
    sum(pageviews) as pageviews,
    sum(sessions) as sessions

  from "dataform"."source_table"

  group by 1, 2

Haz una referencia a una inclusión en un archivo SQLX

Puedes hacer referencia a cualquier constante o función de inclusión dentro de un archivo SQLX. La sintaxis para las referencias incluye depende de la ubicación del archivo de inclusión. Los archivos de nivel superior incluyen un archivo ubicado directamente en el directorio includes/. Un archivo de inclusión anidado se encuentra en un subdirectorio de includes/.

Haz referencia a una inclusión de nivel superior en un archivo SQLX

  • Para hacer referencia a una constante o función de inclusión de nivel superior en una consulta principal de Dataform, ingresa el nombre del archivo de inclusión de definición sin la extensión .js seguida del nombre del objeto exportado.

En la siguiente muestra de código, se hace referencia a la constante firstDate, que se define en el archivo includes/constants.js, en un archivo SQLX de definición de tablas:

  config {type: "table"}
  select * from source_table where date > ${constants.firstDate}

Haz referencia a una inclusión anidada en un archivo SQLX

Para hacer referencia a las inclusiones ubicadas en los subdirectorios de definitions, impórtalas mediante la función require de JavaScript y un bloque js {}.

Para hacer referencia a una inclusión anidada con la función require de JavaScript, sigue estos pasos:

  1. Ve al lugar de trabajo de desarrollo.

  2. En el panel Archivos, expande definitions/.

  3. Selecciona un archivo SQLX.

  4. En el bloque config, ingresa el siguiente fragmento de código:

     js {
   var { VARIABLE_NAME } = require("SUBDIRECTORY_INCLUDE");
 }

    1. Reemplaza VARIABLE_NAME por el nombre de la constante o función que quieres importar.

    2. Reemplaza SUBDIRECTORY_INCLUDE por la ruta del archivo de inclusiones anidadas.

En la siguiente muestra de código, se hace referencia a la constante firstDate, que se define en el archivo includes/allConstants/constants.js anidado, en un archivo SQLX de definición de tablas:

  config {type: "table"}
  js {
    var { firstDate } = require("includes/allConstants/constants");
  }
  select * from source_table where date > ${firstDate}

Usa una función de inclusión de JavaScript con la función ref principal de Dataform

Para usar una función de inclusión de JavaScript con la función ref principal de Dataform, debes pasar ref como argumento de la función de inclusión de JavaScript dentro de un archivo SQLX.

En la siguiente muestra de código, se muestra el archivo includes/script_builder.js con la función renderScript de JavaScript que agrega métricas mediante SUM y grupos y, luego, por dimensión:

function renderScript(table, dimensions, metrics) {
  return `
      SELECT
      ${dimensions.map((field) => `${field} AS ${field}`).join(",\\n")},
      ${metrics.map((field) => `SUM(${field}) AS ${field}`).join(",\\n")}
      FROM ${table}
      GROUP BY ${dimensions.map((field, i) => `${i + 1}`).join(", ")}
    `;
}
module.exports = { renderScript };

En la siguiente muestra de código, se muestra la función de JavaScript renderScript que se usa en el archivo definitions/stats_per_country_and_device.sqlx con la función ref de Dataform core que se pasa como argumento:

${script_builder.renderScript(
  ref("source_table"),
  ["country", "device_type"],
  ["revenue", "pageviews", "sessions"])}

En la siguiente muestra de código, se muestra la consulta definitions/stats_per_country_and_device.sqlx compilada en SQL:

SELECT country AS country,
       device_type AS device_type,
       SUM(revenue) AS revenue,
       SUM(pageviews) AS pageviews,
       SUM(sessions) AS sessions
FROM my_schema.source_table
GROUP BY 1, 2

Para obtener más información sobre la función ref de Dataform core, consulta la Descripción general de Dataform core.

¿Qué sigue?