Knowledge Catalog를 사용하면 메타데이터를 저장하고 관리할 수 있습니다. Dataform 저장소는 기본적으로 추가 구성 없이 Knowledge Catalog에서 사용할 수 있습니다. Knowledge Catalog는 Dataform 저장소에서 다음 메타데이터를 자동으로 검색합니다.
데이터 애셋 이름
데이터 애셋 상위 항목
데이터 애셋 위치
데이터 애셋 유형
해당 Google Cloud 프로젝트
서드 파티 저장소 소스
서비스 계정
시작하기 전에
-
Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
프로젝트를 선택하거나 만드는 데 필요한 역할
- 프로젝트 선택: 프로젝트를 선택하는 데 특정 IAM 역할이 필요하지 않습니다. 역할이 부여된 프로젝트를 선택할 수 있습니다.
-
프로젝트 만들기: 프로젝트를 만들려면
resourcemanager.projects.create권한이 포함된 프로젝트 생성자 역할(roles/resourcemanager.projectCreator)이 필요합니다. 역할 부여 방법 알아보기
-
Dataplex API 및 Data Lineage API가 아직 사용 설정되지 않은 경우 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면
serviceusage.services.enable권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할(roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할(roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할 부여 방법 알아보기 필요한 Identity and Access Management(IAM) 권한이 있는지 확인합니다.
필요한 역할
Knowledge Catalog에서 Dataform 저장소를 관리하고 데이터 계보를 보려면 Dataform 리소스에 대한 액세스 권한을 부여하는 사전 정의된 Dataform 역할과 필요한 Knowledge Catalog 역할이 있어야 합니다.
다음 표에는 각 주 구성원이 Dataform 데이터 계보를 기록하고 보는 데 필요한 역할이 나와 있습니다.
| 작업 | 주 구성원 | 필요한 역할 | 역할을 부여할 위치 |
|---|---|---|---|
| 워크플로 호출에서 계보 기록 | 저장소, 출시 버전 구성 또는 워크플로 구성의 커스텀 서비스 계정입니다. 커스텀 서비스 계정이 설정되지 않은 경우 Dataform 서비스 에이전트(service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com)입니다. |
데이터 계보 이벤트 생성자(roles/datalineage.producer) |
저장소가 포함된 프로젝트 |
| Dataform CLI에서 계보 기록 | CLI에서 사용하는 애플리케이션 기본 사용자 인증 정보 | Data Lineage 이벤트 제작자(roles/datalineage.producer) |
각 출력 테이블의 프로젝트 |
| 계보 그래프 보기 | 계보를 보는 사용자 | 데이터 계보 뷰어(roles/datalineage.viewer) |
계보가 기록되는 프로젝트와 계보를 보는 프로젝트 |
| 계보 그래프에서 Dataform 열기 | 계보를 보는 사용자 | Dataform 뷰어(roles/dataform.viewer) 또는 dataform.repositories.get 및 dataform.workflowInvocations.get 권한 |
저장소가 포함된 프로젝트 |
| BigQuery 테이블 세부정보 보기 | 계보를 보는 사용자 | BigQuery 데이터 뷰어(roles/bigquery.dataViewer) 또는 bigquery.tables.get 권한 |
테이블을 저장하는 프로젝트 |
| BigQuery 작업 세부정보 보기 | 계보를 보는 사용자 | BigQuery 리소스 뷰어(roles/bigquery.resourceViewer) 또는 bigquery.jobs.get 권한 |
작업을 실행하는 프로젝트 |
Data Lineage 이벤트 제작자 역할에는 계보를 기록하는 데 필요한 datalineage.locations.processOpenLineageMessage 권한이 포함되어 있습니다.
Knowledge Catalog에서 메타데이터 관리
Knowledge Catalog는 Dataform 저장소를 다음 항목 값을 사용해 항목으로 로깅합니다.
- 시스템 항목 그룹
- Dataform 저장소의 시스템 항목 그룹은
@dataform입니다. Knowledge Catalog에서 저장소 항목의 세부정보를 보려면dataform시스템 항목 그룹을 확인해야 합니다. 항목 그룹의 모든 항목 목록을 보는 방법에 관한 안내는 Knowledge Catalog 문서의 항목 그룹 세부정보 보기를 참조하세요. - 시스템 항목 유형
- Dataform 저장소의 시스템 항목 유형은
dataform-repository입니다. Dataform 저장소의 세부정보를 보려면dataform-repository시스템 항목 유형을 확인해야 합니다. 선택한 항목 유형의 세부정보를 보는 방법에 관한 안내는 Knowledge Catalog 문서의 항목 유형의 세부정보 보기를 참조하세요. 선택한 항목의 세부정보를 보는 방법에 관한 안내는 Knowledge Catalog 문서의 항목 세부정보 보기를 참조하세요.
애셋 검색
Knowledge Catalog에서 데이터 애셋을 검색하는 방법에 관한 안내는 Knowledge Catalog 문서의 Knowledge Catalog에서 데이터 애셋 검색을 참조하세요.
저장소 주석 추가
Knowledge Catalog의 Dataform 저장소에 추가 컨텍스트를 제공하려면 관점으로 Dataform 항목에 주석을 추가하면 됩니다.
Dataform 저장소의 시스템 관점 유형은 dataform-repository입니다.
관점으로 항목에 주석을 추가하는 방법에 관한 안내는 Knowledge Catalog 문서의 관점 관리 및 메타데이터 보강을 참조하세요.
Knowledge Catalog에서 데이터 계보 추적
Dataform은 Dataform 워크플로 및 BigQuery 파이프라인에서 실행하는 작업의 데이터 계보를 Knowledge Catalog에 보고합니다. 실행된 각 작업에 대해 Knowledge Catalog 및 BigQuery의 계보 그래프는 작업이 읽는 테이블과 작업이 쓰는 테이블 간의 Dataform 프로세스를 보여줍니다. 계보를 보고하기 위해 SQLX 파일을 변경할 필요가 없습니다.
다음 태스크에 Dataform 데이터 계보를 사용할 수 있습니다.
영향 분석: 테이블을 변경하기 전에 모든 다운스트림 작업과 테이블을 식별합니다.
근본 원인 분석: 잘못된 데이터를 작성한 작업 및 워크플로 호출로 추적합니다.
거버넌스: 프로젝트 간에 데이터가 흐르는 방식과 데이터를 이동한 파이프라인을 보여줍니다.
엔드 투 엔드 계보: BigQuery, Managed Service for Apache Airflow, Managed Service for Apache Spark, Dataflow의 계보와 함께 Dataform 계보를 하나의 그래프로 볼 수 있습니다.
데이터 계보 작동 방식
Dataform은 작업이 시작되면 OpenLineage START 이벤트를 Data Lineage API로 전송합니다. 작업이 종료되면 Dataform은 COMPLETE, FAIL 또는 ABORT 이벤트를 전송합니다. 각 Dataform 작업은 Knowledge Catalog에서 BIGQUERY_PIPELINES 소스 유형의 프로세스로 표시되며, 각 작업 실행은 해당 프로세스의 실행으로 표시됩니다.
다음 표에서는 계보를 보고하는 Dataform 작업 유형을 설명합니다.
| 작업 유형 | 보고서 계보 |
|---|---|
hasOutput: true를 사용하는 테이블, 뷰, 증분 테이블, 구체화된 뷰, 어설션, 속성 그래프, 데이터 준비, 작업 |
예. 프로세스, 실행, 테이블 간 계보 링크를 보고합니다. |
hasOutput: true 없이 작업 |
처리 및 실행만 가능합니다. 입력 및 출력이 비어 있으므로 테이블 간 계보 링크가 생성되지 않습니다. |
| 선언 | 아니요. 선언은 다른 작업의 입력으로만 표시됩니다. |
| 노트북, SQL 단위 테스트 | 아니요 |
계보를 보고해도 워크플로 호출이 실패하지 않습니다. Data Lineage API가 사용 중지되었거나, 권한이 없거나, 할당량이 초과된 경우 Dataform은 계보 보고를 건너뛰고 워크플로 호출이 변경 없이 계속됩니다.
Dataform은 각 작업의 BigQuery 처리 위치의 리전 엔드포인트에 계보를 작성합니다. 리전 엔드포인트를 사용할 수 없는 경우 Dataform은 계보를 전역 엔드포인트에 씁니다.
Dataform 워크플로가 데이터 계보에 매핑되는 방식
다음 표에서는 Dataform 실행 항목이 Knowledge Catalog 데이터 계보 정보 모델에 매핑되는 방식을 설명합니다.
| 데이터 계보 객체 | Dataform 상응 항목 |
|---|---|
| 프로세스 | Dataform 작업 |
| 실행 | 워크플로 호출에서 작업 1회 실행 |
| 계보 이벤트 | 해당 실행의 입력 테이블에서 출력 테이블로 연결되는 링크 |
데이터 계보 설정
보고 데이터를 보고하도록 Dataform을 설정하려면 다음 단계를 따르세요.
Dataform 저장소가 포함된 프로젝트와 사용자가 계보를 보는 프로젝트에서 Data Lineage API(
datalineage.googleapis.com)를 사용 설정합니다.저장소가 포함된 프로젝트에서 워크플로를 실행하는 ID에 Data Lineage 이벤트 제작자 역할(
roles/datalineage.producer)을 부여합니다.저장소, 출시 버전 구성 또는 워크플로 구성에서 커스텀 서비스 계정을 사용하는 경우 커스텀 서비스 계정에 역할을 부여합니다.
커스텀 서비스 계정이 설정되지 않은 경우 Dataform 서비스 에이전트(
service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com)에 역할을 부여합니다.
Google 계정의 사용자 인증 정보로 실행되는 워크플로 호출은 계보를 보고하지 않습니다.
데이터 계보 사용 설정 또는 사용 중지
초기 출시 기간에는 데이터 계보 보고가 선택사항입니다.
저장소 또는 BigQuery 파이프라인의 데이터 계보 보고를 제어하려면 workflow_settings.yaml 파일에서 lineage.enabled 속성을 설정합니다.
Google Cloud 콘솔에서 Dataform 페이지로 이동합니다.
저장소를 선택한 후 개발 작업공간을 선택합니다.
파일 창에서
workflow_settings.yaml파일을 엽니다.데이터 계보 보고를 사용 설정하려면 다음
lineage블록을 추가합니다.lineage: enabled: true계보가 기본적으로 사용 설정된 후 저장소를 데이터 계보 보고에서 선택 해제하려면
enabled를false로 설정합니다.lineage: enabled: false변경사항을 저장소에 커밋하고 푸시합니다.
전체 프로젝트의 데이터 계보 보고를 중지하려면 프로젝트에서 Data Lineage API를 사용 중지합니다. API를 사용 중지하면 프로젝트의 다른 서비스에서 데이터 계보 보고도 중지됩니다.
데이터 계보 보기
Dataform 작업이 생성하는 테이블의 데이터 계보를 보려면 다음 단계를 따르세요.
Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.
탐색기 창에서 프로젝트와 데이터 세트를 펼친 후 Dataform 작업에서 생성하는 테이블을 선택합니다.
계보 탭을 클릭합니다.
작업, 저장소, 실행을 보려면 Dataform 프로세스 노드를 선택합니다.
Dataform에서 저장소를 열려면 Dataform에서 열기를 클릭합니다.
계보 그래프 탐색에 대한 자세한 내용은 Knowledge Catalog에서 데이터 계보 보기를 참조하세요.
Dataform CLI에서 데이터 계보 보고
Dataform CLI의 로컬 또는 CI 실행에서 데이터 계보를 보고하려면 workflow_settings.yaml에서 lineage.enabled: true를 설정하거나 다음 명령어를 실행합니다.
dataform run --emit-lineage
--emit-lineage 및 --no-emit-lineage 플래그는 단일 실행에 대해 lineage.enabled 설정을 재정의합니다.
Dataform CLI는 애플리케이션 기본 사용자 인증 정보를 사용하고 각 출력 테이블의 프로젝트에 계보를 기록합니다. 각 프로젝트에서 Data Lineage API를 사용 설정하고 사용자 인증 정보에 Data Lineage 이벤트 제작자 역할(roles/datalineage.producer)을 부여합니다. CLI는 [lineage] 프리픽스를 사용하여 계보 메시지를 stderr에 작성합니다.
CLI에서 계보를 보고하는 방법에 대한 자세한 내용은 GitHub의 Dataform CLI 참조를 확인하세요.
데이터 계보 문제 해결
다음 표에서는 일반적인 데이터 계보 문제와 해결 방법을 설명합니다.
| 증상 | 가능한 원인 | 수정 |
|---|---|---|
| 계보 탭에는 Dataform 노드가 표시되지 않습니다. | Data Lineage API가 사용 중지되었습니다. | 저장소가 포함된 프로젝트와 계보를 보는 프로젝트에서 API를 사용 설정합니다. |
| 저장소는 계보를 보고하지 않습니다. | 워크플로를 실행하는 ID에 데이터 계보 이벤트 제작자 역할이 없습니다. | 커스텀 서비스 계정 또는 Dataform 서비스 에이전트에 roles/datalineage.producer을 부여합니다. |
| 사용자 인증 정보로 실행되는 워크플로 호출은 계보를 보고하지 않습니다. | 계보 보고는 사용자 인증 정보를 지원하지 않습니다. | 커스텀 서비스 계정으로 워크플로를 실행합니다. |
| 역할이 부여되었지만 저장소에서 계보를 보고하지 않습니다. | Dataform은 커스텀 서비스 계정으로 작동할 수 없습니다. | Dataform 서비스 에이전트에 커스텀 서비스 계정에 대한 서비스 계정 토큰 생성자 역할(roles/iam.serviceAccountTokenCreator)을 부여합니다. |
| 저장소 하나가 계보를 보고하지 않습니다. | 저장소가 선택 해제되었습니다. | workflow_settings.yaml에서 lineage.enabled: false가 삭제됨 |
| 일부 실행에 계보가 누락되었습니다. | Data Lineage API 할당량이 초과되었습니다. | 워크플로 실행을 분산하거나 더 높은 할당량을 요청하세요. |
| CLI 실행에서 일부 테이블의 계보를 보고하지 않습니다. | 출력 테이블의 프로젝트에서 API가 사용 설정되지 않았거나 역할이 부여되지 않았습니다. | API를 사용 설정하고 해당 프로젝트에서 역할을 부여합니다. |
| Dataform에서 열기를 클릭하면 권한 오류가 반환됩니다. | 사용자에게 Dataform에 대한 액세스 권한이 없습니다. | 사용자에게 Dataform 뷰어 역할(roles/dataform.viewer)을 부여합니다. |
워크플로 호출에서 첫 번째 권한 또는 API 오류가 발생하면 Dataform은 해당 워크플로 호출의 나머지 부분에 대한 계보 보고를 중지합니다. 다음 워크플로 호출에서 계보를 다시 보고하려고 시도합니다.
데이터 계보 문제에 대해 지원팀에 문의할 때는 워크플로 호출 ID, 프로젝트 ID, 리전을 포함하세요.
워크플로 호출의 계보 로그 보기
Cloud Logging에서 Dataform은 계보 로그 항목을 dataform.googleapis.com/lineage_emission 로그에 기록합니다. 각 항목에는 workflowInvocationId, actionTarget, eventType 필드가 포함됩니다.
워크플로 호출의 계보 로그를 보려면 다음 단계를 따르세요.
Google Cloud 콘솔에서 워크플로 호출의 세부정보 페이지를 엽니다.
로그 보기를 클릭합니다.
jsonPayload.workflowInvocationId에서 워크플로 호출로 필터링된 로그와 함께 Logging이 열립니다.
각 계보 로그 항목의 outcome 필드에는 다음 값 중 하나가 있습니다.
SUCCEEDED: Data Lineage API가 이벤트를 수락했습니다. 이러한 항목의 심각도는DEBUG이고eventType은START,COMPLETE,FAIL또는ABORT입니다.SKIPPED: Dataform에서 계보 보고를 건너뛰었습니다. 이러한 항목은INFO심각도를 가지며 워크플로 호출에서 각 이유에 대해 한 번씩 로깅됩니다.skipReason필드는API_DISABLED,PERMISSION_DENIED,EUC_UNSUPPORTED또는AUTHORITY_UNAVAILABLE이고errorMessage필드에는 해결 단계가 포함됩니다.FAILED: 재시도 후 계보 보고가 실패했습니다. 이러한 항목은WARNING심각도를 가지며errorCode및errorMessage필드를 포함합니다.
로그 탐색기에서 건너뛰거나 실패한 계보 보고를 필터링하려면 다음 쿼리를 실행합니다.
log_id("dataform.googleapis.com/lineage_emission")
jsonPayload.outcome=("SKIPPED" OR "FAILED")
Dataform CLI의 데이터 계보 메시지
Dataform CLI는 다음 계보 메시지를 stderr에 작성합니다.
skip_reason=workflow_opt_out:lineage.enabled는false으로 설정됩니다.skip_reason=invocation_override:--no-emit-lineage또는--emit-lineage=false를 사용한 이 실행에 대해 계보 보고가 사용 중지됩니다.skip_reason=dry_run: 드라이 런은 계보를 보고하지 않습니다.skip_reason=api_disabled: Data Lineage API가 사용 설정되지 않았습니다. CLI는 이 실행에서 계보 요청을 더 이상 전송하지 않습니다.skip_reason=permission_denied: 사용자 인증 정보에 데이터 계보 이벤트 생성자 역할(roles/datalineage.producer)이 없습니다. CLI는 이 실행에서 계보 요청을 더 이상 전송하지 않습니다.Failed to emit lineage for action ...: 한 작업에 대해 계보 보고가 실패했습니다. 다른 작업에 대한 계보 보고는 계속됩니다.
제한사항
Knowledge Catalog에서 Dataform 저장소를 관리하고 데이터 계보를 추적하는 데는 다음과 같은 제한사항이 적용됩니다.
Knowledge Catalog에서는 저장소 수준 및 워크플로 수준 항목만 사용할 수 있습니다. SQLX 정의 파일과 같은 Dataform의 개별 파일 수준 코드 애셋은 별도의 항목으로 분류되지 않습니다.
Dataform은 테이블 수준 계보만 보고합니다. 열 수준 계보는 보고되지 않습니다.
선언, 노트북, SQL 단위 테스트는 계보를 보고하지 않습니다. 선언은 다른 작업의 입력으로만 표시됩니다.
hasOutput: true가 없는 작업은 테이블 간 계보 링크 없이 프로세스 및 실행만 보고합니다.Google 계정의 사용자 인증 정보로 실행되는 워크플로 호출은 계보를 보고하지 않습니다. 계보를 보고하려면 커스텀 서비스 계정을 사용합니다.
데이터 계보 보고에는 프로젝트, ID, 리전별 쓰기에 대한 Data Lineage API 할당량이 적용됩니다. 표준 등급에서 할당량은 분당 약 1,000개의 작업입니다.
위치
Knowledge Catalog를 사용하여 모든 Dataform 위치의 Dataform 저장소를 관리할 수 있습니다.
할당량
Knowledge Catalog에서 Dataform 저장소를 관리하는 경우 Knowledge Catalog 할당량 및 한도가 적용됩니다.
가격 책정
Knowledge Catalog에서 Dataform 저장소를 관리하는 경우 Knowledge Catalog 가격 책정이 적용됩니다.
데이터 계보 수집은 Knowledge Catalog 프리미엄 처리 SKU에 따라 청구되며 테이블 간 계보 링크를 작성하는 이벤트만 청구됩니다. 데이터 계보 스토리지는 메타데이터 스토리지 SKU로 청구됩니다. 데이터 계보 비용을 제어하려면 workflow_settings.yaml에서 워크플로를 선택 해제하거나 Data Lineage API를 사용 중지합니다.
다음 단계
- Knowledge Catalog에 대한 자세한 내용은 Knowledge Catalog 문서의 Knowledge Catalog 개요를 참조하세요.