Dataform core memungkinkan Anda membuat tindakan alur kerja dengan SQLX dan JavaScript. Meskipun opsional, menggunakan JavaScript bersama dengan SQLX untuk membuat elemen serupa berulang kali dalam alur kerja Anda. Misalnya, dengan JavaScript, Anda dapat membuat tampilan setiap tabel dalam alur kerja dengan ID pengguna tertentu dihapus. Anda juga dapat mengembangkan tindakan alur kerja secara eksklusif dengan JavaScript.
Sebelum memulai
Di konsol Google Cloud, buka halaman Dataform.
Pilih atau buat repositori.
Pilih atau buat ruang kerja pengembangan.
Selain itu, Anda harus memahami sintaksis JavaScript dan konsep JavaScript berikut:
- Variabel
- Array
- Pernyataan bersyarat
- Loop for
- Maps
- Functions
- Objek
- Mengekspor dan mengimpor modul
Peran yang diperlukan
Untuk mendapatkan izin yang diperlukan guna mengembangkan alur kerja dengan JavaScript dan menggunakan kembali kode dengan menyertakan 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 ke project, folder, dan organisasi.
Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.
Menambahkan kode JavaScript ke file SQLX
Anda dapat menambahkan kode JavaScript ke file SQLX dengan dua cara: inline atau di dalam blok JavaScript.
Anda dapat menggunakan blok JavaScript untuk menentukan fungsi atau konstanta dalam file SQLX. Anda dapat menggunakan JavaScript inline untuk mengubah kueri SQLX atau SQL secara dinamis.
Contoh kode berikut menunjukkan fungsi JavaScript bawaan self
Dataform yang ditambahkan secara inline ke blok post_operations
dalam 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"
}
Contoh kode berikut menunjukkan konstanta yang ditentukan dalam blok JavaScript dan digunakan secara inline di dalam kueri dalam file SQLX:
js {
const columnName = "foo";
}
SELECT 1 AS ${columnName} FROM "..."
Menggunakan kembali kode di seluruh satu file SQLX dengan enkapsulasi JavaScript
Anda dapat menggunakan kembali kode JavaScript untuk menyederhanakan pengembangan di Dataform. Untuk menggunakan kembali konstanta dan fungsi JavaScript di satu file SQLX, Anda dapat mengenkapsulasinya dalam blok JavaScript. Untuk menggunakan kembali kode JavaScript di satu repositori Dataform, Anda dapat membuat include. Untuk menggunakan kembali kode JavaScript di beberapa repositori Dataform, Anda dapat membuat atau mengimpor paket.
Untuk membuat bagian kode SQL berulang yang dapat Anda gunakan kembali dalam satu file SQLX, Anda dapat mengenkapsulasi fungsi dan konstanta dalam blok JavaScript. Anda dapat menggunakan kembali kode yang ditentukan dalam blok JavaScript hanya di dalam file SQLX tempat blok ditentukan. Untuk mengetahui informasi selengkapnya, lihat Dataform core.
Contoh kode berikut menunjukkan konstanta dan fungsi yang ditentukan dalam blok JavaScript dan digunakan secara inline di dalam kueri dalam file SQLX:
js {
const foo = 1;
function bar(number){
return number+1;
}
}
select
${foo} as one,
${bar(foo)} as two
Menggunakan kembali kode di seluruh repositori tunggal dengan menyertakan
Include adalah konstanta atau fungsi JavaScript yang bersifat global untuk repositori Anda.
Anda menentukan include di direktori includes
repositori Anda. Kemudian, Anda dapat
menggunakannya kembali di seluruh repositori dalam file JavaScript dan SQLX.
Contoh kode berikut menunjukkan definisi konstanta launch_date
dalam file includes/constants.js
:
// filename is includes/constants.js
const launch_date = "11.11.2011";
module.exports = { launch_date };
Contoh kode berikut menunjukkan konstanta launch_date
yang dirujuk dalam kueri
definisi tabel dalam file SQLX:
config {type: "table"}
SELECT * FROM source_table WHERE date > ${constants.launch_date}
Membuat file JavaScript untuk menyertakan
Untuk membuat file JavaScript baru di direktori includes/
, ikuti langkah-langkah berikut:
Di panel Files, di samping
includes/
, klik More.Klik Create file.
Di panel Create new file, lakukan hal berikut:
Di kolom Add a file path, setelah
includes/
, masukkan nama file diikuti dengan.js
. Contohnya,includes/constants.js
Nama file hanya boleh berisi angka, huruf, tanda hubung, dan garis bawah.
Klik Create file.
Membuat konstanta JavaScript
Untuk membuat konstanta yang dapat Anda gunakan kembali di seluruh project, ikuti langkah-langkah berikut:
Buka ruang kerja pengembangan Anda.
Di panel Files, luaskan
includes/
.Buat atau pilih file JavaScript dengan ekstensi
.js
.Di file tersebut, masukkan cuplikan kode berikut:
const CONSTANT_NAME = CONSTANT_VALUE; module.exports = { CONSTANT_NAME };
Ganti kode berikut:
- CONSTANT_NAME: nama konstanta Anda
- CONSTANT_VALUE: nilai konstanta Anda
Opsional: Klik Format.
Contoh kode berikut menentukan konstanta PROJECT_ID
dalam
file includes/constants.js
:
// filename is includes/constants.js
const PROJECT_ID = "my_project_name";
module.exports = { PROJECT_ID };
Contoh kode berikut mereferensikan konstanta PROJECT_ID
dalam kueri
definisi tabel dalam file SQLX:
config { type: "table" }
SELECT * FROM ${constants.PROJECT_ID}.my_schema_name.my_table_name
Contoh kode berikut menunjukkan kueri definisi tabel inti Dataform sebelumnya yang dikompilasi ke dalam SQL:
SELECT * FROM my_project_name.my_schema_name.my_table_name
Membuat fungsi JavaScript kustom
Untuk membuat fungsi JavaScript kustom yang dapat digunakan kembali di seluruh project, ikuti langkah-langkah berikut:
Buka ruang kerja pengembangan Anda.
Di panel Files, luaskan
includes/
.Buat atau pilih file JavaScript dengan ekstensi
.js
.Dalam file, tulis fungsi JavaScript kustom Anda.
Di file tersebut, masukkan cuplikan kode berikut:
module.exports = { FUNCTION_NAME }
Ganti
FUNCTION_NAME
dengan nama fungsi Anda.Opsional: Klik Format.
Contoh kode berikut menunjukkan fungsi JavaScript kustom yang disebut
renderScript
dan disimpan dalam file includes/functions.js
. Fungsi ini
membuat skrip 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 };
Contoh kode berikut menunjukkan penggunaan fungsi JavaScript renderScript
kustom dalam kueri definisi tabel inti Dataform:
config {
type: "table",
tags: ["advanced", "hourly"],
disabled: true
}
${functions.renderScript(ref("source_table"),
["country", "device_type"],
["revenue", "pageviews", "sessions"]
)}
Contoh kode berikut menunjukkan kueri definisi tabel inti Dataform sebelumnya yang dikompilasi ke dalam 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
Mereferensikan include dalam file SQLX
Anda dapat mereferensikan fungsi atau konstanta penyertaan apa pun di dalam file SQLX. Sintaksis
untuk mereferensikan include bergantung pada lokasi file include.
File include tingkat atas terletak langsung di direktori includes/
.
File include bertingkat terletak di subdirektori includes/
.
Mereferensikan penyertaan tingkat teratas dalam file SQLX
- Untuk mereferensikan fungsi atau konstanta penyertaan tingkat atas dalam
kueri inti Dataform, masukkan nama file definisi penyertaan tanpa
ekstensi
.js
, diikuti dengan nama objek yang diekspor.
Contoh kode berikut mereferensikan konstanta firstDate
, yang ditentukan dalam
file includes/constants.js
, dalam file SQLX definisi tabel:
config {type: "table"}
select * from source_table where date > ${constants.firstDate}
Mereferensikan penyertaan bertingkat dalam file SQLX
Untuk mereferensikan include yang terletak di subdirektori definitions
, impor
include menggunakan fungsi require
JavaScript dan blok js {}
.
Untuk mereferensikan penyertaan bertingkat dengan fungsi JavaScript require
, ikuti langkah-langkah berikut:
Buka ruang kerja pengembangan Anda.
Di panel Files, luaskan
definitions/
.Pilih file SQLX.
Di blok
config
, masukkan cuplikan kode berikut:js { var { VARIABLE_NAME } = require("SUBDIRECTORY_INCLUDE"); }
Ganti kode berikut:
- VARIABLE_NAME: nama konstanta atau fungsi yang ingin Anda impor
- SUBDIRECTORY_INCLUDE: jalur
file
includes
bertingkat
Opsional: Klik Format.
Contoh kode berikut mereferensikan konstanta firstDate
, yang ditentukan dalam
file includes/allConstants/constants.js
bertingkat, dalam file SQLX
definisi tabel:
config {type: "table"}
js {
var { firstDate } = require("includes/allConstants/constants");
}
select * from source_table where date > ${firstDate}
Menggunakan fungsi include JavaScript dengan fungsi ref
inti Dataform
Untuk menggunakan fungsi include JavaScript dengan fungsi ref
inti Dataform, Anda harus meneruskan ref
sebagai argumen fungsi include
JavaScript di dalam file SQLX.
Contoh kode berikut menunjukkan file includes/script_builder.js
dengan
fungsi JavaScript renderScript
yang menggabungkan metrik menggunakan SUM
dan mengelompokkan metrik menurut dimensi:
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 };
Contoh kode berikut menunjukkan fungsi JavaScript renderScript
yang digunakan dalam
file definitions/stats_per_country_and_device.sqlx
dengan
fungsi ref
inti Dataform yang diteruskan sebagai argumen:
${script_builder.renderScript(
ref("source_table"),
["country", "device_type"],
["revenue", "pageviews", "sessions"])}
Contoh kode berikut menunjukkan
kueri definitions/stats_per_country_and_device.sqlx
yang dikompilasi ke 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
Untuk informasi selengkapnya tentang fungsi ref
inti Dataform, lihat
inti Dataform.
Menggunakan kembali kode di beberapa repositori dengan paket
Paket adalah kumpulan kode JavaScript yang dapat Anda impor dan gunakan di beberapa repositori Dataform untuk menyederhanakan pengembangan alur kerja.
Anda dapat membuat paket kustom Anda sendiri di Dataform atau menggunakan salah satu paket Dataform open source, yang tersedia di halaman Dataform open source GitHub.
Untuk contoh penggunaan paket open source di Dataform, lihat Menggunakan dimensi yang berubah secara perlahan di Dataform.
Agar dapat menggunakan konten paket di Dataform, Anda harus menginstal paket di repositori Dataform, lalu mengimpornya ke setiap file JavaScript atau SQLX tempat Anda ingin menggunakan paket. Untuk mengetahui informasi selengkapnya, lihat Menginstal paket.
Agar dapat menginstal paket NPM pribadi di repositori Dataform, Anda harus melakukan autentikasi paket.
Membuat alur kerja secara eksklusif dengan JavaScript
Bagian ini menunjukkan cara menggunakan JavaScript untuk membuat tindakan alur kerja di Dataform. Anda mungkin ingin menggunakan JavaScript, bukan inti Dataform, untuk membuat elemen serupa berulang kali dalam alur kerja Anda.
Sebagai alternatif untuk mengembangkan alur kerja di SQLX, atau SQLX yang digabungkan dengan
JavaScript, Anda dapat membuat tindakan alur kerja dalam file .js
hanya dengan menggunakan
JavaScript. Anda dapat membuat beberapa tindakan alur kerja dalam satu file JavaScript
dengan metode global Dataform dan kode JavaScript ES5 arbitrer,
seperti loop dan konstanta. Setiap metode JavaScript global Dataform
berisi properti yang dapat Anda gunakan untuk mengonfigurasi objek yang dibuat.
Anda dapat membuat tindakan alur kerja berikut hanya dengan menggunakan JavaScript di Dataform:
- Pernyataan sumber data
- Tabel
- Pernyataan manual
- Operasi SQL kustom
Dengan JavaScript, Anda dapat membuat tindakan serupa berulang kali dalam alur kerja. Misalnya, Anda dapat membuat tampilan setiap tabel dalam alur kerja dengan ID pengguna tertentu dihapus.
Contoh kode JavaScript berikut memungkinkan Anda membuat tampilan setiap tabel dengan
nilai kolom user_id
yang 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 bernama
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:
Membuat file JavaScript
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 More.Klik Create file.
Di panel Create new file, lakukan hal berikut:
Di kolom Add a file path, setelah
definitions/
, masukkan nama file diikuti dengan.js
. Contoh,definitions/definitions.js
.Nama file hanya boleh berisi angka, huruf, tanda hubung, dan garis bawah.
Klik Create file.
Menetapkan properti tindakan alur kerja dengan JavaScript
Anda dapat menggunakan metode global Dataform berikut untuk membuat tindakan 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 Dataform.
Dalam metode publish()
yang membuat tabel, Anda dapat menetapkan properti tabel
dengan meneruskannya sebagai argumen metode kedua.
Untuk meneruskan properti tabel sebagai argumen kedua publish()
, ikuti langkah-langkah berikut:
Di ruang kerja pengembangan, di panel Files, luaskan
definitions/
.Pilih file JavaScript.
Dalam file, 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 metode:
publish("table1", {
type: "table",
dependencies: ["other_table"],
description: {
"Value is 1"
}
}).query(ctx => "SELECT 1 AS test");
Referensi yang disertakan dalam file JavaScript
Anda dapat mereferensikan fungsi, makro, atau konstanta yang disertakan di dalam file JavaScript. Untuk mengetahui informasi selengkapnya tentang include di Dataform, lihat bagian Menggunakan kembali kode di satu repositori dengan include dalam dokumen ini.
Sintaksis untuk mereferensikan include di dalam file JavaScript bergantung pada lokasi file include. Dataform menyimpan file tersebut di direktori include.
Referensi tingkat teratas mencakup
- Untuk mereferensikan file yang disertakan tingkat atas, referensikan nama file saat mendeklarasikan variabel.
Contoh kode berikut mereferensikan 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 require JavaScript.
Contoh kode berikut mereferensikan 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 informasi selengkapnya tentang
fungsi bawaan Dataform, lihat
referensi API Dataform.
Untuk menggunakan fungsi kueri bawaan dalam metode JavaScript, ikuti langkah-langkah berikut:
Di ruang kerja pengembangan, di panel Files, luaskan
definitions/
.Pilih file JavaScript.
Dalam file, masukkan metode JavaScript Dataform global.
Dalam metode, masukkan argumen
ctx
yang dapat dikontekstualisasikan.Opsional: Jika Anda menggunakan string template JavaScript, gabungkan argumen yang dapat dikontekstualisasikan dalam tanda petik terbalik
``
.Dalam argumen yang dapat dikontekstualisasikan, 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 dikontekstualisasikan dari metode publikasi:
publish("example").query(ctx => `SELECT * FROM ${ctx.ref("other_table")}`);
Mendeklarasikan sumber data alur kerja dengan JavaScript
Anda dapat mendeklarasikan beberapa sumber data dalam satu file deklarasi JavaScript dengan metode JavaScript deklarasi Dataform. Untuk informasi selengkapnya tentang metode deklarasi, lihat Referensi inti Dataform. Untuk informasi selengkapnya tentang sumber data di Dataform, lihat Mendeklarasikan sumber data.
Untuk mendeklarasikan sumber data dalam file JavaScript, ikuti langkah-langkah berikut:
Di ruang kerja pengembangan, di panel Files, luaskan
definitions/
.Pilih file JavaScript.
Di 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 project yang berisi sumber dataBIGQUERY_SCHEMA
: set data BigQuery tempat adanya hubungan eksternalRELATION_NAME
: nama hubungan yang nantinya dapat Anda gunakan untuk mereferensikan sumber data di Dataform
Untuk mendeklarasikan sumber data lain dalam file yang sama, tambahkan blok
declare
tambahan ke file.Opsional: Klik Format.
Menentukan tabel dengan JavaScript
Anda dapat membuat tabel dengan metode publish
JavaScript Dataform. Untuk informasi selengkapnya tentang metode publikasi, lihat
referensi inti Dataform.
Anda dapat menentukan jenis tabel berikut:
- Tabel
- Tabel inkremental
- Lihat
Untuk informasi selengkapnya tentang cara menentukan tabel di Dataform, lihat Membuat tabel.
Untuk menentukan tabel dalam file JavaScript, ikuti langkah-langkah berikut:
Di ruang kerja pengembangan, di panel Files, luaskan
definitions/
.Pilih file JavaScript.
Di file tersebut, masukkan cuplikan kode berikut:
publish("TABLE_NAME").query(ctx => "SELECT_QUERY");
Ganti kode berikut:
TABLE_NAME
: nama tabelSELECT_QUERY
: pernyataan SELECT SQL 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 manual dengan JavaScript
Anda dapat membuat pernyataan SQL manual dalam file JavaScript dengan metode JavaScript pernyataan Dataform. Untuk informasi selengkapnya tentang metode pernyataan, lihat referensi inti Dataform.
Kueri SQL pernyataan manual harus menampilkan nol baris. Jika kueri menampilkan baris saat dijalankan, pernyataan akan gagal. Anda dapat membuat beberapa pernyataan dalam satu file JavaScript.
Untuk informasi selengkapnya tentang pernyataan di Dataform, lihat Menguji tabel dengan pernyataan.
Untuk membuat pernyataan manual dalam file JavaScript, ikuti langkah-langkah berikut:
Di ruang kerja pengembangan, di panel Files, luaskan
definitions/
.Pilih file JavaScript.
Di file tersebut, masukkan cuplikan kode berikut:
assert("ASSERTION_NAME").query(ctx => "CUSTOM_ASSERTION_QUERY");
Ganti kode berikut:
ASSERTION_NAME
: nama untuk pernyataan kustom AndaCUSTOM_ASSERTION_QUERY
: 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 dalam 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 operasi Dataform. Untuk mengetahui 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, di panel Files, luaskan
definitions/
.Pilih file JavaScript.
Di file tersebut, masukkan cuplikan kode berikut:
operate("OPERATION_NAME").queries(ctx => "CUSTOM_SQL_QUERY");
Ganti kode berikut:
OPERATION_NAME
: nama untuk operasi kustomCUSTOM_SQL_QUERY
: 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
dari baris baru
ke 2
:
operate("operation1").queries("INSERT INTO some_table (test_column) VALUES (2)");
Langkah berikutnya
- Untuk mempelajari cara membuat paket, lihat Membuat paket.
- Untuk mempelajari cara menginstal paket, lihat Menginstal paket.
- Untuk mempelajari cara mengautentikasi paket pribadi, lihat Mengautentikasi paket pribadi.
- Untuk mempelajari cara menggunakan paket open source di Dataform, lihat Menggunakan dimensi yang berubah secara perlahan di Dataform.