Criar fluxos de trabalho SQL do Dataform com JavaScript

Neste documento, mostramos como usar o JavaScript para criar elementos do fluxo de trabalho SQL no Dataform. Talvez você queira usar o JavaScript em vez do Dataform para criar elementos semelhantes repetidamente no seu fluxo de trabalho.

Sobre o desenvolvimento de fluxos de trabalho no Dataform com JavaScript

O Dataform Core permite criar ações do fluxo de trabalho SQL com SQLX e JavaScript. Com o JavaScript, é possível criar ações semelhantes repetidamente no seu fluxo de trabalho. Por exemplo, é possível criar uma visualização de cada tabela no seu 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.

É possível definir as seguintes ações com JavaScript no Dataform:

• Tables
• Declarações da fonte de dados
• Declarações
• Operações SQL personalizadas

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.

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 que conceda 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 conseguir as permissões necessárias por meio de papéis personalizados ou de 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 Files, ao lado de definitions/, 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 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 as propriedades do objeto de fluxo de trabalho do Dataform SQL 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 as propriedades deles, consulte a referência principal do Dataform.

No método publish() que cria uma tabela, é possível definir 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 Files, expanda definitions/.

2. Selecione um arquivo JavaScript.

3. No arquivo, adicione propriedades de tabela ao método publish() no seguinte 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");

Inclusões de referência em um arquivo JavaScript

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

A sintaxe para referenciar inclusões dentro de um arquivo JavaScript depende do local desse arquivo. O Dataform armazena esses arquivos no diretório "inclusive".

Inclusões de nível superior de referência

• Para referenciar um arquivo de inclusão de nível superior, faça referência ao nome do arquivo ao declarar suas 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;

Inclusões aninhadas de referência

Para fazer referência a um arquivo de inclusão aninhado, insira o nome do arquivo na função de solicitação 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 fornece 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 Files, 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 contextual.

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 um 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

É possível declarar várias fontes de dados em um arquivo de declaração JavaScript com o método de declaração JavaScript do Dataform. Para mais informações sobre o método de declaração, consulte a referência principal do Dataform. Para saber mais 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, abra o painel Files,

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 pode ser usada mais tarde para fazer referência à fonte de dados no Dataform

4. Para declarar outra fonte de dados no mesmo arquivo, adicione mais um bloco declare 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.

É possível 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 Files, 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 define a tabela.

4. Para definir o tipo de tabela, adicionar dependências de tabela e descrição da tabela, 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 precisa retornar zero linhas. Se a consulta retornar linhas quando executada, a declaração vai falhar. É possível 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 Files, 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 sua 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

É possível definir operações SQL personalizadas em um arquivo JavaScript com o método "Opere JavaScript" 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 Files, 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 sua 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 nova linha 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

• Para saber mais sobre os métodos JavaScript do Dataform e as funções de consulta integradas, consulte a referência principal do Dataform.
• Para saber mais sobre o desenvolvimento no Dataform com JavaScript, consulte Introdução ao JavaScript no Dataform.