오픈소스 Dataform CLI 사용

이 문서에서는 오픈소스 Dataform 명령줄 인터페이스(CLI)를 사용하여 터미널을 통해 SQL 워크플로를 로컬로 개발하는 방법을 보여줍니다.

오픈소스 Dataform CLI를 사용하면 Google Cloud 외부에서 로컬로 Dataform Core를 초기화, 컴파일, 테스트, 실행할 수 있습니다.

Dataform은 Dataform CLI와 상응하는 명령어를 실행하는 데 사용할 수 있는 Docker 이미지를 배포합니다.

Dataform CLI는 애플리케이션 기본 사용자 인증 정보(ADC)를 지원합니다. ADC를 사용하면 애플리케이션 코드를 수정할 필요 없이 로컬 개발 또는 프로덕션과 같은 다양한 환경에서 애플리케이션에 사용자 인증 정보를 제공할 수 있습니다. ADC를 사용하려면 먼저 ADC에 사용자 인증 정보를 제공해야 합니다.

시작하기 전에

Dataform CLI를 설치하기 전에 NPM을 설치합니다.

Dataform CLI 설치

Dataform CLI를 설치하려면 다음 명령어를 실행합니다.
```
npm i -g @dataform/cli@^3.0.0-beta
```

Dataform 프로젝트 초기화

새 Dataform 프로젝트를 초기화하려면 프로젝트 디렉터리 내에서 다음 명령어를 실행합니다.
```
dataform init . PROJECT_NAME DEFAULT_LOCATION
```
다음을 바꿉니다.
- PROJECT_NAME: 프로젝트의 이름
- DEFAULT_LOCATION: Dataform이 BigQuery 데이터를 쓸 리전입니다. BigQuery 리전에 대한 자세한 내용은 BigQuery 위치를 참조하세요.

Dataform 업데이트

Dataform 프레임워크를 업데이트하려면 workflow_settings.yaml 파일에서 dataformCoreVersion을 업데이트한 다음 NPM 설치를 다시 실행합니다.
```
npm i
```

Dataform CLI 업데이트

Dataform CLI 도구를 업데이트하려면 다음 명령어를 실행합니다.
```
npm i -g @dataform/cli@^3.0.0-beta.2
```

사용자 인증 정보 파일 만들기

Dataform은 원격 서비스에 연결하고 디스크에 .df-credentials.json 파일을 만들기 위해 사용자 인증 정보 파일이 필요합니다.

경고: 소스 제어 시스템을 사용하는 경우 이러한 액세스 사용자 인증 정보를 보호하기 위해 df-credentials.json 파일을 커밋하지 마세요. .df-credentials.json 파일을 .gitignore에 추가하는 것이 좋습니다.

사용자 인증 정보 파일을 만들려면 다음 단계를 수행합니다.

다음 명령어를 실행합니다.
```
dataform init-creds
```
사용자 인증 정보 파일 만들기를 안내하는 init-creds 마법사를 따릅니다.

프로젝트 만들기

빈 Dataform 프로젝트의 구조는 다음과 같습니다.

   project-dir
   ├── definitions
   ├── includes
   └── workflow_settings.yaml

BigQuery에 애셋을 배포하도록 Dataform 프로젝트를 만들려면 다음 명령어를 실행합니다.
```
dataform init PROJECT_NAME --default-project YOUR_GOOGLE_CLOUD_PROJECT_ID
```
다음을 바꿉니다.
- PROJECT_NAME: 프로젝트의 이름
- YOUR_GOOGLE_CLOUD_PROJECT_ID: Google Cloud 프로젝트 ID입니다.

프로젝트 클론

서드 파티 Git 저장소에서 기존 Dataform 프로젝트를 클론하려면 Git 제공업체의 안내를 따르세요.

저장소가 클론된 후 클론된 저장소 디렉터리 내에서 다음 명령어를 실행합니다.
```
dataform install
```

테이블 정의

definitions/ 폴더에 정의를 저장합니다.

테이블을 정의하려면 다음 명령어를 실행합니다.
```
echo "config { type: 'TABLE_TYPE' } SELECT_STATEMENT" > definitions/FILE.sqlx
```
다음을 바꿉니다.
- TABLE_TYPE: 테이블 유형(table, incremental 또는 view)
- SELECT_STATEMENT: 테이블을 정의하는 SELECT 문
- FILE: 테이블 정의 파일의 이름

다음 코드 샘플은 example SQLX 파일에 뷰를 정의합니다.

echo "config { type: 'view' } SELECT 1 AS test" > definitions/example.sqlx

수동 어설션 정의

definitions/ 폴더에 정의를 저장합니다.

수동 어설션을 정의하려면 다음 명령어를 실행합니다.
```
echo "config { type: 'assertion' } SELECT_STATEMENT" > definitions/FILE.sqlx
```
다음을 바꿉니다.
- SELECT_STATEMENT: 어설션을 정의하는 SELECT 문
- FILE: 커스텀 SQL 작업 정의 파일의 이름

커스텀 SQL 작업 정의

definitions/ 폴더에 정의를 저장합니다.

커스텀 SQL 작업을 정의하려면 다음 명령어를 실행하세요.
```
echo "config { type: 'operations' } SQL_QUERY" > definitions/FILE.sqlx
```
다음을 바꿉니다.
- SQL_QUERY: 커스텀 SQL 작업
- FILE: 커스텀 SQL 작업 정의 파일의 이름

컴파일 출력 보기

Dataform은 코드를 실시간으로 컴파일합니다.

터미널에서 컴파일 프로세스의 출력을 보려면 다음 명령어를 실행합니다.
```
dataform compile
```
컴파일 프로세스의 출력을 JSON 객체로 보려면 다음 명령어를 실행하세요.
```
dataform compile --json
```
커스텀 컴파일 변수를 사용하여 컴파일 출력을 보려면 다음 명령어를 실행합니다.
```
dataform compile --vars=SAMPLE_VAR=SAMPLE_VALUE,foo=bar
```
다음을 바꿉니다.
- SAMPLE_VAR: 커스텀 컴파일 변수
- SAMPLE_VALUE: 커스텀 컴파일 변수의 값

코드 실행

코드를 실행하기 위해 Dataform은 BigQuery에 액세스하여 현재 상태를 확인하고 이에 따라 결과 SQL을 맞춤설정합니다.

Dataform 프로젝트의 코드를 실행하려면 다음 명령어를 실행합니다.
```
dataform run
```
BigQuery에서 커스텀 컴파일 변수로 Dataform 프로젝트의 코드를 실행하려면 다음 명령어를 실행합니다.
```
dataform run --vars=SAMPLE_VAR=SAMPLE_VALUE,sampleVar2=sampleValue2
```
다음을 바꿉니다.
- SAMPLE_VAR: 커스텀 컴파일 변수
- SAMPLE_VALUE: 커스텀 컴파일 변수의 값
BigQuery에서 Dataform 프로젝트 코드를 실행하고 모든 테이블을 처음부터 다시 빌드하려면 다음 명령어를 실행합니다.
```
dataform run --full-refresh
```

--full-refresh가 없으면 Dataform은 증분 테이블을 처음부터 다시 빌드하지 않고 업데이트합니다.

BigQuery 내에서 실행하지 않고 BigQuery의 현재 상태에 맞게 조정된 최종 컴파일 SQL 코드를 보려면 다음 명령어를 실행합니다.
```
dataform run --dry-run
```

도움받기

사용 가능한 모든 명령어와 옵션을 나열하려면 다음 명령어를 실행합니다.
```
dataform help
```
특정 명령어에 대한 설명을 보려면 다음 명령어를 실행합니다.
```
dataform help COMMAND
```
COMMAND를 알아보려는 명령어로 바꿉니다.

다음 단계

Dataform CLI에 대한 자세한 내용은 Dataform CLI 참조를 확인하세요.
Dataform에 대한 자세한 내용은 Dataform 개요를 참조하세요.