이 페이지는 Cloud Translation API를 통해 번역되었습니다.

저장소 권장사항
컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

이 문서에서는 Dataform 저장소에 관한 다음 정보를 제공합니다.

Dataform의 저장소 권장사항 개요
저장소 크기 개요
저장소 분할
저장소에서 코드 구조화하기

Dataform의 저장소 권장사항 개요

이 섹션에서는 Dataform에서 저장소 크기, 저장소 구조, 코드 수명 주기를 관리하기 위한 권장사항을 간략히 설명합니다.

저장소 크기 권장사항

저장소 크기는 다음과 같이 Dataform 개발의 여러 측면에 영향을 미칩니다.

공동작업
코드베이스 가독성
개발 프로세스
워크플로 컴파일
워크플로 실행

Dataform은 컴파일 리소스에 대한 API 할당량 및 한도를 적용합니다. 저장소 크기가 크면 이러한 할당량과 제한을 초과하는 원인이 될 수 있습니다. 이로 인해 워크플로의 컴파일 및 실행이 실패할 수 있습니다.

이러한 위험을 완화하려면 큰 리포지토리를 분할하는 것이 좋습니다. 큰 저장소를 분할할 때는 큰 워크플로를 다른 저장소에 보관되고 저장소 간 종속 항목으로 연결된 여러 개의 작은 워크플로로 나눕니다.

이 접근 방식을 사용하면 Dataform 할당량 및 한도, 세분화된 프로세스 및 권한을 준수하고, 코드베이스 가독성 및 공동작업을 개선할 수 있습니다. 그러나 분할된 저장소를 관리하는 것은 단일 저장소를 관리하는 것보다 훨씬 까다로울 수 있습니다.

Dataform에서 저장소 크기가 미치는 영향에 대한 자세한 내용은 저장소 크기 개요를 참고하세요. 저장소 분할에 대한 권장사항을 자세히 알아보려면 저장소 분할하기를 참고하세요.

저장소 구조 권장사항

워크플로의 단계를 반영하여 definitions 디렉토리에 파일을 구조화하는 것이 좋습니다. 필요에 가장 적합한 맞춤 구조를 채택할 수 있습니다.

다음 definitions 하위 디렉터리의 권장 구조는 대부분의 워크플로에 대한 주요 단계를 반영합니다.

데이터 소스 선언을 저장하는 sources
intermediate: 데이터 변환 로직을 저장합니다.
output: 출력 테이블의 정의를 저장합니다.
extras (선택사항): 추가 파일을 저장합니다.

Dataform의 모든 파일 이름은 BigQuery 테이블 이름 지정 지침을 준수해야 합니다. Dataform 저장소의 definitions 디렉터리에 있는 파일 이름은 하위 디렉터리 구조를 반영하는 것이 좋습니다.

저장소에서 파일을 구조화하고 이름을 지정하는 권장사항에 대해 자세히 알아보려면 저장소에서 코드 구조화하기를 참고하세요.

코드 수명 주기에 관한 권장사항

Dataform의 기본 코드 수명 주기는 다음 단계로 구성됩니다.

Dataform 작업공간에서 워크플로 코드 개발

Dataform 코어로 개발하거나 전적으로 JavaScript만 가지고 개발할 수 있습니다.
워크플로 설정 파일의 설정을 사용하여 코드를 컴파일 결과로 컴파일합니다.

출시 구성 및 작업공간 컴파일 재정의를 사용하여 맞춤 컴파일 결과를 구성할 수 있습니다.

출시 구성을 사용하면 전체 저장소의 맞춤 컴파일 결과를 구성할 수 있습니다. 나중에 워크플로 구성에서 실행을 예약할 수 있습니다.

작업공간 컴파일 재정의를 사용하면 저장소의 모든 작업공간에 대한 컴파일 재정의를 구성하여 각 작업공간의 맞춤 컴파일 결과를 만들 수 있습니다.
BigQuery에서 컴파일 결과 실행

워크플로 구성을 사용하여 실행 또는 저장소 컴파일 결과를 예약할 수 있습니다.

Dataform에서 코드 수명 주기를 관리하려면 개발, 스테이징, 프로덕션과 같은 실행 환경을 만들 수 있습니다.

Dataform의 코드 수명 주기에 대한 자세한 내용은 Dataform의 코드 수명 주기 소개를 참조하세요.

실행 환경을 단일 저장소에 보관하거나 여러 저장소에 보관하도록 선택할 수 있습니다.

단일 저장소의 실행 환경

작업공간 컴파일 재정의 및 출시 구성을 사용하여 단일 Dataform 저장소에서 개발, 스테이징, 프로덕션과 같은 격리된 실행 환경을 만들 수 있습니다.

다음과 같은 방법으로 격리된 실행 환경을 만들 수 있습니다.

스키마별로 개발 및 프로덕션 테이블 분할
스키마 및 프로젝트별로 개발 및 프로덕션 테이블을 분할합니다. Google Cloud
프로젝트별로 개발, 스테이징, 프로덕션 테이블을 분할합니다. Google Cloud

그런 다음 워크플로 구성을 사용하여 스테이징 및 프로덕션 환경에서 실행을 예약할 수 있습니다. 개발 환경에서 실행을 수동으로 트리거하는 것이 좋습니다.

Dataform의 코드 수명 주기 관리의 권장사항에 대한 자세한 내용은 코드 수명 주기 관리를 참조하세요.

여러 저장소의 코드 수명 주기

코드 수명 주기의 각 단계에 맞춰 Identity and Access Management를 조정하려면 저장소의 여러 사본을 만들어 서로 다른 Google Cloud 프로젝트에 저장하면 됩니다.

각 Google Cloud 프로젝트는 코드 수명 주기의 단계(예: 개발 및 프로덕션)에 해당하는 실행 환경 역할을 합니다.

이 접근 방식에서는 모든 프로젝트에서 저장소의 코드베이스를 동일하게 유지하는 것이 좋습니다. 저장소의 각 사본에서 컴파일 및 실행을 맞춤설정하려면 작업공간 컴파일 재정의, 출시 구성, 워크플로 구성을 사용합니다.

저장소 크기 개요

이 섹션에서는 저장소 크기가 워크플로 개발 및 Dataform 컴파일 리소스 사용량에 미치는 영향을 이해하고 저장소의 컴파일 리소스 사용량을 추정하는 방법을 설명합니다.

Dataform의 저장소 크기 정보

저장소의 크기는 Dataform 개발의 다음 측면에 영향을 미칩니다.

공동작업 대규모 저장소에서 작업하는 여러 공동작업자가 과도한 수의 풀 요청을 생성하여 병합 충돌의 위험이 증가할 수 있습니다.
코드베이스 가독성 단일 저장소에서 워크플로를 구성하는 파일이 많으면 저장소를 탐색하기 어려울 수 있습니다.
개발 프로세스 단일 저장소의 대규모 워크플로의 일부 영역에는 나머지 워크플로에 적용된 권한 및 프로세스와 다른 맞춤 권한 또는 프로세스(예: 예약)가 필요할 수 있습니다. 저장소 크기가 크면 워크플로의 특정 영역에 개발 프로세스를 맞추기가 어렵습니다.
워크플로 컴파일 Dataform은 컴파일 리소스에 사용량 한도를 적용합니다. 저장소 크기가 크면 이러한 한도를 초과하여 컴파일이 실패할 수 있습니다.
워크플로 실행 실행 중에 Dataform은 작업공간 내에서 저장소 코드를 실행하고 애셋을 BigQuery에 배포합니다. 저장소가 클수록 Dataform에서 실행하는 데 시간이 더 오래 걸립니다.

저장소의 크기가 커서 Dataform의 개발에 부정적인 영향을 미치는 경우 여러 개의 작은 저장소로 저장소를 분할할 수 있습니다.

저장소 컴파일 리소스 한도 정보

개발 중에 Dataform은 작업공간 내에서 모든 저장소 코드를 컴파일하여 저장소에 있는 워크플로 표현을 생성합니다. 이를 컴파일 결과라고 합니다. Dataform은 컴파일 리소스에 사용량 한도를 적용합니다.

다음과 같은 이유로 저장소의 사용량 한도가 초과될 수 있습니다.

저장소 코드의 무한 루프 버그
저장소 코드의 메모리 누수 버그
큰 저장소 크기(워크플로 작업 약 1, 000개 이상)

컴파일 리소스의 사용량 한도에 대한 자세한 내용은 Dataform 컴파일 리소스 한도를 참조하세요.

저장소의 컴파일 리소스 사용량 추정

저장소의 다음 컴파일 리소스 사용량을 예측할 수 있습니다.

CPU 시간 사용량입니다.
저장소에 정의된 작업의 그래프로 표현된 직렬화된 최대 데이터 크기입니다.

로컬 Linux 또는 macOS 머신에서 Dataform 워크플로 컴파일 시간을 지정하면 저장소 컴파일의 현재 컴파일 CPU 시간 사용량을 대략적으로 확인할 수 있습니다.

워크플로의 컴파일 시간을 지정하려면 저장소 내부에서 다음 형식으로 Dataform CLI 명령어 dataform compile를 실행합니다.
```
time dataform compile
```
다음 코드 샘플은 time dataform compile 명령어 실행 결과를 보여줍니다.
```
real    0m3.480s
user    0m1.828s
sys     0m0.260s
```

real 결과를 저장소 컴파일의 CPU 시간 사용량을 나타내는 대략적인 지표로 간주할 수 있습니다.

저장소에서 생성된 작업 그래프의 전체 크기를 대략적으로 확인하려면 그래프 출력을 JSON 파일에 작성하면 됩니다. 비압축 JSON 파일의 크기를 전체 그래프 크기의 대략적인 표시기로 취급할 수 있습니다.

워크플로의 컴파일된 그래프 출력을 JSON 파일에 쓰려면 저장소 내에서 다음 Dataform CLI 명령어를 실행합니다.
```
dataform compile --json > graph.json
```

저장소 분할

이 섹션에서는 Dataform 저장소를 분할하고 교차 저장소 종속 항목을 관리하는 전략을 설명합니다.

저장소는 Dataform의 핵심 단위입니다. 저장소에는 워크플로를 구성하는 모든 SQLX 및 JavaScript 파일은 물론 Dataform 구성 파일과 패키지도 저장됩니다. 워크플로를 단일 저장소에 저장하거나 여러 저장소 간에 워크플로를 분할할 수 있습니다.

Dataform에서 저장소를 분할하면 다음과 같은 이점이 있습니다.

컴파일 리소스 사용량에 대한 Dataform 한도 준수 대규모 워크플로를 여러 개의 작은 저장소로 분할하면 컴파일 리소스에 대한 Dataform 한도를 초과할 위험이 줄어듭니다.
세분화된 프로세스 워크플로의 각 분할 프래그먼트와 개발팀에 지속적 통합(CI) 규칙과 같은 프로세스를 개별적으로 설정할 수 있습니다.
세분화된 권한. 워크플로의 전반적인 보안을 개선하기 위해 워크플로의 각 분할 프래그먼트와 개발팀에 개별적으로 권한을 설정할 수 있습니다.
워크플로의 각 분할된 프래그먼트에서 작업하는 공동작업자 수를 최소화하여 공동작업을 개선합니다.
코드베이스 가독성 향상. 대규모 워크플로를 구성하는 파일을 여러 저장소로 분할하면 전체 워크플로를 한 번에 탐색하는 것보다 각 저장소를 개별적으로 탐색하는 것이 더 쉽습니다.
전체 워크플로 실행에 비해 워크플로의 각 분할된 프래그먼트의 워크플로 실행 속도를 높입니다.

Dataform에서 저장소를 분할하면 다음과 같은 단점이 있습니다.

각 Dataform 저장소와 해당 Git 저장소에 필요한 커스텀 지속적 통합 및 지속적 개발 (CI/CD) 구성입니다.
각 Dataform 저장소와 해당 Git 저장소에 필요한 맞춤 예약 구성입니다.
여러 저장소에 있는 워크플로 객체 간의 종속 항목을 관리하기가 어렵습니다.
여러 저장소 간에 분할된 SQL 워크플로의 포괄적인 방향성 비순환 그래프(DAG) 시각화가 부족합니다. 각 저장소에서 생성된 DAG는 전체 워크플로의 일부만 나타냅니다.

저장소 분할 전략

저장소를 분할할 때 상위 SQL 워크플로를 구성하는 파일을 별도의 Dataform 저장소에 있는 더 작은 하위 워크플로로 나눕니다.

다음 방법 중 하나로 저장소를 분할할 수 있습니다.

개발팀당 저장소 1개
도메인당 하나의 저장소(예: 영업, 마케팅, 물류)
중앙 저장소의 콘텐츠를 데이터 소스로 사용하는 중앙 저장소 1개와 도메인당 저장소 1개

서드 파티 Git 호스팅 플랫폼에서 상위 워크플로를 저장하려면 하위 워크플로가 포함된 각각의 별도 저장소를 전용 서드 파티 Git 저장소에 개별적으로 연결해야 합니다.

교차 저장소 종속 항목 관리

저장소를 분할하는 가장 효율적인 방법은 상위 SQL 워크플로를 독립 실행형 하위 SQL 워크플로로 분할하여 독립적인 저장소를 만드는 것입니다. 독립 저장소는 다른 저장소의 콘텐츠를 데이터 소스로 사용하지 않습니다. 이 방식에서는 교차 저장소 종속 항목을 관리할 필요가 없습니다.

교차 저장소 종속 항목을 피할 수 없는 경우 저장소를 이전 저장소에 종속되고 후속 저장소의 데이터 소스가 되는 연속된 저장소로 분할하여 이를 관리할 수 있습니다. 연속된 저장소와 해당 종속 항목은 상위 워크플로의 구조를 가장 잘 반영해야 합니다.

Dataform 데이터 소스 선언을 사용하여 저장소 간에 종속 항목을 만들 수 있습니다. 다른 Dataform 저장소의 BigQuery 테이블 유형을 수정 중인 저장소의 데이터 소스로 선언할 수 있습니다. 데이터 소스를 선언한 후에는 다른 Dataform 워크플로 작업과 마찬가지로 이를 참조하고 이를 사용하여 워크플로를 개발할 수 있습니다.

교차 저장소 종속 항목이 있는 저장소 간에 분할된 워크플로 실행을 예약하는 경우 교차 저장소 종속 항목의 순서대로 저장소를 하나씩 실행해야 합니다.

저장소를 양방향 종속 항목이 있는 저장소 그룹으로 분할하지 않는 것이 좋습니다. 저장소 간의 양방향 종속 항목은 저장소가 다른 저장소의 데이터 소스이면서 해당 저장소를 데이터 소스로 사용하는 경우에 발생합니다. 저장소 간의 양방향 종속 항목은 상위 워크플로의 예약 및 실행뿐만 아니라 개발 프로세스를 복잡하게 만듭니다.

저장소에서 코드 구조화

이 섹션에서는 Dataform 저장소의 루트 definitions 디렉터리에서 워크플로 파일을 구조화하고 이름을 지정하기 위한 권장사항을 설명합니다. definitions 디렉터리의 권장 구조는 워크플로의 단계를 반영합니다. 비즈니스 요구사항에 맞는 구조를 채택할 수 있습니다.

다음과 같은 이유로 definitions 디렉터리에 워크플로 코드를 구성하는 것이 좋습니다.

워크플로의 일부에 팀을 지정하여 코드베이스에서 공동작업을 개선합니다.
조직 변경 시 워크플로의 유지관리성이 향상됩니다.
코드베이스를 통해 탐색을 개선합니다.
코드베이스의 확장성이 향상됩니다.
팀의 관리 오버헤드를 최소화합니다.

권장되는 `definitions` 디렉터리 구조

Dataform 저장소의 루트 definitions 디렉터리에는 워크플로의 요소를 만드는 코드가 포함되어 있습니다. definitions 디렉터리의 파일을 워크플로의 구조를 반영하는 디렉터리 구조로 정리할 수 있습니다.

워크플로를 개발할 때는 소스 테이블을 선언하고 변환하여 비즈니스 또는 분석 목적으로 사용할 수 있는 출력 테이블을 만듭니다.

워크플로의 세 가지 주요 단계를 구분할 수 있습니다.

데이터 소스 선언
소스 데이터 변환
변환된 소스 데이터의 출력 테이블 정의입니다.

definitions 디렉터리의 다음 하위 디렉터리 구조는 워크플로의 주요 단계를 반영합니다.

sources: 데이터 소스 선언 및 소스 데이터의 기본 변환입니다(예: 필터링).
intermediate: 변환된 데이터를 사용하여 outputs 테이블을 정의하기 전에 sources에서 읽고 데이터를 변환하는 테이블 및 작업입니다. 테이블은 일반적으로 Dataform이 BigQuery에 실행한 후 비즈니스 인텔리전스 (BI) 도구와 같은 추가 프로세스 또는 도구에 노출되지 않습니다.
outputs: Dataform이 BigQuery에서 실행한 후 프로세스 또는 도구(예: BI)에서 사용하는 테이블의 정의입니다.
extra: 워크플로의 기본 파이프라인 외부에 있는 파일(예: 머신러닝과 같이 추가 사용을 위해 준비된 워크플로 데이터가 포함된 파일)입니다. 선택사항인 커스텀 하위 디렉터리입니다.

`sources` 관련 권장사항

sources 하위 디렉터리에는 워크플로의 첫 번째 단계인 소스 데이터의 선언과 기본 변환이 포함됩니다.

sources 하위 디렉터리에는 데이터 소스 선언과 열을 필터링, 분류, 변환하거나 이름을 바꾸는 테이블을 저장합니다.

여러 소스의 데이터를 결합하는 테이블을 저장하지 마세요.

intermediate 하위 디렉터리에 저장된 테이블의 sources 데이터를 변환합니다.

Google Ads 또는 Google 애널리틱스와 같은 여러 풀의 데이터 소스를 선언하는 경우 각 풀에 하위 디렉터리를 할당합니다.

다음 샘플은 소스 풀이 두 개인 sources의 하위 디렉터리 구조를 보여줍니다.

definitions/
    sources/
        google_ads/
            google_ads_filtered.sqlx
            google_ads_criteria_metrics.sqlx
            google_ads_criteria_metrics_filtered.sqlx
            google_ads_labels.sqlx
            google_ads_labels_filtered.sqlx
        google_analytics/
            google_analytics_users.sqlx
            google_analytics_users_filtered.sqlx
            google_analytics_sessions.sqlx

동일한 스키마 내에 여러 데이터 소스 테이블을 선언하는 경우 선언을 단일 JavaScript 파일로 통합할 수 있습니다.

JavaScript로 데이터 소스 선언을 만드는 방법에 관한 자세한 내용은 JavaScript로 Dataform 워크플로 만들기를 참고하세요.

다음 코드 샘플에서는 단일 자바스크립트 파일에서 선언된 하나의 스키마 내 여러 데이터 소스를 보여줍니다.

[
  "source_table_1",
  "source_table_2",
  "source_table_3"
].forEach((name) =>
  declare({
    database: "gcp_project",
    schema: "source_dataset",
    name,
  })
);

데이터 소스 변경사항으로부터 워크플로를 보호하려면 각 데이터 소스 선언(예: analytics_users_filtered.sqlx)의 뷰를 만들 수 있습니다. 뷰에는 소스 데이터의 기본 필터링 및 형식이 포함될 수 있습니다. sources 하위 디렉터리에 뷰를 저장합니다.

그런 다음 intermediate 또는 outputs 테이블을 만들 때 원시 소스 테이블 대신 뷰를 참조합니다. 이 방식을 사용하면 소스 테이블을 테스트할 수 있습니다. 소스 테이블이 변경되면 필터를 추가하거나 데이터를 다시 변환하는 등의 방법으로 보기를 수정할 수 있습니다.

`intermediate` 관련 권장사항

intermediate 하위 디렉터리에는 워크플로의 두 번째 단계인 하나 이상의 소스에서 소스 데이터의 변환 및 집계가 포함됩니다.

intermediate 하위 디렉터리에는 하나 이상의 소스에서 소스 데이터를 크게 변환하는 파일(예: 데이터를 조인하는 테이블)을 저장합니다.sources intermediate 하위 디렉터리의 테이블은 일반적으로 소스 테이블 또는 다른 intermediate 테이블의 데이터를 쿼리합니다.

intermediate 테이블을 사용하여 outputs 테이블을 만듭니다. 일반적으로 intermediate 테이블은 Dataform이 BigQuery에 실행한 후 데이터 분석과 같은 추가 용도로 사용되지 않습니다. intermediate 테이블은 출력 테이블을 만들 수 있는 데이터 변환 로직이라고 생각하면 됩니다.

모든 intermediate 테이블을 문서화하고 테스트하는 것이 좋습니다.

`outputs` 관련 권장사항

outputs 하위 디렉터리에는 워크플로의 마지막 단계인 변환된 데이터에서 비즈니스 목적으로 출력 테이블을 만드는 작업이 포함됩니다.

outputs 디렉터리에서 Dataform이 BigQuery에 실행한 후 추가 프로세스 또는 도구에서 사용할 테이블을 저장합니다(예: 보고서 또는 대시보드). outputs 디렉터리의 테이블은 일반적으로 intermediate 테이블의 데이터를 쿼리합니다.

마케팅, 주문, 분석과 같이 관련된 비즈니스 항목별로 outputs 테이블을 그룹화합니다. 각 비즈니스 항목에 하위 디렉터리를 지정합니다.

BigQuery에 출력 테이블을 별도로 저장하려면 출력 테이블 전용 스키마를 구성하면 됩니다. 테이블 스키마를 구성하는 방법은 추가 테이블 설정 구성을 참고하세요.

다음 샘플은 sales 및 marketing 비즈니스 항목이 있는 outputs의 하위 디렉터리 구조를 보여줍니다.

definitions/
    outputs/
        orders/
            orders.sqlx
            returns.sqlx
        sales/
            sales.sqlx
            revenue.sqlx
        marketing/
            campaigns.sqlx

모든 outputs 테이블을 문서화하고 테스트하는 것이 좋습니다.

이름 지정 전략

Dataform의 모든 파일 이름은 BigQuery 테이블 이름 지정 가이드라인을 준수해야 합니다.

Dataform 저장소의 definitions 디렉터리에 있는 파일 이름은 하위 디렉터리 구조를 반영하는 것이 좋습니다.

sources 하위 디렉터리에서 파일 이름은 파일이 관련된 소스를 나타내야 합니다. 소스 이름을 파일 이름의 접두사로 추가합니다(예: analytics_filtered.sqlx).

intermediate 하위 디렉터리에서 파일 이름은 공동작업자가 intermediate 파일을 명확하게 구분할 수 있도록 하위 디렉터리를 식별해야 합니다. 고유한 접두사를 선택하고 intermediate 디렉터리의 파일에만 적용합니다(예: stg_ads_concept.sqlx).

outputs 하위 디렉터리에서 파일 이름은 간결해야 합니다(예: orders.sqlx). 서로 다른 항목 하위 디렉터리에 이름이 동일한 outputs 테이블이 있는 경우 항목을 식별하는 접두사(예: sales_revenue.sqlx 또는 ads_revenue.sqlx)를 추가합니다.

다음 예시는 권장되는 이름 지정 전략을 준수하는 파일 이름이 있는 definitions 디렉터리 내의 하위 디렉터리 구조를 보여줍니다.

definitions/
    sources/
        google_analytics.sqlx
        google_analytics_filtered.sqlx
    intermediate/
        stg_analytics_concept.sqlx
    outputs/
        customers.sqlx
        sales/
            sales.sqlx
            sales_revenue.sqlx
        ads/
            campaigns.sqlx
            ads_revenue.sqlx

다음 단계

Dataform의 코드 수명 주기와 이를 구성하는 다양한 방법에 대해 자세히 알아보려면 Dataform의 코드 수명 주기 소개를 참고하세요.
코드 수명 주기에 관한 권장사항에 대해 자세히 알아보려면 코드 수명 주기 관리를 참고하세요.
Dataform 컴파일 리소스 한도에 대한 자세한 내용은 Dataform 컴파일 리소스 한도를 참고하세요.
Dataform 저장소를 서드 파티 Git 저장소에 연결하는 방법은 서드 파티 Git 저장소에 연결을 참고하세요.
Dataform의 워크플로에 대한 자세한 내용은 SQL 워크플로 소개를 참고하세요.