Dataform core ti consente di creare azioni di flusso di lavoro con SQLX e JavaScript. Sebbene facoltativo, utilizza 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 di flusso di lavoro esclusivamente con JavaScript.
Prima di iniziare
Nella console Google Cloud, vai alla pagina Dataform.
Seleziona o crea un repository.
Seleziona o crea un'area di lavoro di sviluppo.
Inoltre, devi conoscere la sintassi JavaScript e i seguenti concetti di JavaScript:
- Variabili
- Array
- Istruzioni condizionali
- Per 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 di Dataform (roles/dataform.editor) negli spazi di lavoro.
Per saperne di più sulla concessione dei ruoli, consulta Gestire 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 in linea per modificare dinamicamente una query SQLX o SQL.
Il seguente esempio di codice mostra la funzione JavaScript self Dataform core integrata aggiunta in linea 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 in linea 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 unico 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 ulteriori informazioni, consulta Dataform Core.
Il seguente esempio di codice mostra una costante e una funzione definite in un blocco JavaScript e utilizzate in linea 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 elementi include sono costanti o funzioni JavaScript globali per il tuo repository.
Definisci le inclusioni nella directory includes del tuo repository. Puoi poi riutilizzarli nel tuo 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 le inclusioni
Per creare un nuovo file JavaScript nella directory includes/, segui questi passaggi:
Nel riquadro File, accanto a
includes/, fai clic su Altro.Fai clic su Crea file.
Nel riquadro Crea nuovo file:
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.
Fai clic su Crea file.
Creare una costante JavaScript
Per creare una costante che puoi riutilizzare nel progetto:
Vai allo spazio di lavoro di sviluppo.
Nel riquadro File, espandi
includes/.Crea o seleziona un file JavaScript con 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 costante
- CONSTANT_VALUE: il valore della costante
(Facoltativo) Fai clic su Formato.
Il seguente esempio di codice definisce la costante PROJECT_ID nel
includes/constants.js file:
// 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
L'esempio di codice seguente mostra la query di definizione della tabella principale di 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 progetto:
Vai allo spazio di lavoro di sviluppo.
Nel riquadro File, espandi
includes/.Crea o seleziona un file JavaScript con estensione
.js.Nel file, scrivi la funzione JavaScript personalizzata.
Nel file, inserisci il seguente snippet di codice:
module.exports = { FUNCTION_NAME }Sostituisci
FUNCTION_NAMEcon il nome della funzione.(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 personalizzata renderScript in una query di definizione della tabella di Dataform di base:
config {
type: "table",
tags: ["advanced", "hourly"],
disabled: true
}
${functions.renderScript(ref("source_table"),
["country", "device_type"],
["revenue", "pageviews", "sessions"]
)}
L'esempio di codice seguente mostra la query di definizione della tabella di base 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'inclusione in un file SQLX
Puoi fare riferimento a qualsiasi funzione o costante include all'interno di un file SQLX. La sintassi per i riferimenti include dipende dalla posizione del file include.
Un file includes di primo livello si trova direttamente nella directory includes/.
Un file di inclusioni nidificato si trova in una sottodirectory di includes/.
Fare riferimento a un include di primo livello in un file SQLX
- Per fare riferimento a una funzione o una costante di inclusione di primo livello in una query di Dataform Core, inserisci il nome del file di definizione dell'inclusione senza l'estensione
.jsseguito 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 require di JavaScript e un blocco js {}.
Per fare riferimento a un include nidificato con la funzione JavaScript require:
Vai allo spazio 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 che vuoi importare
- SUBDIRECTORY_INCLUDE: il percorso
del file
includesnidificato
(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
per la 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 principale di Dataform
Per utilizzare una funzione di inclusione JavaScript con la funzione ref
di Dataform, devi passare ref come argomento della funzione di inclusione JavaScript
in 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 di Dataform di base 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 di Dataform open source di GitHub.
Per un esempio di utilizzo di un pacchetto open source in Dataform, consulta Utilizzare le dimensioni con variazioni lente in Dataform.
Per poter utilizzare i contenuti di un pacchetto in Dataform, devi installarlo nel tuo repository Dataform e poi importarlo nel singolo file JavaScript o SQLX in cui vuoi utilizzarlo. Per ulteriori informazioni, vedi Installare un pacchetto.
Per poter installare un pacchetto NPM privato in un repository Dataform, devi autenticare il pacchetto.
Creare flussi di lavoro esclusivamente con JavaScript
Questa sezione mostra come utilizzare JavaScript per creare azioni di flusso di lavoro in Dataform. Ti consigliamo di utilizzare JavaScript anziché Dataform Core per creare elementi simili ripetutamente nel flusso di lavoro.
In alternativa allo sviluppo di flussi di lavoro in SQLX o SQLX combinato con
JavaScript, puoi creare azioni di flusso di lavoro nei file .js utilizzando solo
JavaScript. Puoi creare più azioni di flusso di lavoro all'interno di un file JavaScript con metodi globali di 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 di flusso di lavoro utilizzando solo JavaScript in Dataform:
- Dichiarazioni delle origini dati
- Tabelle
- Affermazioni manuali
- Operazioni SQL personalizzate
Con JavaScript, puoi creare azioni simili più volte nel flusso di lavoro. Ad esempio, puoi creare una vista di ogni tabella del flusso di lavoro con determinati ID utente rimossi.
Il seguente codice JavaScript di esempio consente di creare una vista 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 in un unico file JavaScript con metodi globali di Dataform e codice JavaScript ES5 arbitrario, ad esempio loop e costanti.
Puoi definire le seguenti azioni con JavaScript in Dataform:
Creare un file JavaScript
Memorizza i file JavaScript per le definizioni e le dichiarazioni delle origini dati nella directorydefinitions/. Per creare un nuovo file JavaScript nella directory definitions/:
Nel riquadro File, accanto a
definitions/, fai clic su Altro.Fai clic su Crea file.
Nel riquadro Crea nuovo file:
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.
Fai clic su Crea file.
Impostare le proprietà dell'azione del flusso di lavoro con JavaScript
Puoi utilizzare i seguenti metodi globali di Dataform per creare azioni di flusso di lavoro SQL con Dataform:
declare. Utilizzato per dichiarare un'origine dati.publish. Utilizzato per definire una tabella.assert. Utilizzato per creare un'affermazione.operate. Utilizzato per definire un'operazione SQL personalizzata.
Ciascun metodo globale contiene proprietà che puoi utilizzare per configurare l'oggetto creato. Per ulteriori informazioni sui metodi globali e sulle relative proprietà, consulta il riferimento di Dataform.
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:
Nell'area di lavoro di sviluppo, espandi
definitions/nel riquadro File.Seleziona un file JavaScript.
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", });(Facoltativo) Fai clic su Formato.
Il seguente esempio di codice mostra come impostare le proprietà per il 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");
Includere riferimenti in un file JavaScript
Puoi fare riferimento a qualsiasi funzione, macro o costante di inclusione all'interno di un file JavaScript. Per ulteriori informazioni 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 alle inclusioni all'interno di un file JavaScript dipende dalla posizione del file di inclusione. Dataform memorizza questi file nella directory include.
Il livello superiore del riferimento include
- Per fare riferimento a un file di 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;
Include i riferimenti nidificati
Per fare riferimento a un file di inclusioni 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 di Dataform nei metodi JavaScript
Dataform fornisce una serie di funzioni integrate che puoi utilizzare
all'interno delle query, ad esempio ref e self. Per ulteriori informazioni sulle funzioni predefinite di Dataform, consulta il riferimento all'API Dataform.
Per utilizzare una funzione di query integrata in un metodo JavaScript:
Nell'area di lavoro di sviluppo, espandi
definitions/nel riquadro File.Seleziona un file JavaScript.
Nel file, inserisci un metodo JavaScript Dataform globale.
Nel metodo, inserisci un argomento
ctxcontestuale.(Facoltativo) Se utilizzi stringhe di modello JavaScript, racchiudi l'argomento contestuale tra barre graffe
``.Nell'argomento contestuale, inserisci la funzione di query con il relativo parametro come oggetto di contesto.
(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 flusso di lavoro con JavaScript
Puoi dichiarare più origini dati in un unico file di dichiarazione JavaScript con il metodo JavaScript declare di Dataform. Per ulteriori informazioni sul metodo declare, consulta la documentazione di riferimento di Dataform. Per ulteriori informazioni sulle origini dati in Dataform, consulta Dichiarare un'origine dati.
Per dichiarare un'origine dati in un file JavaScript:
Nell'area di lavoro di sviluppo, espandi
definitions/nel riquadro File.Seleziona un file JavaScript.
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 del progetto che contiene l'origine datiBIGQUERY_SCHEMA: il set di dati BigQuery in cui esiste la relazione esternaRELATION_NAME: il nome della relazione che potrai utilizzare in un secondo momento per fare riferimento all'origine dati in Dataform
Per dichiarare un'altra origine dati nello stesso file, aggiungi un altro blocco
declareal file.(Facoltativo) Fai clic su Formato.
Definire una tabella con JavaScript
Puoi creare una tabella con il metodo publish
JavaScript di Dataform. Per ulteriori informazioni sul metodo publish, consulta il riferimento di Dataform Core.
Puoi definire i seguenti tipi di tabelle:
- Tabella
- Tabella incrementale
- Visualizza
Per ulteriori informazioni sulla definizione delle tabelle in Dataform, consulta Creare una tabella.
Per definire una tabella in un file JavaScript:
Nell'area di lavoro di sviluppo, espandi
definitions/nel riquadro File.Seleziona un file JavaScript.
Nel file, inserisci il seguente snippet di codice:
publish("TABLE_NAME").query(ctx => "SELECT_QUERY");Sostituisci quanto segue:
TABLE_NAME: il nome della tabellaSELECT_QUERY: un'istruzione SELECT SQL che definisce la tabella
Per impostare il tipo di tabella, aggiungere le dipendenze della tabella e la descrizione della tabella, imposta le proprietà dell'oggetto del metodo
publish.Per definire un'altra tabella nello stesso file, ripeti i passaggi 3 e 4.
(Facoltativo) Fai clic su Formato.
Definire le asserzioni manuali con JavaScript
Puoi creare asserzioni SQL manuali in un file JavaScript con il metodo JavaScript Dataform assert. Per ulteriori informazioni sul metodo assert, consulta la documentazione di Dataform Core.
Una query SQL di asserzione manuale deve restituire zero righe. Se la query restituisce righe quando viene eseguita, l'asserzione non va a buon fine. Puoi creare più asserzioni in un file JavaScript.
Per ulteriori informazioni sulle asserzioni in Dataform, consulta Testare le tabelle con le asserzioni.
Per creare un'affermazione manuale in un file JavaScript:
Nell'area di lavoro di sviluppo, espandi
definitions/nel riquadro File.Seleziona un file JavaScript.
Nel file, inserisci il seguente snippet di codice:
assert("ASSERTION_NAME").query(ctx => "CUSTOM_ASSERTION_QUERY");Sostituisci quanto segue:
ASSERTION_NAME: il nome dell'affermazione personalizzataCUSTOM_ASSERTION_QUERY: la query di asserzione SQL
Per creare un'altra asserzione nello stesso file, ripeti il passaggio 3.
(Facoltativo) Fai clic su Formato.
Il seguente esempio di codice mostra un'affermazione JavaScript che verifica che nessun valore in source_table sia NULL:
assert("assertion1").query(ctx => "SELECT * FROM source_table WHERE value IS NULL");
Definire operazioni SQL personalizzate con JavaScript
Puoi definire operazioni SQL personalizzate in un file JavaScript con il metodo JavaScript Dataform.operate. Per ulteriori informazioni sulle operazioni SQL personalizzate in Dataform, consulta Aggiungere operazioni SQL personalizzate.
Per definire un'operazione SQL personalizzata con JavaScript:
Nell'area di lavoro di sviluppo, espandi
definitions/nel riquadro File.Seleziona un file JavaScript.
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 personalizzataCUSTOM_SQL_QUERY: la tua query SQL personalizzata
Per definire un'altra operazione SQL personalizzata nello stesso file, ripeti il passaggio 3.
(Facoltativo) Fai clic su Formato.
Il seguente esempio di codice mostra un'operazione SQL personalizzata in un file JavaScript che inserisce una singola 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
- Per scoprire come creare un pacchetto, consulta Creare un pacchetto.
- Per scoprire come installare un pacchetto, consulta Installare un pacchetto.
- Per scoprire come autenticare un pacchetto privato, consulta Autenticare un pacchetto privato.
- Per scoprire come utilizzare un pacchetto open source in Dataform, consulta Utilizzare le dimensioni che cambiano lentamente in Dataform.