이 문서에서는 Dataform 저장소의 루트 definitions 디렉터리에서 SQL 워크플로 파일을 구조화하고 이름을 지정하는 권장사항을 설명합니다. definitions 디렉터리의 권장 구조는 SQL 워크플로의 단계를 반영합니다. 비즈니스 요구사항에 적합한 구조를 채택할 수 있습니다.
다음과 같은 이유로 definitions 디렉터리의 SQL 워크플로 코드를 구성해야 할 수 있습니다.
- 선택한 워크플로 부분에 팀을 지정하여 코드베이스에서 공동작업을 개선합니다.
- 조직 변경 시 SQL 워크플로의 유지관리성이 향상됩니다.
- 코드베이스를 통해 탐색을 개선합니다.
- 코드베이스의 확장성이 향상됩니다.
- 팀의 관리 오버헤드를 최소화합니다.
definitions 디렉터리의 권장 구조
Dataform 저장소의 루트 definitions 디렉터리에는 SQL 워크플로의 요소를 만드는 코드가 포함되어 있습니다. definitions 디렉터리의 파일을 워크플로 구조를 반영하는 디렉터리 구조로 구성할 수 있습니다.
SQL 워크플로를 개발할 때 비즈니스 또는 분석용으로 사용할 수 있는 출력 테이블을 만들도록 소스 테이블을 선언하고 변환합니다.
SQL 워크플로의 세 가지 주요 단계를 구분할 수 있습니다.
- 데이터 소스 선언
- 소스 데이터 변환
- 변환된 소스 데이터의 출력 테이블 정의
definitions 디렉터리의 다음 하위 디렉터리 구조는 SQL 워크플로의 주요 단계를 반영합니다.
sources- 데이터 소스 선언 및 소스 데이터의 기본 변환입니다(예: 필터링).
intermediate- 변환된 데이터를 사용하여
outputs테이블을 정의하기 전에sources에서 읽고 데이터를 변환하는 테이블 및 작업입니다. 테이블은 일반적으로 Dataform이 BigQuery에 실행한 후 비즈니스 인텔리전스(BI) 도구와 같은 추가 프로세스 또는 도구에 노출되지 않습니다. outputs- Dataform이 BigQuery에서 실행한 후 프로세스 또는 도구(예: BI)에서 사용하는 테이블의 정의입니다.
extra- SQL 워크플로의 기본 파이프라인 외부에 있는 파일(예: 머신러닝과 같이 추가 사용을 위해 준비된 워크플로 데이터가 포함된 파일)입니다. 선택적 및 커스텀 하위 디렉터리입니다.
sources 관련 권장사항
sources 하위 디렉터리에는 SQL 워크플로의 첫 번째 단계인 소스 데이터의 선언과 기본 변환이 포함됩니다.
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
동일한 스키마 내에서 여러 데이터 소스 테이블을 선언하는 경우 선언을 단일 자바스크립트 파일로 통합할 수 있습니다. 자바스크립트 파일에서 여러 데이터 소스 선언을 저장할 수 있습니다. 자바스크립트로 데이터 소스 선언을 만드는 방법에 대한 자세한 내용은 자바스크립트로 Dataform SQL 워크플로 만들기를 참조하세요.
다음 코드 샘플에서는 단일 자바스크립트 파일에서 선언된 하나의 스키마 내 여러 데이터 소스를 보여줍니다.
[
"source_table_1",
"source_table_2",
"source_table_3"
].forEach((name) =>
declare({
database: "gcp_project",
schema: "source_dataset",
name,
})
);
데이터 소스 변경으로부터 SQL 워크플로를 보호하려면 각 데이터 소스 선언에 대한 뷰를 만들면 됩니다(예: analytics_users_filtered.sqlx).
뷰에는 소스 데이터의 기본 필터링 및 형식이 포함될 수 있습니다.
sources 하위 디렉터리에 뷰를 저장합니다.
그런 다음 intermediate 또는 outputs 테이블을 만들 때 원시 소스 테이블 대신 뷰를 참조합니다. 이 방식을 사용하면 소스 테이블을 테스트할 수 있습니다.
소스 테이블이 변경되는 경우 필터를 추가하거나 데이터를 다시 변환하는 등의 방법으로 뷰를 수정할 수 있습니다.
intermediate 관련 권장사항
intermediate 하위 디렉터리에는 SQL 워크플로의 두 번째 단계인 하나 이상의 소스에서 소스 데이터의 변환 및 집계가 포함됩니다.
intermediate 하위 디렉터리에서 소스 데이터를 하나 이상의 소스로부터 크게 변환하는 파일을 sources 하위 디렉터리에 저장합니다(예: 데이터를 조인하는 테이블). intermediate 하위 디렉터리의 테이블은 일반적으로 소스 테이블 또는 다른 intermediate 테이블의 데이터를 쿼리합니다.
intermediate 테이블을 사용하여 outputs 테이블을 만듭니다.
일반적으로 intermediate 테이블은 Dataform이 BigQuery에 실행한 후 데이터 분석과 같은 추가 용도로 사용되지 않습니다.
intermediate 테이블을 출력 테이블 생성을 사용 설정하는 데이터 변환 로직으로 생각할 수 있습니다.
모든 intermediate 테이블을 문서화하고 테스트하는 것이 좋습니다.
outputs 관련 권장사항
outputs 하위 디렉터리에는 SQL 워크플로의 마지막 단계인 변환된 데이터에서 비즈니스 목적으로 출력 테이블을 만드는 작업이 포함됩니다.
outputs 디렉터리에서 Dataform이 BigQuery에 실행한 후 추가 프로세스 또는 도구에서 사용할 테이블을 저장합니다(예: 보고서 또는 대시보드). outputs 디렉터리의 테이블은 일반적으로 intermediate 테이블의 데이터를 쿼리합니다.
마케팅, 주문, 분석 등 관련 비즈니스 항목을 기준으로 outputs 테이블을 그룹화합니다. 각 비즈니스 법인에 하위 디렉터리를 전용으로 지정합니다.
출력 테이블을 BigQuery에 별도로 저장하려면 출력 테이블의 전용 스키마를 구성하면 됩니다. 테이블 스키마를 구성하는 방법은 추가 테이블 설정 구성을 참조하세요.
다음 샘플은 두 개의 비즈니스 법인이 있는 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의 SQL 워크플로에 대한 자세한 내용은 SQL 워크플로 소개를 참조하세요.
- Dataform 저장소에 대한 자세한 내용은 저장소 소개를 참조하세요.
- 저장소 분할에 대한 자세한 내용은 저장소 분할 소개를 참조하세요.