BigQuery 어댑터 동작 변경

BigQuery 어댑터 동작 변경 (BigQuery adapter behavior changes)

dbt-bigquery 어댑터에는 소스 프레시니스를 배치 쿼리로 계산하는 bigquery_use_batch_source_freshness, 와일드카드 테이블의 메타데이터 프레시니스를 거부하는 bigquery_reject_wildcard_metadata_source_freshness, 파티션 메타데이터에 표준 SQL을 쓰는 bigquery_use_standard_sql_for_partitions 플래그가 있어요.

출처: 문서

본문

bigquery_use_batch_source_freshness 플래그

bigquery_use_batch_source_freshness 플래그는 기본값이 false예요. dbt_project.yml 파일에서 true로 설정하면 dbt가 각 소스에 메타데이터 요청을 보내는 대신 BigQuery의 INFORMATION_SCHEMA.TABLE_STORAGE 뷰에 단일 배치 쿼리로 source freshness 결과를 계산하게 해요.

이 플래그를 true로 설정하면 source freshness 명령의 성능이 크게 개선돼요. 특히 프로젝트에 많은(1000개 이상) 소스가 있을 때요.

loaded_at_field

bigquery_use_batch_source_freshness가 활성화되면 dbt는 BigQuery 메타데이터 테이블에서 프레시니스를 결정해요. 소스에 loaded_at_field를 구성하면 dbt는 그 소스에 대해 메타데이터 기반 프레시니스 대신 컬럼 기반 프레시니스 검사를 실행해요. 하지만 모든 소스에 loaded_at_field가 설정되면 프레시니스가 컴파일 오류(get_relation_last_modified의 list object has no element 0)로 실패해요. 그 이유는 bigquery_use_batch_source_freshness 플래그가 적어도 하나의 소스가 메타데이터 기반 프레시니스를 사용한다고 가정하기 때문이에요; 모든 소스에 loaded_at_field를 구성하면 이 가정이 깨져요. 이를 피하려면 배치 프레시니스로 확인하려는 소스에서 loaded_at_field를 제거해요.

(dbt v1.12 이상에 적용)

bigquery_reject_wildcard_metadata_source_freshness 플래그

BigQuery 소스가 와일드카드 테이블 식별자(예: events_*)를 사용하면 메타데이터 기반 소스 프레시니스 검사가 잘못된 결과를 반환해요. BigQuery의 client.get_table() 메서드는 와일드카드 식별자에 대해 수정 타임스탬프가 현재 시간을 반영하는 임시 유니언 테이블을 생성해요 — 기반 테이블의 실제 수정 시간이 아니라요. 이 때문에 프레시니스 검사가 나이를 약 0초로 보고해서, 경고 없이 오래된 데이터를 가려요.

bigquery_reject_wildcard_metadata_source_freshness 플래그는 와일드카드 테이블 식별자를 사용하는 BigQuery 소스에 대해 dbt가 메타데이터 기반 소스 프레시니스 검사를 어떻게 처리할지 제어해요.

기본적으로 이 플래그는 false로 설정돼요. 와일드카드 식별자가 있는 테이블은 메타데이터 기반 프레시니스 검사를 계속 실행하지만, dbt는 새 동작에 옵트인하라고 조언하는 deprecation 경고를 발생시켜요. 예를 들어:

WARNING: Raise an error when metadata-based source freshness is used with awildcard table identifier (e.g. 'events_*'). BigQuery returns the current timeas the modified timestamp for wildcard tables, causing freshness checks toalways report ~0 seconds.You may opt into the new behavior sooner by setting`flags.bigquery_reject_wildcard_metadata_source_freshness` to `true` in `dbt_project.yml`.

이 플래그를 true로 설정하면 와일드카드 테이블 식별자로 메타데이터 기반 소스 프레시니스 검사를 실행할 때 dbt가 DbtRuntimeError를 발생시켜요. 예를 들어:

Runtime Error in source my_* (models/schema.yml) Metadata-based source freshness is not supported for wildcard table '`dbt-test-env`.`dbt_username`.`events_*`'. Please set 'loaded_at_field' on this source to use a query-based freshness check instead.

와일드카드 테이블의 프레시니스를 계산하려면 소스에 loaded_at_field를 구성해 쿼리 기반 프레시니스 검사를 사용해요.

예시 구성: models/schema.yml

sources:
  - name: events
    database: dbt-test-env
    schema: dbt_username
    tables:
      - name: events
        identifier: "events_*" # wildcard table identifier in BigQuery
        config:
          freshness:
            warn_after: {count: 12, period: hour}
            error_after: {count: 24, period: hour}
          loaded_at_field: _etl_loaded_at

bigquery_use_standard_sql_for_partitions 플래그

BigQuery는 2026년 6월 1일부터 레거시 SQL을 deprecate합니다. 그 날짜 이후에 만들어진 새 Google Cloud Platform 프로젝트는 레거시 SQL을 지원하지 않아요. get_partitions_metadata() 매크로는 현재 $__PARTITIONS_SUMMARY__와 함께 레거시 SQL을 사용하는데, 이 deprecation 이후 동작을 멈출 거예요.

bigquery_use_standard_sql_for_partitions 플래그는 get_partitions_metadata()를 호출할 때 dbt가 레거시 SQL($__PARTITIONS_SUMMARY__) 대신 표준 SQL(INFORMATION_SCHEMA.PARTITIONS)을 사용할지 제어해요.

기본적으로 이 플래그는 true로 설정되어 표준 SQL을 활성화해요. 레거시 SQL로 되돌리려면 dbt_project.yml에서 플래그를 false로 설정해요.

레거시 SQL에서 전환할 때 다음을 유의해요:

비용: $__PARTITIONS_SUMMARY__는 쿼리 비용이 무료예요. INFORMATION_SCHEMA.PARTITIONS는 바이트당이 아니라 BigQuery의 플랫 요금으로 쿼리당 청구돼요. 컬럼 차이: 두 소스 사이에 호환되는 것은 partition_id뿐이에요. 레거시 메타테이블은 project_id, dataset_id, table_id, creation_time, last_modified_time도 반환했어요. get_partitions_metadata() 결과에서 그 컬럼들에 접근하는 커스텀 매크로가 있다면 업데이트해야 해요. IAM 권한: INFORMATION_SCHEMA.PARTITIONS는 bigquery.tables.getData 대신 bigquery.tables.get과 bigquery.tables.list가 필요해요. 커스텀 IAM 역할은 업데이트가 필요할 수 있어요. 표준 사전 정의 역할(roles/bigquery.dataViewer, roles/bigquery.dataEditor, roles/bigquery.admin)은 이미 필요한 모든 권한을 포함하므로 영향을 받지 않아요.

더 알아보기 (Learn more)