Menggunakan kembali variabel dan fungsi dengan include dalam Dataform

Dokumen ini menunjukkan cara membuat penyertaan JavaScript untuk menggunakan kembali kode dalam Dataform.

Di folder includes/ repositori, Anda dapat menentukan yang mencakup JavaScript. Termasuk konstanta atau fungsi global yang dapat Anda gunakan kembali di seluruh repositori.

Sebelum memulai

Di konsol Google Cloud, buka halaman Dataform.

Buka Dataform
Pilih atau buat repositori Dataform.
Pilih atau buat Ruang kerja pengembangan dataform.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk menggunakan kembali kode 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 untuk disertakan dalam Dataform

Untuk membuat file JavaScript baru di direktori includes/, ikuti langkah-langkah berikut:

Di panel Files, di samping includes/, klik menu More.
Klik Create file.
Di panel Create new file, lakukan langkah berikut:
1. 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.
2. 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.
Dalam 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
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 Dataform core di atas 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 Anda, ikuti langkah-langkah berikut:

Buka ruang kerja pengembangan Anda.
Di panel Files, luaskan includes/.
Buat atau pilih file JavaScript dengan ekstensi .js.
Dalam file tersebut, tulis fungsi JavaScript kustom Anda.
Dalam 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, dalam file includes/functions.js, yang menghasilkan 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 di atas 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 penyertaan dalam file SQLX

Anda dapat mereferensikan setiap fungsi atau konstanta include dalam file SQLX. Sintaksis untuk penyertaan referensi bergantung pada lokasi file yang disertakan. File penyertaan tingkat atas terletak langsung di direktori includes/. File penyertaan bertingkat terletak di subdirektori includes/.

Mereferensikan penyertaan level teratas dalam file SQLX

Untuk mereferensikan fungsi atau konstanta penyertaan level 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 menyertakan referensi yang terletak di subdirektori definitions, impor menyertakan dengan 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 penyertaan JavaScript dengan fungsi inti Dataform `ref`

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 berdasarkan 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 mengetahui informasi selengkapnya tentang fungsi inti Dataform ref, lihat Ringkasan inti Dataform.

Langkah selanjutnya

Untuk mempelajari cara mereferensikan yang disertakan dalam file JavaScript, lihat Membuat alur kerja SQL dengan JavaScript.
Untuk mempelajari cara menggunakan kembali kode dengan dan memblokir serta inline JavaScript di dalam file inti Dataform, lihat Ringkasan inti Dataform.