Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat tabel

Di Dataform, tabel adalah salah satu jenis objek yang membentuk alur kerja. Anda dapat membuat tabel yang mereferensikan data dari sumber data yang dideklarasikan untuk alur kerja atau dari tabel lain dalam alur kerja. Dataform mengompilasi definisi tabel Anda ke dalam SQL secara real time. Saat Anda memicu eksekusi, Dataform akan mengeksekusi kode SQL dan membuat tabel yang ditentukan di BigQuery.

Anda dapat membuat jenis tabel berikut dalam file SQLX type: "table":

table: tabel reguler.
incremental: tabel inkremental.
view: tampilan tabel. Untuk informasi selengkapnya, lihat Pengantar tampilan.
- materialized: tampilan tabel terwujud. Untuk informasi selengkapnya, lihat Pengantar tampilan terwujud.

Anda juga dapat menentukan partisi dan cluster tabel.

Untuk menyimpan catatan tujuan tabel atau hubungannya dengan tabel lain dalam alur kerja, Anda dapat menambahkan dokumentasi ke tabel atau kolom yang dipilih.

Untuk menguji data dalam tabel terhadap kondisi tertentu, Anda dapat membuat kueri pengujian kualitas data yang disebut pernyataan. Dataform menjalankan pernyataan setiap kali memperbarui alur kerja Anda dan memberi tahu Anda jika ada pernyataan yang gagal.

Untuk mengganti setelan tabel default, seperti database atau schema, dan menonaktifkan pembuatan tabel, atau menjalankan pernyataan SQL sebelum atau setelah pembuatan tabel, Anda dapat mengonfigurasi setelan tabel tambahan.

Anda dapat mengonfigurasi setelan tabel tambahan untuk melakukan hal berikut:

Ganti setelan tabel default, seperti database atau schema.
Nonaktifkan pembuatan tabel.
Menjalankan pernyataan SQL sebelum atau setelah pembuatan tabel.

Untuk mengatur tabel di BigQuery setelah menjalankannya, Anda dapat menambahkan label BigQuery. Untuk mempelajari lebih lanjut, lihat Pengantar label.

Untuk membatasi akses data di tingkat kolom tabel, Anda dapat menambahkan tag kebijakan BigQuery. Untuk mempelajari lebih lanjut, lihat Pengantar kontrol akses tingkat kolom.

Selain menentukan tabel dalam file SQLX type: "table", Anda dapat membuat tabel kosong dengan menentukan kueri SQL kustom dalam file SQLX type: "operations". Anda mungkin ingin membuat tabel kosong agar layanan lain dapat mengisinya dengan data.

Sebelum memulai

Di konsol Google Cloud, buka halaman Dataform.

Buka Dataform
Buat dan lakukan inisialisasi ruang kerja pengembangan di repositori Anda.
Opsional: Deklarasikan sumber data.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menyelesaikan tugas dalam dokumen ini, 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 tabel

Bagian ini menunjukkan cara membuat tabel dengan inti Dataform di Dataform.

Tentang definisi tabel

Untuk menentukan tabel, Anda menentukan jenis tabel dan menulis pernyataan SELECT dalam file SQLX type: "table". Dataform kemudian mengompilasi kode inti Dataform ke dalam SQL, menjalankan kode SQL, dan membuat tabel yang ditentukan di BigQuery.

Dalam pernyataan SELECT inti Dataform, Anda menentukan struktur tabel dan mereferensikan objek alur kerja lainnya.

Selain menentukan tabel dalam file SLQX type: "table", Anda dapat membuat tabel kosong dengan menentukan kueri SQL kustom dalam file SQLX type: "operations". Untuk mengetahui informasi selengkapnya, lihat Membuat tabel kosong.

Mereferensikan dependensi dengan `ref`

Untuk mereferensikan objek alur kerja dalam pernyataan SELECT dan otomatis menambahkannya sebagai dependensi, gunakan fungsi ref. Dataform mengeksekusi dependensi sebelum tabel yang bergantung padanya untuk memastikan pengurutan pipeline yang benar.

Fungsi ref adalah fungsi inti Dataform bawaan yang sangat penting untuk pengelolaan dependensi di Dataform. Fungsi ref memungkinkan Anda mereferensikan dan secara otomatis bergantung pada objek berikut yang ditentukan dalam alur kerja Dataform, bukan melakukan hard code pada nama skema dan tabel:

Tabel dari semua jenis tabel yang didukung.
Deklarasi sumber data.
Operasi SQL kustom dengan properti hasOutput yang disetel ke true.

Dataform menggunakan fungsi ref untuk membuat hierarki dependensi dari semua tabel yang akan dibuat atau diperbarui.

Setelah mengompilasi, Dataform akan menambahkan pernyataan boilerplate ke pernyataan SQL, seperti CREATE, REPLACE, INSERT, atau MERGE.

Contoh kode berikut menunjukkan definisi tabel dengan penggunaan fungsi ref:

config { type: "table" }

SELECT
  order_date AS date,
  order_id AS order_id,
  order_status AS order_status,
  SUM(item_count) AS item_count,
  SUM(amount) AS revenue

FROM ${ref("store_clean")}

GROUP BY 1, 2

Dalam fungsi ref, Anda memberikan nama deklarasi tabel atau sumber data yang ingin Anda andalkan. Ini biasanya adalah nama file SQLX tempat deklarasi tabel atau sumber data tersebut ditentukan.

Jika nama tabel diganti, gunakan nama yang diganti dalam fungsi ref. Misalnya, referensikan tabel dengan config { name: "overridden_name" } sebagai ref("overridden_name"). Untuk informasi selengkapnya tentang cara mengganti nama tabel, lihat Mengonfigurasi setelan tabel tambahan.

Jika memiliki beberapa tabel dengan nama yang sama dalam skema yang berbeda, Anda dapat mereferensikan tabel tertentu dengan memberikan dua argumen ke fungsi ref: nama skema dan nama tabel.

Contoh kode berikut menunjukkan fungsi ref dengan dua argumen untuk menentukan tabel dalam skema tertentu:

config { type: "table" }
SELECT * FROM ${ref("schema", "store_clean")}

Anda juga dapat menambahkan dependensi tabel secara manual ke blok config untuk tabel, pernyataan, deklarasi sumber data, atau operasi SQL kustom yang tidak direferensikan dalam fungsi ref dalam pernyataan SELECT. Dataform menjalankan dependensi ini sebelum tabel dependen.

Contoh kode berikut menunjukkan dependensi tabel di blok config:

config { dependencies: [ "unreferenced_table" ] }
SELECT * FROM ...

Untuk informasi selengkapnya tentang pengelolaan dependensi dalam alur kerja Anda, lihat Mendeklarasikan dependensi.

Mereferensikan tabel lain dengan `resolve`

Fungsi resolve memungkinkan Anda mereferensikan deklarasi tabel atau sumber data dalam pernyataan SELECT seperti fungsi ref, tetapi tidak menambahkan referensi sebagai dependensi. Hal ini berarti bahwa objek yang dirujuk menggunakan fungsi resolve tidak memengaruhi eksekusi tabel yang menggunakan fungsi resolve.

Untuk mengetahui informasi selengkapnya tentang fungsi inti Dataform bawaan, lihat Referensi inti Dataform.

Membuat file SQLX untuk definisi tabel

Simpan file SQLX definisi tabel di direktori definitions/. Untuk membuat file SQLX baru di direktori definitions/, ikuti langkah-langkah berikut:

Di konsol Google Cloud, buka halaman Dataform.

Buka Dataform
Untuk membuka repositori, klik nama repositori.
Untuk membuka ruang kerja pengembangan, klik nama ruang kerja.
Di panel Files, di samping definitions/, klik More.
Klik Create file.
Di kolom Add a file path, masukkan nama file, diikuti dengan .sqlx setelah definitions/. Contohnya, definitions/my-table.sqlx

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

Menentukan jenis tabel

Untuk membuat definisi jenis tabel baru, ikuti langkah-langkah berikut:

Di ruang kerja pengembangan, di panel Files, luaskan direktori definitions/.
Pilih file SQLX definisi tabel yang ingin Anda edit.
Di file tersebut, masukkan cuplikan kode berikut:
```
config { type: "TABLE_TYPE" }
```
Ganti TABLE_TYPE dengan salah satu jenis tabel berikut:
- table
- incremental
- view
Opsional: Untuk menentukan tampilan terwujud, masukkan properti materialized di bagian type: "view" dalam format berikut:
```
config {
  type: "view",
  materialized: true
}
```
Untuk mengetahui informasi selengkapnya, lihat ITableConfig.
Opsional: Klik Format.

Menentukan struktur dan dependensi tabel

Untuk menulis pernyataan SELECT definisi tabel dan menentukan struktur serta dependensi tabel, ikuti langkah-langkah berikut:

Di ruang kerja pengembangan, di panel Files, luaskan direktori definitions/.
Pilih file SQLX definisi tabel yang ingin Anda edit.
Di bawah blok config, tulis pernyataan SELECT.
Opsional: Klik Format.

Contoh kode berikut menunjukkan definisi tabel dengan pernyataan SELECT dan fungsi ref:

config { type: "table" }
SELECT
  customers.id AS id,
  customers.first_name AS first_name,
  customers.last_name AS last_name,
  customers.email AS email,
  customers.country AS country,
  COUNT(orders.id) AS order_count,
  SUM(orders.amount) AS total_spent
FROM
  dataform-samples.dataform_sample.crm_customers AS customers
  LEFT JOIN ${ref('order_stats')} orders
    ON customers.id = orders.customer_id

WHERE
  customers.id IS NOT NULL
  AND customers.first_name <> 'Internal account'
  AND country IN ('UK', 'US', 'FR', 'ES', 'NG', 'JP')

GROUP BY 1, 2, 3, 4, 5

Menambahkan dependensi tabel manual

Untuk menambahkan dependensi tabel yang tidak direferensikan dalam pernyataan SELECT, tetapi perlu dieksekusi sebelum tabel saat ini, ikuti langkah-langkah berikut:

Di ruang kerja pengembangan, di panel Files, luaskan direktori definitions/.
Pilih file SQLX definisi tabel yang ingin Anda edit.
Di blok config tabel, masukkan cuplikan kode berikut:
```
dependencies: [ "DEPENDENCY_TABLE", ]
```
Ganti DEPENDENCY_TABLE dengan nama file tabel yang ingin Anda tambahkan sebagai dependensi. Anda dapat memasukkan beberapa nama file.
Opsional: Klik Format.

Contoh kode berikut menunjukkan dua tabel yang ditambahkan sebagai dependensi tabel manual ke blok config file definisi tabel:

config { dependencies: [ "some_table", "some_other_table" ] }

Membuat partisi dan cluster tabel

Bagian ini menunjukkan cara menggunakan inti Dataform untuk membuat partisi dan cluster tabel. BigQuery mendukung tabel berpartisi dan pengelompokan tabel. Untuk mengetahui informasi selengkapnya, lihat Pengantar tabel yang dipartisi dan Membuat dan menggunakan tabel yang dikelompokkan.

Membuat partisi tabel

Untuk membuat partisi tabel, ikuti langkah-langkah berikut:

Buka ruang kerja pengembangan Anda.
Di panel Files, luaskan definitions/.
Buka file SQLX definisi tabel.
Di blok config, tambahkan blok bigquery di bawah deklarasi jenis tabel dalam format berikut:
```
config {
  type: "table",
  bigquery: {
  }
}
```
Di blok bigquery, masukkan cuplikan kode berikut:
```
    partitionBy: "PARTITION_EXPRESSION"
```
Ganti PARTITION_EXPRESSION dengan ekspresi untuk mempartisi tabel.
Opsional: Klik Format.

Contoh kode berikut menunjukkan partisi tabel berdasarkan jam dalam file SQLX definisi tabel:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATETIME_TRUNC(<timestamp_column>, HOUR)"
  }
}

Contoh kode berikut menunjukkan partisi tabel berdasarkan nilai bilangan bulat dalam file SQLX definisi tabel:

config {
  type: "table",
  bigquery: {
    partitionBy: "RANGE_BUCKET(<integer_column>, GENERATE_ARRAY(0, 1000000, 1000))"
  }
}

Menetapkan filter partisi

Untuk menetapkan filter partisi, ikuti langkah-langkah berikut:

Buka ruang kerja pengembangan Anda.
Di panel Files, luaskan definitions/.
Buka file SQLX definisi tabel yang dipartisi.
Di blok bigquery, masukkan cuplikan kode berikut:
```
requirePartitionFilter : true
```
Opsional: Klik Format.

Contoh kode berikut menunjukkan filter partisi yang ditetapkan di blok bigquery file SQLX tabel yang dipartisi:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    requirePartitionFilter : true
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

Untuk informasi selengkapnya tentang filter partisi di BigQuery, lihat Menetapkan atribut filter partisi wajib di tabel berpartisi.

Menetapkan periode retensi data untuk partisi

Untuk mengontrol retensi semua partisi dalam tabel berpartisi, ikuti langkah-langkah berikut:

Buka ruang kerja pengembangan Anda.
Di panel Files, luaskan definitions/.
Buka file SQLX definisi tabel yang dipartisi.
Di blok bigquery, masukkan cuplikan kode berikut:
```
partitionExpirationDays: NUMBER_OF_DAYS
```
Ganti NUMBER_OF_DAYS dengan jumlah hari yang ingin Anda simpan untuk partisi.
Opsional: Klik Format.

Contoh kode berikut menunjukkan periode retensi untuk partisi yang ditetapkan ke 14 hari di blok bigquery file SQLX tabel berpartisi:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    partitionExpirationDays: 14,
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

Membuat cluster tabel

Untuk membuat cluster tabel, ikuti langkah-langkah berikut:

Buka ruang kerja pengembangan Anda.
Di panel Files, luaskan definitions/.
Buka file SQLX definisi tabel.
Di blok bigquery, masukkan cuplikan kode berikut:
```
    clusterBy: ["CLUSTER_COLUMN"]
```
Ganti CLUSTER_COLUMN dengan nama kolom yang ingin Anda gunakan untuk mengelompokkan tabel. Untuk mengetahui informasi selengkapnya, lihat clustering_column_list.
Opsional: Klik Format.

Contoh kode berikut menunjukkan tabel berpartisi yang dikelompokkan menurut kolom name dan revenue:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    clusterBy: ["name", "revenue"]
  }
}
SELECT CURRENT_TIMESTAMP() as ts, name, revenue

Mengonfigurasi tabel inkremental

Bagian ini menunjukkan cara menggunakan inti Dataform untuk mengonfigurasi tabel inkremental.

Tentang tabel inkremental

Dataform memperbarui tabel secara berbeda berdasarkan jenis tabel. Selama setiap eksekusi tabel atau tampilan, Dataform akan mem-build ulang seluruh tabel atau tampilan dari awal.

Saat Anda menentukan tabel inkremental, Dataform akan mem-build tabel inkremental dari awal hanya untuk pertama kalinya. Selama eksekusi berikutnya, Dataform hanya menyisipkan atau menggabungkan baris baru ke dalam tabel inkremental sesuai dengan kondisi yang Anda konfigurasikan.

Dataform hanya menyisipkan baris baru ke kolom yang sudah ada di tabel inkremental. Jika Anda membuat perubahan pada kueri definisi tabel inkremental, misalnya, dengan menambahkan kolom baru, Anda harus membuat ulang tabel dari awal. Untuk melakukannya, saat berikutnya Anda memicu eksekusi tabel, pilih opsi Jalankan dengan pembaruan penuh.

Berikut adalah beberapa kasus penggunaan umum untuk tabel inkremental:

Pengoptimalan performa: Untuk beberapa jenis data, seperti log web atau data analisis, Anda mungkin ingin hanya memproses data baru, bukan memproses ulang seluruh tabel.
Pengurangan latensi: Anda dapat menggunakan tabel inkremental untuk menjalankan alur kerja dengan cepat, tetapi sering, sehingga mengurangi latensi downstream tabel output.
Ringkasan harian: Anda dapat mengonfigurasi tabel inkremental untuk membuat snapshot harian data tabel, misalnya, untuk analisis longitudinal setelan pengguna yang disimpan dalam database produksi.

Memproses subset baris dalam tabel inkremental

Untuk menentukan subkumpulan baris yang akan diproses Dataform selama setiap eksekusi, tambahkan klausa WHERE bersyarat ke file definisi SQLX tabel inkremental. Dalam klausa WHERE, Anda dapat menentukan kondisi inkremental dan kondisi non-inkremental. Dataform menerapkan kondisi inkremental selama eksekusi tabel tanpa pembaruan penuh, dan kondisi non-inkremental selama eksekusi dengan pembaruan penuh.

Untuk mengonfigurasi tabel inkremental, ikuti langkah-langkah berikut:

Buka ruang kerja pengembangan Anda.
Di panel Files, luaskan definitions/.
Buka file SQLX definisi tabel inkremental.
Masukkan klausa WHERE dalam format berikut:
```
config { type: "incremental" }

SELECT_STATEMENT

${when(incremental(), `WHERE INCREMENTAL_CONDITION`, `WHERE NON_INCREMENTAL_CONDITION`) }
```
Ganti kode berikut:
- SELECT_STATEMENT: pernyataan SELECT yang menentukan tabel Anda.
- INCREMENTAL_CONDITION: kondisi yang Anda tentukan dalam klausa WHERE untuk memilih baris yang akan diproses Dataform selama eksekusi tabel tanpa refresh penuh.
- NON_INCREMENTAL_CONDITION: kondisi yang Anda tentukan dalam klausa WHERE untuk memilih baris yang akan diproses Dataform selama eksekusi tabel dengan refresh penuh.
Opsional: Klik Format.

Contoh kode berikut menunjukkan tabel inkremental yang secara bertahap memproses baris tabel productiondb.logs:

config { type: "incremental" }

SELECT timestamp, message FROM ${ref("productiondb", "logs")}

${when(incremental(),
   `WHERE date > (SELECT MAX(date) FROM ${self()}) AND country = "UK"`,
   `WHERE country = "UK"`)}

Contoh kode berikut menunjukkan tabel inkremental yang membuat snapshot tabel productiondb.customers:

config { type: "incremental" }

SELECT CURRENT_DATE() AS snapshot_date, customer_id, name, account_settings FROM ${ref("productiondb", "customers")}

${when(incremental(), `WHERE snapshot_date > (SELECT MAX(snapshot_date) FROM ${self()})`) }

Menggabungkan baris dalam tabel inkremental

Untuk memastikan bahwa tabel inkremental hanya berisi satu baris yang sesuai dengan kombinasi kolom yang dipilih, tetapkan kolom yang dipilih sebagai uniqueKey untuk menggabungkan baris yang memiliki nilai uniqueKey yang sama. Saat memperbarui tabel, Dataform menggabungkan baris dengan nilai uniqueKey yang sama, bukan menambahkannya.

Untuk mengonfigurasi penggabungan dalam tabel inkremental, ikuti langkah-langkah berikut:

Buka ruang kerja pengembangan Anda.
Di panel Files, luaskan definitions/.
Memilih file SQLX definisi tabel inkremental
Di blok config, tetapkan kolom yang dipilih sebagai uniqueKey dalam format berikut:
```
uniqueKey: ["COLUMN_NAME"]
```
Ganti COLUMN_NAME dengan nama kolom yang dipilih.
Opsional: Klik Format.

Contoh kode berikut menunjukkan tabel inkremental dengan kolom transaction_id ditetapkan sebagai uniqueKey untuk memastikan tabel tersebut selalu berisi satu baris:

config {
  type: "incremental",
  uniqueKey: ["transaction_id"]
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

Memfilter baris dalam tabel inkremental

Dalam tabel yang dipartisi inkremental, agar Dataform tidak memindai seluruh tabel untuk menemukan baris yang cocok, tetapkan updatePartitionFilter agar hanya mempertimbangkan subkumpulan kumpulan data.

Contoh kode berikut menunjukkan tabel partisi inkremental dengan penggabungan yang dikonfigurasi dengan menetapkan properti uniqueKey dan updatePartitionFilter:

config {
  type: "incremental",
  uniqueKey: ["transaction_id"],
  bigquery: {
    partitionBy: "DATE(timestamp)",
    updatePartitionFilter:
        "timestamp >= timestamp_sub(current_timestamp(), interval 24 hour)"
  }
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

Menghindari pemindaian tabel penuh saat menyerap dari tabel yang dipartisi

Saat membuat tabel inkremental yang mereferensikan tabel berpartisi, sebaiknya buat kueri tabel untuk menghindari pemindaian tabel lengkap dari tabel berpartisi selama setiap pembaruan inkremental.

Anda dapat membatasi jumlah partisi yang dipindai BigQuery untuk memperbarui tabel inkremental menggunakan ekspresi konstan dalam kueri tabel. Untuk mengubah nilai dari tabel yang dipartisi menjadi ekspresi konstan, gunakan skrip BigQuery untuk mendeklarasikan nilai sebagai variabel dalam blok pre_operations. Kemudian, gunakan variabel sebagai ekspresi konstan dalam klausa WHERE dalam kueri SELECT.

Dengan konfigurasi ini, Dataform akan memperbarui tabel inkremental berdasarkan partisi terbaru dari tabel berpartisi yang dirujuk, tanpa memindai seluruh tabel.

Untuk mengonfigurasi tabel inkremental yang mereferensikan tabel berpartisi dan menghindari pemindaian tabel penuh, ikuti langkah-langkah berikut:

Buka ruang kerja pengembangan Anda.
Di panel Files, luaskan definitions/.
Memilih file SQLX definisi tabel inkremental
Di blok pre_operations, deklarasikan variabel dengan skrip BigQuery.
Filter pernyataan SELECT yang menentukan tabel dengan klausa WHERE yang mereferensikan variabel yang dideklarasikan.
Opsional: Klik Format.

Contoh kode berikut menunjukkan tabel inkremental tempat tabel raw_events yang direferensikan dipartisi oleh event_timestamp:

config {
  type: "incremental",
}

pre_operations {
  DECLARE event_timestamp_checkpoint DEFAULT (
    ${when(incremental(),
    `SELECT max(event_timestamp) FROM ${self()}`,
    `SELECT timestamp("2000-01-01")`)}
  )
}

SELECT
  *
FROM
  ${ref("raw_events")}
WHERE event_timestamp > event_timestamp_checkpoint

Dalam contoh kode sebelumnya, variabel event_timestamp_checkpoint ditentukan dalam blok pre_operations. Variabel event_timestamp_checkpoint kemudian digunakan sebagai ekspresi konstan dalam klausa WHERE.

Mem-build ulang tabel inkremental dari awal dengan pembaruan penuh

Anda dapat memaksa tabel inkremental untuk dibuat ulang dari awal menggunakan antarmuka command line dengan opsi --full-refresh atau opsi Run with full refresh saat memicu eksekusi alur kerja.

Saat Anda memilih opsi refresh penuh, di ruang kerja pengembangan atau dengan menggunakan Dataform CLI, Dataform akan mengabaikan parameter ${when(incremental(), ... } selama eksekusi dan membuat ulang tabel dengan pernyataan CREATE OR REPLACE.

Melindungi tabel inkremental dari refresh penuh

Untuk melindungi tabel inkremental agar tidak dibuat ulang dari awal dan potensi hilangnya data, Anda dapat menetapkan tabel inkremental sebagai protected. Anda mungkin ingin mencegah tabel inkremental di-build ulang jika sumber data Anda bersifat sementara.

Untuk menandai tabel inkremental sebagai protected, ikuti langkah-langkah berikut:

Buka ruang kerja pengembangan Anda.
Di panel Files, luaskan definitions/.
Pilih file SQLX definisi tabel inkremental.
Di blok config, masukkan protected: true.
Opsional: Klik Format.

Contoh kode berikut menunjukkan tabel inkremental yang ditandai sebagai protected:

config {
  type: "incremental",
  protected: true
}
SELECT ...

Menambahkan dokumentasi tabel

Bagian ini menunjukkan cara menambahkan deskripsi tabel beserta kolom dan datanya ke file SQLX inti Dataform.

Anda dapat menambahkan deskripsi tabel, kolom, dan data ke semua jenis tabel di Dataform: tabel, tabel inkremental, dan tampilan.

Anda dapat mendokumentasikan hal berikut:

Tujuan tabel.
Konten atau peran kolom atau kumpulan data dalam tabel.
Hubungan tabel dan tindakan lain dari alur kerja Anda, misalnya, tabel atau tampilan yang bergantung pada tabel saat ini.
Pernyataan yang diterapkan ke tabel.
Pra-operasi atau pasca-operasi yang diterapkan ke tabel.
Pemilik tabel—yaitu, pengguna yang membuatnya. Informasi ini mungkin berguna jika beberapa anggota tim mengerjakan alur kerja.

Menambahkan deskripsi tabel

Untuk menambahkan deskripsi ke tabel dalam file SQLX, ikuti langkah-langkah berikut:

Di konsol Google Cloud, buka halaman Dataform.

Buka Dataform
Pilih repositori.
Pilih ruang kerja pengembangan.
Di panel Files, klik file SQLX definisi tabel yang ingin Anda edit.
Di blok config file, masukkan deskripsi tabel dalam format berikut:
```
description: "Description of the table",
```
Opsional: Klik Format.

Contoh kode berikut menunjukkan deskripsi tabel yang ditambahkan ke blok config file definisi tabel SQLX:

config {
  type: "table",
  description: "Description of the table",
 }

Menambahkan deskripsi kolom dan data

Untuk menambahkan deskripsi setiap kolom dan data ke file SQLX, ikuti langkah-langkah berikut:

Di blok config file definisi tabel, masukkan columns: {}.
Di dalam columns: {}, masukkan deskripsi kolom dalam format berikut:
```
column_name: "Description of the column",
```

Di dalam columns: {}, masukkan deskripsi data dalam format berikut:

  record_name: {
      description: "Description of the record",
      columns: {
        record_column_name: "Description of the record column"
      }
}

Opsional: Klik Format.

Contoh kode berikut menunjukkan deskripsi tabel, kolom, dan data dalam blok config file definisi tabel SQLX:

config {
  type: "table",
  description: "Description of the table.",
  columns: {
    column1_name: "Description of the first column",
    column2_name: "Description of the second column",
    column3_name: "Description of the third column",
    record_name: {
      description: "Description of the record.",
      columns: {
       record_column1_name: "Description of the first record column",
       record_column2_name: "Description of the second record column",
      }
    }
  }
}
SELECT
  "first_column_value" AS column_1_name,
  "second_column_value" AS column_2_name,
  "third_column_value" AS column_3_name,
  STRUCT("first" AS record_column1_name,
    "second" AS record_column2_name) AS record_name

Menggunakan kembali dokumentasi kolom dengan menyertakan

Anda dapat menggunakan kembali deskripsi kolom di Dataform di seluruh alur kerja SQL dengan menyertakan JavaScript. Sebaiknya gunakan kembali dokumentasi kolom jika Anda memiliki beberapa kolom dengan nama dan deskripsi yang sama dalam alur kerja SQL.

Untuk membuat deskripsi kolom yang dapat digunakan kembali, tentukan konstanta include JavaScript dengan nama kolom dan deskripsinya.

Anda dapat menentukan konstanta dengan deskripsi satu kolom, atau konstanta dengan deskripsi kolom atau kumpulan untuk menggunakan kembali deskripsi semua kolom dalam tabel. Untuk informasi selengkapnya tentang cara membuat dan menggunakan include di Dataform, lihat Menggunakan kembali kode di satu repositori dengan include.

Contoh kode berikut menunjukkan beberapa konstanta dengan deskripsi setiap kolom yang ditentukan dalam file JavaScript includes/docs.js:


// filename is includes/docs.js

const user_id = `A unique identifier for a user`;
const age = `The age of a user`;
const creation_date = `The date this user signed up`;
const user_tenure = `The number of years since the user's creation date`;
const badge_count = `The all-time number of badges the user has received`;
const questions_and_answer_count = `The all-time number of questions and answers the user has created`;
const question_count = `The all-time number of questions the user has created`;
const answer_count = `The all-time number of answers the user has created`;
const last_badge_received_at = `The time the user received their most recent badge`;
const last_posted_at = `The time the user last posted a question or answer`;
const last_question_posted_at = `The time the user last posted an answer`;
const last_answer_posted_at = `The time the user last posted a question`;

module.exports = {
   user_id,
   age,
   creation_date,
   user_tenure,
   badge_count,
   questions_and_answer_count,
   question_count,
   answer_count,
   last_badge_received_at,
   last_posted_at,
   last_question_posted_at,
   last_answer_posted_at,
};

Contoh kode berikut menunjukkan konstanta user_id dan age, yang ditentukan dalam includes/docs.js, yang digunakan dalam file definisi tabel SQLX definitions/my_table.sqlx untuk membuat dokumentasi untuk kolom yang dipilih dalam tabel:

config {
  type: "table",
  description: "Table description.",
  columns: {
    user_id: docs.user_id,
    column2_name: "Description of the second column",
    column3_name: "Description of the third column",
    age: docs.age,
  }
}

SELECT ...

Contoh kode berikut menunjukkan konstanta dengan kumpulan deskripsi kolom yang ditentukan dalam file JavaScript includes/docs.js:


// filename is includes/docs.js

const columns = {
    user_id = `A unique identifier for a user`,
    age = `The age of a user`,
    creation_date = `The date this user signed up`,
    user_tenure = `The number of years since the user's creation date`,
    badge_count = `The all-time number of badges the user has received`,
    questions_and_answer_count = `The all-time number of questions and answers the user has created`,
    question_count = `The all-time number of questions the user has created`,
    answer_count = `The all-time number of answers the user has created`,
    last_badge_received_at = `The time the user received their most recent badge`,
    last_posted_at = `The time the user last posted a question or answer`,
    last_question_posted_at = `The time the user last posted an answer`,
    last_answer_posted_at = `The time the user last posted a question`,
}


module.exports = {
  columns
};

Contoh kode berikut menunjukkan konstanta columns, yang ditentukan dalam includes/table_docs.js dan digunakan dalam file definisi tabel SQLX definitions/my_table.sqlx untuk membuat dokumentasi untuk semua kolom dalam tabel:

config { type: "table",
description: "My table description",
columns: docs.columns
}

SELECT 1 AS one

Langkah berikutnya

Untuk mempelajari cara mengonfigurasi setelan tabel tambahan, lihat Mengonfigurasi setelan tabel tambahan.
Untuk mempelajari cara menguji data tabel dengan pernyataan, lihat Menguji tabel dengan pernyataan.
Untuk mempelajari cara menentukan tabel dengan JavaScript, lihat Membuat alur kerja Dataform dengan JavaScript.
Untuk mempelajari cara menggunakan kembali kode dengan menyertakan, lihat Menggunakan kembali kode di satu repositori dengan menyertakan.
Untuk mempelajari cara menggunakan antarmuka command line Dataform, lihat Menggunakan CLI Dataform.

Membuat tabel

Sebelum memulai

Peran yang diperlukan

Membuat tabel

Tentang definisi tabel

Mereferensikan dependensi dengan ref

Mereferensikan tabel lain dengan resolve

Membuat file SQLX untuk definisi tabel

Menentukan jenis tabel

Menentukan struktur dan dependensi tabel

Menambahkan dependensi tabel manual

Membuat partisi dan cluster tabel

Membuat partisi tabel

Menetapkan filter partisi

Menetapkan periode retensi data untuk partisi

Membuat cluster tabel

Mengonfigurasi tabel inkremental

Tentang tabel inkremental

Memproses subset baris dalam tabel inkremental

Menggabungkan baris dalam tabel inkremental

Memfilter baris dalam tabel inkremental

Menghindari pemindaian tabel penuh saat menyerap dari tabel yang dipartisi

Mem-build ulang tabel inkremental dari awal dengan pembaruan penuh

Melindungi tabel inkremental dari refresh penuh

Menambahkan dokumentasi tabel

Menambahkan deskripsi tabel

Menambahkan deskripsi kolom dan data

Menggunakan kembali dokumentasi kolom dengan menyertakan

Langkah berikutnya

Mereferensikan dependensi dengan `ref`

Mereferensikan tabel lain dengan `resolve`