Criar fluxos de trabalho SQL do Dataform com JavaScript

Neste documento, mostramos como usar JavaScript para criar elementos de fluxo de trabalho SQL no Dataform. Use JavaScript em vez do Dataform Core para criar elementos semelhantes repetidamente no fluxo de trabalho.

Sobre o desenvolvimento de fluxos de trabalho no Dataform com JavaScript

O Dataform Core permite criar ações de fluxo de trabalho SQL com SQLX e JavaScript. Com JavaScript, é possível criar ações semelhantes repetidamente no fluxo de trabalho. Por exemplo, é possível criar uma visualização de cada tabela no fluxo de trabalho com determinados IDs de usuário removidos.

O exemplo de código JavaScript a seguir permite criar uma visualização de cada tabela em que o valor do campo user_id não corresponde a um dos valores na lista blocked_user_ids:

  const tableNames = ["user_events", "user_settings", "user_logs"];

  tableNames.forEach(tableName => {
    publish(tableName + "_blocked_removed").query(
      ctx => `
        SELECT * FROM ${ctx.ref(tableName)}
        WHERE user_id NOT IN (
          SELECT user_id
          FROM ${ctx.ref("blocked_user_ids")}
        )`
    );
  });

Este exemplo de código cria três visualizações chamadas user_events_blocked_removed, user_settings_blocked_removed e user_logs_blocked_removed que não contêm nenhum dos IDs de usuário bloqueados.

É possível criar várias ações em um arquivo JavaScript com métodos globais do Dataform e código JavaScript ES5 arbitrário, como loops e constantes.

Você pode definir as seguintes ações com JavaScript no Dataform:

Antes de começar

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

    Acessar o Dataform

  2. Selecione ou crie um repositório.

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

Funções exigidas

Para receber as permissões necessárias para desenvolver um fluxo de trabalho SQL com JavaScript, peça ao administrador para conceder a você o papel do IAM Editor do Dataform (roles/dataform.editor) nos espaços de trabalho. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Também é possível receber as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Criar um arquivo JavaScript no Dataform

Armazene arquivos JavaScript para definições e declarações de fonte de dados no diretório definitions/. Para criar um novo arquivo JavaScript no diretório definitions/, siga estas etapas:

  1. No painel Arquivos, ao lado de definitions/, clique no menu Mais .

  2. Clique em Criar arquivo.

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

    1. No campo Add a file path, depois de definitions/, insira o nome do arquivo seguido de .js. Por exemplo, definitions/definitions.js.

      Os nomes de arquivos podem incluir apenas números, letras, hifens e sublinhados.

    2. Clique em Criar arquivo.

Definir propriedades do objeto do fluxo de trabalho SQL do Dataform com JavaScript

É possível usar os seguintes métodos globais do Dataform para criar objetos de fluxo de trabalho SQL com o Dataform:

  • declare. Usado para declarar uma fonte de dados.
  • publish. Usado para definir uma tabela.
  • assert. Usado para criar uma declaração.
  • operate. Usado para definir uma operação SQL personalizada.

Cada um dos métodos globais contém propriedades que podem ser usadas para configurar o objeto criado. Para mais informações sobre métodos globais e propriedades deles, consulte a referência principal do Dataform.

No método publish() que cria uma tabela, defina as propriedades da tabela transmitindo-as como o segundo argumento do método.

Para transmitir as propriedades da tabela como o segundo argumento de publish(), siga estas etapas:

  1. No espaço de trabalho de desenvolvimento, no painel Arquivos, expanda definitions/.

  2. Selecione um arquivo JavaScript.

  3. No arquivo, adicione propriedades da tabela ao método publish() neste formato:

     method("first_method_argument", {
   property1: "property1_value",
   property2: "property2_value",
   property3: "property3_value",
 });

  4. Opcional: clique em Formatar.

O exemplo de código a seguir mostra como definir propriedades para o método publish() transmitindo as propriedades como um segundo argumento do método:

  publish("table1", {
    type: "table",
    dependencies: ["other_table"],
    description: {
      "Value is 1"
    }
  }).query(ctx => "SELECT 1 AS test");

A referência inclui em um arquivo JavaScript

Você pode fazer referência a qualquer função, macro ou constante inclusiva dentro de um arquivo JavaScript. Para mais informações sobre inclusões no Dataform, consulte Reutilizar variáveis e funções com inclusões de JavaScript.

A sintaxe de inclusão de referências dentro de um arquivo JavaScript depende do local desse arquivo. O Dataform armazena esses arquivos no diretório inclui.

Referências de nível superior incluem

  • Para fazer referência a um arquivo de inclusões de nível superior, faça referência ao nome do arquivo ao declarar as variáveis.

O exemplo de código a seguir faz referência às variáveis serviceName e serviceId do arquivo includes/service.js:

  const {serviceName, serviceId} = service;

Referência de inclusões aninhadas

Para fazer referência a um arquivo de inclusões aninhadas, insira o nome do arquivo na função obrigatória do JavaScript.

O exemplo de código a seguir faz referência às variáveis serviceName e serviceId do arquivo includes/allServices/service.js:

  const {serviceName, serviceId} = require("includes/allServices/service.js");

Usar funções de consulta do Dataform em métodos JavaScript

O Dataform oferece várias funções integradas que podem ser usadas dentro de consultas, como ref e self. Para mais informações sobre as funções integradas do Dataform, consulte a referência da API Dataform.

Para usar uma função de consulta integrada em um método JavaScript, siga estas etapas:

  1. No espaço de trabalho de desenvolvimento, no painel Arquivos, expanda definitions/.

  2. Selecione um arquivo JavaScript.

  3. No arquivo, insira um método JavaScript do Dataform global.

  4. No método, insira um argumento ctx contextualizável.

  5. Opcional: se você estiver usando strings de modelo JavaScript, coloque o argumento contextual entre crases ``.

  6. No argumento contextual, insira a função de consulta com o parâmetro dela como objeto de contexto.

  7. Opcional: clique em Formatar.

O exemplo de código a seguir mostra a função de consulta ref encapsulada em um argumento contextual do método de publicação:

  publish("example").query(ctx => `SELECT * FROM ${ctx.ref("other_table")}`);

Declarar uma fonte de dados do fluxo de trabalho SQL com JavaScript

Você pode declarar várias fontes de dados em um arquivo de declaração JavaScript com o método JavaScript de declaração do Dataform. Para mais informações sobre o método de declaração, consulte a referência principal do Dataform. Para mais informações sobre fontes de dados no Dataform, consulte Declarar uma fonte de dados.

Para declarar uma fonte de dados em um arquivo JavaScript, siga estas etapas:

  1. No espaço de trabalho de desenvolvimento, no painel Arquivos, expanda "definições/".

  2. Selecione um arquivo JavaScript.

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

     declare({
   database: "DATABASE_PROJECT_ID",
   schema: "BIGQUERY_SCHEMA",
   name: "RELATION_NAME",
 });

    Substitua:

    • DATABASE_PROJECT_ID: o ID do projeto que contém a fonte de dados.
    • BIGQUERY_SCHEMA: o conjunto de dados do BigQuery em que a relação externa existe.
    • RELATION_NAME: o nome da relação que você pode usar mais tarde para fazer referência à fonte de dados no Dataform

  4. Para declarar outra fonte de dados no mesmo arquivo, adicione um bloco declare extra ao arquivo.

  5. Opcional: clique em Formatar.

Definir uma tabela com JavaScript

É possível criar uma tabela com o método publish JavaScript do Dataform. Para mais informações sobre o método de publicação, consulte a referência principal do Dataform.

Você pode definir os seguintes tipos de tabela: tabela, tabela incremental e visualização. Para mais informações sobre como definir tabelas no Dataform, consulte Criar uma tabela.

Para definir uma tabela em um arquivo JavaScript, siga estas etapas:

  1. No espaço de trabalho de desenvolvimento, no painel Arquivos, expanda definitions/.

  2. Selecione um arquivo JavaScript.

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

     publish("TABLE_NAME").query(ctx => "SELECT_QUERY");

    1. Substitua TABLE_NAME pelo nome da tabela.

    2. Substitua SELECT_QUERY por uma instrução SQL SELECT que defina a tabela.

  4. Para definir o tipo e a descrição da tabela, adicione as dependências dela e defina as propriedades do objeto do método publish.

  5. Para definir outra tabela no mesmo arquivo, repita as etapas 3 e 4.

  6. Opcional: clique em Formatar.

Definir declarações manuais do Dataform com JavaScript

É possível criar declarações SQL manuais em um arquivo JavaScript com o método JavaScript de declaração do Dataform. Para mais informações sobre o método de declaração, consulte a referência principal do Dataform.

Uma consulta SQL de declaração manual não pode retornar linhas. Se a consulta retornar linhas quando executada, a declaração falhará. Você pode criar várias declarações em um arquivo JavaScript.

Para mais informações sobre declarações no Dataform, consulte Testar tabelas com declarações.

Para criar uma declaração manual em um arquivo JavaScript, siga estas etapas:

  1. No espaço de trabalho de desenvolvimento, no painel Arquivos, expanda definitions/.

  2. Selecione um arquivo JavaScript.

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

     assert("ASSERTION_NAME").query(ctx => "CUSTOM_ASSERTION_QUERY");

    1. Substitua ASSERTION_NAME pelo nome da sua declaração personalizada.

    2. Substitua CUSTOM_ASSERTION_QUERY pela consulta de declaração SQL.

  4. Para criar outra declaração no mesmo arquivo, repita a etapa 3.

  5. Opcional: clique em Formatar.

O exemplo de código a seguir mostra uma declaração JavaScript que declara que nenhum valor em source_table é NULL:

  assert("assertion1").query(ctx => "SELECT * FROM source_table WHERE value IS NULL");

Definir operações SQL personalizadas com JavaScript

Você pode definir operações SQL personalizadas em um arquivo JavaScript com o método JavaScript de operação do Dataform. Para mais informações sobre operações SQL personalizadas no Dataform, consulte Adicionar operações SQL personalizadas.

Para definir uma operação SQL personalizada com JavaScript, siga estas etapas:

  1. No espaço de trabalho de desenvolvimento, no painel Arquivos, expanda definitions/.

  2. Selecione um arquivo JavaScript.

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

     operate("OPERATION_NAME").queries(ctx => "CUSTOM_SQL_QUERY");

    1. Substitua OPERATION_NAME pelo nome da operação personalizada.

    2. Substitua CUSTOM_SQL_QUERY pela consulta SQL personalizada.

  4. Para definir outra operação SQL personalizada no mesmo arquivo, repita a etapa 3.

  5. Opcional: clique em Formatar.

O exemplo de código a seguir mostra uma operação SQL personalizada em um arquivo JavaScript que insere uma única linha nova em some_table e define test_column da nova linha como 2:

  operate("operation1").queries("INSERT INTO some_table (test_column) VALUES (2)");

A seguir