저장소에서 코드 구조화

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

다음과 같은 이유로 definitions 디렉터리에 SQL 워크플로 코드를 구성할 수 있습니다.

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

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

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

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

  1. 데이터 소스 선언
  2. 소스 데이터 변환
  3. 변환된 소스 데이터의 출력 테이블 정의

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

동일한 스키마 내에 여러 데이터 소스 테이블을 선언하는 경우 선언을 단일 JavaScript 파일로 통합할 수 있습니다. JavaScript 파일에 여러 데이터 소스 선언을 저장할 수 있습니다. JavaScript로 데이터 소스 선언을 만드는 방법에 관한 자세한 내용은 JavaScript로 Dataform SQL 워크플로 만들기를 참고하세요.

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

[
  "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

다음 단계