Dokumen ini menunjukkan cara menambahkan deskripsi tabel beserta kolom dan catatannya ke file SQLX inti Dataform.
Anda dapat menambahkan deskripsi tabel, kolom, dan catatan ke semua jenis tabel di Dataform: tabel, tabel inkremental, dan tampilan.
Anda mungkin ingin mendokumentasikan hal-hal berikut :
- Tujuan tabel.
- Konten atau peran kolom atau catatan dalam tabel.
- Hubungan tabel dan objek lain dalam alur kerja SQL Anda, misalnya, tabel atau tampilan yang bergantung pada tabel saat ini.
- Pernyataan diterapkan ke tabel.
- Pra-operasi atau pasca-operasi yang diterapkan pada tabel.
- Pemilik tabel, artinya pengguna yang membuatnya. Hal ini mungkin berguna jika beberapa anggota tim mengerjakan alur kerja.
Sebelum memulai
Sebelum memulai, buat tabel.
Peran yang diperlukan
Untuk mendapatkan izin yang diperlukan untuk mendokumentasikan tabel,
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.
Tambahkan deskripsi tabel
Untuk menambahkan deskripsi ke tabel dalam {i>file<i} SQLX, ikuti langkah-langkah berikut:
Di Konsol Cloud, buka halaman Dataform.
Pilih repositori.
Pilih ruang kerja pengembangan.
Di panel Files, klik file SQLX definisi tabel yang ingin diedit.
Dalam 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",
}
Tambahkan deskripsi kolom dan catatan
Untuk menambahkan deskripsi masing-masing kolom dan kumpulan data ke file SQLX, ikuti langkah-langkah berikut:
- Dalam blok
config
file definisi tabel Anda, masukkancolumns: {}
. 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 catatan 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
Gunakan kembali dokumentasi kolom di Dataform dengan menyertakan
Anda dapat menggunakan kembali deskripsi kolom di seluruh alur kerja SQL Anda dengan menyertakan JavaScript. Anda mungkin ingin menggunakan kembali dokumentasi kolom jika memiliki beberapa kolom dengan nama dan deskripsi yang sama dalam alur kerja SQL Anda.
- Untuk membuat deskripsi kolom yang dapat digunakan kembali, tentukan konstanta penyertaan JavaScript dengan nama kolom dan deskripsinya.
Anda dapat menentukan konstanta dengan deskripsi satu kolom, atau konstanta dengan deskripsi set atau kolom untuk menggunakan kembali deskripsi dari semua kolom dalam tabel. Untuk informasi selengkapnya tentang membuat dan menggunakan fungsi yang disertakan dalam Dataform, lihat Menggunakan kembali variabel dan fungsi dengan penyertaan dalam Dataform.
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 bagi 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
, yang digunakan dalam file definisi tabel SQLX definitions/my_table.sqlx
untuk membuat dokumentasi bagi semua kolom dalam tabel:
config { type: "table",
description: "My table description",
columns: docs.columns
}
SELECT 1 AS one
Langkah selanjutnya
- Untuk mempelajari cara membuat dan menggunakan fitur yang disertakan dalam Dataform, lihat Menggunakan kembali variabel dan fungsi dengan penyertaan dalam Dataform.
- Untuk mempelajari cara mengonfigurasi partisi dan cluster tabel, lihat Membuat partisi dan cluster tabel.
- Untuk mempelajari cara menguji data tabel dengan pernyataan, lihat Menguji tabel dengan pernyataan.