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

このドキュメントでは、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 インクルードを使用することで、SQL ワークフロー全体で列の説明を再利用できます。SQL ワークフローで同じ名前と説明の列が複数ある場合は、列のドキュメントを再利用することをおすすめします。

再利用可能な列の説明を作成するには、列の名前と説明を使用して JavaScript include 定数を定義します。

単一の列の説明で定数を定義することも、セットまたは列の説明で定数を定義して、テーブル内のすべての列の説明を再利用することもできます。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 でインクルードを使用して変数と関数を再利用するをご覧ください。
テーブルのパーティションとクラスタを構成する方法については、テーブルのパーティションとクラスタの作成をご覧ください。
アサーションを使用してテーブルデータをテストする方法については、アサーションを使用したテーブルのテストをご覧ください。

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