Membuat alur kerja Dataform SQL dengan JavaScript

Dokumen ini menunjukkan cara menggunakan JavaScript untuk membuat elemen alur kerja SQL dalam Dataform. Anda dapat menggunakan JavaScript daripada Dataform core untuk membuat elemen serupa berulang kali dalam alur kerja Anda.

Tentang mengembangkan alur kerja di Dataform dengan JavaScript

Dataform core memungkinkan Anda membuat tindakan alur kerja SQL dengan SQLX dan JavaScript. Dengan JavaScript, Anda dapat membuat tindakan serupa berulang kali dalam alur kerja. Misalnya, Anda dapat membuat tampilan setiap tabel dalam alur kerja Anda dengan menghapus ID pengguna tertentu.

Contoh kode JavaScript berikut memungkinkan Anda membuat tampilan setiap tabel dengan nilai kolom user_id tidak sesuai dengan salah satu nilai dalam daftar 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")}
        )`
    );
  });

Contoh kode ini membuat tiga tampilan dengan nama user_events_blocked_removed, user_settings_blocked_removed, dan user_logs_blocked_removed yang tidak berisi ID pengguna yang diblokir.

Anda dapat membuat beberapa tindakan dalam satu file JavaScript dengan metode global Dataform dan kode JavaScript ES5 arbitrer, seperti loop dan konstanta.

Anda dapat menentukan tindakan berikut dengan JavaScript di Dataform:

Tables
Deklarasi sumber data
Pernyataan
Operasi SQL kustom

Sebelum memulai

Di konsol Google Cloud, buka halaman Dataform.

Buka Dataform
Pilih atau buat repositori.
Pilih atau buat ruang kerja pengembangan.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk mengembangkan alur kerja SQL dengan JavaScript, minta administrator untuk memberi Anda peran IAM Dataform Editor (roles/dataform.editor) di ruang kerja. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Membuat file JavaScript di Dataform

Simpan file JavaScript untuk definisi dan deklarasi sumber data di direktori definitions/. Untuk membuat file JavaScript baru di direktori definitions/, ikuti langkah-langkah berikut:

Di panel Files, di samping definitions/, klik menu More.
Klik Create file.
Di panel Create new file, lakukan langkah berikut:
1. Di kolom Add a file path, setelah definitions/, masukkan nama file, diikuti dengan .js. Contoh, definitions/definitions.js.
  
  Nama file hanya dapat berisi angka, huruf, tanda hubung, dan garis bawah.
2. Klik Create file.

Menetapkan properti objek alur kerja Dataform SQL dengan JavaScript

Anda dapat menggunakan metode global Dataform berikut untuk membuat objek alur kerja SQL dengan Dataform:

declare. Digunakan untuk mendeklarasikan sumber data.
publish. Digunakan untuk menentukan tabel.
assert. Digunakan untuk membuat pernyataan.
operate. Digunakan untuk menentukan operasi SQL kustom.

Setiap metode global berisi properti yang dapat Anda gunakan untuk mengonfigurasi objek yang dibuat. Untuk informasi selengkapnya tentang metode global dan propertinya, lihat Referensi inti Formulir data.

Dalam metode publish() yang membuat tabel, Anda dapat menetapkan properti tabel dengan meneruskannya sebagai argumen metode kedua.

Untuk meneruskan properti tabel sebagai argumen kedua dari publish(), ikuti langkah-langkah berikut:

Di ruang kerja pengembangan Anda, di panel Files, luaskan definitions/.
Pilih file JavaScript.

Dalam file ini, tambahkan properti tabel ke metode publish() dalam format berikut:

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

Opsional: Klik Format.

Contoh kode berikut menunjukkan cara menetapkan properti ke metode publish() dengan meneruskan properti sebagai argumen kedua dari metode tersebut:

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

Referensi disertakan dalam file JavaScript

Anda dapat mereferensikan fungsi penyertaan, makro, atau konstanta apa pun di dalam file JavaScript. Untuk mengetahui informasi selengkapnya tentang penyertaan dalam Dataform, lihat artikel Menggunakan kembali variabel dan fungsi dengan JavaScript yang disertakan.

Sintaksis untuk referensi mencakup di dalam file JavaScript bergantung pada lokasi file penyertaan. Dataform menyimpan file tersebut di direktori termasuk.

Referensi level atas mencakup

Untuk mereferensikan file penyertaan tingkat atas, referensikan nama file saat mendeklarasikan variabel.

Contoh kode berikut merujuk ke variabel serviceName dan serviceId dari file includes/service.js:

  const {serviceName, serviceId} = service;

Referensi bertingkat mencakup

Untuk mereferensikan file include bertingkat, masukkan nama file dalam fungsi yang memerlukan JavaScript.

Contoh kode berikut merujuk ke variabel serviceName dan serviceId dari file includes/allServices/service.js:

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

Menggunakan fungsi kueri Dataform dalam metode JavaScript

Dataform menyediakan sejumlah fungsi bawaan yang dapat Anda gunakan di dalam kueri, seperti ref dan self. Untuk mengetahui informasi selengkapnya tentang fungsi bawaan Dataform, lihat Referensi Dataform API.

Untuk menggunakan fungsi kueri bawaan di metode JavaScript, ikuti langkah-langkah berikut:

Di ruang kerja pengembangan Anda, di panel Files, luaskan definitions/.
Pilih file JavaScript.
Dalam file, masukkan metode JavaScript Dataform global.
Dalam metode ini, masukkan argumen ctx yang dapat dikonteks.
Opsional: Jika Anda menggunakan string template JavaScript, gabungkan argumen yang dapat dikonteks dengan menggunakan tanda kutip terbalik ``.
Dalam argumen yang dapat dikonteks, masukkan fungsi kueri dengan parameternya sebagai objek konteks.
Opsional: Klik Format.

Contoh kode berikut menunjukkan fungsi kueri ref yang digabungkan di dalam argumen yang dapat kontekstual dari metode publikasi:

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

Mendeklarasikan sumber data alur kerja SQL dengan JavaScript

Anda dapat mendeklarasikan beberapa sumber data dalam satu file deklarasi JavaScript dengan metode JavaScript Dataform. Untuk mengetahui informasi selengkapnya tentang metode deklarasi, lihat Referensi inti Formulir data. Untuk mengetahui informasi selengkapnya tentang sumber data dalam Formulir data, lihat Mendeklarasikan sumber data.

Untuk mendeklarasikan sumber data di file JavaScript, ikuti langkah-langkah berikut:

Di ruang kerja pengembangan Anda, di panel Files, luaskan definisi/.
Pilih file JavaScript.
Dalam file tersebut, masukkan cuplikan kode berikut:
```
 declare({
   database: "DATABASE_PROJECT_ID",
   schema: "BIGQUERY_SCHEMA",
   name: "RELATION_NAME",
 });
```
Ganti kode berikut:
- DATABASE_PROJECT_ID: project ID untuk project yang berisi sumber data
- BIGQUERY_SCHEMA: set data BigQuery tempat adanya relasi eksternal
- RELATION_NAME: nama relasi yang nantinya dapat Anda gunakan untuk mereferensikan sumber data dalam Dataform
Untuk mendeklarasikan sumber data lain dalam file yang sama, tambahkan blok declare tambahan ke file tersebut.
Opsional: Klik Format.

Menentukan tabel dengan JavaScript

Anda dapat membuat tabel dengan metode publish Dataform JavaScript. Untuk informasi selengkapnya tentang metode publikasi, lihat Referensi inti formulir data.

Anda dapat menentukan jenis tabel berikut: tabel, tabel inkremental, dan tampilan. Untuk mengetahui informasi selengkapnya tentang cara menentukan tabel di Dataform, lihat Membuat tabel.

Untuk menentukan tabel di file JavaScript, ikuti langkah-langkah berikut:

Di ruang kerja pengembangan Anda, di panel Files, luaskan definitions/.
Pilih file JavaScript.
Dalam file tersebut, masukkan cuplikan kode berikut:
```
 publish("TABLE_NAME").query(ctx => "SELECT_QUERY");
```
1. Ganti TABLE_NAME dengan nama tabel.
2. Ganti SELECT_QUERY dengan pernyataan SQL SELECT yang menentukan tabel.
Untuk menetapkan jenis tabel, menambahkan dependensi tabel, dan menambahkan deskripsi tabel, tetapkan properti objek dari metode publish.
Untuk menentukan tabel lain dalam file yang sama, ulangi langkah 3 dan langkah 4.
Opsional: Klik Format.

Menentukan pernyataan Dataform manual dengan JavaScript

Anda dapat membuat pernyataan SQL manual dalam file JavaScript dengan metode JavaScript pernyataan bentuk data. Untuk informasi selengkapnya tentang metode pernyataan, lihat Referensi inti Formulir data.

Kueri SQL pernyataan manual harus menampilkan nol baris. Jika kueri menampilkan baris saat dieksekusi, pernyataan akan gagal. Anda dapat membuat beberapa pernyataan dalam satu file JavaScript.

Untuk mengetahui informasi selengkapnya tentang pernyataan dalam Dataform, lihat Menguji tabel dengan pernyataan.

Untuk membuat pernyataan manual di file JavaScript, ikuti langkah-langkah berikut:

Di ruang kerja pengembangan Anda, di panel Files, luaskan definitions/.
Pilih file JavaScript.
Dalam file tersebut, masukkan cuplikan kode berikut:
```
 assert("<var>ASSERTION_NAME</var>").query(ctx => "<var>CUSTOM_ASSERTION_QUERY</var>");
```
1. Ganti ASSERTION_NAME dengan nama untuk pernyataan kustom Anda.
2. Ganti CUSTOM_ASSERTION_QUERY dengan kueri pernyataan SQL Anda.
Untuk membuat pernyataan lain dalam file yang sama, ulangi langkah 3.
Opsional: Klik Format.

Contoh kode berikut menunjukkan pernyataan JavaScript yang menyatakan bahwa tidak ada nilai di source_table yang merupakan NULL:

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

Menentukan operasi SQL kustom dengan JavaScript

Anda dapat menentukan operasi SQL kustom dalam file JavaScript dengan metode JavaScript mengoperasikan Dataform. Untuk informasi selengkapnya tentang operasi SQL kustom di Dataform, lihat Menambahkan operasi SQL kustom.

Untuk menentukan operasi SQL kustom dengan JavaScript, ikuti langkah-langkah berikut:

Di ruang kerja pengembangan Anda, di panel Files, luaskan definitions/.
Pilih file JavaScript.
Dalam file tersebut, masukkan cuplikan kode berikut:
```
 operate("OPERATION_NAME").queries(ctx => "CUSTOM_SQL_QUERY");
```
1. Ganti OPERATION_NAME dengan nama operasi kustom.
2. Ganti CUSTOM_SQL_QUERY dengan kueri SQL kustom Anda.
Untuk menentukan operasi SQL kustom lainnya dalam file yang sama, ulangi langkah 3.
Opsional: Klik Format.

Contoh kode berikut menunjukkan operasi SQL kustom dalam file JavaScript yang menyisipkan satu baris baru ke dalam some_table dan menetapkan test_column baris baru ke 2:

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

Langkah selanjutnya

Untuk mempelajari lebih lanjut metode JavaScript Dataform dan fungsi kueri bawaan, lihat Referensi inti Dataform.
Untuk mempelajari lebih lanjut pengembangan di Dataform dengan JavaScript, lihat Pengantar JavaScript di Dataform.