Riutilizza le variabili e le funzioni con include in Dataform

Questo documento mostra come creare elementi JavaScript inclusi per riutilizzare il codice in Dataform.

Nella cartella includes/ del repository, puoi definire l'inclusione di JavaScript. Le inclusioni sono costanti o funzioni globali che puoi riutilizzare nell'intero repository.

Prima di iniziare

Nella console Google Cloud, vai alla pagina Dataform.

Vai a Dataform
Seleziona o crea un repository Dataform.
Seleziona o crea un'area di lavoro di sviluppo Dataform.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per riutilizzare il codice con JavaScript incluso, chiedi all'amministratore di concederti il ruolo IAM Editor Dataform (roles/dataform.editor) per le aree di lavoro. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Potresti anche essere in grado di ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Crea un file JavaScript per l'inclusione in Dataform

Per creare un nuovo file JavaScript nella directory includes/, procedi nel seguente modo:

Nel riquadro File, accanto a includes/, fai clic sul menu Altro .
Fai clic su Crea file.
Nel riquadro Crea nuovo file, procedi nel seguente modo:
1. Nel campo Aggiungi un percorso file, dopo includes/, inserisci il nome del file seguito da .js. Ad esempio: includes/constants.js.
  
  I nomi 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 possa essere riutilizzata in tutto il progetto, segui questi passaggi:

Vai all'area di lavoro di sviluppo.
Nel riquadro File, espandi includes/.
Crea o seleziona un file JavaScript con l'estensione .js.
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 tua costante
- CONSTANT_VALUE: il valore della tua costante
(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 di 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 precedente query di definizione della tabella Dataform core 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 da riutilizzare nel progetto, segui questi passaggi:

Vai all'area di lavoro di sviluppo.
Nel riquadro File, espandi includes/.
Crea o seleziona un file JavaScript con l'estensione .js.
Nel file, scrivi la funzione JavaScript personalizzata.
Nel file, inserisci il seguente snippet di codice:
```
 module.exports = { FUNCTION_NAME }
```
Sostituisci FUNCTION_NAME con il nome della funzione.
(Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra una funzione JavaScript personalizzata, denominata renderScript, nel file includes/functions.js, che 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 principale Dataform:

  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 Dataform riportata sopra 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'inclusione in un file SQLX

Puoi fare riferimento a qualsiasi funzione o costante di inclusione all'interno di un file SQLX. La sintassi per i riferimenti alle include dipende dalla posizione del file di inclusione. Un file di inclusione 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 funzione o una costante di inclusione di primo livello in una query principale di Dataform, inserisci il nome del file di definizione di 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 di tabella:

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

Fare riferimento a un'inclusione nidificata in un file SQLX

Il riferimento include che si trova nelle sottodirectory di definitions, l'importazione include utilizzando la funzione JavaScript require e un blocco js {}.

Per fare riferimento a un elemento nidificato con la funzione JavaScript require, segui questi passaggi:

Vai all'area di lavoro di sviluppo.
Nel riquadro File, espandi definitions/.
Seleziona un file SQLX.
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 da importare
- SUBDIRECTORY_INCLUDE: il percorso del file includes nidificato
(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 di tabella:

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

Utilizza una funzione di inclusione JavaScript con la funzione `ref` principale di Dataform

Per utilizzare una funzione di inclusione JavaScript con la funzione ref di base di Dataform, devi passare ref come argomento della funzione JavaScript di inclusione 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 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 Dataform core ref 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 ulteriori informazioni sulla funzione ref principale di Dataform, consulta Panoramica del core di Dataform.

Passaggi successivi

Per scoprire come fare riferimento agli elementi inclusi nei file JavaScript, consulta Creare flussi di lavoro SQL con JavaScript.
Per informazioni su come riutilizzare il codice con, nonché bloccare e incorporare JavaScript all'interno dei file Dataform core, consulta la panoramica del core di Dataform.