Menguji tabel dengan pernyataan

Dokumen ini menunjukkan cara menggunakan inti Dataform 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 kondisi 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 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 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:

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 diperlukan guna 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 ke project, folder, dan organisasi.

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 membuat tabel, Anda dapat melihat apakah pernyataan diteruskan di tab Log eksekusi alur kerja di ruang kerja Anda.

Anda dapat membuat pernyataan berikut di blok config tabel:

  • nonNull

    Kondisi ini menyatakan bahwa kolom yang ditentukan bukan 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 menyatakan 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 akan gagal jika baris tabel 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 menyatakan 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 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, 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 Add a file path, masukkan nama file, diikuti dengan .sqlx. Misalnya, definitions/custom_assertion.sqlx.

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

  4. Klik Create file.

  5. Di panel Files, klik file baru.

  6. Dalam file tersebut, masukkan:

    config {
  type: "assertion"
}

  7. Di bawah blok config, tulis kueri SQL 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

Menetapkan pernyataan sebagai dependensi

Jika tindakan alur kerja B bergantung pada tindakan alur kerja A yang memiliki pernyataan, kegagalan pernyataan tindakan A tidak akan memblokir Dataform dari mengeksekusi tindakan B. Untuk mengeksekusi tindakan B hanya jika pernyataan tindakan A lulus, Anda harus menetapkan pernyataan tindakan A sebagai dependensi tindakan B.

Anda dapat menetapkan pernyataan sebagai dependensi tindakan yang dipilih dengan cara berikut:

Menetapkan pernyataan yang dipilih sebagai dependensi

Anda dapat menetapkan pernyataan yang dipilih secara manual sebagai dependensi dengan menambahkannya ke dependencies: [ "" ] di blok config dari tindakan yang diedit.

Misalnya, jika tindakan B bergantung pada tindakan A, dan Anda ingin tindakan B hanya bergantung pada pernyataan yang dipilih dari tindakan A, Anda dapat menambahkan pernyataan yang dipilih tersebut ke blok config tindakan B.

Anda dapat menetapkan pernyataan yang dipilih secara manual sebagai dependensi untuk semua jenis tindakan, kecuali deklarasi sumber data.

Menetapkan pernyataan tindakan dependensi yang dipilih sebagai dependensi

Anda dapat menetapkan parameter includeDependentAssertions untuk secara otomatis menetapkan semua pernyataan langsung dari tindakan alur kerja dependensi yang dipilih sebagai dependensi tindakan yang diedit. Dataform menambahkan pernyataan ini sebagai dependensi selama setiap kompilasi tindakan untuk memastikan bahwa dependensi telah diperbarui jika pernyataan tindakan dependensi berubah.

Misalnya, jika tindakan C bergantung pada tindakan A dan B, tetapi Anda hanya ingin tindakan C bergantung pada pernyataan tindakan A, Anda dapat mengedit tindakan C dan menetapkan parameter includeDependentAssertions untuk secara otomatis menetapkan semua pernyataan tindakan A sebagai dependensi tindakan C.

Anda dapat menetapkan parameter includeDependentAssertions untuk tindakan dari jenis berikut:

  • table
  • view
  • operations
Menetapkan pernyataan semua tindakan dependensi sebagai dependensi

Anda dapat menetapkan parameter dependOnDependencyAssertions untuk menetapkan semua pernyataan langsung dari semua tindakan dependensi tindakan yang diedit secara otomatis sebagai dependensi tambahan tindakan yang diedit. Dataform menambahkan pernyataan ini sebagai dependensi selama setiap kompilasi tindakan untuk memastikan bahwa dependensi telah diperbarui jika pernyataan tindakan dependensi berubah.

Misalnya, jika tindakan C bergantung pada tindakan A dan B, Anda dapat mengedit tindakan C dan menetapkan parameter dependOnDependencyAssertions untuk menetapkan semua pernyataan tindakan A dan B secara otomatis sebagai dependensi tindakan C.

Anda dapat menetapkan parameter dependOnDependencyAssertions untuk tindakan dari jenis berikut:

  • table
  • view
  • operations

Saat Anda menetapkan parameter dependOnDependencyAssertions dan parameter includeDependentAssertions dalam satu file, parameter includeDependentAssertions akan diprioritaskan. Misalnya, jika Anda menetapkan dependOnDependencyAssertions ke true, tetapi juga menetapkan includeDependentAssertions ke false untuk tindakan dependensi yang dipilih, Dataform tidak akan menambahkan pernyataan tindakan tersebut ke dependensi.

Contoh kode berikut menunjukkan parameter dependOnDependencyAssertions dan includeDependentAssertions yang ditetapkan dalam file definisi tabel yang sama:

// filename is tableName.sqlx

config {
type: "table",
dependOnDependencyAssertions: true,
dependencies: [ "actionA", {name: "actionB", includeDependentAssertions: false} ]
}

SELECT * FROM ${ref("actionC")}

Pada contoh kode sebelumnya, Dataform menambahkan semua pernyataan langsung actionA dan actionC ke dependensi tableName selama kompilasi.

Menetapkan pernyataan yang dipilih sebagai dependensi

Untuk menjalankan tindakan alur kerja hanya jika pernyataan yang dipilih lulus, Anda dapat menambahkan pernyataan yang dipilih ke dependencies: [ "" ] di blok config dari tindakan yang diedit.

Untuk menetapkan pernyataan yang dipilih sebagai dependensi tindakan alur kerja yang dipilih, ikuti langkah-langkah berikut:

  1. Di ruang kerja pengembangan, di panel Files, luaskan definitions/.
  2. Pilih file SQLX tindakan alur kerja.
  3. Di blok config file tindakan, masukkan dependencies: [ "" ].

  4. Di dalam dependencies: [ "" ], masukkan nama pernyataan tindakan atau nama file pernyataan manual yang ingin Anda tetapkan sebagai dependensi dalam salah satu format berikut:

    nonNull

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_nonNull"]
}

    Ganti kode berikut:

    • ACTION_TYPE: jenis tindakan alur kerja: table, view, atau operations.
    • ACTION_DATASET_NAME: nama set data tempat tindakan ditentukan. Set data default ditentukan dalam file setelan alur kerja.
    • ACTION_NAME: nama tindakan tempat pernyataan ditentukan.

    rowConditions

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_rowConditions"]
}

    Ganti kode berikut:

    • ACTION_TYPE: jenis tindakan alur kerja: table, view, atau operations.
    • DATASET_NAME: nama set data tempat tindakan ditentukan. Set data default ditentukan dalam file setelan alur kerja.
    • ACTION_NAME: nama tindakan tempat pernyataan ditentukan.

    uniqueKey

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_uniqueKey_INDEX"]
}

    Ganti kode berikut:

    • ACTION_TYPE: jenis tindakan alur kerja: table, view, atau operations.
    • DATASET_NAME: nama set data tempat tabel ditentukan. Set data default ditentukan dalam file setelan alur kerja.
    • ACTION_NAME: nama tabel tempat pernyataan ditentukan.
    • INDEX: 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: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_uniqueKeys_INDEX"]
}

    Ganti kode berikut:

    • ACTION_TYPE: jenis tindakan alur kerja: table, view, atau operations.
    • DATASET_NAME: nama set data tempat tabel ditentukan. Set data default ditentukan dalam file setelan alur kerja.
    • ACTION_NAME: nama tabel tempat pernyataan ditentukan.
    • INDEX: 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: "ACTION_TYPE",
  dependencies: [ "MANUAL_ASSERTION_NAME"]
}

    Ganti kode berikut:

    • ACTION_TYPE: jenis tindakan alur kerja: table, view, atau operations.
    • MANUAL_ASSERTION_NAME nama pernyataan manual.

  5. Untuk menambahkan pernyataan lain sebagai dependensi ke tabel yang diedit, ulangi Langkah 4.

  6. Opsional: Klik Format.

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

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

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

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

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

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

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

Menetapkan pernyataan tindakan yang dipilih sebagai dependensi

Untuk mengeksekusi tindakan alur kerja hanya jika semua pernyataan langsung tindakan dependensi yang dipilih lulus, tetapkan parameter includeDependentAssertions ke true dalam tindakan yang diedit. Dataform secara otomatis menambahkan pernyataan langsung tindakan dependensi yang dipilih ke dependensi selama kompilasi. Nilai defaultnya adalah false.

Untuk menetapkan semua pernyataan tindakan dependensi yang dipilih sebagai dependensi, ikuti langkah-langkah berikut:

  1. Di ruang kerja pengembangan, di panel Files, luaskan definitions/.
  2. Pilih file SQLX tindakan alur kerja.

  3. Dalam file, tetapkan parameter includeDependentAssertions ke true dengan salah satu cara berikut:

    Di blok config

    config {
type: "ACTION_TYPE",
dependencies: [{name: "dEPENDENCY_ACTION_NAME", includeDependentAssertions: true}]
}

    Ganti kode berikut:

    • ACTION_TYPE: jenis tindakan alur kerja: table, view, atau operations.
    • DEPENDENCY_ACTION_NAME: nama tindakan dependensi yang pernyataannya ingin Anda tetapkan sebagai dependensi tindakan yang diedit.

    Dalam pernyataan SELECT

      config { type: "ACTION_TYPE" }

  SELECT * FROM ${ref({name: "DEPENDENCY_ACTION_NAME", includeDependentAssertions: true})}

    Ganti kode berikut:

    • ACTION_TYPE: jenis tindakan alur kerja: table, view, atau operations.
    • DEPENDENCY_ACTION_NAME: nama tindakan dependensi yang pernyataannya ingin Anda tetapkan sebagai dependensi tindakan yang diedit.

  4. Opsional: Klik Format.

Contoh kode berikut menunjukkan tableC yang bergantung pada viewA, tableB, dan semua pernyataan tableB:

// filename is tableC.sqlx

config {
type: "table",
dependencies: ["viewA", {name: "tableB", includeDependentAssertions: true}]
}

SELECT * FROM ...

Dalam contoh kode sebelumnya, Dataform secara otomatis menambahkan semua pernyataan langsung tableB sebagai dependensi ke tableC selama kompilasi.

Menetapkan pernyataan semua tindakan dependensi sebagai dependensi

Untuk mengeksekusi tindakan alur kerja hanya jika semua pernyataan langsung dari semua tindakan dependensi lulus, tetapkan parameter dependOnDependencyAssertions ke true dalam tindakan yang diedit. Dataform secara otomatis menambahkan pernyataan langsung tindakan dependensi sebagai dependensi selama kompilasi. Nilai defaultnya adalah false.

Saat Anda menetapkan parameter dependOnDependencyAssertions dan parameter includeDependentAssertions dalam satu file, parameter includeDependentAssertions akan diprioritaskan untuk tindakan dependensi yang ditetapkan.

Untuk menetapkan semua pernyataan tindakan dependensi yang dipilih sebagai dependensi, ikuti langkah-langkah berikut:

  1. Di ruang kerja pengembangan, di panel Files, luaskan definitions/.
  2. Pilih file SQLX tindakan alur kerja.

  3. Dalam file, tetapkan parameter dependOnDependencyAssertions ke true dalam format berikut:

    config {
type: "ACTION_TYPE",
dependOnDependencyAssertions: true,
dependencies: [ "dependency1", "dependency2" ]
}

    Ganti ACTION_TYPE: jenis tindakan alur kerja. Nilai yang didukung mencakup table, view, dan operations.

  4. Opsional: Klik Format.

Contoh kode berikut menunjukkan sometableE yang bergantung pada sometableA, sometabletableB, sometableC, dan sometableD serta semua pernyataan langsung tabel dependensi:

// filename is sometableE.sqlx

config {
type: "table",
dependOnDependencyAssertions: true,
dependencies: [ "sometableA", "sometableB" ]
}

SELECT * FROM ${ref("sometableC")}
SELECT * FROM ${ref("sometableD")}

Dalam contoh kode sebelumnya, Dataform otomatis menambahkan semua pernyataan langsung sometableA, sometableB, sometableC, dan sometableD sebagai dependensi ke sometableE selama kompilasi.

Langkah selanjutnya