Creare flussi di lavoro SQL Dataform con JavaScript

Questo documento mostra come utilizzare JavaScript per creare elementi di flusso di lavoro SQL in Dataform. Potresti voler usare JavaScript anziché il core Dataform per creare ripetutamente elementi simili nel flusso di lavoro.

Informazioni sullo sviluppo di flussi di lavoro in Dataform con JavaScript

Dataform Core consente crei azioni del flusso di lavoro SQL con SQLX e JavaScript. Con JavaScript, puoi creare azioni simili ripetutamente nel tuo flusso di lavoro. Ad esempio, puoi creare una visualizzazione di ogni tabella nel 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 nel 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, come come loop e costanti.

Puoi definire le seguenti azioni con JavaScript in Dataform:

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'area di lavoro di sviluppo.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per sviluppare un flusso di lavoro SQL con JavaScript, chiedi all'amministratore di concederti Ruolo IAM dell'editor Dataform (roles/dataform.editor) nelle aree di lavoro. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

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

Creare un file JavaScript in Dataform

Archivia i file JavaScript per le definizioni e le dichiarazioni dell'origine dati nel Directory definitions/. Per creare un nuovo file JavaScript in definitions/ seguire questi passaggi:

  1. Nel riquadro File, accanto a definitions/, fai clic sull'icona Menu Altro.

  2. Fai clic su Crea file.

  3. Nel riquadro Crea nuovo file, segui questi passaggi:

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

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

    2. Fai clic su Crea file.

Imposta le proprietà dell'oggetto del flusso di lavoro SQL Dataform con JavaScript

Puoi utilizzare i seguenti metodi globali Dataform per creare file SQL oggetti flusso di lavoro 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 creato. Per ulteriori informazioni sui metodi globali e sulle loro proprietà, vedi il riferimento principale di Dataform.

Nel metodo publish() che crea una tabella, puoi impostare le proprietà della tabella passandoli 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, espandi definitions/ nel riquadro File.

  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à per il metodo publish() passando le proprietà come secondo argomento del metodo:

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

Il riferimento include in un file JavaScript

Puoi fare riferimento a qualsiasi funzione, macro o costante include all'interno di un file JavaScript . Per ulteriori informazioni sulle inclusioni in Dataform, consulta Riutilizzare variabili e funzioni con JavaScript.

La sintassi per i riferimenti include l'interno di un file JavaScript dipende dalla percorso del file di inclusione. Dataform archivia questi file include la directory.

I riferimenti di primo livello includono

  • Per fare riferimento a un file include di primo livello, fai riferimento al nome file quando con la dichiarazione delle variabili.

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

  const {serviceName, serviceId} = service;

Inclusioni nidificate di riferimento

Per fare riferimento a un file Includi nidificato, inserisci il nome del file nel campo JavaScript richiedono una funzione.

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

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

Utilizzare le funzioni di query Dataform nei metodi JavaScript

Dataform offre una serie di funzioni integrate che puoi utilizzare all'interno delle query, ad esempio ref e self. Per ulteriori informazioni per le funzioni integrate di Dataform, Riferimento per l'API Dataform.

Per utilizzare una funzione di query integrata in un metodo JavaScript, segui questi passaggi:

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

  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 di modello JavaScript, aggrega la classe argomento contestuale nei apici inversi ``.

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

  7. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra la funzione di query ref inserita all'interno di un argomento contestuale del metodo publish:

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

Dichiara un'origine dati del flusso di lavoro SQL con JavaScript

Puoi dichiarare più origini dati in un file di dichiarazione JavaScript con il metodo di dichiarazione JavaScript Dataform. Per ulteriori informazioni il metodo dichiara, consulta il riferimento principale di Dataform. Per ulteriori informazioni 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 definizioni/.

  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 del progetto che contiene l'origine dati
    • BIGQUERY_SCHEMA: il set di dati BigQuery in cui relazione esterna esistente
    • RELATION_NAME: il nome della relazione che potrai utilizzare in seguito per fare riferimento all'origine dati in Dataform

  4. Per dichiarare un'altra origine dati nello stesso file, aggiungi un extra declare bloccare il file.

  5. (Facoltativo) Fai clic su Formato.

Definisci una tabella con JavaScript

Puoi creare una tabella con l'publish di Dataform JavaScript . Per ulteriori informazioni sul metodo di pubblicazione, consulta Riferimento principale per Dataform.

Puoi definire i seguenti tipi di tabella: tabella, tabella incrementale e vista. Per saperne di più sulla definizione delle tabelle in Dataform, consulta Crea una tabella.

Per definire una tabella in un file JavaScript:

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

  2. Seleziona un file JavaScript.

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

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

    1. Sostituisci TABLE_NAME con il nome della tabella.

    2. Sostituisci SELECT_QUERY con un'istruzione SQL SELECT la definizione della tabella.

  4. Per impostare il tipo di tabella, aggiungere le dipendenze della tabella e aggiungere 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 Dataform manuali con JavaScript

Puoi creare asserzioni SQL manuali in un file JavaScript con il Metodo JavaScript per l'asserzione di Dataform. Per ulteriori informazioni sul Assertion, consulta il riferimento principale di Dataform.

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 una file JavaScript.

Per ulteriori informazioni sulle asserzioni in Dataform, consulta Testare tabelle con asserzioni.

Per creare un'asserzione manuale in un file JavaScript, segui questi passaggi:

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

  2. Seleziona un file JavaScript.

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

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

    1. Sostituisci ASSERTION_NAME con il nome della tua personalizzata l'asserzione.

    2. Sostituisci CUSTOM_ASSERTION_QUERY con il tuo SQL asserzione.

  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 asserisce che non il 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 Dataform esegue il metodo JavaScript. Per ulteriori informazioni le operazioni SQL personalizzate in Dataform, vedi Aggiungi operazioni SQL personalizzate.

Per definire un'operazione SQL personalizzata con JavaScript:

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

  2. Seleziona un file JavaScript.

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

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

    1. Sostituisci OPERATION_NAME con il nome della personalizzazione operativa.

    2. Sostituisci CUSTOM_SQL_QUERY con la tua 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 singola nuova riga in some_table e imposta test_column della nuova riga a 2:

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

Passaggi successivi