Menguji kualitas data

Dokumen ini menunjukkan cara menguji kode alur kerja dengan pernyataan tabel dan pengujian unit 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. Membuat tabel.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk membuat pernyataan dan pengujian unit, minta administrator untuk memberi Anda peran IAM berikut:

• Dataform Editor (roles/dataform.editor) di ruang kerja
• Untuk menyinkronkan metadata pernyataan ke Knowledge Catalog: Editor Katalog Dataplex (roles/dataplex.catalogEditor) di project atau grup entri @bigquery

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

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

Menguji data dengan pernyataan

Pernyataan adalah kueri pengujian kualitas data yang menemukan baris yang melanggar satu atau beberapa kondisi yang ditentukan dalam kueri. Jika kueri menampilkan baris apa pun, pernyataan akan gagal. Dataform menjalankan pernyataan setiap kali memperbarui alur kerja Anda dan akan 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 setelan alur kerja Anda, Dataform membuat tampilan ini dalam skema pernyataan tempat Anda dapat memeriksa hasil pernyataan.

Misalnya, untuk skema dataform_assertions default, Dataform 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:

• Tambahkan pernyataan bawaan ke blok config tabel.

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

• Tambahkan 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.

Catatan: Pernyataan Dataform otomatis diintegrasikan dengan skor kualitas data Knowledge Catalog (Pratinjau). Selama eksekusi pipeline, hasil pernyataan Dataform akan otomatis dipublikasikan ke Knowledge Catalog. Hasil ini akan mengisi kartu skor kualitas data Knowledge Catalog dengan status lulus atau gagal. Setiap eksekusi akan menimpa kartu skor kualitas data yang ada yang dipublikasikan oleh eksekusi Dataform sebelumnya, tetapi tidak memengaruhi kartu skor yang dibuat oleh pemindaian data Knowledge Catalog. Untuk memeriksa status pembaruan metadata, ikuti petunjuk di Memeriksa log eksekusi ruang kerja. Untuk melihat hasil ini di Knowledge Catalog, ikuti petunjuk di Menelusuri resource.

Membuat pernyataan bawaan

Anda dapat menambahkan pernyataan Dataform bawaan ke blok config tabel. Dataform menjalankan pernyataan ini setelah pembuatan tabel. Setelah Dataform membuat tabel, Anda dapat melihat apakah pernyataan lulus di tab Log eksekusi alur kerja ruang kerja Anda.

Anda dapat membuat pernyataan berikut di blok config tabel:

• nonNull

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

  Contoh kode berikut menunjukkan pernyataan nonNull dalam blok config 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 terhadap setiap kondisi baris. Pernyataan akan gagal jika ada baris tabel yang menghasilkan false.

  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 tertentu, tidak ada baris tabel yang memiliki nilai yang sama.

  Contoh kode berikut menunjukkan pernyataan uniqueKey di blok config tampilan:

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

• uniqueKeys

  Kondisi ini menyatakan 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 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. Di dalam assertions: {}, tambahkan pernyataan Anda.
4. Opsional: Klik Format.

Contoh kode berikut menunjukkan kondisi yang ditambahkan di 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 nol baris. Jika kueri menampilkan baris saat dijalankan, pernyataan akan gagal.

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

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

3. Di kolom Tambahkan jalur file, masukkan nama file yang diikuti dengan .sqlx. Misalnya, definitions/custom_assertion.sqlx.

   Nama file hanya boleh menyertakan 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 atau beberapa kueri Anda.

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

Menguji kualitas data dengan pengujian unit

Pengujian unit adalah pengujian kualitas data, yang ditentukan dalam file .sqlx khusus, yang meniru semua dependensi tindakan alur kerja yang diuji dan memberikan hasil yang diharapkan. Anda dapat menggunakan pengujian unit untuk menguji tindakan Dataform terhadap input tiruan yang dikontrol untuk memverifikasi apakah kode tindakan menangani kasus ekstrem, nilai null, agregasi, ekspresi reguler, dan logika bersyarat dengan benar.

Mock untuk dependensi tindakan, seperti tabel, tampilan, atau deklarasi mentah pendahulu yang dirujuk dalam fungsi ${ref()}, ditentukan dalam blok input. Setiap blok input mereferensikan dependensi berdasarkan namanya dan berisi kueri SQL yang menentukan baris tiruan. Kueri ini biasanya berupa serangkaian pernyataan SELECT yang digabungkan dengan UNION ALL. Hasil yang diharapkan adalah kueri SQL yang merepresentasikan hasil menjalankan input yang ditentukan melalui pernyataan SQL tindakan alur kerja.

Dataform menjalankan pengujian unit baris demi baris dan membandingkan hasil sebenarnya dari menjalankan logika SQL tindakan alur kerja terhadap data tiruan dengan set hasil yang diharapkan.

Pengujian unit diselesaikan ke status berikut:

• SUCCESS: Pengujian lulus. Hasil sebenarnya sesuai dengan hasil yang diharapkan.
• FAILURE: Pengujian gagal. Hasil aktual tidak sesuai dengan hasil yang diharapkan.

Batasan

Pengujian unit Dataform tersedia dengan batasan berikut:

• Pengujian unit tersedia di Dataform core versi 3.0.56 dan yang lebih baru.
• Ukuran maksimum data input dalam pengujian unit adalah 100 baris per input.

Membuat pengujian unit

Simpan file .sqlx untuk pengujian unit di direktori definitions/. Untuk membuat file pengujian unit .sqlx baru di direktori definitions/, ikuti langkah-langkah berikut:

1. Di konsol Google Cloud , buka halaman Dataform.

   Buka halaman Dataform

2. Pilih repositori.

3. Pilih ruang kerja pengembangan.

4. Di panel Files, di samping definitions/, klik menu More.

5. Klik Create file.

6. Di panel Create new file, lakukan hal berikut:

   1. Di kolom Add a file path, setelah definitions/, masukkan nama file yang diikuti dengan _test.sqlx. Contoh, definitions/customer_spend_test.sqlx.

      Nama file hanya boleh menyertakan angka, huruf, tanda hubung, dan garis bawah.

   2. Klik Create file.

7. Di file pengujian, tambahkan blok config berikut:

   config {
     type: "test",
     dataset: "ACTION_NAME"
   }
   

   Ganti ACTION_NAME dengan nama tindakan yang divalidasi oleh pengujian ini.

8. Untuk mengejek tindakan yang diuji, tambahkan blok input untuk setiap dependensi tindakan, dan tulis kueri SQL yang menguji dependensi tersebut dalam format berikut:

   input "DEPENDENCY_NAME" {
   SELECT ...
   SELECT ...
   }
   

   Ganti DEPENDENCY_NAME dengan nama dependensi tindakan yang diuji yang ditiru oleh input ini.

9. Di bawah blok input, tulis kueri SQL standar yang merepresentasikan baris output yang diharapkan dalam format berikut:

   -- Expected Output
   SELECT ...
   SELECT ...
   

Kueri output yang diharapkan hanya boleh menampilkan baris dan kolom yang seharusnya dihasilkan oleh tindakan yang diuji berdasarkan input tiruan.

Contoh kode berikut menunjukkan tindakan alur kerja customer_spend.sqlx:

config {
type: "table",
name: "customer_spend"
}

SELECT
  c.customer_id,
  c.name,
  SUM(o.amount) AS total_completed_amount
FROM
  ${ref("source_customers")} c
  JOIN
  ${ref("source_orders")} o
  ON c.customer_id = o.customer_id
WHERE
  o.status = 'COMPLETED'
GROUP BY
  1, 2

Contoh kode berikut menunjukkan pengujian unit customer_spend_test.sqlx yang mengejek dependensi tindakan customer_spend.sqlx, dan menentukan hasil yang diharapkan untuk ejekan:

config {
  type: "test",
  dataset: "customer_spend"
}

input "source_customers" {
  SELECT 101 AS customer_id, 'Alice' AS name UNION ALL
  SELECT 102 AS customer_id, 'Bob' AS name UNION ALL
  SELECT 103 AS customer_id, 'Charlie' AS name
}

input "source_orders" {
  -- Alice has one completed and one pending order
  SELECT 1 AS order_id, 101 AS customer_id, 'COMPLETED' AS status, 100.0 AS amount UNION ALL
  SELECT 2 AS order_id, 101 AS customer_id, 'PENDING' AS status, 50.0 AS amount UNION ALL
  -- Bob has one completed order
  SELECT 3 AS order_id, 102 AS customer_id, 'COMPLETED' AS status, 250.0 AS amount UNION ALL
  -- Charlie has no orders
  SELECT 4 AS order_id, 999 AS customer_id, 'COMPLETED' AS status, 10.0 AS amount
}

-- Expected Output
SELECT 101 AS customer_id, 'Alice' AS name, 100.0 AS total_completed_amount UNION ALL
SELECT 102 AS customer_id, 'Bob' AS name, 250.0 AS total_completed_amount

Menjalankan pengujian unit

Untuk menjalankan pengujian unit, ikuti langkah-langkah berikut:

Konsol

1. Di konsol Google Cloud , buka halaman Dataform.

   Buka halaman Dataform

2. Pilih repositori.

3. Pilih ruang kerja pengembangan.

4. Klik Start execution  > Execute actions.

5. Di panel Execute, di bagian Execution mode, pilih Unit tests.

6. Pilih salah satu opsi berikut:

   • Pilih pengujian unit: menjalankan pengujian unit yang Anda pilih secara manual.
   • Pilih pengujian unit yang diberi tag: menjalankan pengujian unit dengan tag yang dipilih.
   • Semua pengujian unit: menjalankan semua pengujian unit di ruang kerja.

7. Opsional: Di bagian Opsi eksekusi, centang kotak Jalankan sebagai tugas interaktif dengan prioritas tinggi untuk menjalankan pengujian unit secara langsung, dengan memprioritaskan kecepatan eksekusi.

   Jika Anda tidak mencentang kotak Jalankan sebagai tugas interaktif dengan prioritas tinggi, Dataform akan menjalankan pengujian unit menggunakan resource batch secara default, dengan memprioritaskan penghematan biaya komputasi.

8. Klik Start execution.

API

Untuk menjalankan pengujian unit secara terprogram, buat pemanggilan alur kerja menggunakan metode WorkflowInvocations.create, dan tetapkan parameter eksekusi pengujian unit berikut dalam objek invocationConfig:

"executionMode": "UNIT_TESTS_ONLY"

Parameter ini, yang ditetapkan ke "UNIT_TESTS_ONLY", memicu eksekusi pengujian unit yang ditentukan di repositori.

Opsional: "queryPriority": "INTERACTIVE"

Jika parameter ini disetel ke "INTERACTIVE", Dataform akan menjalankan kueri secara langsung. Jika tidak disetel, Dataform menjalankan pengujian unit dengan prioritas kueri batch default.

Opsional: "includedTargets": []

Dengan parameter ini, Anda dapat menentukan pengujian unit sehingga Dataform hanya menjalankan pengujian ini.

Opsional: "includedTags": []

Dengan parameter ini, Anda dapat menentukan tag sehingga Dataform hanya menjalankan uji unit yang diberi tag tersebut.

Contoh kode berikut menunjukkan isi pemanggilan alur kerja yang menjalankan semua pengujian unit yang ditentukan di repositori my-repo dengan prioritas kueri batch default:

{
  "compilationResult": "projects/my-project/locations/us/repositories/my-repo/compilationResults/my-compilation-id",
  "invocationConfig": {
    "executionMode": "UNIT_TESTS_ONLY"
  }
}

Contoh kode berikut menunjukkan isi pemanggilan alur kerja yang hanya menjalankan pengujian unit my-test dengan prioritas kueri interaktif:

{
  "compilationResult": "projects/my-project/locations/us/repositories/my-repo/compilationResults/my-compilation-id",
  "invocationConfig": {
    "executionMode": "UNIT_TESTS_ONLY",
    "queryPriority": "INTERACTIVE",
    "includedTargets": [
      {
        "database": "my-project",
        "schema": "my-dataset",
        "name": "my-test"
      }
    ]
  }
}

Contoh kode berikut menunjukkan isi pemanggilan alur kerja yang menjalankan pengujian unit di repositori my-repo yang diberi tag dengan test-tag-1 atau test-tag-2:

{
  "compilationResult": "projects/my-project/locations/us/repositories/my-repo/compilationResults/my-compilation-id",
  "invocationConfig": {
    "executionMode": "UNIT_TESTS_ONLY",
    "queryPriority": "INTERACTIVE",
    "includedTags": [
      "test-tag-1",
      "test-tag-2"
    ]
  }
}

Memeriksa hasil pengujian unit

Anda dapat memeriksa perbedaan antara skrip yang diharapkan dan skrip sebenarnya dari pengujian unit dalam Grafik yang dikompilasi atau di Eksekusi.

Grafik yang dikompilasi

Untuk melihat skrip aktual dan yang diharapkan dari pengujian unit dalam grafik alur kerja tindakan yang dikompilasi, ikuti langkah-langkah berikut:

1. Di konsol Google Cloud , buka halaman Dataform.

   Buka halaman Dataform

2. Pilih repositori.

3. Pilih ruang kerja pengembangan.

4. Opsional: Untuk melihat pengujian unit yang ditautkan ke tindakan yang diuji, bukan melihatnya sebagai node grafik independen, tetapkan setelan includeTestsInCompiledGraph ke true dalam file workflow_settings.yaml:

   1. Pilih file workflow_settings.yaml.
   2. Tambahkan kode berikut:

   includeTestsInCompiledGraph: true
   

5. Klik Grafik gabungan.

6. Di grafik yang dikompilasi, pilih pengujian unit, lalu klik Query.

7. Bandingkan Skrip SQL Aktual dan Skrip SQL yang Diharapkan.

Eksekusi

1. Di konsol Google Cloud , buka halaman Dataform.

   Buka halaman Dataform

2. Pilih repositori.

3. Pilih ruang kerja pengembangan.

4. Klik Eksekusi, lalu klik Lihat detail di samping uji unit yang dipilih.

5. Bandingkan Kueri hasil sebenarnya dan Kueri hasil yang diharapkan.

Praktik terbaik untuk pengujian unit

Memastikan set data tiruan tetap kecil

Pertahankan data input tiruan di bawah 10 baris agar kompilasi lebih cepat dan proses pen-debug-an lebih mudah.

Menentukan urutan baris eksplisit

Selalu tambahkan klausa ORDER BY ke kueri tindakan dan kueri output yang diharapkan untuk memastikan pengurutan baris yang deterministik selama evaluasi.

Secara eksplisit melakukan transmisi kolom dalam pernyataan tiruan

Melakukan casting kolom secara eksplisit dalam pernyataan tiruan—misalnya, dengan menggunakan CAST(100 AS INT64)—mempertahankan ketatnya jenis dan mencegah error kompilasi.

Sertakan kasus pengujian dengan NULL atau nilai yang tidak ada

Menyertakan kasus pengujian dengan nilai NULL atau nilai yang tidak ada dalam kueri tiruan input memastikan bahwa pernyataan COALESCE, operasi string, dan kriteria filter Anda menangani data produksi yang tidak lengkap atau null dengan aman.

Contoh kode berikut menunjukkan kasus pengujian NULL:

input "source_customers" {
  SELECT 101 AS customer_id, 'Alice' AS name UNION ALL
  SELECT 102 AS customer_id, NULL AS name -- Test null handling
}

Langkah berikutnya

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