테이블 만들기

Dataform에서 테이블은 워크플로를 구성하는 객체 유형 중 하나입니다. 워크플로에 선언된 데이터 소스의 데이터 또는 워크플로의 다른 테이블에서 데이터를 참조하는 테이블을 만들 수 있습니다. Dataform은 테이블 정의를 실시간으로 SQL로 컴파일합니다. 실행을 트리거하면 Dataform이 SQL 코드를 실행하고 BigQuery에서 정의된 테이블을 만듭니다.

type: "table" SQLX 파일에서 다음 테이블 유형을 만들 수 있습니다.

• table: 일반 테이블입니다.
• incremental: 증분 테이블입니다.
• view: 테이블 뷰 자세한 내용은 뷰 소개를 참고하세요.
  • materialized: 구체화된 테이블 뷰입니다. 자세한 내용은 구체화된 뷰 소개를 참조하세요.

테이블 파티션 및 클러스터를 정의할 수도 있습니다.

테이블의 목적 또는 워크플로의 다른 테이블과의 관계를 기록하려면 테이블 또는 선택한 열에 문서를 추가하면 됩니다.

특정 조건에 대해 테이블의 데이터를 테스트하려면 어설션이라는 데이터 품질 테스트 쿼리를 만들면 됩니다. Dataform은 워크플로를 업데이트할 때마다 어설션을 실행하고 어설션이 실패할 경우 알림을 제공합니다.

선택한 테이블의 기본 스키마, 데이터베이스, 이름을 재정의하려면 테이블 설정을 재정의하면 됩니다.

테이블 만들기를 사용 중지하거나 테이블 만들기 전후에 SQL 문을 실행하려면 추가 작업을 구성하면 됩니다.

실행 후 BigQuery에서 테이블을 정리하려면 BigQuery 라벨을 추가하면 됩니다. 자세한 내용은 라벨 소개를 참조하세요.

테이블 열 수준에서 데이터 액세스를 제한하려면 BigQuery 정책 태그를 추가하면 됩니다. 자세한 내용은 열 수준 액세스 제어 소개를 참조하세요.

테이블 실행 전반에서 외부 시스템에서 적용한 BigQuery 데이터 정책 및 데이터 거버넌스 태그 (미리보기)를 유지하려면 액세스 제어 메타데이터를 유지하면 됩니다.

type: "table" SQLX 파일에 테이블을 정의하는 것 외에 type: "operations" SQLX 파일에 빈 SQLX 파일에 커스텀 SQL 쿼리를 정의하여 빈 테이블을 생성할 수 있습니다. 다른 서비스에서 데이터로 채울 수 있도록 빈 테이블을 만들 수 있습니다.

시작하기 전에

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

   Dataform으로 이동

2. 저장소에서 개발 작업공간을 만들고 초기화합니다.

3. 선택사항: 데이터 소스를 선언합니다.

필요한 역할

이 문서의 태스크를 완료하는 데 필요한 권한을 얻으려면 관리자에게 다음의 IAM 역할을 부여해 달라고 요청하세요.

• 작업공간에 대한 Dataform 편집자 (roles/dataform.editor)
• 메타데이터를 Knowledge Catalog에 동기화: 프로젝트 또는 @bigquery 항목 그룹에 대한 Dataplex 카탈로그 편집자 (roles/dataplex.catalogEditor)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

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

액세스 제어 메타데이터를 보존하려면 Dataform 워크플로를 실행하는 서비스 계정에 태스크에 따라 특정 IAM 권한이 있어야 합니다.

• 메타데이터 추출: INFORMATION_SCHEMA.COLUMNS 뷰를 읽으려면 서비스 계정에 데이터 세트 또는 테이블 스키마에 대한 읽기 권한이 있어야 합니다. 이러한 권한은 다음 IAM 역할에 포함되어 있습니다.

  • BigQuery 데이터 뷰어(roles/bigquery.dataViewer)
  • BigQuery 데이터 편집자(roles/bigquery.dataEditor)
  • BigQuery 데이터 소유자(roles/bigquery.dataOwner)
  • BigQuery 관리자(roles/bigquery.admin)

• 데이터 거버넌스 태그 적용: 테이블 및 뷰에 데이터 거버넌스 태그를 연결하고 관리하려면 서비스 계정에 bigquery.tables.createTagBinding 및 bigquery.tables.deleteTagBinding 권한이 필요합니다. 이러한 권한은 다음과 같은 사전 정의된 IAM 역할에 포함되어 있습니다.

  • 태그 사용자(roles/resourcemanager.tagUser)
  • 태그 관리자 (roles/resourcemanager.tagAdmin)

• 데이터 정책 적용: 데이터 정책 (태그 없는 정책 포함)을 만들고 업데이트하려면 서비스 계정에 bigquery.dataPolicies.create 및 bigquery.dataPolicies.update 권한이 필요합니다. 이러한 권한은 다음과 같은 사전 정의된 IAM 역할에 포함되어 있습니다.

  • BigQuery 데이터 정책 관리자(roles/bigquerydatapolicy.admin)
  • BigQuery 관리자(roles/bigquery.admin)

테이블 만들기

이 섹션에서는 Dataform에서 Dataform Core를 사용하여 테이블을 만드는 방법을 보여줍니다.

테이블 정의에 대한 정보

테이블을 정의하려면 테이블 유형을 정의하고 type: "table" SQLX 파일에 SELECT 문을 작성합니다. 그러면 Dataform이 Dataform Core 코드를 SQL로 컴파일하고 SQL 코드를 실행하며 BigQuery에서 정의된 테이블을 만듭니다.

Dataform Core SELECT 문에서 테이블 구조를 정의하고 워크플로의 다른 객체를 참조합니다.

type: "table" SQLX 파일에 테이블을 정의하는 것 외에 type: "operations" SQLX 파일에 커스텀 SQL 쿼리를 정의하여 빈 테이블을 생성할 수 있습니다. 자세한 내용은 빈 테이블 만들기를 참고하세요.

ref로 종속 항목 참조

SELECT 문에서 워크플로 작업을 참조하고 종속 항목으로 자동 추가하려면 ref 함수를 사용하세요. Dataform은 올바른 파이프라인 순서 지정을 확인하기 위해 종속 항목에 영향을 받는 테이블보다 종속 항목을 먼저 실행합니다.

ref 함수는 Dataform의 종속 항목 관리에 중요한 기본 제공 Dataform Core 함수입니다. ref 함수를 사용하면 스키마 및 테이블 이름을 하드 코딩하는 대신 Dataform 워크플로에 정의된 다음 객체를 참조하고 자동으로 종속시킬 수 있습니다.

• 지원되는 모든 테이블 유형의 테이블
• 데이터 소스 선언
• hasOutput 속성이 true로 설정된 커스텀 SQL 작업

Dataform은 ref 함수를 사용하여 만들거나 업데이트할 모든 테이블의 종속 항목 트리를 빌드합니다.

컴파일 후 Dataform은 CREATE, REPLACE, INSERT, MERGE와 같은 상용구 문을 SQL 문에 추가합니다.

다음 코드 샘플은 ref 함수를 사용하는 테이블 정의를 보여줍니다.

config { type: "table" }

SELECT
  order_date AS date,
  order_id AS order_id,
  order_status AS order_status,
  SUM(item_count) AS item_count,
  SUM(amount) AS revenue

FROM ${ref("store_clean")}

GROUP BY 1, 2

ref 함수에서 사용하려는 테이블 또는 데이터 소스 선언의 이름을 제공합니다. 일반적으로 해당 테이블 또는 데이터 소스 선언이 정의된 SQLX 파일의 파일 이름입니다.

테이블 이름이 재정의된 경우 ref 함수에서 재정의된 이름을 사용합니다. 예를 들어 config { name: "overridden_name" }이 있는 테이블을 ref("overridden_name")으로 참조합니다. 자세한 내용은 테이블 설정 재정의 및 재정의된 테이블 이름으로 테이블 참조를 참고하세요.

서로 다른 스키마에 동일한 이름의 테이블이 여러 개 있는 경우 ref 함수에 스키마 이름과 테이블 이름이라는 두 인수를 제공하여 특정 테이블을 참조할 수 있습니다.

다음 코드 샘플은 특정 스키마 내에서 테이블을 지정하는 두 개의 인수가 있는 ref 함수를 보여줍니다.

config { type: "table" }
SELECT * FROM ${ref("schema", "store_clean")}

또한 SELECT 문의 ref 함수에서 참조되지 않는 테이블, 어설션, 데이터 소스 선언 또는 커스텀 SQL 작업의 config 블록에 테이블 종속 항목을 추가할 수도 있습니다. Dataform은 종속 테이블보다 먼저 이러한 종속 항목을 실행합니다.

다음 코드 샘플은 config 블록의 테이블 종속 항목을 보여줍니다.

config { dependencies: [ "unreferenced_table" ] }
SELECT * FROM ...

워크플로의 종속 항목 관리에 대한 자세한 내용은 종속 항목 설정을 참고하세요.

resolve로 다른 테이블 참조

resolve 함수를 사용하면 ref 함수와 같은 SELECT 문에서 테이블 또는 데이터 소스 선언을 참조할 수 있지만 참조를 종속 항목으로 추가할 수는 없습니다. 즉, resolve 함수를 사용하여 참조된 객체는 resolve 함수를 사용하는 테이블 실행에 영향을 미치지 않습니다.

기본 제공 Dataform Core 함수에 대한 자세한 내용은 Dataform Core 참조를 확인하세요.

테이블 정의를 위한 SQLX 파일 만들기

테이블 정의 SQLX 파일을 definitions/ 디렉터리에 저장합니다. definitions/ 디렉터리에 새 SQLX 파일을 만들려면 다음 단계를 따르세요.

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

   Dataform으로 이동

2. 저장소를 열려면 저장소 이름을 클릭합니다.

3. 개발 작업공간을 열려면 작업공간 이름을 클릭합니다.

4. 파일 창에서 definitions/ 옆에 있는 더보기를 클릭합니다.

5. 파일 만들기를 클릭합니다.

6. 파일 경로 추가 필드에 definitions/를 입력하고 파일 이름 다음에 .sqlx를 입력합니다. 예를 들면 definitions/my-table.sqlx입니다.

   파일 이름에는 숫자, 문자, 하이픈, 밑줄만 포함할 수 있습니다.

7. 파일 만들기를 클릭합니다.

테이블 유형 정의

새 테이블 유형 정의를 만들려면 다음 단계를 따르세요.

1. 개발 작업공간의 파일 창에서 definitions/ 디렉터리를 확장합니다.
2. 수정할 테이블 정의 SQLX 파일을 선택합니다.

3. 파일에 다음 코드 스니펫을 입력합니다.

   config { type: "TABLE_TYPE" }
   

   TABLE_TYPE을 다음 테이블 유형 중 하나로 바꿉니다.

   • table
   • incremental
   • view

4. (선택사항): 구체화된 뷰를 정의하려면 type: "view" 아래에 materialized 속성을 다음 형식으로 입력합니다.

   config {
     type: "view",
     materialized: true
   }
   

   자세한 내용은 ITableConfig를 참고하세요.

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

테이블 구조 및 종속 항목 정의

테이블 정의 SELECT 문을 작성하고 테이블 구조와 종속 항목을 정의하려면 다음 단계를 따르세요.

1. 개발 작업공간의 파일 창에서 definitions/ 디렉터리를 펼칩니다.
2. 수정할 테이블 정의 SQLX 파일을 선택합니다.
3. config 블록 아래에 SELECT 문을 작성합니다.
4. (선택사항): 형식을 클릭합니다.

다음 코드 샘플은 SELECT 문과 ref 함수가 있는 테이블 정의를 보여줍니다.

config { type: "table" }
SELECT
  customers.id AS id,
  customers.first_name AS first_name,
  customers.last_name AS last_name,
  customers.email AS email,
  customers.country AS country,
  COUNT(orders.id) AS order_count,
  SUM(orders.amount) AS total_spent
FROM
  dataform-samples.dataform_sample.crm_customers AS customers
  LEFT JOIN ${ref('order_stats')} orders
    ON customers.id = orders.customer_id

WHERE
  customers.id IS NOT NULL
  AND customers.first_name <> 'Internal account'
  AND country IN ('UK', 'US', 'FR', 'ES', 'NG', 'JP')

GROUP BY 1, 2, 3, 4, 5

수동 테이블 종속 항목 추가

SELECT 문에서 참조되지 않지만 현재 테이블 전에 실행해야 하는 테이블 종속 항목을 추가하려면 다음 단계를 따르세요.

1. 개발 작업공간의 파일 창에서 definitions/ 디렉터리를 펼칩니다.
2. 수정할 테이블 정의 SQLX 파일을 선택합니다.

3. 테이블의 config 블록에 다음 코드 스니펫을 입력합니다.

   dependencies: [ "DEPENDENCY_TABLE", ]
   

   DEPENDENCY_TABLE을 종속 항목으로 추가하려는 테이블의 파일 이름으로 바꿉니다. 여러 파일 이름을 입력할 수 있습니다.

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

다음 코드 샘플은 테이블 정의 파일의 config 블록에 수동 테이블 종속 항목으로 추가된 두 테이블을 보여줍니다.

config { dependencies: [ "some_table", "some_other_table" ] }

테이블 설정 재정의

선택한 테이블의 기본 스키마, 데이터베이스, 이름을 재정의할 수 있습니다.

기본적으로 테이블은 workflow_settings.yaml에서 설정한 스키마 및 데이터베이스 구성을 따릅니다. 테이블 이름은 테이블 정의 SQLX 파일의 이름과 동일합니다.

선택한 테이블의 스키마와 이름을 재정의하려면 다음 단계를 따르세요.

1. 개발 작업공간으로 이동합니다.

2. 파일 창에서 definitions/를 펼칩니다.

3. SQLX 테이블 정의 파일을 엽니다.

4. config 블록에 다음 코드 스니펫을 입력합니다.

    {
      schema: "OVERRIDDEN_SCHEMA",
      database: "OVERRIDDEN_DATABASE",
      name: "OVERRIDDEN_NAME"
    }
   

   다음을 바꿉니다.

   • OVERRIDDEN_SCHEMA: 테이블을 만들 BigQuery 데이터 세트입니다.

   • OVERRIDDEN_DATABASE: 테이블을 만들려는 BigQuery 프로젝트의 ID입니다.

   • OVERRIDDEN_NAME: 테이블 이름으로, SQLX 테이블 정의 파일 이름과 다릅니다.

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

자세한 내용은 재정의된 테이블 이름으로 테이블 참조를 참조하세요.

Apache Iceberg 관리 테이블 만들기

Dataform을 사용하여 Iceberg 테이블 형식으로 BigQuery 테이블을 만듭니다. 이러한 테이블을 Iceberg 관리형 테이블이라고 합니다. 필수 역할 및 기타 설정 태스크에 대한 자세한 내용은 Iceberg 관리형 테이블 워크플로의 시작하기 전에 단계를 참조하세요.

Iceberg 테이블 정의 만들기

테이블을 만들려면 테이블 정의 파일의 bigquery 블록에서 Iceberg 구성을 정의합니다.

테이블을 정의하려면 다음 단계를 따르세요.

1. 개발 작업공간으로 이동합니다.
2. 파일 창에서 definitions/를 펼칩니다.
3. 테이블 정의 SQLX 파일을 엽니다.

4. config 블록에 다음 형식의 iceberg 블록이 포함된 bigquery 블록을 추가합니다.

   config {
     type: "table",
     name: "my_table",
     uniqueKey: ["uniquekey"],
     bigquery: {
       iceberg: {
         bucket_name: "BUCKET_NAME"
       }
     }
   }
   

   BUCKET_NAME을 테이블 데이터가 저장된 Cloud Storage 버킷의 이름으로 바꿉니다.

   다른 속성은 선택사항이며 지정되지 않은 경우 기본값이 있습니다. 자세한 내용은 iceberg 속성을 참고하세요.

   각 테이블의 값을 제공하거나 workflow_settings.yaml에서 워크플로 수준 기본값을 설정할 수 있습니다. iceberg 블록에서 속성을 명시적으로 설정하여 워크플로 수준 기본값을 재정의할 수 있습니다.

테이블 파티션 및 클러스터 만들기

이 섹션에서는 Dataform Core를 사용하여 테이블 파티션 및 클러스터를 만드는 방법을 보여줍니다. BigQuery는 파티션을 나눈 테이블과 테이블 클러스터링을 지원합니다. 자세한 내용은 파티션을 나눈 테이블 소개 및 클러스터링된 테이블 만들기 및 사용을 참고하세요.

테이블 파티션 만들기

테이블 파티션을 만들려면 다음 단계를 따르세요.

1. 개발 작업공간으로 이동합니다.
2. 파일 창에서 definitions/를 펼칩니다.
3. 테이블 정의 SQLX 파일을 엽니다.

4. config 블록에서 테이블 유형 선언 아래에 bigquery 블록을 다음 형식으로 추가합니다.

   config {
     type: "table",
     bigquery: {
     }
   }
   

5. bigquery 블록에 다음 코드 스니펫을 입력합니다.

       partitionBy: "PARTITION_EXPRESSION"
   

   PARTITION_EXPRESSION을 테이블 파티션 나누기의 표현식으로 바꿉니다.

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

다음 코드 샘플은 테이블 정의 SQLX 파일에서 시간별로 테이블을 파티셔닝하는 방법을 보여줍니다.

config {
  type: "table",
  bigquery: {
    partitionBy: "DATETIME_TRUNC(<timestamp_column>, HOUR)"
  }
}

다음 코드 샘플은 테이블 정의 SQLX 파일에서 정수 값으로 테이블을 파티셔닝하는 방법을 보여줍니다.

config {
  type: "table",
  bigquery: {
    partitionBy: "RANGE_BUCKET(<integer_column>, GENERATE_ARRAY(0, 1000000, 1000))"
  }
}

파티션 필터 설정

파티션 필터를 설정하려면 다음 단계를 따르세요.

1. 개발 작업공간으로 이동합니다.
2. 파일 창에서 definitions/를 펼칩니다.
3. 파티션을 나눈 테이블 정의 SQLX 파일을 엽니다.

4. bigquery 블록에 다음 코드 스니펫을 입력합니다.

   requirePartitionFilter : true
   

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

다음 코드 샘플은 파티션을 나눈 테이블 SQLX 파일의 bigquery 블록에 설정된 파티션 필터를 보여줍니다.

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    requirePartitionFilter : true
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

BigQuery의 파티션 필터에 대한 자세한 내용은 파티션을 나눈 테이블에 필수 파티션 필터 속성 설정을 참조하세요.

파티션 보관 기간 설정

파티션을 나눈 테이블의 모든 파티션 보관을 제어하려면 다음 단계를 따르세요.

1. 개발 작업공간으로 이동합니다.
2. 파일 창에서 definitions/를 펼칩니다.
3. 파티션을 나눈 테이블 정의 SQLX 파일을 엽니다.

4. bigquery 블록에 다음 코드 스니펫을 입력합니다.

   partitionExpirationDays: NUMBER_OF_DAYS
   

   NUMBER_OF_DAYS를 파티션을 보관할 일수로 바꿉니다.

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

다음 코드 샘플은 파티션을 나눈 테이블 SQLX 파일의 bigquery 블록에서 14일로 설정된 파티션의 보관 기간을 보여줍니다.

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    partitionExpirationDays: 14,
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

테이블 클러스터 만들기

테이블 클러스터를 만들려면 다음 단계를 따르세요.

1. 개발 작업공간으로 이동합니다.
2. 파일 창에서 definitions/를 펼칩니다.
3. 테이블 정의 SQLX 파일을 엽니다.

4. bigquery 블록에 다음 코드 스니펫을 입력합니다.

       clusterBy: ["CLUSTER_COLUMN"]
   

   CLUSTER_COLUMN을 테이블을 클러스터링할 열의 이름으로 바꿉니다. 자세한 내용은 clustering_column_list를 참조하세요.

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

다음 코드 샘플은 name 및 revenue 열로 클러스터링된 파티션을 나눈 테이블을 보여줍니다.

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    clusterBy: ["name", "revenue"]
  }
}
SELECT CURRENT_TIMESTAMP() as ts, name, revenue

증분 테이블 구성

이 섹션에서는 Dataform Core를 사용하여 증분 테이블을 구성하는 방법을 보여줍니다.

증분 테이블 정보

Dataform은 테이블 유형에 따라 테이블을 다르게 업데이트합니다. 테이블 또는 뷰를 실행할 때마다 Dataform은 전체 테이블 또는 뷰를 처음부터 다시 빌드합니다.

증분 테이블을 정의하면 Dataform은 처음에만 증분 테이블을 처음부터 빌드합니다. 후속 실행 중에 Dataform은 구성한 조건에 따라 증분 테이블에 새 행을 삽입하거나 병합합니다.

Dataform은 증분 테이블에 이미 존재하는 열에만 새 행을 삽입합니다. 증분 테이블 정의 쿼리를 변경하는 경우(예: 새 열 추가) 테이블을 처음부터 다시 빌드해야 하는지 결정해야 합니다. 테이블을 다시 빌드하려면 다음에 테이블 실행을 트리거할 때 전체 새로고침으로 실행 옵션을 선택합니다. 다른 옵션은 전체 새로고침 없이 증분 테이블 스키마 변경을 참고하세요.

다음은 증분 테이블의 몇 가지 일반적인 사용 사례입니다.

성능 최적화

웹 로그 또는 분석 데이터와 같은 일부 데이터 유형의 경우 전체 테이블을 다시 처리하는 대신 새 레코드만 처리하는 것이 좋습니다.

지연 시간 감소

증분 테이블을 사용하여 워크플로를 빠르게 자주 실행하여 출력 테이블의 다운스트림 지연 시간을 줄일 수 있습니다.

일일 스냅샷

예를 들어 프로덕션 데이터베이스에 저장된 사용자 설정의 종단 분석을 위해 테이블 데이터의 일일 스냅샷을 만들도록 증분 테이블을 구성할 수 있습니다.

증분 테이블에서 행의 하위 집합 처리

각 실행 중에 Dataform에서 처리할 행의 하위 집합을 확인하려면 증분 테이블 SQLX 정의 파일에 조건부 WHERE 절을 추가합니다. WHERE 절에서는 증분 조건과 비증분 조건을 지정할 수 있습니다. Dataform은 전체 새로고침 없이 테이블 실행 중에 증분 조건을 적용하고 전체 새로고침으로 실행 중에 비증분 조건을 적용합니다.

증분 테이블을 구성하려면 다음 단계를 따르세요.

1. 개발 작업공간으로 이동합니다.
2. 파일 창에서 definitions/를 펼칩니다.
3. 증분 테이블 정의 SQLX 파일을 엽니다.

4. WHERE 절을 다음 형식으로 입력합니다.

   config { type: "incremental" }
   
   SELECT_STATEMENT
   
   ${when(incremental(), `WHERE INCREMENTAL_CONDITION`, `WHERE NON_INCREMENTAL_CONDITION`) }
   

   다음을 바꿉니다.

   • SELECT_STATEMENT: 테이블을 정의하는 SELECT 문입니다.
   • INCREMENTAL_CONDITION: 전체 새로고침 없이 테이블 실행 중에 Dataform이 처리할 행을 선택하기 위해 WHERE 절에 지정하는 조건
   • NON_INCREMENTAL_CONDITION: 전체 새로고침으로 테이블을 실행하는 동안 Dataform이 처리할 행을 선택하기 위해 WHERE 절에 지정하는 조건

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

다음 코드 샘플에서는 productiondb.logs 테이블 행을 점진적으로 처리하는 증분 테이블을 보여줍니다.

config { type: "incremental" }

SELECT timestamp, message FROM ${ref("productiondb", "logs")}

${when(incremental(),
   `WHERE date > (SELECT MAX(date) FROM ${self()}) AND country = "UK"`,
   `WHERE country = "UK"`)}

다음 코드 샘플에서는 productiondb.customers 테이블의 스냅샷을 만드는 증분 테이블을 보여줍니다.

config { type: "incremental" }

SELECT CURRENT_DATE() AS snapshot_date, customer_id, name, account_settings FROM ${ref("productiondb", "customers")}

${when(incremental(), `WHERE snapshot_date > (SELECT MAX(snapshot_date) FROM ${self()})`) }

증분 테이블에서 행 병합

증분 테이블에 선택한 열 조합에 해당하는 행이 하나만 포함되어 있는지 확인하려면 선택한 열을 uniqueKey로 설정하여 동일한 uniqueKey 값을 가진 행을 병합합니다. 테이블을 업데이트할 때 Dataform은 동일한 uniqueKey 값을 가진 행을 추가하는 대신 병합합니다.

증분 테이블에서 병합을 구성하려면 다음 단계를 따르세요.

1. 개발 작업공간으로 이동합니다.
2. 파일 창에서 definitions/를 펼칩니다.
3. 증분 테이블 정의 SQLX 파일을 선택합니다.

4. config 블록에서 선택한 열을 다음 형식으로 uniqueKey로 설정합니다.

   uniqueKey: ["COLUMN_NAME"]
   

   COLUMN_NAME을 선택한 열의 이름으로 바꿉니다.

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

다음 코드 샘플은 항상 하나의 행이 포함되어 있는지 확인하기 위해 transaction_id 열이 uniqueKey로 설정된 증분 테이블을 보여줍니다.

config {
  type: "incremental",
  uniqueKey: ["transaction_id"]
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

증분 테이블에서 행 필터링

증분 파티션을 나눈 테이블에서 Dataform 전체 테이블을 검색하여 일치하는 행을 찾지 않도록 하려면 레코드의 하위 집합만 고려하도록 updatePartitionFilter를 설정합니다.

참고: updatePartitionFilter 속성은 uniqueKey 속성에 하나 이상의 열이 정의된 경우에만 작동합니다. uniqueKey 속성 없이 updatePartitionFilter 속성을 구성하면 Dataform은 병합 전략 대신 삽입 전략을 사용합니다.

다음 코드 샘플은 두 가지 고유한 필터링 유형을 사용하여 updatePartitionFilter 및 uniqueKey 속성으로 병합이 구성된 증분 파티션을 나눈 테이블을 보여줍니다.

• updatePartitionFilter 속성을 사용한 타겟 가지치기: MERGE 작업 중에 타겟 테이블에서 스캔되는 파티션을 제한하여 uniqueKey와 일치하는 행을 찾습니다.
• WHERE 절을 사용한 소스 가지치기: 증분 실행 중에 소스 테이블에서 가져오는 행을 제한합니다. ${when(incremental(), ...)} 함수를 사용하여 달성할 수 있습니다.

config {
  type: "incremental",
  uniqueKey: ["transaction_id"],
  bigquery: {
    partitionBy: "DATE(timestamp)",
    updatePartitionFilter:
        "timestamp >= timestamp_sub(current_timestamp(), interval 24 hour)"
  }
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

파티션을 나눈 테이블에서 수집할 때 전체 테이블 스캔 방지

파티션을 나눈 테이블을 참조하는 증분 테이블을 만들 때는 각 증분 업데이트 중에 파티션을 나눈 테이블의 전체 테이블 스캔을 방지하도록 테이블 쿼리를 빌드하는 것이 좋습니다.

테이블 쿼리에서 상수 표현식을 사용하여 증분 테이블을 업데이트하기 위해 BigQuery에서 스캔하는 파티션 수를 제한할 수 있습니다. 파티션을 나눈 테이블의 값을 상수 표현식으로 변환하려면 BigQuery 스크립팅을 사용하여 값을 pre_operations 블록의 변수로 선언합니다. 그런 다음 변수를 SELECT 쿼리의 WHERE 절에서 상수 표현식으로 사용합니다.

이 구성을 사용하면 Dataform은 전체 테이블을 스캔하지 않고 참조된 파티션을 나눈 테이블의 가장 최신 파티션을 기반으로 증분 테이블을 업데이트합니다.

파티션을 나눈 테이블을 참조하고 전체 테이블 검색을 방지하는 증분 테이블을 구성하려면 다음 단계를 따르세요.

1. 개발 작업공간으로 이동합니다.
2. 파일 창에서 definitions/를 펼칩니다.
3. 증분 테이블 정의 SQLX 파일을 선택합니다.
4. pre_operations 블록에서 BigQuery 스크립트로 변수를 선언합니다.
5. 선언된 변수를 참조하는 WHERE 절을 사용하여 테이블을 정의하는 SELECT 문을 필터링합니다.
6. (선택사항): 형식을 클릭합니다.

다음 코드 샘플은 참조된 raw_events 테이블이 event_timestamp로 파티션을 나눈 증분 테이블을 보여줍니다.

config {
  type: "incremental",
}

pre_operations {
  DECLARE event_timestamp_checkpoint DEFAULT (
    ${when(incremental(),
    `SELECT max(event_timestamp) FROM ${self()}`,
    `SELECT timestamp("2000-01-01")`)}
  )
}

SELECT
  *
FROM
  ${ref("raw_events")}
WHERE event_timestamp > event_timestamp_checkpoint

앞의 코드 샘플에서 event_timestamp_checkpoint 변수는 pre_operations 블록에 정의됩니다. 그런 다음 event_timestamp_checkpoint 변수가 WHERE 절에서 상수 표현식으로 사용됩니다.

전체 새로고침으로 증분 테이블을 처음부터 다시 빌드

--full-refresh 옵션으로 명령줄 인터페이스를 사용하거나 워크플로 실행을 트리거할 때 전체 새로고침으로 실행 옵션을 사용하여 증분 테이블을 강제로 처음부터 다시 빌드할 수 있습니다.

개발 작업공간에서 또는 Dataform CLI를 사용하여 전체 새로고침 옵션을 선택하면 Dataform이 실행 중에 ${when(incremental(), ... } 파라미터를 무시하고 CREATE OR REPLACE 문을 사용하여 테이블을 다시 만듭니다.

전체 새로고침으로부터 증분 테이블 보호

증분 테이블이 처음부터 다시 빌드되고 데이터가 손실될 가능성을 방지하려면 증분 테이블을 protected로 설정하면 됩니다. 데이터 소스가 임시인 경우 증분 테이블이 다시 빌드되지 않도록 방지할 수 있습니다.

증분 테이블을 protected로 표시하려면 다음 단계를 따르세요.

1. 개발 작업공간으로 이동합니다.
2. 파일 창에서 definitions/를 펼칩니다.
3. 증분 테이블 정의 SQLX 파일을 선택합니다.
4. config 블록에 protected: true를 입력합니다.
5. (선택사항): 형식을 클릭합니다.

다음 코드 샘플은 protected로 표시된 증분 테이블을 보여줍니다.

config {
  type: "incremental",
  protected: true
}
SELECT ...

전체 새로고침 없이 증분 테이블 스키마 변경

미리보기

이 제품 또는 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 제품 및 기능은 '현재 상태 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

참고: 의견을 제공하거나 지원을 요청하려면 [e-mail]으로 문의하세요.

onSchemaChange 구성 속성을 사용하여 테이블을 완전히 새로고침하지 않고도 SELECT 쿼리에서 증분 테이블 스키마를 수정할 수 있습니다. 이 속성을 사용하면 이전 데이터를 보존하면서 테이블에 새 열을 추가하거나 테이블에서 기존 열을 삭제할 수 있습니다. 이 방법을 사용하면 데이터 손실을 방지하고 BigQuery에서 수동 업데이트를 피할 수 있습니다.

이 기능을 사용하려면 Dataform core 3.0.11 이상을 설치해야 합니다.

참고: 이 기능은 Dataform CLI에서 사용할 수 없습니다.

onSchemaChange 속성을 설정하면 Dataform은 SELECT 쿼리를 확인하여 열이 추가되거나 삭제되었는지 확인합니다. 그런 다음 Dataform은 onSchemaChange 속성 값으로 지정된 작업을 수행합니다.

onSchemaChange 속성을 설정하려면 다음 단계를 따르세요.

1. 개발 작업공간으로 이동합니다.
2. 파일 창에서 definitions/를 펼칩니다.
3. 증분 테이블 정의 SQLX 파일을 선택합니다.

4. config 블록에 다음 코드 스니펫을 입력합니다.

   onSchemaChange: "ON_CHANGE_ACTION"
   

   ON_CHANGE_ACTION를 다음 작업 중 하나로 바꿉니다.

   • IGNORE (기본값): 추가된 열을 무시하고 누락된 열에 대한 오류를 표시합니다. onSchemaChange이 설정되지 않은 경우 스키마가 변경될 때의 기본 동작입니다.
   • FAIL: Dataform이 스키마 변경사항을 감지하면 작업을 중지하여 스키마를 일관되게 유지합니다.
   • EXTEND: 쿼리의 새 열을 증분 테이블에 추가하고 이전 레코드에 NULL 값을 추가합니다. 쿼리의 원래 스키마에서 열이 삭제되거나 누락된 경우 오류를 표시합니다. 이 설정을 사용하여 런타임 중에 증분 테이블에 새 열을 추가할 수 있습니다.

   • SYNCHRONIZE: 쿼리의 새 열을 증분 테이블에 추가하고 이전 레코드에 NULL 값을 추가합니다. 원래 스키마에 있었지만 현재 쿼리에는 없는 열을 삭제합니다.

     주의: SYNCHRONIZE 작업은 실행취소할 수 없으며 이 옵션으로 열을 삭제하면 데이터가 손실될 수 있습니다.
     참고: 파티셔닝된 열과 클러스터링된 열을 삭제하면 부정적인 결과가 발생할 수 있으므로 이러한 열의 삭제는 지원되지 않습니다. 파티셔닝되거나 클러스터링된 열이 삭제된 경우 ALTER TABLE DROP COLUMN 문으로 처리됩니다. Dataform은 파티션을 나눈 열이나 클러스터링된 열에서 ALTER TABLE DROP COLUMN 문이 실행되지 않도록 검사하거나 유효성 검사를 실행하지 않습니다. 따라서 이러한 열을 삭제하는 경우 신중하게 진행하고 잠재적인 부정적인 결과를 인지해야 합니다.

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

다음 코드 샘플은 onSchemaChange 속성에 EXTEND 작업이 설정된 증분 테이블을 보여줍니다.

config {
    type: "incremental",
    onSchemaChange: "EXTEND",
}
SELECT ...

테이블 문서 추가

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

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

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

• 테이블의 용도
• 테이블의 열 또는 레코드의 콘텐츠 또는 역할
• 테이블과 워크플로의 다른 작업(예: 현재 테이블에 종속된 테이블 또는 뷰)의 관계
• 테이블에 적용된 어설션입니다.
• 테이블에 적용된 사전 작업 또는 사후 작업입니다.
• 테이블의 소유자. 즉, 테이블을 만든 사용자입니다. 이 정보는 여러 팀원이 워크플로에서 작업하는 경우에 유용할 수 있습니다.

Knowledge Catalog의 메타데이터 추가

BigQuery의 표준 메타데이터(예: 데이터 세트, 테이블, 뷰)는 Knowledge Catalog에서 자동으로 사용할 수 있습니다.

.sqlx 파일의 구성 블록에서 직접 테이블 및 뷰의 커스텀 메타데이터를 정의할 수도 있습니다. 작업이 완료되면 Dataform은 Knowledge Catalog에 대한 메타데이터 동기화를 자동으로 시작합니다. 이 보강 프로세스는 SQLX 구성에 정의된 시맨틱 메타데이터로 Knowledge Catalog를 업데이트합니다.

메타데이터 키를 사용하여 Knowledge Catalog의 정보를 지정합니다. 강화 프로세스는 다음 메타데이터 구조를 지원합니다.

• 개요: 항목의 문서 및 요약 텍스트입니다. Dataform Core 버전 3.0.37 이상이 필요합니다.
• 일반 관점: 테이블 시스템 및 유형 정보와 같은 시맨틱 세부정보입니다. Dataform Core 버전 3.0.52 이상이 필요합니다.

다음 구성 예시에서는 Knowledge Catalog의 테이블 구성에 개요 및 일반 메타데이터 관점을 추가하는 방법을 보여줍니다.

config {
  type: "table",
  metadata: {
    overview: "This table provides standardized trip data.",
    extraProperties: {
        generic: {
              system: "BigQuery",
              type: "table"
        }
      }
  }
}

메타데이터 업데이트 상태를 확인하려면 Dataform 워크플로의 경우 작업공간 실행 로그 검사를, BigQuery 파이프라인의 경우 이전 수동 실행 보기를 참조하세요.

동기화된 메타데이터를 확인하려면 Knowledge Catalog에서 애셋을 검색하면 됩니다. 자세한 내용은 리소스 검색을 참고하세요.

테이블 설명 추가

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

1. Google 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로 열 문서 재사용

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

• 재사용 가능한 열 설명을 만들려면 열 이름과 설명으로 JavaScript include 상수를 정의합니다.

단일 열 설명이 있는 상수를 정의하거나 열 설명 집합이 있는 상수를 정의하여 테이블의 모든 열 설명을 재사용할 수 있습니다. Dataform에서 include 만들기 및 사용에 대한 자세한 내용은 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
};

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

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

SELECT 1 AS one

BigQuery 라벨 추가

이 섹션에서는 Dataform의 테이블에 라벨을 추가하는 방법을 보여줍니다.

BigQuery는 리소스에 라벨을 추가하는 기능을 지원합니다. BigQuery의 라벨에 대한 자세한 내용은 라벨 소개를 참고하세요.

Dataform에서 테이블에 BigQuery 라벨을 추가하려면 테이블 정의 SQLX 파일의 config 블록에 있는 bigquery 블록에 라벨을 추가합니다.

테이블 정의 파일에 BigQuery 라벨을 추가하려면 다음 단계를 따르세요.

1. 개발 작업공간으로 이동합니다.
2. 파일 창에서 definitions/를 펼칩니다.
3. SQLX 테이블 정의 파일을 선택합니다.

4. config 블록에서 다음 형식으로 라벨을 추가합니다.

   bigquery: {
       labels: {
         LABEL1: "VALUE_OF_LABEL1"
       }
     }
   

   다음을 바꿉니다.

   • LABEL1: 라벨 이름
   • VALUE_OF_LABEL1: 라벨 값

5. (선택사항): 특수문자가 포함된 이름으로 라벨을 추가하려면 라벨 이름을 따옴표("") 안에 입력합니다.

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

다음 코드 샘플은 파티션을 나눈 테이블 정의 SQLX 파일의 bigquery 블록에 추가된 department:shipping 및 cost-center:logistics 라벨을 보여줍니다.

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    labels: {
      department: "shipping",
      "cost-center": "logistics"
    }
  }
}

SELECT CURRENT_TIMESTAMP() AS ts

액세스 제어 메타데이터 보존

참고: 자동 거버넌스 보존에는 Dataform Core 3.0.62 이상이 필요합니다.

Dataform이 객체를 다시 만드는 워크플로 작업(예: 전체 새로고침 중 표준 테이블, 뷰 또는 증분 테이블)을 실행할 때 일반적으로 BigQuery에서 CREATE OR REPLACE 문을 생성하여 객체 스키마와 데이터를 업데이트합니다. BigQuery에서 기본적으로 테이블 교체 작업은 외부 데이터 거버넌스 시스템에서 적용한 데이터 정책 및 데이터 거버넌스 태그 (프리뷰)와 같은 기존 열 수준 액세스 제어 메타데이터를 자동으로 삭제합니다.

preserveGovernanceControls 옵션을 사용 설정하면 워크플로 실행 전반에서 태그가 없는 데이터 정책을 비롯한 기존 BigQuery 데이터 정책과 데이터 거버넌스 태그를 자동으로 유지하도록 Dataform을 구성할 수 있습니다. 이 옵션을 사용 설정하면 Dataform은 실행 중에 다음 시퀀스를 수행합니다.

1. INFORMATION_SCHEMA.COLUMNS 뷰에서 기존 열 메타데이터를 백업합니다.
2. 중간 빈 스테이징 테이블을 만듭니다.
3. 중간 테이블에 보안 정책을 다시 적용합니다.
4. 데이터로 테이블을 채웁니다.
5. 원자적 테이블 스왑을 수행하여 원래 테이블을 대체합니다.

표에 자동 거버넌스 보존 사용 설정

개별 테이블, 증분 테이블 또는 뷰에 대해 데이터 정책 및 데이터 거버넌스 태그의 자동 보존을 사용 설정하려면 객체의 SQLX 정의 파일의 config 블록에서 preserveGovernanceControls 매개변수를 true로 설정합니다.

개별 테이블에 거버넌스 보존을 구성하려면 다음을 수행합니다.

1. 개발 작업공간으로 이동합니다.
2. 파일 창에서 definitions/를 펼칩니다.
3. SQLX 테이블 정의 파일을 선택합니다.
4. config 블록에 preserveGovernanceControls: true를 입력합니다.
5. (선택사항): 형식을 클릭합니다.

다음 코드 샘플은 거버넌스 보존이 사용 설정된 테이블 정의를 보여줍니다.

config {
  type: "table",
  preserveGovernanceControls: true
}

SELECT
  customer_id,
  email,
  phone_number
FROM
  ${ref("raw_customers")}

모든 테이블에 자동 거버넌스 보존 사용 설정

저장소의 workflow_settings.yaml 파일에서 preserveGovernanceControls 매개변수를 true로 설정하여 저장소의 모든 테이블, 증분 테이블, 뷰에 대해 자동화된 거버넌스 보존을 프로젝트 전체 기본 동작으로 사용 설정할 수 있습니다.

프로젝트 전체 기본값을 설정하려면 다음 예와 같이 preserveGovernanceControls 매개변수를 workflow_settings.yaml 파일에 추가합니다.

defaultProject: my-gcp-project-id
defaultDataset: my_dataform_dataset
defaultLocation: US
defaultAssertionDataset: my_dataform_assertions
dataformCoreVersion: 3.0.62
preserveGovernanceControls: true

workflow_settings.yaml 파일에서 전역적으로 거버넌스 보존을 사용 설정하는 경우 이 동작을 재정의하고 개별 테이블의 config 블록에서 preserveGovernanceControls 파라미터를 false로 설정하여 특정 테이블의 보존을 사용 중지할 수 있습니다.

사후 작업을 사용하여 행 액세스 정책 다시 적용

거버넌스 보존을 사용 설정하면 BigQuery 데이터 정책 및 데이터 거버넌스 태그와 같은 열 수준 메타데이터가 자동으로 보호되지만 행 액세스 정책은 자동으로 복원되지 않습니다. 객체 대체는 기존 행 수준 보안 규칙을 삭제하므로 SQLX 테이블 정의 파일의 post_operations 블록 내에 SQL DDL 문을 정의하여 테이블 생성 후 행 액세스 정책을 다시 적용할 수 있습니다.

다음 코드 샘플은 테이블의 post_operations 블록에서 행 액세스 정책을 다시 적용하는 방법을 보여줍니다.

config {
  type: "table",
}

SELECT
  bike_id,
  start_time,
  duration
FROM
  ${ref("raw_trips")}

post_operations {
  CREATE ROW ACCESS POLICY my_policy
  ON ${self()}
  GRANT TO ('serviceAccount:sa-name@example-gcp-project.')
  FILTER USING (bike_id LIKE 'US-%');
}

제한사항

거버넌스 보존 기능을 사용할 때는 다음 제한사항을 고려하세요.

• 스키마 열 삭제 SQLX 테이블 정의에서 열이 삭제되면 Dataform은 복원 단계에서 삭제된 열과 연결된 백업된 데이터 정책 및 태그를 무시합니다.
• 스키마 열 이름 바꾸기 SQLX 테이블 정의에서 기존 열의 이름을 바꾸면 Dataform에서 이전 태그 또는 정책 연결을 새 열 이름에 매핑할 수 없습니다. 따라서 이러한 열의 기존 태그와 정책이 손실되거나 바뀌므로 이름을 바꾼 열에 태그와 정책을 수동으로 다시 적용해야 합니다.
• 파티션 나누기 및 클러스터링 변경사항 preserveGovernanceControls를 사용하는 기존 테이블의 파티셔닝 또는 클러스터링을 변경하는 것은 지원되지 않습니다. BigQuery는 교체를 거부합니다. 이 문제를 해결하려면 테이블을 삭제하고 워크플로를 다시 실행합니다. 다시 생성된 테이블에 열 수준 데이터 정책과 데이터 거버넌스 태그를 수동으로 다시 적용해야 합니다.
• 파티션 만료 삭제. 구성에서 partitionExpirationDays 속성을 삭제해도 기존 테이블에서 파티션 만료가 삭제되지 않습니다. 기존 테이블에서 파티션 만료를 삭제하려면 옵션을 선택한 값으로 명시적으로 설정하거나 테이블을 수동으로 변경해야 합니다.
• 표 유형 실행이 완료되면 테이블이 테이블 클론 (INFORMATION_SCHEMA.TABLES의 table_type = 'CLONE')으로 보고됩니다. 표준 테이블처럼 작동하며 클론 메타데이터에 표시된 기본 테이블은 더 이상 존재하지 않습니다.
• 테이블 수준 메타데이터 및 행 액세스 정책 테이블 수준 태그와 행 수준 액세스 정책은 실행 간에 보존되지 않습니다. SQLX 테이블 정의 파일의 post_operations 블록 내에 SQL DDL 문을 정의하여 테이블 생성 후 행 액세스 정책을 다시 적용할 수 있습니다.
• 비트랜잭션 테이블 스왑 BigQuery DDL 작업은 트랜잭션이 아닙니다. 원자적 이름 바꾸기 시퀀스 중간에 워크플로 실행이 실패하면 대상 테이블이 중간 상태로 남아 있는 경우(예: 테이블 이름이 영구적으로 TABLE_NAME_old로 변경되거나 df_tmp_intermediate로 남아 있는 경우) 수동 개입이 필요할 수 있습니다.
• 정책 태그. 자동 거버넌스 보존은 BigQuery 정책 태그를 지원하지 않습니다. 대신 BigQuery 데이터 거버넌스 태그 (미리보기)와 데이터 정책을 열에 추가하여 기본 SQL 통합을 사용하세요.

스토리지 비용 고려사항

preserveGovernanceControls가 사용 설정되면 Dataform은 실행할 때마다 (또는 증분 테이블의 전체 새로고침마다) 임시 스테이징 테이블을 통해 테이블을 다시 빌드합니다. BigQuery에서 테이블을 다시 만드는 경우와 마찬가지로 테이블 데이터의 이전 버전은 데이터 세트의 구성된 기간(기본적으로 7일) 동안 시간 이동에 보관된 후 7일의 장애 안전 기간이 이어집니다.

논리적 스토리지 청구는 BigQuery의 기본 청구 모델인 반면 물리적 스토리지 청구는 데이터 세트별로 구성되는 선택 설정입니다. 데이터 세트에서 물리적 스토리지 청구를 사용하는 경우 이 보관된 시간 이동 및 장애 안전 데이터는 활성 테이블 외에 추가로 청구됩니다. 따라서 자주 재빌드되는 대규모 테이블은 스토리지 비용을 눈에 띄게 증가시킬 수 있습니다.

이 비용을 줄이려면 다음을 수행합니다.

• 데이터 세트의 시간 이동 기간을 최소 2일로 단축합니다.
• 전체 다시 빌드가 자주 발생하지 않도록 증분 테이블을 사용합니다.
• 데이터 세트의 논리적 및 물리적 스토리지 청구를 비교하여 물리적 청구가 여전히 더 비용 효율적인 옵션인지 확인합니다.

참고: 시간 이동 기간이 짧을수록 삭제되거나 수정된 데이터를 복구할 수 있는 기간도 줄어들며 안전 조치 기간은 단축할 수 없습니다.

다음 단계

• 어설션으로 테이블 데이터를 테스트하는 방법은 데이터 품질 테스트를 참조하세요.
• JavaScript로 테이블을 정의하는 방법을 알아보려면 JavaScript만으로 워크플로 만들기를 참조하세요.
• include를 사용하여 코드를 재사용하는 방법은 include를 사용하여 단일 저장소에서 코드 재사용을 참고하세요.
• Dataform 명령줄 인터페이스를 사용하는 방법은 Dataform CLI 사용을 참조하세요.