Dataform API로 컴파일 재정의 구성

이 문서에서는 Dataform API를 사용하여 컴파일 재정의로 컴파일 결과를 만들고 실행하는 방법을 보여줍니다.

Dataform API 컴파일 재정의 정보

SQL 워크플로를 실행하기 위해 Dataform은 코드를 SQL로 컴파일하여 컴파일 결과를 만듭니다. 그런 다음 워크플로 호출 중 Dataform이 BigQuery에서 컴파일 결과를 실행합니다.

기본적으로 Dataform은 dataform.json 파일의 설정을 사용하여 컴파일 결과를 만듭니다. 개발 수명 주기의 여러 단계에서 실행된 데이터를 격리하려면 컴파일 재정의로 기본 설정을 재정의하면 됩니다.

터미널에서 Dataform API 요청을 전달하면 컴파일 재정의로 단일 컴파일 결과를 만들고 실행할 수 있습니다. 작업공간 또는 선택한 Git committish의 컴파일 결과를 만들 수 있습니다.

컴파일 재정의로 컴파일 결과를 만들려면 Dataform API compilationResults.create 요청을 보내야 합니다. 요청에서 Dataform이 컴파일 결과로 컴파일되려면 작업공간 또는 Git commitish를 소스로 지정해야 합니다. compilationResults.create 요청의 CodeCompilationConfig 객체에서 컴파일 재정의를 구성할 수 있습니다.

그런 다음 Dataform API workflowInvocations.create 요청에서 생성된 컴파일 결과를 실행할 수 있습니다.

Dataform API를 사용하여 다음 컴파일 재정의를 구성할 수 있습니다.

Google Cloud 프로젝트: Dataform이 컴파일 결과를 실행하는 Google Cloud 프로젝트로, dataform.json에 defaultDatabase로 설정합니다.
테이블 프리픽스: 컴파일 결과의 모든 테이블 이름에 추가된 커스텀 프리픽스입니다.
스키마 서픽스: dataform.json의 defaultSchema로 또는 테이블의 config 블록에 schema 매개변수에 정의된 테이블 스키마에 추가된 커스텀 서픽스입니다.
컴파일 변수 값: 컴파일 결과에 사용할 컴파일 변수의 값입니다. 컴파일 변수를 사용하여 테이블을 조건부로 실행할 수 있습니다.

하나의 컴파일 결과에만 사용할 수 있는 Dataform API 컴파일 재정의에 대한 대안으로 Google Cloud 콘솔에서 작업공간 컴파일 재정의를 구성할 수 있습니다.

Dataform에서 컴파일 재정의를 구성하는 다른 방법에 대해 알아보려면 코드 수명 주기 소개를 참조하세요.

시작하기 전에

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

Dataform으로 이동
저장소를 선택하거나 만듭니다.
개발 작업공간을 선택하거나 만듭니다.

컴파일 결과 소스 설정

Dataform API compilationResults.create 요청을 전송하려면 컴파일 결과의 소스를 지정해야 합니다.

Dataform 작업공간 또는 Git 브랜치, Git 태그 또는 Git 커밋 SHA를 compilationResults.create 요청의 소스로 설정할 수 있습니다.

작업공간을 컴파일 결과 소스로 설정

compilationResults.create 요청에서 workspace 속성을 다음 형식의 선택된 Dataform 작업공간 경로로 채웁니다.

{
"workspace": "projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY_NAME/workspaces/WORKSPACE_NAME"
}

다음을 바꿉니다.

PROJECT_NAME: Google Cloud 프로젝트 이름
LOCATION: dataform.json에 설정된 Dataform 저장소의 위치
REPOSITORY_NAME: Dataform 저장소의 이름
WORKSPACE_NAME: Dataform 작업공간 이름

다음 코드 샘플은 "sales-test"라는 작업공간으로 설정된 compilationResults.create 요청의 workspace 속성을 보여줍니다.

{
"workspace": "projects/analytics/locations/europe-west4/repositories/sales/workspaces/sales-test"
}

Git commitish를 컴파일 결과 소스로 설정

compilationResults.create 요청에서 gitCommitish 속성을 다음 형식의 선택된 Git 브랜치, 태그 또는 커밋 SHA로 채웁니다.
```
{
  "gitCommitish": "GIT_COMMITISH"
}
```

GIT_COMMITISH를 컴파일 결과의 선택된 Git 브랜치, Git 태그 또는 Git 커밋 SHA로 바꿉니다.

다음 코드 샘플은 "staging"으로 설정된 compilationResults.create 요청의 gitCommitish 속성을 보여줍니다.

{
  "gitCommitish": "staging"
}

기본 Google Cloud 프로젝트 재정의

개발에 사용되는 프로젝트와 별개로 Google Cloud 프로젝트에서 스테이징 또는 프로덕션 테이블을 만들려면 Dataform API compilationResults.create 요청의 CodeCompilationConfig 객체에 다른 Google Cloud 프로젝트 ID를 전달할 수 있습니다.

compilationResults.create 요청에 별도의 기본 프로젝트 ID를 전달하면 dataform.json 파일에 구성된 기본 Google Cloud 프로젝트 ID가 재정의되지만 개별 테이블에 구성된 Google Cloud 프로젝트 ID는 재정의되지 않습니다.

기본 Google Cloud 프로젝트 ID를 재정의하려면 defaultDatabase 속성을 CodeCompilationConfig 객체에서 다음 형식의 선택된 Google Cloud 프로젝트 ID로 설정합니다.
```
{
  "codeCompilationConfig": {
    "defaultDatabase": "PROJECT_NAME"
  }
}
```

PROJECT_NAME을 컴파일 결과에 설정하려는 Google Cloud 프로젝트 ID로 바꿉니다.

테이블 프리픽스 추가

컴파일 결과에서 테이블을 빠르게 식별하려면 Dataform API compilationResults.create 요청의 CodeCompilationConfig 객체에 테이블 프리픽스를 전달하여 컴파일 결과의 모든 테이블 이름에 프리픽스를 추가합니다.

테이블 프리픽스를 추가하려면 CodeCompilationConfig 객체에서 tablePrefix 속성을 다음 형식으로 설정합니다.

{
  "codeCompilationConfig": {
    "tablePrefix": "PREFIX",
  }
}

PREFIX를 추가할 서픽스(예: _staging)로 바꿉니다. 예를 들어 dataform.json의 defaultSchema가 dataform으로 설정된 경우 Dataform은 dataform_staging 스키마에 테이블을 만듭니다.

스키마 서픽스 추가

개발, 스테이징, 프로덕션 데이터를 분리하려면 Dataform API compilationResults.create 요청의 CodeCompilationConfig 객체에 스키마 서픽스를 전달하여 컴파일 결과의 스키마에 서픽스를 추가합니다.

스키마 서픽스를 추가하려면 CodeCompilationConfig 객체에서 schemaSuffix 속성을 다음 형식으로 설정합니다.

{
  "codeCompilationConfig": {
    "schemaSuffix": "SUFFIX",
  }
}

SUFFIX를 추가할 서픽스(예: _staging)로 바꿉니다. 예를 들어 dataform.json의 defaultSchema가 dataform으로 설정된 경우 Dataform은 dataform_staging 스키마에 테이블을 만듭니다.

참고: CodeCompilationConfig schemaSuffix 매개변수는 개별 파일의 config 블록에 구성된 스키마를 재정의합니다.

컴파일 변수를 사용하여 선택한 파일을 조건부로 실행

특정 실행 설정에서만 선택된 테이블을 실행하려면 실행 설정의 컴파일 변수를 만든 다음 Dataform API compilationResults.create 요청의 CodeCompilationConfig 객체에 이 값을 전달합니다.

Dataform API를 사용하여 특정 실행 설정에서 테이블을 조건부로 실행하려면 다음 단계를 따르세요.

컴파일 변수를 만들어 선택한 테이블에 추가합니다.
Dataform API 컴파일 요청의 codeCompilationConfig 블록에 다음 형식의 YOUR_VARIABLE 및 VALUE 키-값 쌍을 설정합니다.
```
{
 "codeCompilationConfig": {
   "vars": {
     "YOUR_VARIABLE": "VALUE"
   }
 }
}
```
YOUR_VARIABLE을 변수 이름(예: executionSetting)으로 바꿉니다.
VALUE를 선택한 테이블에 설정된 when 조건을 충족하는 이 컴파일 결과의 변수 값으로 바꿉니다.

다음 코드 샘플은 Dataform API 컴파일 요청에 전달된 executionSetting 변수를 보여줍니다.

{
  "gitCommitish": "staging",
  "codeCompilationConfig": {
    "vars": {
      "executionSetting": "staging"
    }
  }
}

컴파일 재정의로 컴파일 결과 실행

compilationResults.create 요청으로 생성된 컴파일 결과를 실행하려면 workflowInvocations.create 요청의 compilationResults.create 요청에서 반환된 컴파일 결과 ID를 전달합니다.

다음 코드 샘플은 workflowInvocations.create 요청에 전달된 컴파일 결과 ID를 보여줍니다.

{
  "compilationResult": "projects/my-project-name/locations/europe-west4/repositories/my-repository-name/compilationResults/7646b4ed-ac8e-447f-93cf-63c43249ff11"
}

다음 단계

Dataform에서 컴파일 재정의를 구성하는 방법에 대한 자세한 내용은 코드 수명 주기 소개를 참조하세요.
Dataform API에 대한 자세한 내용은 Dataform API를 참조하세요.
Google Cloud 콘솔을 사용하여 저장소의 모든 작업공간에 대한 컴파일 재정의를 구성하는 방법은 작업공간 컴파일 재정의 구성을 참조하세요.