오픈소스 Dataform CLI 사용

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

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

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

시작하기 전에

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

Dataform CLI 설치

  • Dataform CLI를 설치하려면 다음 명령어를 실행합니다.

    npm i -g @dataform/cli

Dataform 프로젝트 초기화

  • 새 Dataform 프로젝트를 초기화하려면 프로젝트 디렉터리 내에서 다음 명령어를 실행합니다.

    dataform init . PROJECT_NAME DEFAULT_LOCATION

    다음을 바꿉니다.

    • PROJECT_NAME: 프로젝트의 이름

    • DEFAULT_LOCATION (선택사항): Dataform이 BigQuery 데이터를 작성할 위치 설정되지 않은 경우 Dataform은 SQL 쿼리가 참조하는 데이터 세트를 기반으로 위치를 결정합니다. 작동 방식은 다음과 같습니다.

      • 쿼리가 동일한 위치의 데이터 세트를 참조하는 경우 Dataform은 해당 위치를 사용합니다.
      • 쿼리가 두 개 이상의 서로 다른 위치의 데이터 세트를 참조하는 경우 오류가 발생합니다. 이 제한사항에 대한 자세한 내용은 리전 간 데이터 세트 복제를 참조하세요.
      • 쿼리가 데이터 세트를 참조하지 않는 경우 Dataform의 기본 위치는 US 멀티 리전입니다. 다른 위치를 선택하려면 기본 위치를 설정합니다. 또는 쿼리에서 @@location 시스템 변수 를 사용합니다. 자세한 내용은 위치 지정을 참조하세요.

Dataform Core 업데이트

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

    npm i

Dataform CLI 업데이트

  • Dataform CLI 도구를 업데이트하려면 다음 명령어를 실행합니다.

    npm i -g @dataform/cli@^3.0.50

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

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

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

  1. 다음 명령어를 실행합니다.

    dataform init-creds

  2. 사용자 인증 정보 파일 만들기를 안내하는 init-creds 마법사를 따릅니다.

프로젝트 만들기

Dataform Core 3.0.0 이상의 빈 Dataform 프로젝트에는 다음과 같은 구조가 있습니다.

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

  • BigQuery에 애셋을 배포할 Dataform 프로젝트를 만들려면 다음 명령어를 실행합니다.

    dataform init PROJECT_NAME --default-database YOUR_GOOGLE_CLOUD_PROJECT_ID --default-location DEFAULT_LOCATION

    다음을 바꿉니다.

    • PROJECT_NAME: 프로젝트의 이름
    • YOUR_GOOGLE_CLOUD_PROJECT_ID: 프로젝트 ID입니다. Google Cloud

    • DEFAULT_LOCATION (선택사항): Dataform이 BigQuery 데이터를 작성할 위치 설정되지 않은 경우 Dataform은 SQL 쿼리가 참조하는 데이터 세트를 기반으로 위치를 결정합니다. 작동 방식은 다음과 같습니다.

      • 쿼리가 동일한 위치의 데이터 세트를 참조하는 경우 Dataform은 해당 위치를 사용합니다.
      • 쿼리가 두 개 이상의 서로 다른 위치의 데이터 세트를 참조하는 경우 오류가 발생합니다. 이 제한사항에 대한 자세한 내용은 리전 간 데이터 세트 복제를 참조하세요.
      • 쿼리가 데이터 세트를 참조하지 않는 경우 Dataform의 기본 위치는 US 멀티 리전입니다. 다른 위치를 선택하려면 기본 위치를 설정합니다. 또는 쿼리에서 @@location 시스템 변수 를 사용합니다. 자세한 내용은 위치 지정을 참조하세요.

프로젝트 클론

타사 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에 대해 코드 테스트 실행을 수행하려면 다음 명령어를 실행합니다.

    dataform run --dry-run

도움말 보기

  • 사용 가능한 모든 명령어와 옵션을 나열하려면 다음 명령어를 실행합니다.

    dataform help

  • 특정 명령어의 설명을 보려면 다음 명령어를 실행합니다.

    dataform help COMMAND

    COMMAND를 자세히 알아보려는 명령어로 바꿉니다.

다음 단계