Introdução ao JavaScript no Dataform

Este documento ajuda você a entender como usar JavaScript para desenvolver fluxos de trabalho SQL no Dataform.

O Dataform Core permite criar objetos de fluxo de trabalho SQL com SQLX e JavaScript. Embora opcional, usar JavaScript com SQLX para criar elementos semelhantes repetidamente no fluxo de trabalho Por exemplo, com JavaScript, é possível criar uma visualização de cada tabela no fluxo de trabalho sem determinados IDs de usuário. Você também pode desenvolver objetos de fluxo de trabalho SQL exclusivamente com JavaScript.

Para começar a desenvolver fluxos de trabalho SQL do Dataform usando JavaScript, você precisa conhecer a sintaxe do JavaScript e os seguintes conceitos de JavaScript:

  • Variáveis
  • Matrizes
  • Instruções condicionais
  • Repetições for
  • Mapas
  • Funções
  • Objetos
  • Como exportar e importar módulos

Adicionar código JavaScript a um arquivo SQLX

É possível adicionar o código JavaScript a um arquivo SQLX de duas maneiras: in-line ou dentro de um bloco JavaScript.

Você pode usar um bloco JavaScript para definir funções ou constantes em um arquivo SQLX. É possível usar JavaScript inline para modificar dinamicamente uma consulta SQLX ou SQL.

O exemplo de código a seguir mostra a principal função JavaScript integrada do Dataform self adicionada in-line ao bloco post_operations em um arquivo SQLX:

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 a seguir mostra uma constante definida em um bloco JavaScript e usada inline dentro de uma consulta em um arquivo SQLX:

js {
  const columnName = "foo";
}

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

Reutilizar código com JavaScript

É possível reutilizar o código JavaScript para simplificar o desenvolvimento no Dataform. Para reutilizar constantes e funções JavaScript em um único arquivo SQLX, é possível encapsular elas em um bloco JavaScript. Para reutilizar o código JavaScript em um único repositório do Dataform, crie inclusões. Para reutilizar o código JavaScript em vários repositórios do Dataform, crie ou importe um pacote.

Reutilizar código em um único arquivo SQLX com encapsulamento de JavaScript

Para criar partes repetitivas do código SQL que podem ser reutilizadas em um único arquivo SQLX, é possível encapsular funções e constantes em um bloco JavaScript. Só é possível reutilizar o código definido em um bloco JavaScript dentro do arquivo SQLX em que o bloco está definido. Para mais informações, consulte Visão geral do Dataform Core.

O exemplo de código a seguir mostra uma constante e uma função definidas em um bloco JavaScript e usadas in-line dentro de uma consulta em um arquivo SQLX:

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

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

Reutilizar código em um único repositório com inclusões

Inclui constantes do JavaScript ou funções globais para seu repositório. Você pode definir inclusões no diretório includes do repositório. Você pode reutilizá-los no repositório em arquivos JavaScript e SQLX.

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

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

O exemplo de código a seguir mostra a constante launch_date referenciada em uma consulta de definição de tabela em um arquivo SQLX:

config {type: "table"}

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

Reutilize código em vários repositórios com pacotes

Os pacotes são coleções de código JavaScript que podem ser importados e usados em vários repositórios do Dataform para otimizar o desenvolvimento do fluxo de trabalho SQL.

É possível criar seu próprio pacote personalizado no Dataform ou usar um dos pacotes de código aberto do Dataform, disponíveis na página do Dataform de código aberto do GitHub.

Para um exemplo de uso de um pacote de código aberto no Dataform, consulte Usar dimensões com alterações lentas no Dataform.

Para usar o conteúdo de um pacote no Dataform, você precisa instalar o pacote no repositório do Dataform e importá-lo para o arquivo JavaScript ou SQLX individual em que quer usar o pacote. Para mais informações, consulte Instalar um pacote no Dataform.

Para instalar um pacote NPM particular em um repositório do Dataform, você precisa autenticar o pacote.

Criar fluxos de trabalho SQL em JavaScript

Como alternativa ao desenvolvimento de fluxos de trabalho SQL em SQLX ou SQLX combinado com JavaScript, é possível criar objetos de fluxo de trabalho SQL em arquivos .js usando somente JavaScript. É possível criar vários objetos de fluxo de trabalho SQL em um arquivo JavaScript com métodos globais do Dataform e código JavaScript ES5 arbitrário, como loops e constantes. Cada um dos métodos JavaScript global do Dataform contém propriedades que podem ser usadas para configurar os objetos criados.

É possível criar os seguintes objetos de fluxo de trabalho SQL usando apenas JavaScript no Dataform:

  • Declarações de fonte de dados
  • Declarações manuais
  • Tabelas
  • Declarações manuais
  • Operações SQL personalizadas

Para mais informações sobre como criar objetos de fluxo de trabalho SQL usando somente JavaScript, consulte Criar fluxos de trabalho SQL do Dataform com JavaScript.

A seguir