テーブルドキュメントを追加する

このドキュメントでは、テーブルとその列とレコードの説明を Dataform コア SQLX ファイルに追加する方法について説明します。

Dataform のすべてのテーブルタイプ（テーブル、増分テーブル、ビュー）にテーブル、列、レコードの説明を追加できます。

次の内容を文書化する場合があります。

テーブルの目的。
テーブル内の列またはレコードの内容または役割。
SQL ワークフローのテーブルとその他のオブジェクト（現在のテーブルに依存するテーブルやビューなど）の関係。
テーブルに適用されるアサーション。
テーブルに適用される前オペレーションまたは後オペレーション。
テーブルのオーナー（テーブルを作成したユーザー）。これは、複数のチームメンバーがワークフローに取り組んでいる場合に便利です。

始める前に

必要なロール

テーブルを文書化するために必要な権限を取得するには、ワークスペースに対する Dataform 編集者（roles/dataform.editor）IAM ロールの付与を管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセスを管理するをご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

テーブルの説明を追加する

SQLX ファイル内のテーブルに説明を追加するには、次の手順を行います。

Cloud コンソールで、[Dataform] ページに移動します。

[Dataform] ページに移動
リポジトリを選択します。
開発ワークスペースを選択します。
[ファイル] ペインで、編集するテーブル定義 SQLX ファイルをクリックします。
ファイルの config ブロックに、次の形式でテーブルの説明を入力します。
```
description: "Description of the table",
```
省略可: [書式] をクリックします。

次のコードサンプルは、SQLX テーブル定義ファイルの config ブロックに追加されたテーブルの説明を示しています。

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

列とレコードの説明を追加する

個々の列とレコードの説明を SQLX ファイルに追加する手順は次のとおりです。

テーブル定義ファイルの config ブロックに「columns: {}」と入力します。
columns: {} 内に、次の形式で列の説明を入力します。
```
column_name: "Description of the column",
```

columns: {} 内に、次の形式でレコードの説明を入力します。

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

省略可: [書式] をクリックします。

次のコードサンプルは、SQLX テーブル定義ファイルの config ブロック内のテーブル、列、レコードの説明を示しています。

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

インクルードを使用して Dataform の列ドキュメントを再利用する

JavaScript の include を使用して、SQL ワークフローの列の説明を再利用できます。SQL ワークフローに同じ名前と説明の列が複数ある場合は、列のドキュメントを再利用できます。

再利用可能な列の説明を作成するには、列の名前とその説明を使用して JavaScript インクルード定数を定義します。

単一の列の説明で定数を定義するか、セットまたは列の説明で定数を定義して、テーブルのすべての列の説明を再利用できます。Dataform でのインクルードの作成と使用の詳細については、Dataform でインクルードを使用して変数と関数を再利用するをご覧ください。

次のコードサンプルは、includes/docs.js JavaScript ファイルで定義された個々の列の説明を含む複数の定数を示しています。


// 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,
};

次のコードサンプルは、includes/docs.js で定義された user_id 定数と age 定数を示しています。これは、テーブル内の選択した列のドキュメントを生成するために、definitions/my_table.sqlx SQLX テーブル定義ファイルで使用されます。

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

次のコードサンプルは、includes/docs.js JavaScript ファイルで定義された一連の列の説明を持つ定数です。


// 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
};

次のコードサンプルは、includes/table_docs.js で定義されている columns 定数を示しています。このテーブルは、definitions/my_table.sqlx SQLX テーブル定義ファイルでテーブル内のすべての列に関するドキュメントを生成するために使用されます。

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

SELECT 1 AS one

次のステップ

Dataform でインクルードを作成して使用する方法については、Dataform でインクルードを使用して変数と関数を再利用するをご覧ください。
テーブルのパーティションとクラスタを構成する方法については、テーブルパーティションとクラスタを作成するをご覧ください。
アサーションを使用してテーブルデータをテストする方法については、アサーションを使用してテーブルをテストするをご覧ください。

テーブル ドキュメントを追加する