Dataform 워크플로 설정 구성

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

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

저장소 설정 정보

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

Dataform Core 3.0부터 기본적으로 워크플로 설정은 workflow_settings.yaml 파일에 저장됩니다. 이전 버전의 Dataform Core에서는 워크플로 설정이 dataform.json 파일에 저장됩니다. Dataform Core 3.0 workflow_settings.yaml 파일은 dataform.json과 하위 호환됩니다. 계속해서 dataform.json을 사용하여 Dataform 설정을 구성할 수 있습니다.

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 데이터 세트로, 기본적으로 dataform입니다.
  • 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!"
  )}

다음 단계