Menguji tabel dengan pernyataan

Dokumen ini menunjukkan cara menggunakan Dataform core untuk membuat pernyataan tabel Dataform dan menguji kode alur kerja Anda.

Tentang pernyataan

Pernyataan adalah kueri pengujian kualitas data yang menemukan baris yang melanggar satu atau beberapa aturan yang ditentukan dalam kueri. Jika kueri menampilkan baris apa pun, pernyataan akan gagal. Dataform menjalankan pernyataan setiap kali memperbarui alur kerja SQL Anda, dan memberi tahu Anda jika ada pernyataan yang gagal.

Dataform secara otomatis membuat tampilan di BigQuery yang berisi hasil kueri pernyataan yang dikompilasi. Seperti yang dikonfigurasi dalam file dataform.json, Dataform akan membuat tampilan ini dalam skema pernyataan tempat Anda dapat memeriksa hasil pernyataan.

Misalnya, untuk skema dataform_assertions default, Dataform akan membuat tampilan di BigQuery dalam format berikut: dataform_assertions.assertion_name.

Anda dapat membuat pernyataan untuk semua jenis tabel Dataform: tabel, tabel inkremental, tampilan, dan tampilan terwujud.

Anda dapat membuat pernyataan dengan cara berikut:

• Menambahkan pernyataan bawaan ke blok konfigurasi tabel.

  Anda dapat menambahkan pernyataan bawaan ke blok config sebuah tabel dan menentukan kondisinya.

• Menambahkan pernyataan manual dalam file SQLX terpisah.

  Anda menulis pernyataan kustom secara manual dalam file SQLX terpisah untuk kasus penggunaan lanjutan atau untuk set data yang tidak dibuat oleh Dataform.

Sebelum memulai

1. Di konsol Google Cloud, buka halaman Dataform.

   Buka halaman Dataform

2. Pilih atau buat repositori.

3. Pilih atau buat ruang kerja pengembangan.

4. Menentukan tabel.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk membuat pernyataan, 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 pernyataan bawaan

Anda dapat menambahkan pernyataan Dataform bawaan ke blok config tabel. Dataform menjalankan pernyataan ini setelah pembuatan tabel. Setelah Dataform memublikasikan tabel, Anda dapat memeriksa pernyataan tersebut.

Anda dapat membuat pernyataan berikut di blok config tabel:

• nonNull

  Kondisi ini menegaskan bahwa kolom yang ditentukan tidak null di semua baris tabel. Kondisi ini digunakan untuk kolom yang tidak pernah bisa bernilai null.

  Contoh kode berikut menunjukkan pernyataan nonNull dalam blok config sebuah tabel:

config {
  type: "table",
  assertions: {
    nonNull: ["user_id", "customer_id", "email"]
  }
}
SELECT ...

• rowConditions

  Kondisi ini menegaskan bahwa semua baris tabel mengikuti logika kustom yang Anda tentukan. Setiap kondisi baris adalah ekspresi SQL kustom, dan setiap baris tabel dievaluasi berdasarkan setiap kondisi baris. Pernyataan gagal jika ada baris tabel yang melanggar kondisi baris apa pun.

  Contoh kode berikut menunjukkan pernyataan rowConditions kustom dalam blok config tabel inkremental:

config {
  type: "incremental",
  assertions: {
    rowConditions: [
      'signup_date is null or signup_date > "2022-08-01"',
      'email like "%@%.%"'
    ]
  }
}
SELECT ...

• uniqueKey

  Kondisi ini menegaskan bahwa, dalam kolom yang ditentukan, tidak ada baris tabel yang memiliki nilai yang sama.

  Contoh kode berikut menunjukkan pernyataan uniqueKey dalam blok config tampilan:

config {
  type: "view",
  assertions: {
    uniqueKey: ["user_id"]
  }
}
SELECT ...

• uniqueKeys

  Kondisi ini menegaskan bahwa, di kolom yang ditentukan, tidak ada baris tabel yang memiliki nilai yang sama. Pernyataan gagal jika ada lebih dari satu baris dalam tabel dengan nilai yang sama untuk semua kolom yang ditentukan.

  Contoh kode berikut menunjukkan pernyataan uniqueKeys dalam blok config sebuah tabel:

config {
  type: "table",
  assertions: {
    uniqueKeys: [["user_id"], ["signup_date", "customer_id"]]
  }
}
SELECT ...

Menambahkan pernyataan ke blok config

Untuk menambahkan pernyataan ke blok konfigurasi tabel, ikuti langkah-langkah berikut:

1. Di ruang kerja pengembangan Anda, di panel Files, pilih file SQLX definisi tabel.
2. Di blok config file tabel, masukkan assertions: {}.
3. Dalam assertions: {}, tambahkan pernyataan Anda.
4. Opsional: Klik Format.

Contoh kode berikut menunjukkan kondisi yang ditambahkan dalam blok config:

config {
  type: "table",
  assertions: {
    uniqueKey: ["user_id"],
    nonNull: ["user_id", "customer_id"],
    rowConditions: [
      'signup_date is null or signup_date > "2019-01-01"',
      'email like "%@%.%"'
    ]
  }
}
SELECT ...

Membuat pernyataan manual dengan SQLX

Pernyataan manual adalah kueri SQL yang Anda tulis dalam file SQLX khusus. Kueri SQL pernyataan manual harus menampilkan baris nol. Jika kueri menampilkan baris saat dieksekusi, pernyataan akan gagal.

Untuk menambahkan pernyataan manual di file SQLX baru, ikuti langkah-langkah berikut:

1. Di panel Files, di samping definitions/, klik menu More.
2. Klik Create file.

3. Di kolom Add a file path, masukkan nama file diikuti dengan .sqlx. Misalnya, definitions/custom_assertion.sqlx.

   Nama file hanya dapat berisi angka, huruf, tanda hubung, dan garis bawah.

4. Klik Create file.

5. Di panel Files, klik file baru.

6. Dalam file, masukkan:

   config {
     type: "assertion"
   }
   

7. Di bawah blok config, tulis kueri SQL Anda atau beberapa kueri.

8. Opsional: Klik Format.

Contoh kode berikut menunjukkan pernyataan manual dalam file SQLX yang menyatakan bahwa kolom a, b, dan c tidak pernah NULL di sometable:

config { type: "assertion" }

SELECT
  *
FROM
  ${ref("sometable")}
WHERE
  a IS NULL
  OR b IS NULL
  OR c IS NULL

Menambahkan pernyataan sebagai dependensi

Jika tabel B bergantung pada tabel A yang memiliki pernyataan, kegagalan pernyataan A tabel tidak akan memblokir Dataform agar tidak membuat tabel B. Untuk mengeksekusi tabel B hanya jika pernyataan A tabel diteruskan, tambahkan pernyataan ini sebagai dependensi ke dependencies: [ "" ] dalam blok config tabel B.

Contoh kode berikut menunjukkan pernyataan yang ditambahkan ke tabel A dalam set data dataform:

config {
  type: "table",
  assertions: {
    uniqueKey: ["user_id"],
    nonNull: ["user_id", "customer_id"],
  }
}

Contoh kode berikut menunjukkan pernyataan A tabel yang ditambahkan sebagai dependensi ke tabel B:

config {
  type: "table",
  dependencies: [ "dataform_A_assertions_uniqueKey_0",  "dataform_A_assertions_nonNull"]
}

Untuk mengeksekusi tabel hanya jika pernyataan manual tertentu diteruskan, Anda dapat menambahkan file SQLX pernyataan manual ke dependencies: [ "" ] dalam blok config.

Contoh kode berikut menunjukkan pernyataan manual yang ditentukan dalam file manualAssertion, yang ditambahkan sebagai dependensi ke tampilan:

config {
  type: "view",
  dependencies: [ "manualAssertion"]
}

Untuk menambahkan file pernyataan atau tabel dengan pernyataan dalam blok config-nya sebagai dependensi tabel, ikuti langkah-langkah berikut:

1. Di ruang kerja pengembangan Anda, di panel Files, luaskan definitions/.
2. Pilih file SQLX tabel.
3. Di blok config file tabel, masukkan dependencies: [ "" ].
4. Dalam dependencies: [ "" ], masukkan nama pernyataan tabel atau nama file pernyataan manual yang ingin Anda tetapkan sebagai dependensi dalam salah satu format berikut:

nonNull

config {
  type: "table",
  dependencies: [ "TABLE_DATASET_NAME_TABLE_NAME_assertions_nonNull"]
}

Ganti kode berikut:

• DATASET_NAME dengan nama set data tempat tabel ditentukan. Set data default ditentukan di workflow_settings.yaml file.
• TABLE_NAME dengan nama tabel tempat pernyataan ditentukan.

rowConditions

config {
  type: "table",
  dependencies: [ "TABLE_DATASET_NAME_TABLE_NAME_assertions_rowConditions"]
}

Ganti kode berikut:

• DATASET_NAME dengan nama set data tempat tabel ditentukan. Set data default ditentukan di workflow_settings.yaml file.
• TABLE_NAME dengan nama tabel tempat pernyataan ditentukan.

uniqueKey

config {
  type: "table",
  dependencies: [ "TABLE_DATASET_NAME_TABLE_NAME_assertions_uniqueKey_INDEX"]
}

Ganti kode berikut:

• DATASET_NAME dengan nama set data tempat tabel ditentukan. Set data default ditentukan di workflow_settings.yaml file.
• TABLE_NAME dengan nama tabel tempat pernyataan ditentukan.
• INDEX dengan indeks array kunci yang ditentukan dalam pernyataan uniqueKey yang ingin Anda tambahkan sebagai dependensi. Misalnya, 0 atau 1. Jika hanya satu array kunci yang ditentukan dalam pernyataan, indeksnya adalah 0.

uniqueKeys

config {
  type: "table",
  dependencies: [ "TABLE_DATASET_NAME_TABLE_NAME_assertions_uniqueKeys_INDEX"]
}

Ganti kode berikut:

• DATASET_NAME dengan nama set data tempat tabel ditentukan. Set data default ditentukan di workflow_settings.yaml file.
• TABLE_NAME dengan nama tabel tempat pernyataan ditentukan.
• INDEX dengan indeks array kunci yang ditentukan dalam pernyataan uniqueKeys yang ingin Anda tambahkan sebagai dependensi—misalnya, 0 atau 1. Jika hanya satu array kunci yang ditentukan dalam pernyataan, indeksnya adalah 0.

pernyataan manual

config {
  type: "table",
  dependencies: [ "MANUAL_ASSERTION_NAME"]
}

Ganti kode berikut:

• MANUAL_ASSERTION_NAME nama pernyataan manual.

1. Untuk menambahkan pernyataan lain sebagai dependensi ke tabel yang diedit, ulangi Langkah 4.
2. Opsional: Klik Format.

Contoh kode berikut menunjukkan file manual_assertion dan pernyataan tabel sometable yang ditambahkan sebagai dependensi ke tabel:

config {
  type: "table",
  dependencies: [ "manual_assertion",  "dataform_sometable_assertions_nonNull" ,  "dataform_sometable_assertions_rowConditions"]
}

SELECT * FROM ${ref("referenced_table")} LEFT JOIN ...

Langkah selanjutnya

• Untuk mempelajari jenis pernyataan lebih lanjut, lihat Dataform API.
• Untuk mempelajari cara menetapkan pernyataan dengan JavaScript, lihat Membuat alur kerja SQL dengan JavaScript.
• Untuk mempelajari cara menjalankan alur kerja secara manual, lihat Memicu eksekusi.