Tambahkan dokumentasi tabel

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:

  1. Di Konsol Cloud, buka halaman Dataform.

    Buka halaman Dataform

  2. Pilih repositori.

  3. Pilih ruang kerja pengembangan.

  4. Di panel Files, klik file SQLX definisi tabel yang ingin diedit.

  5. Dalam blok config file, masukkan deskripsi tabel dalam format berikut:

    description: "Description of the table",

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

  1. Dalam blok config file definisi tabel Anda, masukkan columns: {}.

  2. Di dalam columns: {}, masukkan deskripsi kolom dalam format berikut:

    column_name: "Description of the column",

  3. 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"
      }
}

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

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