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
No Console do Google Cloud, acesse a página Dataform.
Selecione ou crie um repositório.
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:
No painel Arquivos, ao lado de
definitions/
, clique no menu Mais .Clique em Criar arquivo.
No painel Criar novo arquivo, faça o seguinte:
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.
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:
No espaço de trabalho de desenvolvimento, no painel Arquivos, expanda
definitions/
.Selecione um arquivo JavaScript.
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", });
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:
No espaço de trabalho de desenvolvimento, no painel Arquivos, expanda
definitions/
.Selecione um arquivo JavaScript.
No arquivo, insira um método JavaScript do Dataform global.
No método, insira um argumento
ctx
contextualizável.Opcional: se você estiver usando strings de modelo JavaScript, coloque o argumento contextual entre crases ``.
No argumento contextual, insira a função de consulta com o parâmetro dela como objeto de contexto.
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:
No espaço de trabalho de desenvolvimento, no painel Arquivos, expanda "definições/".
Selecione um arquivo JavaScript.
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
Para declarar outra fonte de dados no mesmo arquivo, adicione um bloco
declare
extra ao arquivo.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:
No espaço de trabalho de desenvolvimento, no painel Arquivos, expanda
definitions/
.Selecione um arquivo JavaScript.
No arquivo, digite o seguinte snippet de código:
publish("TABLE_NAME").query(ctx => "SELECT_QUERY");
Substitua
TABLE_NAME
pelo nome da tabela.Substitua
SELECT_QUERY
por uma instrução SQL SELECT que defina a tabela.
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
.Para definir outra tabela no mesmo arquivo, repita as etapas 3 e 4.
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:
No espaço de trabalho de desenvolvimento, no painel Arquivos, expanda
definitions/
.Selecione um arquivo JavaScript.
No arquivo, digite o seguinte snippet de código:
assert("ASSERTION_NAME").query(ctx => "CUSTOM_ASSERTION_QUERY");
Substitua
ASSERTION_NAME
pelo nome da sua declaração personalizada.Substitua
CUSTOM_ASSERTION_QUERY
pela consulta de declaração SQL.
Para criar outra declaração no mesmo arquivo, repita a etapa 3.
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:
No espaço de trabalho de desenvolvimento, no painel Arquivos, expanda
definitions/
.Selecione um arquivo JavaScript.
No arquivo, digite o seguinte snippet de código:
operate("OPERATION_NAME").queries(ctx => "CUSTOM_SQL_QUERY");
Substitua
OPERATION_NAME
pelo nome da operação personalizada.Substitua
CUSTOM_SQL_QUERY
pela consulta SQL personalizada.
Para definir outra operação SQL personalizada no mesmo arquivo, repita a etapa 3.
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
- 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.