테이블 문서 추가

이 문서에서는 테이블 및 테이블 열과 레코드에 대한 설명을 Dataform 핵심 SQLX 파일에 추가하는 방법을 보여줍니다.

테이블, 증분 테이블, 뷰 등 Dataform의 모든 테이블 유형에 테이블, 열, 레코드 설명을 추가할 수 있습니다.

다음 사항을 문서화하는 것이 좋습니다.

  • 테이블의 용도
  • 테이블의 열 또는 레코드의 콘텐츠 또는 역할
  • SQL 워크플로의 테이블과 기타 객체 관계(예: 현재 테이블에 의존하는 테이블 또는 뷰)
  • 테이블에 적용된 어설션
  • 테이블에 적용되는 사전 작업 또는 사후 작업
  • 테이블 소유자, 즉 테이블을 만든 사용자를 의미합니다. 이 기능은 여러 팀 구성원이 워크플로에 작업하는 경우에 유용할 수 있습니다.

시작하기 전에

시작하기 전에 테이블을 만듭니다.

필요한 역할

테이블을 문서화하는 데 필요한 권한을 얻으려면 관리자에게 작업공간의 Dataform 편집자(roles/dataform.editor) IAM 권한을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

테이블 설명 추가

SQLX 파일의 테이블에 설명을 추가하려면 다음 단계를 따르세요.

  1. Cloud 콘솔에서 Dataform 페이지로 이동합니다.

    Dataform 페이지로 이동

  2. 저장소를 선택합니다.

  3. 개발 작업공간을 선택합니다.

  4. 파일 창에서 수정하려는 테이블 정의 SQLX 파일을 클릭합니다.

  5. 파일의 config 블록에 다음 형식으로 테이블 설명을 입력합니다.

    description: "Description of the table",

  6. (선택사항): 형식을 클릭합니다.

다음 코드 샘플은 SQLX 테이블 정의 파일의 config 블록에 추가된 테이블 설명을 보여줍니다.

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

열 및 레코드 설명 추가

개별 열 및 레코드에 대한 설명을 SQLX 파일에 추가하려면 다음 단계를 따르세요.

  1. 테이블 정의 파일의 config 블록에 columns: {}를 입력합니다.

  2. columns: {} 안에 열 설명을 다음 형식으로 입력합니다.

    column_name: "Description of the column",

  3. columns: {} 내에 레코드 설명을 다음 형식으로 입력합니다.

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

  4. (선택사항): 형식을 클릭합니다.

다음 코드 샘플은 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

include로 Dataform에서 열 문서 재사용

JavaScript include를 통해 SQL 워크플로에서 열 설명을 재사용할 수 있습니다. SQL 워크플로에 이름과 설명이 동일한 열이 여러 개 있는 경우 열 문서를 재사용하는 것이 좋습니다.

상수를 단일 열에 대한 설명으로 정의하거나 상수 또는 집합 또는 열 설명을 사용하여 상수를 정의하여 테이블의 모든 열에 대한 설명을 재사용할 수 있습니다. Dataform에서 include 만들기 및 사용에 대한 자세한 내용은 Dataform에서 include로 변수 및 함수 재사용을 참조하세요.

다음 코드 샘플은 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,
};

다음 코드 샘플은 테이블에서 선택한 열에 대한 문서를 생성하기 위해 definitions/my_table.sqlx SQLX 테이블 정의 파일에서 사용되는 includes/docs.js에 정의된 user_id 및 age 상수를 보여줍니다.

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

다음 코드 샘플은 테이블의 모든 열에 대한 문서를 생성하기 위해 definitions/my_table.sqlx SQLX 테이블 정의 파일에서 사용되는 includes/table_docs.js에 정의된 columns 상수를 보여줍니다.

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

SELECT 1 AS one

다음 단계