Criar fluxos de trabalho SQL do Dataform com JavaScript

Este documento mostra como usar JavaScript para criar elementos de fluxo de trabalho SQL em o Dataform. Use JavaScript em vez do Dataform Core para criar elementos semelhantes repetidamente em seu fluxo de trabalho.

Sobre o desenvolvimento de fluxos de trabalho no Dataform com JavaScript

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

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

Você pode criar várias ações em um arquivo JavaScript com Métodos globais do Dataform e código JavaScript ES5 arbitrário, como como loops e constantes.

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

• Tabelas
• 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.

   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 ter as permissões necessárias para desenvolver um fluxo de trabalho SQL com JavaScript, peça ao administrador para conceder a você Papel do IAM Editor do Dataform (roles/dataform.editor) em 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 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 definitions/. Para criar um novo arquivo JavaScript no 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 Adicionar um caminho de arquivo, depois de definitions/, insira o nome do arquivo seguido por .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 SQL objetos de fluxo de trabalho 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 a objeto criado. Para mais informações sobre métodos globais e suas propriedades, consulte Referência principal do Dataform.

No método publish() que cria uma tabela, é possível definir as propriedades dela. passando-os como o segundo argumento do método.

Para transmitir as propriedades da tabela como o segundo argumento de publish(), faça o seguinte: 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() 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(). passando 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 inclusiva, macro ou constante dentro de um JavaScript . Para mais informações sobre inclusões no Dataform, consulte Reutilizar variáveis e funções com inclusões de JavaScript.

A sintaxe das inclusões de referência dentro de um arquivo JavaScript depende da localização do arquivo de inclusão. O Dataform armazena esses arquivos no 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 quando declarando suas variáveis.

O exemplo de código a seguir faz referência a serviceName e serviceId variáveis 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, digite o nome do arquivo no diretório exigem função.

O exemplo de código a seguir faz referência a serviceName e serviceId variáveis 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 em consultas, como ref e self. Para mais informações sobre 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, junte o argumento contextual entre crases ``.

6. No argumento contextual, insira a função de consulta com seu parâmetro da seguinte forma: 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 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 o 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 mais declare ao arquivo.

5. Opcional: clique em Formatar.

Definir uma tabela com JavaScript

É possível criar uma tabela com o JavaScript do Dataform publish . 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 definindo a tabela.

4. Para definir o tipo de tabela, adicionar dependências 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

Você pode criar declarações SQL manuais em um arquivo JavaScript com o Método JavaScript de declaração do Dataform. Para mais informações sobre , 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á. É possível criar várias declarações em uma JavaScript.

Para mais informações sobre declarações no Dataform, consulte Teste 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 customização declaração.

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

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 arquivo o 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 O Dataform opera o método JavaScript. 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 do bloco de anúncios personalizado. operação

   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 nova linha em some_table e define test_column da nova linha para 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 os funções de consulta, consulte a Referência principal do Dataform.
• Para saber mais sobre como desenvolver no Dataform com JavaScript, consulte Introdução ao JavaScript no Dataform.