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
En la consola de Google Cloud, ve a la página Dataform.
Selecciona o crea un repositorio de Dataform.
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:
En el panel Files, junto a
includes/
, haz clic en el menú More.Haz clic en Crear archivo.
En el panel Create new file, haz lo siguiente:
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.
Haz clic en Crear archivo.
Crea una constante de JavaScript
Para crear una constante que puedas reutilizar en todo tu proyecto, sigue estos pasos:
Ve a tu lugar de trabajo de desarrollo.
En el panel Files, expande
includes/
.Crea o selecciona un archivo JavaScript con la extensión
.js
.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
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:
Ve a tu lugar de trabajo de desarrollo.
En el panel Files, expande
includes/
.Crea o selecciona un archivo JavaScript con la extensión
.js
.En el archivo, escribe tu función de JavaScript personalizada.
En el archivo, ingresa el siguiente fragmento de código:
module.exports = { FUNCTION_NAME }
Reemplaza
FUNCTION_NAME
por el nombre de tu función.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:
Ve a tu lugar de trabajo de desarrollo.
En el panel Files, expande
definitions/
.Selecciona un archivo SQLX.
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.
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?
Para obtener información sobre cómo hacer referencia a inclusiones en archivos JavaScript, consulta Crea flujos de trabajo de SQL con JavaScript.
Para obtener más información sobre cómo reutilizar código con JavaScript, bloquearlo y usarlo dentro de los archivos principales de Dataform, consulta Descripción general de los archivos principales de Dataform.