Utilizzare JavaScript 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 consente di 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
• Cicli for
• 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 Dataform Editor (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 singolo repository Dataform, puoi creare include. 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 della 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 more_vert 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

Crea 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 funzione.

6. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra una funzione JavaScript personalizzata chiamata renderScript e archiviata 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 include 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.

L'esempio di codice seguente 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 ref di Dataform Core, 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 workflow.

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