Dataform 워크플로 설정 구성

이 페이지에서는 특정 저장소의 Dataform SQL 워크플로 처리 설정을 수정하는 방법을 설명합니다.

설정 파일을 편집하여 스키마 이름을 바꾸거나 사용자 정의 컴파일 변수를 저장소에 추가할 수 있습니다.

저장소 설정 정보

각 Dataform 저장소에는 고유한 워크플로 설정 파일이 포함되어 있습니다. 파일에는 Dataform이 BigQuery에 애셋을 게시하는 Google Cloud 프로젝트 ID와 스키마가 포함됩니다. Dataform은 기본 설정을 사용하며, 이러한 기본 설정은 설정 파일을 편집하여 필요에 가장 적합하도록 재정의할 수 있습니다.

Dataform Core 3.0.0부터 워크플로 설정은 기본적으로 workflow_settings.yaml 파일에 저장됩니다. 이전 버전의 Dataform 핵심에서는 워크플로 설정이 dataform.json 파일에 저장되었습니다. Dataform 코어 3.0 workflow_settings.yaml 파일은 dataform.json와 하위 호환됩니다. 계속해서 dataform.json을 사용하여 워크플로 설정을 저장할 수 있습니다. 향후 호환성을 위해 저장소 워크플로 설정을 workflow_settings.yaml 형식으로 이전하는 것이 좋습니다.

workflow_settings.yaml 정보

Dataform Core 3.0에 도입된 workflow_settings.yaml 파일은 Dataform 워크플로 설정을 YAML 형식으로 저장합니다.

다음 코드 샘플은 workflow_settings.yaml 샘플 파일을 보여줍니다.

  defaultProject: my-gcp-project-id
  defaultDataset: dataform
  defaultLocation: australia-southeast2
  defaultAssertionDataset: dataform_assertions

앞의 코드 샘플에서 키-값 쌍은 다음과 같습니다.

• defaultProject: BigQuery Google Cloud 프로젝트 ID입니다.
• defaultDataset: Dataform이 애셋을 만드는 BigQuery 데이터 세트로, 기본적으로 dataform입니다.
• defaultLocation: 기본 BigQuery 데이터 세트 리전입니다. BigQuery 데이터 세트 위치에 대한 자세한 내용은 데이터 세트 위치를 참조하세요. 이 위치에서 Dataform은 코드를 처리하고 실행된 데이터를 저장합니다. 처리 리전은 BigQuery 데이터 세트의 위치와 일치해야 하지만 Dataform 저장소 리전과는 일치하지 않아도 됩니다.
• defaultAssertionDataset: Dataform이 어설션 결과가 있는 뷰를 만드는 BigQuery 데이터 세트로, 기본적으로 dataform_assertions입니다.

workflow_settings.yaml 속성에 대한 자세한 내용은 GitHub의 워크플로 설정의 구성 참조에서 알아보세요.

dataform.projectConfig 객체의 속성으로 Dataform 코드의 workflow_settings.yaml에 정의된 속성에 액세스할 수 있습니다.

workflow_settings.yaml 옵션에서 코드 액세스 가능한 dataform.projectConfig 옵션으로의 다음 매핑이 적용됩니다.

• defaultProject => defaultDatabase.
• defaultDataset => defaultSchema.
• defaultAssertionDataset => assertionSchema.
• projectSuffix => databaseSuffix.
• datasetSuffix => schemaSuffix.
• namePrefix => tablePrefix.

다음 코드 샘플은 뷰의 SELECT 문에서 호출되는 dataform.projectConfig 객체를 보여 줍니다.

  config { type: "view" }
  SELECT ${when(
    !dataform.projectConfig.tablePrefix,
    "table prefix is set!",
    "table prefix is not set!"
  )}

dataform.json 정보

dataform.json 파일은 JSON 형식으로 Dataform 워크플로를 저장합니다.

다음 코드 샘플은 dataform.json 샘플 파일을 보여줍니다.

  {
    "warehouse": "bigquery",
    "defaultDatabase": "my-gcp-project-id",
    "defaultSchema": "dataform",
    "defaultLocation": "australia-southeast2",
    "assertionSchema": "dataform_assertions"
  }

앞의 코드 샘플에서 키-값 쌍은 다음과 같습니다.

• warehouse: BigQuery를 가리키는 포인터로, Dataform이 애셋을 만드는 위치입니다.
• defaultDatabase: BigQuery Google Cloud 프로젝트 ID입니다.
• defaultSchema: Dataform에서 애셋을 만드는 BigQuery 데이터 세트입니다.
• defaultLocation: 기본 BigQuery 데이터 세트 리전입니다. BigQuery 데이터 세트 위치에 대한 자세한 내용은 데이터 세트 위치를 참고하세요. 이 위치에서 Dataform은 코드를 처리하고 실행된 데이터를 저장합니다. 처리 리전은 BigQuery 데이터 세트의 위치와 일치해야 하지만 Dataform 저장소 리전과는 일치하지 않아도 됩니다.
• assertionSchema: Dataform이 어설션 결과가 있는 뷰를 만드는 BigQuery 데이터 세트로, 기본적으로 dataform_assertions입니다.

dataform.projectConfig 객체의 속성으로 프로젝트 코드의 dataform.json에 정의된 속성에 액세스할 수 있습니다.

시작하기 전에

1. 저장소 만들기

2. 저장소에서 개발 작업공간 만들기 및 초기화

필요한 역할

Dataform 설정을 구성하는 데 필요한 권한을 얻으려면 관리자에게 저장소의 Dataform 관리자(roles/dataform.admin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

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

스키마 이름 구성

스키마 이름을 구성하려면 workflow_settings.yaml 파일에서 defaultDataset 및 defaultAssertionSchema 속성을 수정하거나 dataform.json 파일에서 defaultSchema 및 assertionSchema 속성을 수정해야 합니다.

스키마 이름을 구성하려면 다음 단계를 따르세요.

workflow_settings.yaml

1. 개발 작업공간의 파일 창에서 workflow_settings.yaml 파일을 클릭합니다.

2. defaultDataset, defaultAssertionSchema 또는 둘 다의 값을 수정합니다.

다음 코드 샘플은 workflow_settings.yaml 파일에 정의된 커스텀 defaultDataset 이름을 보여줍니다.

  ...
  defaultDataset: mytables
  ...

dataform.json

1. 개발 작업공간의 파일 창에서 dataform.json 파일을 클릭합니다.

2. defaultSchema, assertionSchema 또는 둘 다의 값을 수정합니다.

다음 코드 샘플은dataform.json 파일에 정의된 커스텀 defaultSchema 이름을 보여줍니다.

{
  ...
  "defaultSchema": "mytables",
  ...
}

커스텀 컴파일 변수 만들기

컴파일 변수에는 출시 구성 또는 Dataform API 요청에서 컴파일 재정의로 수정할 수 있는 값이 포함됩니다.

workflow_settings.yaml에서 컴파일 변수를 정의하고 선택한 테이블에 이를 추가한 후, 출시 구성 또는 Dataform API 컴파일 재정의에서 해당 값을 수정하여 조건부로 테이블을 실행할 수 있습니다.

컴파일 변수를 사용하여 조건부로 테이블을 실행하는 방법에 대한 자세한 내용은 Dataform의 코드 수명 주기 소개를 참조하세요.

저장소 전체에서 사용할 수 있는 컴파일 변수를 만들려면 다음 단계를 따르세요.

workflow_settings.yaml

1. Dataform 개발 작업공간으로 이동합니다.
2. 파일 창에서 workflow_settings.yaml 파일을 선택합니다.

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

   "vars": {
     "YOUR_VARIABLE":"VALUE"
   }
   

   다음을 바꿉니다.

   • YOUR_VARIABLE을 변수 이름으로 바꿉니다.
   • VALUE를 컴파일 변수의 기본값으로 바꿉니다.

다음 코드 샘플은 workflow_settings.yaml 파일에서 myVariableValue로 설정된 myVariableName 컴파일 변수를 보여줍니다.

...
vars:
  myVariableName: myVariableValue
...

다음 코드 샘플은 executionSetting 컴파일 변수가 dev로 설정된 workflow_settings.yaml 파일을 보여줍니다.

defaultProject: default_bigquery_database
defaultLocation: us-west1
defaultDataset: dataform_data,
vars:
executionSetting: dev

dataform.json

1. Dataform 개발 작업공간으로 이동합니다.
2. 파일 창에서 dataform.json 파일을 선택합니다.

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

   "vars": {
     "YOUR_VARIABLE":"VALUE"
   }
   

   다음을 바꿉니다.

   • YOUR_VARIABLE을 변수 이름으로 바꿉니다.
   • VALUE를 컴파일 변수의 기본값으로 바꿉니다.

다음 코드 샘플은 dataform.json 파일에서 myVariableValue로 설정된 myVariableName 컴파일 변수를 보여줍니다.

{
  ...
  "vars": {
    "myVariableName": "myVariableValue"
  },
  ...
}

다음 코드 샘플은 executionSetting 컴파일 변수가 dev로 설정된 dataform.json 파일을 보여줍니다.

{
"warehouse": "bigquery",
"defaultSchema": "dataform_data",
"defaultDatabase": "default_bigquery_database".
"defaultLocation":"us-west-1",
"vars": {
"executionSetting":"dev"
}
}

테이블에 컴파일 변수 추가

SQLX 테이블 정의 파일에 컴파일 변수를 추가하려면 다음 단계를 따르세요.

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

3. 파일에서 when 절을 다음 형식으로 입력합니다.

   ${when(dataform.projectConfig.vars.YOUR_VARIABLE === "SET_VALUE", "CONDITION")}
   

   다음을 바꿉니다.

   • YOUR_VARIABLE을 변수 이름으로 바꿉니다(예: executionSetting).
   • SET_VALUE를 변수 값으로 바꿉니다(예: staging).
   • CONDITION을 테이블 실행 조건으로 바꿉니다.

다음 코드 샘플은 when 절과 스테이징 실행 설정에서 데이터의 10%를 실행하는 executionSetting 변수를 포함하는 테이블 정의 SQLX 파일을 보여줍니다.

  select
    *
  from ${ref("data")}
  ${when(
    dataform.projectConfig.vars.executionSetting === "staging",
    "where mod(farm_fingerprint(id) / 10) = 0",
  )}

다음 코드 샘플은 when 절과 myVariableName 변수가 있는 뷰 정의 SQLX 파일을 보여줍니다.

  config { type: "view" }
  SELECT ${when(
    dataform.projectConfig.vars.myVariableName === "myVariableValue",
    "myVariableName is set to myVariableValue!",
    "myVariableName is not set to myVariableValue!"
  )}

워크플로 설정을 workflow_settings.yaml로 이전

워크플로 설정 파일이 향후 Dataform 코어 프레임워크 버전과 호환되도록 하려면 워크플로 설정을 dataform.json 파일에서 workflow_settings.yaml 파일로 이전해야 합니다.

workflow_settings.yaml 파일은 dataform.json 파일을 대체합니다.

Dataform Core가 저장소의 유일한 종속 항목 패키지인 경우 workflow_settings.yaml 파일이 package.json 파일도 대체합니다. package.json를 workflow_settings.yaml로 대체하는 방법에 관한 자세한 내용은 Dataform Core 패키지 관리를 참고하세요.

다음 표는 워크플로 설정 속성의 dataform.json에서 workflow_settings.yaml로의 매핑을 보여줍니다.

dataform.json의 속성	workflow_settings.yaml의 속성	설명
assertionSchema	defaultAssertionDataset	(필수 항목) 어설션의 기본 데이터 세트입니다.
defaultDatabase	defaultProject	(필수 항목) 기본 Google Cloud 프로젝트 이름입니다.
defaultLocation	defaultLocation	(필수 항목) Dataform에서 테이블을 만드는 기본 BigQuery 위치입니다. BigQuery 위치에 대한 자세한 내용은 데이터 세트 위치를 참고하세요.
defaultSchema	defaultDataset	(필수 항목) 기본 데이터 세트입니다.
databaseSuffix	projectSuffix	(선택사항) 모든 Google Cloud 프로젝트 참조에 추가할 접미사입니다.
schemaSuffix	datasetSuffix	(선택사항) 모든 작업 데이터 세트에 추가할 접미사입니다.
tablePrefix	namePrefix	(선택사항) 모든 작업 이름 앞에 추가할 접두사입니다.
vars	vars	(선택사항) 컴파일 중에 프로젝트 코드에서 사용할 수 있는 사용자 정의 변수입니다. key: value 쌍 목록을 포함하는 객체입니다.
warehouse	-	dataform.json에서 요구됨. bigquery로 설정해야 합니다. workflow_settings.yaml에서 사용할 수 없습니다.
-	dataformCoreVersion	dataform.json에서 사용할 수 없습니다. 새 저장소의 경우 기본적으로 workflow_settings.yaml에 설치됩니다. 자세한 내용은 Dataform Core 패키지 관리를 참고하세요.

워크플로 설정을 workflow_settings.yaml로 이전하려면 다음 단계를 따르세요.

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

   Dataform 페이지로 이동

2. 저장소를 선택한 후 작업공간을 선택합니다.

3. 파일 창에서 추가추가를 클릭한 다음 파일 만들기를 클릭합니다.

4. 파일 경로 추가 필드에 workflow_settings.yaml를 입력합니다.

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

6. workflow_settings.yaml 파일에서 YAML 형식으로 매핑된 dataform.json 파일의 설정을 추가합니다.

7. 파일 창에서 dataform.json 옆에 있는 더보기 메뉴를 클릭한 다음 삭제를 클릭합니다.

8. dataform.json 삭제를 확인하려면 삭제를 클릭합니다.

다음 코드 샘플은 dataform.json 파일에 정의된 워크플로 설정을 보여줍니다.

{
  "warehouse": "bigquery",
  "defaultDatabase": "dataform-demos",
  "defaultLocation": "US",
  "defaultSchema": "dataform",
  "assertionSchema": "dataform_assertions"
  "vars": {
    "environmentName": "development"
  }
}

다음 코드 샘플은 위의 dataform.json 파일을 workflow_settings.yaml로 변환한 것을 보여줍니다.

defaultProject: dataform-demos
defaultLocation: US
defaultDataset: dataform
defaultAssertionDataset: dataform_assertions
vars:
    environmentName: "development"

다음 단계

• Dataform Core 패키지를 workflow_settings.yaml로 이전하는 방법은 Dataform Core 패키지 관리 참고하기

• Dataform 프로젝트 설정에 대한 자세한 내용은 IProjectConfig 참조 살펴보기