Mengonfigurasi setelan alur kerja Dataform

Halaman ini menunjukkan cara mengedit setelan pemrosesan alur kerja SQL Dataform untuk repositori tertentu.

Anda mungkin ingin mengedit file setelan untuk mengganti nama skema atau menambahkan variabel kompilasi kustom ke repositori Anda.

Tentang setelan repositori

Setiap repositori Dataform berisi file setelan alur kerja yang unik. File ini berisi ID project Google Cloud dan skema tempat Dataform memublikasikan aset di BigQuery. Dataform menggunakan setelan default yang dapat Anda ganti agar sesuai dengan kebutuhan Anda dengan mengedit file setelan.

Mulai Dataform core 3.0.0, setelan alur kerja disimpan di file workflow_settings.yaml secara default. Pada versi inti Dataform sebelumnya, setelan alur kerja disimpan dalam file dataform.json. File workflow_settings.yaml inti Dataform 3.0 kompatibel dengan dataform.json. Anda dapat terus menggunakan dataform.json untuk menyimpan setelan alur kerja. Sebagai praktik terbaik, Anda harus memigrasikan setelan alur kerja repositori ke format workflow_settings.yaml untuk kompatibilitas di masa mendatang.

Tentang workflow_settings.yaml

File workflow_settings.yaml, yang diperkenalkan di Dataform core 3.0, menyimpan setelan alur kerja Dataform dalam format YAML.

Contoh kode berikut menunjukkan contoh file workflow_settings.yaml:

  defaultProject: my-gcp-project-id
  defaultDataset: dataform
  defaultLocation: australia-southeast2
  defaultAssertionDataset: dataform_assertions

Dalam contoh kode sebelumnya, pasangan nilai kunci dijelaskan sebagai berikut:

  • defaultProject: Project ID Google Cloud BigQuery Anda.
  • defaultDataset: Set data BigQuery tempat Dataform membuat aset, yang disebut dataform secara default.
  • defaultLocation: Region set data BigQuery default Anda. Untuk mengetahui informasi selengkapnya tentang lokasi set data BigQuery, lihat Lokasi set data Di lokasi ini, Dataform memproses kode Anda dan menyimpan data yang dieksekusi. Region pemrosesan ini harus cocok dengan lokasi set data BigQuery Anda, tetapi tidak perlu cocok dengan region repositori Dataform.
  • defaultAssertionDataset: Set data BigQuery tempat Dataform membuat tampilan dengan hasil pernyataan, yang disebut dataform_assertions secara default.

Untuk mengetahui informasi selengkapnya tentang properti workflow_settings.yaml, lihat referensi konfigurasi untuk setelan alur kerja di GitHub.

Anda dapat mengakses properti yang ditentukan di workflow_settings.yaml dalam kode Dataform sebagai properti objek dataform.projectConfig.

Pemetaan berikut dari opsi workflow_settings.yaml ke opsi dataform.projectConfig yang dapat diakses kode berlaku:

  • defaultProject => defaultDatabase.
  • defaultDataset => defaultSchema.
  • defaultAssertionDataset => assertionSchema.
  • projectSuffix => databaseSuffix.
  • datasetSuffix => schemaSuffix.
  • namePrefix => tablePrefix.

Contoh kode berikut menunjukkan objek dataform.projectConfig yang dirujuk dalam pernyataan SELECT dalam tampilan:

  config { type: "view" }
  SELECT ${when(
    !dataform.projectConfig.tablePrefix,
    "table prefix is set!",
    "table prefix is not set!"
  )}

Tentang dataform.json

File dataform.json menyimpan setelan alur kerja Dataform dalam format JSON.

Contoh kode berikut menunjukkan contoh file dataform.json:

  {
    "warehouse": "bigquery",
    "defaultDatabase": "my-gcp-project-id",
    "defaultSchema": "dataform",
    "defaultLocation": "australia-southeast2",
    "assertionSchema": "dataform_assertions"
  }

Dalam contoh kode sebelumnya, pasangan nilai kunci dijelaskan sebagai berikut:

  • warehouse: Pointer ke BigQuery, tempat Dataform membuat aset.
  • defaultDatabase: Project ID Google Cloud BigQuery Anda.
  • defaultSchema: Set data BigQuery tempat Dataform membuat aset.
  • defaultLocation: Region set data BigQuery default Anda. Untuk mengetahui informasi selengkapnya tentang lokasi set data BigQuery, lihat Lokasi set data. Di lokasi ini, Dataform memproses kode Anda dan menyimpan data yang dieksekusi. Region pemrosesan ini harus cocok dengan lokasi set data BigQuery Anda, tetapi tidak perlu cocok dengan region repositori Dataform.
  • assertionSchema: Set data BigQuery tempat Dataform membuat tampilan dengan hasil pernyataan, yang disebut dataform_assertions secara default.

Anda dapat mengakses properti yang ditentukan dalam dataform.json dalam kode project sebagai properti objek dataform.projectConfig.

Sebelum memulai

  1. Buat repositori.

  2. Buat dan lakukan inisialisasi ruang kerja pengembangan di repositori Anda.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna mengonfigurasi setelan Dataform, minta administrator untuk memberi Anda peran IAM Dataform Admin (roles/dataform.admin) di repositori. 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.

Mengonfigurasi nama skema

Untuk mengonfigurasi nama skema, Anda perlu mengedit properti defaultDataset dan defaultAssertionSchema dalam file workflow_settings.yaml, atau properti defaultSchema dan assertionSchema dalam file dataform.json.

Untuk mengonfigurasi nama skema, ikuti langkah-langkah berikut:

workflow_settings.yaml

  1. Di ruang kerja pengembangan, di panel Files, klik file workflow_settings.yaml.

  2. Edit nilai defaultDataset, defaultAssertionSchema, atau keduanya.

Contoh kode berikut menunjukkan nama defaultDataset kustom yang ditentukan dalam file workflow_settings.yaml:

  ...
  defaultDataset: mytables
  ...

dataform.json

  1. Di ruang kerja pengembangan, di panel Files, klik file dataform.json.

  2. Edit nilai defaultSchema, assertionSchema, atau keduanya.

Contoh kode berikut menunjukkan nama defaultSchema kustom yang ditentukan dalam file dataform.json:

{
  ...
  "defaultSchema": "mytables",
  ...
}

Membuat variabel kompilasi kustom

Variabel kompilasi berisi nilai yang dapat Anda ubah dengan penggantian kompilasi dalam konfigurasi rilis atau dalam permintaan Dataform API.

Setelah menentukan variabel kompilasi di workflow_settings.yaml dan menambahkannya ke tabel yang dipilih, Anda dapat menggunakan modifikasi nilainya dalam konfigurasi rilis atau penggantian kompilasi Dataform API untuk mengeksekusi tabel secara kondisional.

Untuk informasi selengkapnya tentang cara menjalankan tabel secara kondisional menggunakan variabel kompilasi, lihat Pengantar siklus proses kode di Dataform.

Untuk membuat variabel kompilasi yang dapat Anda gunakan di seluruh repositori, ikuti langkah-langkah berikut:

workflow_settings.yaml

  1. Buka ruang kerja pengembangan Dataform Anda.
  2. Di panel Files, pilih file workflow_settings.yaml.

  3. Masukkan cuplikan kode berikut:

    "vars": {
  "YOUR_VARIABLE":"VALUE"
}

    Ganti kode berikut:

    • YOUR_VARIABLE dengan nama untuk variabel.
    • VALUE dengan nilai default variabel kompilasi.

Contoh kode berikut menunjukkan variabel kompilasi myVariableName yang ditetapkan ke myVariableValue dalam file workflow_settings.yaml:

...
vars:
  myVariableName: myVariableValue
...

Contoh kode berikut menunjukkan file workflow_settings.yaml dengan variabel kompilasi executionSetting yang ditetapkan ke dev:

defaultProject: default_bigquery_database
defaultLocation: us-west1
defaultDataset: dataform_data,
vars:
executionSetting: dev

dataform.json

  1. Buka ruang kerja pengembangan Dataform Anda.
  2. Di panel Files, pilih file dataform.json.

  3. Masukkan cuplikan kode berikut:

    "vars": {
  "YOUR_VARIABLE":"VALUE"
}

    Ganti kode berikut:

    • YOUR_VARIABLE dengan nama untuk variabel.
    • VALUE dengan nilai default variabel kompilasi.

Contoh kode berikut menunjukkan variabel kompilasi myVariableName yang ditetapkan ke myVariableValue dalam file dataform.json:

{
  ...
  "vars": {
    "myVariableName": "myVariableValue"
  },
  ...
}

Contoh kode berikut menunjukkan file dataform.json dengan variabel kompilasi executionSetting yang ditetapkan ke dev:

{
"warehouse": "bigquery",
"defaultSchema": "dataform_data",
"defaultDatabase": "default_bigquery_database".
"defaultLocation":"us-west-1",
"vars": {
"executionSetting":"dev"
}
}

Menambahkan variabel kompilasi ke tabel

Untuk menambahkan variabel kompilasi ke file definisi tabel SQLX, ikuti langkah-langkah berikut:

  1. Buka ruang kerja pengembangan Dataform Anda.
  2. Di panel Files, pilih file definisi tabel SQLX.

  3. Dalam file tersebut, masukkan klausa when dalam format berikut:

    ${when(dataform.projectConfig.vars.YOUR_VARIABLE === "SET_VALUE", "CONDITION")}

    Ganti kode berikut:

    • YOUR_VARIABLE dengan nama variabel Anda, misalnya executionSetting.
    • SET_VALUE dengan nilai untuk variabel, misalnya, staging.
    • CONDITION dengan kondisi untuk eksekusi tabel.

Contoh kode berikut menunjukkan file SQLX definisi tabel dengan klausa when dan variabel executionSetting yang mengeksekusi 10% data dalam setelan eksekusi staging:

  select
    *
  from ${ref("data")}
  ${when(
    dataform.projectConfig.vars.executionSetting === "staging",
    "where mod(farm_fingerprint(id) / 10) = 0",
  )}

Contoh kode berikut menunjukkan file SQLX definisi tampilan dengan klausa when dan variabel myVariableName:

  config { type: "view" }
  SELECT ${when(
    dataform.projectConfig.vars.myVariableName === "myVariableValue",
    "myVariableName is set to myVariableValue!",
    "myVariableName is not set to myVariableValue!"
  )}

Memigrasikan setelan alur kerja ke workflow_settings.yaml

Untuk memastikan file setelan alur kerja Anda kompatibel dengan versi framework inti Dataform mendatang, Anda harus memigrasikan setelan alur kerja dari file dataform.json ke file workflow_settings.yaml.

File workflow_settings.yaml menggantikan file dataform.json.

Jika inti Dataform adalah satu-satunya paket dependensi di repositori Anda, file workflow_settings.yaml juga akan menggantikan file package.json. Untuk informasi selengkapnya tentang mengganti package.json dengan workflow_settings.yaml, lihat Mengelola paket inti Dataform.

Tabel berikut menunjukkan pemetaan properti setelan alur kerja dari dataform.json ke workflow_settings.yaml:

Properti di dataform.json Properti di workflow_settings.yaml Deskripsi
assertionSchema defaultAssertionDataset Wajib. Set data default untuk pernyataan.
defaultDatabase defaultProject Wajib. Nama project Google Cloud default.
defaultLocation defaultLocation Wajib. Lokasi BigQuery default tempat Dataform akan membuat tabel. Untuk mengetahui informasi selengkapnya tentang lokasi BigQuery, lihat Lokasi set data.
defaultSchema defaultDataset Wajib. Set data default.
databaseSuffix projectSuffix Opsional. Akhiran yang akan ditambahkan ke semua referensi project Google Cloud.
schemaSuffix datasetSuffix Opsional. Akhiran yang akan ditambahkan ke semua set data tindakan.
tablePrefix namePrefix Opsional. Awalan yang akan ditambahkan ke semua nama tindakan.
vars vars Opsional. Variabel buatan pengguna yang disediakan untuk kode project selama kompilasi. Objek yang berisi daftar pasangan key: value.
warehouse - Wajib di dataform.json. Harus ditetapkan ke bigquery. Tidak tersedia di workflow_settings.yaml.
- dataformCoreVersion Tidak tersedia di dataform.json. Diinstal di workflow_settings.yaml secara default untuk repositori baru. Untuk informasi selengkapnya, lihat Mengelola paket inti Dataform.

Untuk memigrasikan setelan alur kerja ke workflow_settings.yaml, ikuti langkah-langkah berikut:

  1. Di konsol Google Cloud, buka halaman Dataform.

    Buka halaman Dataform

  2. Pilih repositori, lalu pilih ruang kerja.

  3. Di panel Files, klik addAdd, lalu klik Create file.

  4. Di kolom Add a file path, masukkan workflow_settings.yaml.

  5. Klik Create file.

  6. Dalam file workflow_settings.yaml, tambahkan setelan dari file dataform.json, yang dipetakan ke format YAML.

  7. Di panel Files, klik menu More di samping dataform.json, lalu klik Delete.

  8. Untuk mengonfirmasi penghapusan dataform.json, klik Hapus.

Contoh kode berikut menunjukkan setelan alur kerja yang ditentukan dalam file dataform.json:

{
  "warehouse": "bigquery",
  "defaultDatabase": "dataform-demos",
  "defaultLocation": "US",
  "defaultSchema": "dataform",
  "assertionSchema": "dataform_assertions"
  "vars": {
    "environmentName": "development"
  }
}

Contoh kode berikut menunjukkan file dataform.json sebelumnya yang dikonversi menjadi workflow_settings.yaml:

defaultProject: dataform-demos
defaultLocation: US
defaultDataset: dataform
defaultAssertionDataset: dataform_assertions
vars:
    environmentName: "development"

Langkah selanjutnya