Reutiliza variables y funciones con inclusiones en Dataform

En este documento, se muestra cómo crear inclusiones de JavaScript para reutilizar el 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 la consola de Google Cloud, 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.

Funciones obligatorias

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

Es posible que también puedas obtener los permisos necesarios mediante funciones personalizadas, o bien otras funciones predefinidas.

Crea un archivo JavaScript para inclusiones en Dataform

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

  1. En el panel Files, junto a includes/, haz clic en el menú More.

  2. Haz clic en Crear archivo.

  3. En el panel Create new file, haz lo siguiente:

    1. En el campo Agregar una ruta de acceso al archivo, 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. Haz clic en Crear archivo.

Crea una constante de JavaScript

Para crear una constante que puedas reutilizar en todo tu proyecto, sigue estos pasos:

  1. Ve a tu lugar de trabajo de desarrollo.

  2. En el panel Files, 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 };

    Reemplaza lo siguiente:

    • CONSTANT_NAME: Es el nombre de tu constante.
    • CONSTANT_VALUE: El valor de tu constante

  5. Opcional: Haz clic en Formato.

La siguiente muestra de código 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

En la siguiente muestra de código, se ve la consulta de definición de tablas Dataform core compilada anteriormente 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 todo tu proyecto, sigue estos pasos:

  1. Ve a tu lugar de trabajo de desarrollo.

  2. En el panel Files, 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.

  6. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se observa una función personalizada de JavaScript, llamada renderScript, en el archivo includes/functions.js, que genera una secuencia de comandos 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 indica el uso de la función renderScript de JavaScript personalizada en una consulta de definición de tablas principales 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 ve la consulta de definición de tablas principal de Dataform compilada en SQL que se incluye más arriba:

  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

Cómo hacer referencia a una inclusión en un archivo SQLX

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

Cómo hacer referencia a una inclusión de nivel superior en un archivo SQLX

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

La siguiente muestra de código hace referencia a la constante firstDate, definida 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}

Cómo hacer referencia a una inclusión anidada en un archivo SQLX

Para hacer referencia a inclusiones ubicadas en subdirectorios de definitions, debes importarlas con 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 a tu lugar de trabajo de desarrollo.

  2. En el panel Files, 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");
 }

    Reemplaza lo siguiente:

    • VARIABLE_NAME: Es el nombre de la constante o la función que deseas importar.
    • SUBDIRECTORY_INCLUDE: Es la ruta de acceso del archivo includes anidado.

  5. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se hace referencia a la constante firstDate, definida 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 ve el archivo includes/script_builder.js con la función renderScript de JavaScript que agrega métricas mediante SUM y los agrupa 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 indica la función renderScript de JavaScript que se usa en el archivo definitions/stats_per_country_and_device.sqlx con la función ref principal de Dataform pasada como un argumento:

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

En la siguiente muestra de código, se ve 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 principal de Dataform, consulta la Descripción general de la función principal de Dataform.

¿Qué sigue?