Utilizzare JavaScript in Dataform

Questo documento ti aiuta a capire come utilizzare JavaScript per sviluppare flussi di lavoro in Dataform. Questo documento mostra anche come utilizzare JavaScript per creare azioni del flusso di lavoro e come creare inclusioni JavaScript per riutilizzare il codice in Dataform.

Dataform Core ti consente di creare azioni del workflow con SQLX e JavaScript. Sebbene sia facoltativo, l'utilizzo di JavaScript insieme a SQLX per creare elementi simili ripetutamente nel flusso di lavoro. Ad esempio, con JavaScript puoi creare una visualizzazione di ogni tabella del flusso di lavoro con determinati ID utente rimossi. Puoi anche sviluppare azioni del flusso di lavoro esclusivamente con JavaScript.

Prima di iniziare

  1. Nella console Google Cloud , vai alla pagina Dataform.

    Vai a Dataform

  2. Seleziona o crea un repository.

  3. Seleziona o crea un workspace di sviluppo.

Inoltre, devi avere familiarità con la sintassi JavaScript e con i seguenti concetti JavaScript:

  • Variabili
  • Array
  • Istruzioni condizionali
  • Per i loop
  • Maps
  • Funzioni
  • Oggetti
  • Esportazione e importazione di moduli

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per sviluppare un flusso di lavoro con JavaScript e riutilizzare il codice con le inclusioni JavaScript, chiedi all'amministratore di concederti il ruolo IAM Editor Dataform (roles/dataform.editor) negli spazi di lavoro. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Aggiungere codice JavaScript a un file SQLX

Puoi aggiungere codice JavaScript a un file SQLX in due modi: in linea o all'interno di un blocco JavaScript.

Puoi utilizzare un blocco JavaScript per definire funzioni o costanti in un file SQLX. Puoi utilizzare JavaScript incorporato per modificare dinamicamente una query SQLX o SQL.

Il seguente esempio di codice mostra la funzione JavaScript integrata principale di Dataform self aggiunta inline al blocco post_operations in un file SQLX:

config {type: "table"}

SELECT * FROM ...

post_operations {
  GRANT `roles/bigquery.dataViewer`
  ON
  TABLE ${self()}
  TO "group:allusers@example.com", "user:otheruser@example.com"
}

Il seguente esempio di codice mostra una costante definita in un blocco JavaScript e utilizzata inline all'interno di una query in un file SQLX:

js {
  const columnName = "foo";
}

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

Riutilizzare il codice in un singolo file SQLX con l'incapsulamento JavaScript

Puoi riutilizzare il codice JavaScript per semplificare lo sviluppo in Dataform. Per riutilizzare costanti e funzioni JavaScript in un singolo file SQLX, puoi incapsularle in un blocco JavaScript. Per riutilizzare il codice JavaScript in un unico repository Dataform, puoi creare includi. Per riutilizzare il codice JavaScript in più repository Dataform, puoi creare o importare un pacchetto.

Per creare parti ripetitive di codice SQL che puoi riutilizzare all'interno di un singolo file SQLX, puoi incapsulare funzioni e costanti in un blocco JavaScript. Puoi riutilizzare il codice definito in un blocco JavaScript solo all'interno del file SQLX in cui è definito il blocco. Per maggiori informazioni, consulta la pagina Dataform Core.

Il seguente esempio di codice mostra una costante e una funzione definite in un blocco JavaScript e utilizzate inline all'interno di una query in un file SQLX:

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

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

Riutilizzare il codice in un singolo repository con gli include

Gli include sono costanti o funzioni JavaScript globali per il tuo repository. Definisci gli include nella directory includes del repository. Puoi riutilizzarli nel repository nei file JavaScript e SQLX.

Il seguente esempio di codice mostra la definizione della costante launch_date nel file includes/constants.js:

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

Il seguente esempio di codice mostra la costante launch_date a cui viene fatto riferimento in una query di definizione di tabella in un file SQLX:

config {type: "table"}

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

Crea un file JavaScript per gli include

Per creare un nuovo file JavaScript nella directory includes/:

  1. Nel riquadro File, accanto a includes/, fai clic su Altro.

  2. Fai clic su Crea file.

  3. Nel riquadro Crea nuovo file:

    1. Nel campo Aggiungi un percorso del file, dopo includes/, inserisci il nome del file seguito da .js. Ad esempio: includes/constants.js.

      I nomi dei file possono includere solo numeri, lettere, trattini e trattini bassi.

    2. Fai clic su Crea file.

Creare una costante JavaScript

Per creare una costante che puoi riutilizzare nel progetto:

  1. Vai al tuo workspace di sviluppo.

  2. Nel riquadro File, espandi includes/.

  3. Crea o seleziona un file JavaScript con estensione .js.

  4. Nel file, inserisci il seguente snippet di codice:

     const CONSTANT_NAME = CONSTANT_VALUE;
 module.exports = { CONSTANT_NAME };

    Sostituisci quanto segue:

    • CONSTANT_NAME: il nome della costante
    • CONSTANT_VALUE: il valore della costante

  5. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice definisce la costante PROJECT_ID nel file includes/constants.js:

  // filename is includes/constants.js
  const PROJECT_ID = "my_project_name";
  module.exports = { PROJECT_ID };

Il seguente esempio di codice fa riferimento alla costante PROJECT_ID in una query di definizione della tabella in un file SQLX:

  config { type: "table" }
  SELECT * FROM ${constants.PROJECT_ID}.my_schema_name.my_table_name

Il seguente esempio di codice mostra la query di definizione della tabella principale Dataform precedente compilata in SQL:

  SELECT * FROM my_project_name.my_schema_name.my_table_name

Creare una funzione JavaScript personalizzata

Per creare una funzione JavaScript personalizzata che puoi riutilizzare nel tuo progetto, segui questi passaggi:

  1. Vai al tuo workspace di sviluppo.

  2. Nel riquadro File, espandi includes/.

  3. Crea o seleziona un file JavaScript con estensione .js.

  4. Nel file, scrivi la tua funzione JavaScript personalizzata.

  5. Nel file, inserisci il seguente snippet di codice:

     module.exports = { FUNCTION_NAME }

    Sostituisci FUNCTION_NAME con il nome della tua funzione.

  6. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra una funzione JavaScript personalizzata chiamata renderScript e memorizzata nel file includes/functions.js. La funzione genera uno script SQL:

  function renderScript(table, dimensions, metrics) {
    return `
        select
        ${dimensions.map(field => `${field} as ${field}`).join(",")},
        ${metrics.map(field => `sum(${field}) as ${field}`).join(",\n")}
        from ${table}
        group by ${dimensions.map((field, i) => `${i + 1}`).join(", ")}
      `;
  }

  module.exports = { renderScript };

Il seguente esempio di codice mostra l'utilizzo della funzione JavaScript renderScript personalizzata in una query di definizione della tabella Dataform Core:

  config {
      type: "table",
      tags: ["advanced", "hourly"],
      disabled: true
  }

  ${functions.renderScript(ref("source_table"),
                                ["country", "device_type"],
                                ["revenue", "pageviews", "sessions"]
                                )}

Il seguente esempio di codice mostra la query di definizione della tabella principale di Dataform precedente compilata in SQL:

  select
    country as country,
    device_type as device_type,
    sum(revenue) as revenue,
    sum(pageviews) as pageviews,
    sum(sessions) as sessions

  from "dataform"."source_table"

  group by 1, 2

Fare riferimento a un include in un file SQLX

Puoi fare riferimento a qualsiasi funzione o costante di inclusione all'interno di un file SQLX. La sintassi per fare riferimento agli include dipende dalla posizione del file include. Un file include di primo livello si trova direttamente nella directory includes/. Un file di inclusione nidificato si trova in una sottodirectory di includes/.

Fare riferimento a un'inclusione di primo livello in un file SQLX

  • Per fare riferimento a una costante o a una funzione di inclusione di primo livello in una query Dataform Core, inserisci il nome del file di definizione dell'inclusione senza l'estensione .js, seguito dal nome dell'oggetto esportato.

Il seguente esempio di codice fa riferimento alla costante firstDate, definita nel file includes/constants.js, in un file SQLX di definizione della tabella:

  config {type: "table"}
  select * from source_table where date > ${constants.firstDate}

Fare riferimento a un'inclusione nidificata in un file SQLX

Per fare riferimento agli include che si trovano nelle sottodirectory di definitions, importa gli include utilizzando la funzione JavaScript require e un blocco js {}.

Per fare riferimento a un'inclusione nidificata con la funzione JavaScript require, segui questi passaggi:

  1. Vai al tuo workspace di sviluppo.

  2. Nel riquadro File, espandi definitions/.

  3. Seleziona un file SQLX.

  4. Nel blocco config, inserisci il seguente snippet di codice:

     js {
   var { VARIABLE_NAME } = require("SUBDIRECTORY_INCLUDE");
 }

    Sostituisci quanto segue:

    • VARIABLE_NAME: il nome della costante o della funzione che vuoi importare
    • SUBDIRECTORY_INCLUDE: il percorso del file includes nidificato

  5. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice fa riferimento alla costante firstDate, definita nel file includes/allConstants/constants.js nidificato, in un file SQLX di definizione della tabella:

  config {type: "table"}
  js {
    var { firstDate } = require("includes/allConstants/constants");
  }
  select * from source_table where date > ${firstDate}

Utilizzare una funzione di inclusione JavaScript con la funzione ref di Dataform Core

Per utilizzare una funzione di inclusione JavaScript con la funzione principale ref di Dataform, devi passare ref come argomento della funzione di inclusione JavaScript all'interno di un file SQLX.

Il seguente esempio di codice mostra il file includes/script_builder.js con la funzione JavaScript renderScript che aggrega le metriche utilizzando SUM e le raggruppa per dimensione:

function renderScript(table, dimensions, metrics) {
  return `
      SELECT
      ${dimensions.map((field) => `${field} AS ${field}`).join(",\\n")},
      ${metrics.map((field) => `SUM(${field}) AS ${field}`).join(",\\n")}
      FROM ${table}
      GROUP BY ${dimensions.map((field, i) => `${i + 1}`).join(", ")}
    `;
}
module.exports = { renderScript };

Il seguente esempio di codice mostra la funzione JavaScript renderScript utilizzata nel file definitions/stats_per_country_and_device.sqlx con la funzione ref Dataform Core passata come argomento:

${script_builder.renderScript(
  ref("source_table"),
  ["country", "device_type"],
  ["revenue", "pageviews", "sessions"])}

Il seguente esempio di codice mostra la query definitions/stats_per_country_and_device.sqlx compilata in SQL:

SELECT country AS country,
       device_type AS device_type,
       SUM(revenue) AS revenue,
       SUM(pageviews) AS pageviews,
       SUM(sessions) AS sessions
FROM my_schema.source_table
GROUP BY 1, 2

Per saperne di più sulla funzione ref di Dataform Core, consulta Dataform Core.

Riutilizzare il codice in più repository con i pacchetti

I pacchetti sono raccolte di codice JavaScript che puoi importare e utilizzare in più repository Dataform per semplificare lo sviluppo del flusso di lavoro.

Puoi creare il tuo pacchetto personalizzato in Dataform o utilizzare uno dei pacchetti Dataform open source, disponibili nella pagina Dataform open source di GitHub.

Per poter utilizzare i contenuti di un pacchetto in Dataform, devi installarlo nel repository Dataform e poi importarlo nel singolo file JavaScript o SQLX in cui vuoi utilizzarlo. Per saperne di più, vedi Installare un pacchetto.

Per poter installare un pacchetto NPM privato in un repository Dataform, devi autenticare il pacchetto.

Creare workflow esclusivamente con JavaScript

Questa sezione mostra come utilizzare JavaScript per creare azioni del flusso di lavoro in Dataform. Ti consigliamo di utilizzare JavaScript anziché Dataform core per creare elementi simili ripetutamente nel tuo flusso di lavoro.

In alternativa allo sviluppo di workflow in SQLX o SQLX combinato con JavaScript, puoi creare azioni del workflow nei file .js utilizzando solo JavaScript. Puoi creare più azioni del flusso di lavoro all'interno di un file JavaScript con metodi globali Dataform e codice JavaScript ES5 arbitrario, come cicli e costanti. Ciascuno dei metodi JavaScript globali di Dataform contiene proprietà che puoi utilizzare per configurare gli oggetti creati.

Puoi creare le seguenti azioni del flusso di lavoro utilizzando solo JavaScript in Dataform:

  • Dichiarazioni delle origini dati
  • Tabelle
  • Asserzioni manuali
  • Operazioni SQL personalizzate

Con JavaScript, puoi creare azioni simili ripetutamente nel flusso di lavoro. Ad esempio, puoi creare una visualizzazione di ogni tabella del flusso di lavoro con determinati ID utente rimossi.

Il seguente esempio di codice JavaScript consente di creare una visualizzazione di ogni tabella in cui il valore del campo user_id non corrisponde a uno dei valori nell'elenco 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")}
        )`
    );
  });

Questo esempio di codice crea tre viste denominate user_events_blocked_removed, user_settings_blocked_removed e user_logs_blocked_removed che non contengono nessuno degli ID utente bloccati.

Puoi creare più azioni all'interno di un file JavaScript con metodi globali Dataform e codice JavaScript ES5 arbitrario, ad esempio cicli e costanti.

Puoi definire le seguenti azioni con JavaScript in Dataform:

Crea un file JavaScript

Archivia i file JavaScript per le definizioni e le dichiarazioni delle origini dati nella directory definitions/. Per creare un nuovo file JavaScript nella directory definitions/, segui questi passaggi:

  1. Nel riquadro File, accanto a definitions/, fai clic su Altro.

  2. Fai clic su Crea file.

  3. Nel riquadro Crea nuovo file:

    1. Nel campo Aggiungi un percorso del file, dopo definitions/, inserisci il nome del file seguito da .js. Ad esempio, definitions/definitions.js.

      I nomi dei file possono includere solo numeri, lettere, trattini e trattini bassi.

    2. Fai clic su Crea file.

Impostare le proprietà dell'azione del workflow con JavaScript

Puoi utilizzare i seguenti metodi globali di Dataform per creare azioni del flusso di lavoro SQL con Dataform:

  • declare. Utilizzato per dichiarare un'origine dati.
  • publish. Utilizzato per definire una tabella.
  • assert. Utilizzato per creare un'asserzione.
  • operate. Utilizzato per definire un'operazione SQL personalizzata.

Ciascuno dei metodi globali contiene proprietà che puoi utilizzare per configurare l'oggetto creato. Per saperne di più sui metodi globali e sulle relative proprietà, consulta il riferimento di Dataform Core.

Nel metodo publish() che crea una tabella, puoi impostare le proprietà della tabella passandole come secondo argomento del metodo.

Per passare le proprietà della tabella come secondo argomento di publish(), segui questi passaggi:

  1. Nell'area di lavoro di sviluppo, nel riquadro File, espandi definitions/.

  2. Seleziona un file JavaScript.

  3. Nel file, aggiungi le proprietà della tabella al metodo publish() nel seguente formato:

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

  4. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra come impostare le proprietà sul metodo publish() passandole come secondo argomento del metodo:

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

Inclusioni di riferimenti in un file JavaScript

Puoi fare riferimento a qualsiasi funzione, macro o costante include all'interno di un file JavaScript. Per saperne di più sugli include in Dataform, consulta la sezione Riutilizzare il codice in un singolo repository con gli include di questo documento.

La sintassi per fare riferimento agli include all'interno di un file JavaScript dipende dalla posizione del file include. Dataform archivia questi file nella directory includes.

Il riferimento di primo livello include

  • Per fare riferimento a un file include di primo livello, fai riferimento al nome del file quando dichiari le variabili.

Il seguente esempio di codice fa riferimento alle variabili serviceName e serviceId del file includes/service.js:

  const {serviceName, serviceId} = service;

Inclusioni nidificate dei riferimenti

Per fare riferimento a un file di inclusione nidificato, inserisci il nome del file nella funzione require di JavaScript.

Il seguente esempio di codice fa riferimento alle variabili serviceName e serviceId del file includes/allServices/service.js:

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

Utilizzare le funzioni di query Dataform nei metodi JavaScript

Dataform fornisce una serie di funzioni integrate che puoi utilizzare all'interno delle query, ad esempio ref e self. Per saperne di più sulle funzioni integrate di Dataform, consulta il riferimento API Dataform.

Per utilizzare una funzione di query integrata in un metodo JavaScript:

  1. Nell'area di lavoro di sviluppo, nel riquadro File, espandi definitions/.

  2. Seleziona un file JavaScript.

  3. Nel file, inserisci un metodo JavaScript Dataform globale.

  4. Nel metodo, inserisci un argomento ctx contestualizzabile.

  5. (Facoltativo) Se utilizzi stringhe modello JavaScript, racchiudi l'argomento contestuale tra apici inversi ``.

  6. Nell'argomento contestuale, inserisci la funzione di query con il relativo parametro come oggetto di contesto.

  7. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra la funzione di query ref racchiusa in un argomento contestuale del metodo publish:

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

Dichiarare un'origine dati del workflow con JavaScript

Puoi dichiarare più origini dati in un unico file di dichiarazione JavaScript con il metodo JavaScript Dataform declare. Per saperne di più sul metodo declare, consulta il riferimento di Dataform Core. Per saperne di più sulle origini dati in Dataform, vedi Dichiarare un'origine dati.

Per dichiarare un'origine dati in un file JavaScript:

  1. Nell'area di lavoro di sviluppo, nel riquadro File, espandi definitions/.

  2. Seleziona un file JavaScript.

  3. Nel file, inserisci il seguente snippet di codice:

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

    Sostituisci quanto segue:

    • DATABASE_PROJECT_ID: l'ID progetto del progetto che contiene l'origine dati
    • BIGQUERY_SCHEMA: il set di dati BigQuery in cui esiste la relazione esterna
    • RELATION_NAME: il nome della relazione che puoi utilizzare in un secondo momento per fare riferimento all'origine dati in Dataform

  4. Per dichiarare un'altra origine dati nello stesso file, aggiungi un blocco declare aggiuntivo al file.

  5. (Facoltativo) Fai clic su Formato.

Definisci una tabella con JavaScript

Puoi creare una tabella con il metodo JavaScript publish Dataform. Per saperne di più sul metodo di pubblicazione, consulta la documentazione di riferimento di Dataform Core.

Puoi definire i seguenti tipi di tabelle:

  • Tabella
  • Tabella incrementale
  • Visualizza

Per saperne di più sulla definizione delle tabelle in Dataform, vedi Creare tabelle.

Per definire una tabella in un file JavaScript:

  1. Nell'area di lavoro di sviluppo, nel riquadro File, espandi definitions/.

  2. Seleziona un file JavaScript.

  3. Nel file, inserisci il seguente snippet di codice:

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

    Sostituisci quanto segue:

    • TABLE_NAME: il nome della tabella
    • SELECT_QUERY: un'istruzione SQL SELECT che definisce la tabella

  4. Per impostare il tipo di tabella, aggiungere le dipendenze della tabella e la descrizione della tabella, imposta le proprietà dell'oggetto del metodo publish.

  5. Per definire un'altra tabella nello stesso file, ripeti i passaggi 3 e 4.

  6. (Facoltativo) Fai clic su Formato.

Definisci le asserzioni manuali con JavaScript

Puoi creare asserzioni SQL manuali in un file JavaScript con il metodo JavaScript Dataform assert. Per saperne di più sul metodo assert, consulta il riferimento di Dataform Core.

Una query SQL di asserzione manuale deve restituire zero righe. Se la query restituisce righe quando viene eseguita, l'asserzione non riesce. Puoi creare più asserzioni in un unico file JavaScript.

Per ulteriori informazioni sulle asserzioni in Dataform, consulta Testare la qualità dei dati.

Per creare un'asserzione manuale in un file JavaScript:

  1. Nell'area di lavoro di sviluppo, nel riquadro File, espandi definitions/.

  2. Seleziona un file JavaScript.

  3. Nel file, inserisci il seguente snippet di codice:

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

    Sostituisci quanto segue:

    • ASSERTION_NAME: il nome dell'asserzione personalizzata
    • CUSTOM_ASSERTION_QUERY: la query di asserzione SQL

  4. Per creare un'altra asserzione nello stesso file, ripeti il passaggio 3.

  5. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra un'asserzione JavaScript che afferma che nessun valore in source_table è NULL:

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

Definisci operazioni SQL personalizzate con JavaScript

Puoi definire operazioni SQL personalizzate in un file JavaScript con il metodo JavaScript operate di Dataform. Per saperne di più sulle operazioni SQL personalizzate in Dataform, consulta Creare operazioni.

Per definire un'operazione SQL personalizzata con JavaScript:

  1. Nell'area di lavoro di sviluppo, nel riquadro File, espandi definitions/.

  2. Seleziona un file JavaScript.

  3. Nel file, inserisci il seguente snippet di codice:

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

    Sostituisci quanto segue:

    • OPERATION_NAME: il nome dell'operazione personalizzata
    • CUSTOM_SQL_QUERY: la query SQL personalizzata

  4. Per definire un'altra operazione SQL personalizzata nello stesso file, ripeti il passaggio 3.

  5. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra un'operazione SQL personalizzata in un file JavaScript che inserisce una nuova riga in some_table e imposta test_column della nuova riga su 2:

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

Passaggi successivi