Reutilizar variáveis e funções com inclusões no Dataform

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

  1. No console do Google Cloud, acesse a página Dataform.

    Acesse o Dataform

  2. Selecione ou crie um repositório do Dataform.

  3. 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:

  1. No painel Files, ao lado de includes/, clique no menu More.

  2. Clique em Criar arquivo.

  3. No painel Criar novo arquivo, faça o seguinte:

    1. 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.

    2. Clique em Criar arquivo.

Criar uma constante JavaScript

Para criar uma constante que possa ser reutilizada no projeto, siga estas etapas:

  1. Acesse seu espaço de trabalho de desenvolvimento.

  2. No painel Files, expanda includes/.

  3. Crie ou selecione um arquivo JavaScript com a extensão .js.

  4. 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

  5. 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:

  1. Acesse seu espaço de trabalho de desenvolvimento.

  2. No painel Files, expanda includes/.

  3. Crie ou selecione um arquivo JavaScript com a extensão .js.

  4. No arquivo, escreva a função JavaScript personalizada.

  5. No arquivo, digite o seguinte snippet de código:

     module.exports = { FUNCTION_NAME }

    Substitua FUNCTION_NAME pelo nome da sua função.

  6. 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:

  1. Acesse seu espaço de trabalho de desenvolvimento.

  2. No painel Files, expanda definitions/.

  3. Selecione um arquivo SQLX.

  4. 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.

  5. 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