Neste documento, mostramos como criar inclusões do JavaScript para reutilizar o código no Dataform.
Na pasta includes/
do repositório, é possível definir as inclusões do
JavaScript. As inclusões são constantes ou funções globais que você pode reutilizar em
todo o repositório.
Antes de começar
No console do Google Cloud, acesse a página Dataform.
Selecione ou crie um repositório do Dataform.
Selecione ou crie um espaço de trabalho de desenvolvimento do Dataform.
Funções exigidas
Para ter as permissões necessárias para reutilizar o código com inclusões do JavaScript,
peça ao administrador para conceder a você o
papel do IAM de Editor do Dataform (roles/dataform.editor
) nos espaços de trabalho.
Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
Talvez você também consiga receber as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.
Criar um arquivo JavaScript para inclusões no Dataform
Para criar um novo arquivo JavaScript no diretório includes/
, siga estas
etapas:
No painel Files, ao lado de
includes/
, clique no menu More.Clique em Criar arquivo.
No painel Criar novo arquivo, faça o seguinte:
No campo Adicionar um caminho de arquivo, depois de
includes/
, insira o nome do arquivo seguido de.js
. Por exemplo,includes/constants.js
.Os nomes de arquivos só podem incluir números, letras, hifens e sublinhados.
Clique em Criar arquivo.
Criar uma constante JavaScript
Para criar uma constante que possa ser reutilizada no projeto, siga estas etapas:
Acesse seu espaço de trabalho de desenvolvimento.
No painel Files, expanda
includes/
.Crie ou selecione um arquivo JavaScript com a extensão
.js
.No arquivo, digite o seguinte snippet de código:
const CONSTANT_NAME = CONSTANT_VALUE; module.exports = { CONSTANT_NAME };
Substitua:
- CONSTANT_NAME: o nome da constante
- CONSTANT_VALUE: o valor da constante
Opcional: clique em Formatar.
O exemplo de código abaixo define a constante PROJECT_ID
no
arquivo includes/constants.js
:
// filename is includes/constants.js
const PROJECT_ID = "my_project_name";
module.exports = { PROJECT_ID };
O exemplo de código a seguir faz referência à constante PROJECT_ID
em uma consulta de definição de tabela em um arquivo SQLX:
config { type: "table" }
SELECT * FROM ${constants.PROJECT_ID}.my_schema_name.my_table_name
O exemplo de código a seguir mostra a consulta de definição de tabela do núcleo do Dataform acima compilada no SQL:
SELECT * FROM my_project_name.my_schema_name.my_table_name
Criar uma função JavaScript personalizada
Para criar uma função JavaScript personalizada que você pode reutilizar no seu projeto, siga estas etapas:
Acesse seu espaço de trabalho de desenvolvimento.
No painel Files, expanda
includes/
.Crie ou selecione um arquivo JavaScript com a extensão
.js
.No arquivo, escreva a função JavaScript personalizada.
No arquivo, digite o seguinte snippet de código:
module.exports = { FUNCTION_NAME }
Substitua
FUNCTION_NAME
pelo nome da sua função.Opcional: clique em Formatar.
O exemplo de código a seguir mostra uma função JavaScript personalizada, chamada
renderScript
, no arquivo includes/functions.js
, que gera um script
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 };
O exemplo de código a seguir mostra o uso da função JavaScript renderScript
personalizada em uma consulta de definição de tabela principal do Dataform:
config {
type: "table",
tags: ["advanced", "hourly"],
disabled: true
}
${functions.renderScript(ref("source_table"),
["country", "device_type"],
["revenue", "pageviews", "sessions"]
)}
O exemplo de código a seguir mostra a consulta de definição de tabela principal do Dataform acima compilada no 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
Referenciar uma inclusão em um arquivo SQLX
Você pode referenciar qualquer função de inclusão ou constante dentro de um arquivo SQLX. A
sintaxe para referências inclui depende do local do arquivo de inclusão.
Um arquivo de inclusão de nível superior está localizado diretamente no diretório includes/
.
Um arquivo de inclusão aninhado está localizado em um subdiretório de includes/
.
Referenciar uma inclusão de nível superior em um arquivo SQLX
- Para fazer referência a uma função ou constante de inclusão de nível superior em uma
consulta principal do Dataform, insira o nome do arquivo de definição de inclusão sem
a extensão
.js
seguida pelo nome do objeto exportado.
O exemplo de código a seguir faz referência à constante firstDate
, definida no arquivo includes/constants.js
, em um arquivo SQLX de definição de tabela:
config {type: "table"}
select * from source_table where date > ${constants.firstDate}
Referenciar uma inclusão aninhada em um arquivo SQLX
Para fazer referência a inclusões localizadas nos subdiretórios de definitions
, a importação
de inclusão usa a função require
do JavaScript e um bloco js {}
.
Para referenciar uma inclusão aninhada com a função JavaScript require
,
siga estas etapas:
Acesse seu espaço de trabalho de desenvolvimento.
No painel Files, expanda
definitions/
.Selecione um arquivo SQLX.
No bloco
config
, insira este snippet de código:js { var { VARIABLE_NAME } = require("SUBDIRECTORY_INCLUDE"); }
Substitua:
- VARIABLE_NAME: o nome da constante ou da função que você quer importar
- SUBDIRECTORY_INCLUDE: o caminho
do arquivo
includes
aninhado.
Opcional: clique em Formatar.
O exemplo de código a seguir faz referência à constante firstDate
, definida no arquivo includes/allConstants/constants.js
aninhado, em um arquivo SQLX de definição de tabela:
config {type: "table"}
js {
var { firstDate } = require("includes/allConstants/constants");
}
select * from source_table where date > ${firstDate}
Usar uma função de inclusão do JavaScript com a função ref
principal do Dataform
Para usar uma função de inclusão do JavaScript com a função ref
principal do
Dataform, transmita ref
como um argumento da função de inclusão
do JavaScript dentro de um arquivo SQLX.
O exemplo de código a seguir mostra o arquivo includes/script_builder.js
com a função JavaScript renderScript
que agrega métricas usando SUM
e agrupa em seguida por dimensão:
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 };
O exemplo de código a seguir mostra a função JavaScript renderScript
usada no
arquivo definitions/stats_per_country_and_device.sqlx
com a
função ref
principal do Dataform transmitida como um argumento:
${script_builder.renderScript(
ref("source_table"),
["country", "device_type"],
["revenue", "pageviews", "sessions"])}
O exemplo de código a seguir mostra a
consulta definitions/stats_per_country_and_device.sqlx
compilada para 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 mais informações sobre a função ref
principal do Dataform, consulte
Visão geral do Dataform Core.
A seguir
Para saber como referenciar inclusões em arquivos JavaScript, consulte Criar fluxos de trabalho SQL com JavaScript.
Para saber mais sobre a reutilização de códigos com JavaScript em bloco e inline nos arquivos principais do Dataform, consulte Visão geral do núcleo do Dataform.