Use JavaScript no Dataform

O Dataform core permite-lhe criar ações de fluxo de trabalho com SQLX e JavaScript. Embora seja opcional, pode usar JavaScript juntamente com SQLX para criar elementos semelhantes repetidamente no seu fluxo de trabalho. Por exemplo, com JavaScript, pode criar uma vista de cada tabela no seu fluxo de trabalho com determinados IDs de utilizadores removidos. Também pode desenvolver ações de fluxo de trabalho exclusivamente com JavaScript.

Antes de começar

1. Na Google Cloud consola, aceda à página Dataform.

   Aceder ao Dataform

2. Selecione ou crie um repositório.

3. Selecione ou crie um espaço de trabalho de desenvolvimento.

Além disso, tem de estar familiarizado com a sintaxe JavaScript e os seguintes conceitos de JavaScript:

• Variáveis
• Matrizes
• Declarações condicionais
• Para repetições
• Maps
• Funções
• Objetos
• Exportação e importação de módulos

Funções necessárias

Para receber as autorizações de que precisa para desenvolver um fluxo de trabalho com JavaScript e reutilizar código com inclusões de JavaScript, peça ao seu administrador para lhe conceder a função do editor do Dataform (roles/dataform.editor) IAM em espaços de trabalho. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Adicione código JavaScript a um ficheiro SQLX

Pode adicionar código JavaScript a um ficheiro SQLX de duas formas: inline ou dentro de um bloco JavaScript.

Pode usar um bloco JavaScript para definir funções ou constantes num ficheiro SQLX. Pode usar JavaScript inline para modificar dinamicamente uma consulta SQLX ou SQL.

O seguinte exemplo de código mostra a função JavaScript incorporada do núcleo do Dataform adicionada inline ao bloco post_operations num ficheiro SQLX:self

config {type: "table"}

SELECT * FROM ...

post_operations {
  GRANT `roles/bigquery.dataViewer`
  ON
  TABLE ${self()}
  TO "group:allusers@example.com", "user:otheruser@example.com"
}

O exemplo de código seguinte mostra uma constante definida num bloco JavaScript e usada inline numa consulta num ficheiro SQLX:

js {
  const columnName = "foo";
}

SELECT 1 AS ${columnName} FROM "..."

Reutilize código num único ficheiro SQLX com encapsulamento de JavaScript

Pode reutilizar o código JavaScript para simplificar o desenvolvimento no Dataform. Para reutilizar constantes e funções JavaScript num único ficheiro SQLX, pode encapsulá-las num bloco JavaScript. Para reutilizar código JavaScript num único repositório do Dataform, pode criar inclusões. Para reutilizar código JavaScript em vários repositórios do Dataform, pode criar ou importar um pacote.

Para criar partes repetitivas de código SQL que pode reutilizar num único ficheiro SQLX, pode encapsular funções e constantes num bloco JavaScript. Só pode reutilizar código definido num bloco de JavaScript no ficheiro SQLX onde o bloco está definido. Para mais informações, consulte o Dataform core.

O exemplo de código seguinte mostra uma constante e uma função definidas num bloco de JavaScript e usadas inline numa consulta num ficheiro SQLX:

js {
 const foo = 1;
 function bar(number){
     return number+1;
 }
}

select
 ${foo} as one,
 ${bar(foo)} as two

Reutilize código num único repositório com inclusões

As inclusões são constantes ou funções JavaScript globais para o seu repositório. Define as inclusões no diretório includes do seu repositório. Em seguida, pode reutilizá-los no seu repositório em ficheiros JavaScript e SQLX.

O seguinte exemplo de código mostra a definição da constante launch_date no ficheiro includes/constants.js:

// filename is includes/constants.js
const launch_date = "11.11.2011";
module.exports = { launch_date };

O exemplo de código seguinte mostra a constante launch_date referenciada numa consulta de definição de tabela num ficheiro SQLX:

config {type: "table"}

SELECT * FROM source_table WHERE date > ${constants.launch_date}

Crie um ficheiro JavaScript para inclusões

Para criar um novo ficheiro JavaScript no diretório includes/, siga estes passos:

1. No painel Ficheiros, junto a includes/, clique em more_vert Mais.

2. Clique em Criar ficheiro.

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

   1. No campo Adicionar um caminho do ficheiro, após includes/, introduza o nome do ficheiro seguido de .js. Por exemplo, includes/constants.js.

      Os nomes de ficheiros só podem incluir números, letras, hífenes e sublinhados.

   2. Clique em Criar ficheiro.

Crie uma constante de JavaScript

Para criar uma constante que pode reutilizar no seu projeto, siga estes passos:

1. Aceda ao seu espaço de trabalho de desenvolvimento.

2. No painel Ficheiros, expanda includes/.

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

4. No ficheiro, introduza o seguinte fragmento do código:

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

   Substitua o seguinte:

   • CONSTANT_NAME: o nome da sua constante
   • CONSTANT_VALUE: o valor da sua constante

5. Opcional: clique em Formatar.

O exemplo de código seguinte define a constante PROJECT_ID no ficheiro includes/constants.js:

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

O exemplo de código seguinte faz referência à constante PROJECT_ID numa consulta de definição de tabela num ficheiro SQLX:

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

O seguinte exemplo de código mostra a consulta de definição da tabela principal do Dataform anterior compilada em SQL:

  SELECT * FROM my_project_name.my_schema_name.my_table_name

Crie uma função de JavaScript personalizada

Para criar uma função de JavaScript personalizada que pode reutilizar no seu projeto, siga estes passos:

1. Aceda ao seu espaço de trabalho de desenvolvimento.

2. No painel Ficheiros, expanda includes/.

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

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

5. No ficheiro, introduza o seguinte fragmento do código:

    module.exports = { FUNCTION_NAME }
   

   Substitua FUNCTION_NAME pelo nome da sua função.

6. Opcional: clique em Formatar.

O seguinte exemplo de código mostra uma função JavaScript personalizada que é chamada renderScript e armazenada no ficheiro includes/functions.js. A função 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 seguinte mostra a utilização da função JavaScript renderScript personalizada numa 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 seguinte mostra a consulta de definição da tabela principal do Dataform anterior compilada em 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

Referencie uma inclusão num ficheiro SQLX

Pode referenciar qualquer função de inclusão ou constante num ficheiro SQLX. A sintaxe para referenciar includes depende da localização do ficheiro include. Um ficheiro de inclusão de nível superior está localizado diretamente no diretório includes/. Um ficheiro de inclusões aninhado está localizado num subdiretório de includes/.

Referencie uma inclusão de nível superior num ficheiro SQLX

• Para fazer referência a uma função de inclusão ou a uma constante de nível superior numa consulta do Dataform core, introduza o nome do ficheiro de definição de inclusão sem a extensão .js, seguido do nome do objeto exportado.

O exemplo de código seguinte faz referência à constante firstDate, definida no ficheiro includes/constants.js, num ficheiro SQLX de definição de tabela:

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

Referencie uma inclusão aninhada num ficheiro SQLX

Para fazer referência a inclusões localizadas em subdiretórios de definitions, importe inclusões através da função require JavaScript e de um bloco js {}.

Para fazer referência a uma inclusão aninhada com a função JavaScript require, siga estes passos:

1. Aceda ao seu espaço de trabalho de desenvolvimento.

2. No painel Ficheiros, expanda definitions/.

3. Selecione um ficheiro SQLX.

4. No bloco config, introduza o seguinte fragmento do código:

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

   Substitua o seguinte:

   • VARIABLE_NAME: o nome da constante ou da função que quer importar
   • SUBDIRECTORY_INCLUDE: o caminho do ficheiro includes aninhado

5. Opcional: clique em Formatar.

O exemplo de código seguinte faz referência à constante firstDate, definida no ficheiro includes/allConstants/constants.js aninhado, num ficheiro SQLX de definição de tabela:

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

Use uma função de inclusão do JavaScript com a função ref do Dataform core

Para usar uma função de inclusão do JavaScript com a função ref principal do Dataform, tem de transmitir ref como um argumento da função de inclusão do JavaScript num ficheiro SQLX.

O exemplo de código seguinte mostra o ficheiro includes/script_builder.js com a função JavaScript renderScript que agrega métricas através de SUM e as agrupa 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 seguinte mostra a função JavaScript renderScript usada no ficheiro definitions/stats_per_country_and_device.sqlx com a função ref Dataform core transmitida como argumento:

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

O seguinte exemplo de código mostra a consulta definitions/stats_per_country_and_device.sqlx compilada para SQL: