Menambahkan dokumentasi tabel

Dokumen 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 data dalam tabel.
  • Hubungan tabel dan objek lain dari alur kerja SQL 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, yang berarti 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 guna 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 ke project, folder, dan organisasi.

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

Menambahkan deskripsi tabel

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

  1. Di Cloud Console, 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 Anda edit.

  5. Di 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",
 }

Menambahkan deskripsi kolom dan data

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

  1. Di blok config file definisi tabel, 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 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 di Dataform dengan menyertakan

Anda dapat menggunakan kembali deskripsi kolom di seluruh alur kerja SQL 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 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 variabel dan fungsi dengan include di 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 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, yang 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 selanjutnya