자동화된 프로파일링 및 데이터 품질 규칙을 설정하면 신뢰 신호와 비즈니스 컨텍스트로 메타데이터를 보강할 수 있습니다.
AI가 초기 규칙을 초안 작성하고 사용자가 검토, 구체화, 검증하는 Human-in-the-Loop 접근 방식을 사용하면 프로필 통계를 데이터 품질 프레임워크로 빠르게 변환할 수 있습니다.
목표
- 구체화된 뷰로 중첩된 BigQuery 데이터를 평면화하여 Knowledge Catalog 프로파일링을 사용 설정합니다.
- Python 클라이언트 라이브러리를 사용하여 Knowledge Catalog 프로필 스캔을 실행합니다.
- Antigravity CLI를 사용하여 프로필 통계를 기반으로 데이터 품질 규칙을 생성합니다.
- 인간 참여형 검토 프로세스를 사용하여 AI 생성 규칙을 Knowledge Catalog 품질 스캔으로 검증하고 배포합니다.
시작하기 전에
시작하기 전에 결제가 사용 설정된 프로젝트가 있어야 합니다. Google Cloud
개발 환경 준비
다음 단계에서는 클라우드에서 실행되는 명령줄 환경인 Cloud Shell을 사용합니다.
콘솔의 오른쪽 상단 툴바에서 Cloud Shell 활성화를 클릭합니다. Google Cloud 환경을 프로비저닝하고 연결하는 데 몇 분 정도 걸립니다.
Cloud Shell에서 프로젝트 ID 및 환경 변수를 설정합니다.
export PROJECT_ID=$(gcloud config get-value project) gcloud config set project $PROJECT_ID export LOCATION="us-central1" export BQ_LOCATION="us" export DATASET_ID="kc_dq_codelab" export TABLE_ID="ga4_transactions"공개 샘플 데이터도
us(멀티 리전)에 있으므로 위치로us(멀티 리전)를 사용합니다. BigQuery 쿼리의 경우 소스 데이터와 대상 테이블이 동일한 위치에 있어야 합니다.필요한 서비스를 사용 설정합니다.
gcloud services enable dataplex.googleapis.com \ bigquery.googleapis.com \ serviceusage.googleapis.com \ aiplatform.googleapis.com샘플 데이터와 결과를 저장할 BigQuery 데이터 세트를 만듭니다.
bq --location=us mk --dataset $PROJECT_ID:$DATASET_IDGoogle Merchandise Store의 공개 이커머스 데이터 세트에서 제공되는 샘플 데이터를 준비합니다.
다음
bq명령어는kc_dq_codelab데이터 세트에 새 테이블ga4_transactions를 만듭니다. 스캔이 빠르게 실행되도록 하루 (2021-01-31)의 데이터만 복사합니다.bq query \ --use_legacy_sql=false \ --destination_table=$PROJECT_ID:$DATASET_ID.$TABLE_ID \ --replace=true \ 'SELECT * FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_20210131`'이 튜토리얼의 폴더 구조와 지원 파일이 포함된 GitHub 저장소를 클론합니다.
# Perform a shallow clone to get only the latest repository structure without the full history git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git cd devrel-demos # Specify and download only the folder we need for this lab git sparse-checkout set data-analytics/programmatic-dq cd data-analytics/programmatic-dq이 디렉터리가 활성 작업 영역입니다.
중첩 데이터 프로파일링
데이터 프로파일링을 사용하면 Knowledge Catalog에서 데이터의 null 비율, 고유성, 값 분포와 같은 최상위 열의 통계를 찾아 데이터를 이해하는 데 도움을 줍니다.
중첩된 필드의 통계를 가져오려면 구체화된 뷰 집합을 사용하여 데이터를 평면화하면 됩니다. 이렇게 하면 각 중첩된 필드가 Knowledge Catalog에서 프로파일링할 수 있는 최상위 열로 바뀝니다.
중첩된 스키마 가져오기
모든 중첩된 구조를 포함하여 소스 테이블의 전체 스키마를 가져오고 출력을 JSON 파일로 저장합니다.
bq show --schema --format=json $PROJECT_ID:$DATASET_ID.$TABLE_ID > bq_schema.json
스키마 보기:
jq < bq_schema.json
bq_schema.json 파일은 복잡한 구조를 보여줍니다.
구체화된 뷰로 데이터 평면화
중첩된 데이터를 평면화할 때는 동일한 뷰에서 여러 독립적인 배열을 중첩 해제하지 않는 것이 중요합니다. 이렇게 하면 배열 간에 암시적 교차 조인 (카티전 프로덕트)이 실행되어 행이 잘못 곱해지고 데이터가 손상됩니다.
대신 각기 다른 목적으로 빌드된 여러 뷰를 만드는 것이 좋습니다. 각 뷰는 단일하고 명확한 세부정보 수준을 유지해야 합니다. 이 단계에서는 다음 구체화된 뷰를 만듭니다.
- 세션 평면 뷰 (
mv_ga4_user_session_flat.sql): 이벤트당 하나의 행 - 트랜잭션 뷰 (
mv_ga4_ecommerce_transactions.sql): 트랜잭션당 하나의 행 - 항목 뷰 (
mv_ga4_ecommerce_items.sql): 항목당 하나의 행
프로젝트 저장소는 이러한 뷰를 정의하는 devrel-demos/data-analytics/programmatic-dq 디렉터리에 세 개의 SQL 파일을 제공합니다.
다음 BigQuery 명령어를 사용하여 Cloud Shell에서 이러한 파일을 실행합니다.
envsubst < mv_ga4_user_session_flat.sql | bq query --use_legacy_sql=false
envsubst < mv_ga4_ecommerce_transactions.sql | bq query --use_legacy_sql=false
envsubst < mv_ga4_ecommerce_items.sql | bq query --use_legacy_sql=false
Python 클라이언트로 프로필 스캔 실행
이제 각 구체화된 뷰에 대해 Knowledge Catalog 데이터 프로필 스캔을 만들고 실행할 수 있습니다. 다음 Python 스크립트는 google-cloud-dataplex 클라이언트 라이브러리를 사용하여 이 프로세스를 자동화합니다.
스크립트를 실행하기 전에 프로젝트 디렉터리에 격리된 Python 가상 환경을 만듭니다.
# Create the virtual environment
python3 -m venv dq_venv
# Activate the environment
source dq_venv/bin/activate
가상 환경 내에 Knowledge Catalog 클라이언트 라이브러리를 설치합니다.
# Install the Knowledge Catalog client library
pip install google-cloud-dataplex
이제 환경을 설정하고 라이브러리를 설치했으므로 1_run_scan.py 스크립트를 사용할 준비가 되었습니다. 이 스크립트는 각 스캔을 만들고 실행하여 세 개의 구체화된 뷰를 프로파일링합니다. 완료되면 다음 단계에서 AI 기반 데이터 품질 규칙을 생성하는 데 사용하는 풍부한 통계 요약을 출력합니다.
Cloud Shell 터미널에서 스크립트를 실행합니다.
python3 1_run_scan.py
프로필 스캔 확인
콘솔에서 새 프로필 스캔을 확인할 수 있습니다. Google Cloud
- 탐색 메뉴의 제어 섹션에서 Knowledge Catalog 및 데이터 프로파일링 및 품질 로 이동합니다.
- 최신 작업 상태와 함께 나열된 세 개의 프로필 스캔을 찾습니다. 스캔을 클릭하여 세부 결과를 탐색합니다.
프로필 결과를 JSON으로 내보내기
Antigravity CLI에서 프로필 스캔을 읽으려면 콘텐츠를 로컬 파일로 추출해야 합니다.
2_dq_profile_save.py 스크립트를 사용하여 mv_ga4_user_session_flat 뷰의 최신 성공 스캔을 찾고 프로필 데이터를 다운로드하여 dq_profile_results.json이라는 파일에 저장합니다.
python3 2_dq_profile_save.py
스크립트가 완료되면 디렉터리에 dq_profile_results.json 파일이 생성됩니다. 이 파일에는 데이터 품질 규칙을 생성하는 데 필요한 세부 통계 메타데이터가 포함되어 있습니다. 다음 명령어를 실행하여 콘텐츠를 살펴봅니다.
cat dq_profile_results.json
Antigravity CLI로 데이터 품질 규칙 생성
이제 Antigravity CLI를 사용하여 로컬 프로필 스캔 결과를 읽을 수 있습니다.
복잡한 데이터 세트에 대한 데이터 품질 사양을 수동으로 작성하는 것은 시간이 많이 걸리고 오류가 발생하기 쉽습니다. 생성형 AI 에이전트를 사용하면 선언적 구성 초안을 몇 초 만에 작성하여 이 워크플로를 가속화할 수 있습니다. 이를 통해 데이터팀은 수동 구문 초안 작성에서 비즈니스에 부합하는 고급 인간 참여형 (HITL) 감독으로 전환할 수 있습니다.
Antigravity CLI를 시작하려면 다음 명령어를 사용합니다.
agy
이제 품질 규칙을 생성할 준비가 되었습니다. CLI는 현재 디렉터리의 파일을 읽을 수 있으므로 새 프로필 스캔 데이터를 직접 사용할 수 있습니다.
에이전트에 계획을 만들라는 프롬프트 입력
먼저 에이전트에 통계 프로필을 분석하고 실행 계획을 제안하도록 요청합니다. 분석 및 정당화에 집중하도록 아직 YAML 파일을 작성하지 말라고 지시합니다.
대화형 Antigravity CLI 세션에서 다음 구조화된 프롬프트를 입력합니다.
# Context
You are preparing a data quality rule configuration plan for Google Cloud Knowledge Catalog based on data profile statistics.
# Input
- File Path: `./dq_profile_results.json` (contains metrics like null percentage, distinct counts, and distributions)
# Task
Analyze the input statistics and propose a step-by-step plan for establishing automated data quality rules.
*Do not write any YAML code in this step.* Focus only on analytical planning.
# Rule Mapping Strategy
For candidate columns, match the statistical metrics to the most appropriate expectations:
- `nonNullExpectation`: Propose for columns with 0% null values in the profile.
- `setExpectation`: Propose for columns with a highly limited, stable set of categorical values.
- `rangeExpectation`: Propose for numeric columns with consistent and predictable value boundaries.
# Guidelines
- Provide a metric-based justification for each proposed rule (for example, "Recommend nonNullExpectation for column 'user_pseudo_id' because its null percentage is 0%").
- Flag volatile metrics such as hardcoded row counts that could cause false-positive alerts in production.
# Output Format
Provide your analysis and proposed rules as a structured, step-by-step markdown plan with clear headings.
에이전트는 JSON 파일을 분석하고 다음과 같은 구조화된 계획을 반환합니다.
Automated Data Quality Rule Configuration Plan
Google Cloud Knowledge Catalog (Dataplex Data Quality)
──────
## Executive Summary
This analytical planning document outlines a step-by-step strategy for configuring automated data quality (DQ) rules in Google Cloud Knowledge Catalog (formerly Dataplex Data Quality) based on profiling statistics.
The dataset contains 26,489 rows representing GA4 event logs. Based on statistical metrics (null ratios, distinct value distributions, and data types), candidate columns are mapped to appropriate expectation rules.
──────
## 1. Data Profile Overview & Statistical Highlights
Column Name │ Data Type │ Null Ratio │ Distinct Count │ Key Value Range / Categories
─────────────────┼───────────┼────────────────┼────────────────┼──────────────────────────────────────────────────
event_date │ STRING │ 0.0% (0) │ 1 (3.78e-05) │ "20210131" (100%)
event_timestamp │ INTEGER │ 0.0% (0) │ ~16,539 (0.62) │ Min: 1612051200657906, Max: 1612137595412363
event_name │ STRING │ 0.0% (0) │ 16 (0.0006) │ page_view (35.8%), user_engagement (18.9%), etc.
user_pseudo_id │ STRING │ 0.0% (0) │ ~2,545 (0.09) │ 18–21 characters string identifiers
user_id │ STRING │ 100.0% (1.0) │ 0 (0.0) │ Entirely NULL
device_category │ STRING │ 0.0% (0) │ 3 (0.0001) │ desktop (57.5%), mobile (40.1%), tablet (2.4%)
... │ ... │ ... │ ... │ ...
──────
## 2. Rule Mapping Strategy & Analytical Justifications
### Step 1: Nullability Rules (nonNullExpectation)
Propose nonNullExpectation for mandatory columns where the data profile demonstrates 0% null values.
• user_pseudo_id, event_timestamp, event_name, event_date, stream_id, platform, device_category (Metric Justification: nullRatio is 0.0%)
│ [!NOTE] Exclusions:
│ • user_id: Has a nullRatio of 100.0% (unauthenticated traffic).
│ • device_language: Has a nullRatio of 37.53%.
──────
### Step 2: Categorical Value Set Validation (setExpectation)
Propose setExpectation for columns with a highly limited, stable set of categorical domain values.
• device_category: Distinct count is exactly 3. Allowed set: ['desktop', 'mobile', 'tablet']
• platform: Distinct count is 1. Allowed set expanded to: ['WEB', 'ANDROID', 'IOS'] to avoid over-fitting.
• geo_continent: Distinct count is 6. Allowed set: ['Americas', 'Asia', 'Europe', 'Africa', 'Oceania', 'Antarctica', '(not set)']
──────
### Step 3: Numeric & Timestamp Boundary Validation (rangeExpectation)
Propose rangeExpectation for numeric columns with consistent and predictable value boundaries.
• event_timestamp: rangeExpectation requiring event_timestamp > 0 (avoid dynamic microsecond range hardcoding)
• stream_id: rangeExpectation requiring positive integer stream IDs (stream_id > 0)
──────
## 3. Risk Warning: Volatile Metrics & Production False Positives
│ [!WARNING] Volatile Metrics Flagged for Risk Mitigation:
1. Hardcoded Total Row Count (rowCount = 26,489) -> Daily event volume fluctuates. Use dynamic volume thresholds.
2. Hardcoded Partition Date (event_date = '20210131') -> Breaks on future runs. Validate against YYYYMMDD regex patterns.
3. Exact Timestamp Range Bounds -> Enforcing these microsecond limits on incoming live pipelines will reject all future data.
4. Single-Value Domain Restrictions -> Single profile sample might lack active streams. Set sets according to enterprise schema.
──────
## Summary Table of Proposed Rules
Target Column │ Rule Type │ Metric-Based Justification │ Operational Considerations
─────────────────┼────────────────────┼────────────────────────────┼──────────────────────────────────────────────────
user_pseudo_id │ nonNullExpectation │ Null Ratio: 0.0% │ Core identifier, strictly required
event_timestamp │ nonNullExpectation │ Null Ratio: 0.0% │ Temporal key, strictly required
event_timestamp │ rangeExpectation │ Min: > 0 (Microseconds) │ Avoid hardcoding epoch min/max
event_name │ nonNullExpectation │ Null Ratio: 0.0% │ Required event taxonomy key
event_name │ setExpectation │ Categorical distribution │ Map to standard GA4 event taxonomy
device_category │ nonNullExpectation │ Null Ratio: 0.0% │ Required form-factor dimension
device_category │ setExpectation │ Distinct Count: 3 values │ ['desktop', 'mobile', 'tablet']
... │ ... │ ... │ ...
데이터 품질 규칙 생성
이것은 전체 워크플로에서 가장 중요한 단계인 인간 참여형 (HITL) 검토입니다. 에이전트가 생성한 계획은 데이터의 통계 패턴을 기반으로 합니다. 에이전트는 비즈니스 컨텍스트, 향후 데이터 변경사항 또는 데이터의 특정 의도를 이해하지 못합니다. 인간 전문가로서의 역할은 이 계획을 코드로 전환하기 전에 검증, 수정, 승인하는 것입니다.
HITL 검토 중에 검증할 항목
다음과 같은 핵심 비즈니스 기준에 따라 에이전트의 제안된 계획을 확인합니다.
- 통계적 이상과 비즈니스 현실:
- 이유: AI 에이전트는 하루 샘플에서 null이 0% 인 열에 null이 포함되어서는 안 된다고 가정하거나 제한된 과거 분포를 기반으로 엄격한 숫자 범위를 설정할 수 있습니다.
- 작업: 제안된 경계 (예:
rangeExpectation또는nonNullExpectation)가 실제 비즈니스 제약조건을 반영하는지 아니면 샘플 세트 아티팩트인지 확인합니다.
- 변동성이 큰 측정항목 (예: 행 수):
- 이유:
rowCount또는 테이블 증가와 같은 측정항목은 활성 엔터프라이즈 환경에서 매일 다릅니다. 정적 규칙은 거짓양성 알림을 유발합니다. - 작업: 동적 트랜잭션 테이블에 정적 임곗값을 적용하는 규칙을 거부하거나 수정합니다.
- 이유:
- 카테고리 완전성 (
setExpectation):- 이유: 프로필 데이터는 스캔된 샘플 창에 있는 값만 표시합니다. 해당 기간에 발생하지 않은 유효한 카테고리를 예측할 수 없습니다.
- 작업: 공식 비즈니스 용어집 또는 참조 데이터와 비교하여 카테고리 목록을 확인하고 샘플에서 생략된 유효한 값을 추가합니다 (예: 누락된 리전 코드 또는 제품 카테고리 추가).
프롬프트 의견으로 계획 구체화
에이전트에 의견을 제공하고 코드 생성에 대한 최종 명령어를 제공합니다. 실제로 수신한 계획과 적용하려는 수정사항을 기반으로 다음 프롬프트를 조정합니다.
프롬프트는 템플릿일 뿐입니다. 첫 번째 줄은 특정 수정사항을 추가하는 위치입니다.
이 프롬프트는 Knowledge Catalog에 정확한 YAML 구조가 필요하므로 DataQualityRule 사양을 준수해야 합니다. 이렇게 하면 구문 오류 또는 오래된 스키마 버전이 방지됩니다.
# Feedback & Approvals
[YOUR CORRECTIONS AND APPROVAL GO HERE. Examples:
- "The plan looks good. Please proceed."
- "The rowCount rule is not necessary, as the table size changes daily. The rest of the plan is approved. Please proceed."
- "For the setExpectation on the geo_continent column, please also include 'Antarctica'."]
# Objective
Based on the approved analysis plan and the provided feedback, generate the final `dq_rules.yaml` file conforming to the standard `DataQualityRule` schema.
# Instructions
1. **Rule Justifications**: For every generated rule, add a YAML comment (`#`) on the line directly above it, briefly explaining the justification established in the plan.
2. **Schema Alignment**: Ensure the structure strictly adheres to the required Knowledge Catalog data quality scan specification. Refer to the `sample_rule.yaml` file in the current directory and the `DataQualityRule` class definition as the schema authority. Search for the `data_quality.py` file inside the `./dq_venv/lib/` directory to read this class definition.
3. **Data-Driven Values**: Derive all rule parameters, such as thresholds or expected values, directly from the statistical metrics in `dq_profile_results.json`.
# Constraints
- **Output Purity**: Return ONLY the raw, valid, and properly formatted YAML code block.
- Do not include conversational preambles, introductory sentences, explanations, or markdown blocks around the YAML.
이제 에이전트는 검증된 안내를 기반으로 작업 디렉터리에 dq_rules.yaml이라는 YAML 파일을 생성합니다.
데이터 품질 스캔 만들기 및 실행
이제 에이전트가 생성하고 사람이 검증한 데이터 품질 규칙 집합이 있으므로 스캔으로 등록하고 배포할 수 있습니다.
/quit를 입력하거나Ctrl+C를 두 번 눌러 Antigravity CLI를 종료합니다.그런 다음 Knowledge Catalog에서 데이터 스캔을 만듭니다.
export DQ_SCAN="dq-scan" gcloud dataplex datascans create data-quality $DQ_SCAN \ --project=$PROJECT_ID \ --location=$LOCATION \ --data-quality-spec-file=dq_rules.yaml \ --data-source-resource="//bigquery.googleapis.com/projects/$PROJECT_ID/datasets/$DATASET_ID/tables/mv_ga4_user_session_flat"스캔을 실행합니다.
gcloud dataplex datascans run $DQ_SCAN --location=$LOCATION --project=$PROJECT_ID이 명령어는
dq-scan이라는 데이터 품질 스캔을 만듭니다.콘솔의 Knowledge Catalog 섹션에서 스캔의 진행 상황을 확인합니다. Google Cloud
- 탐색 메뉴의 제어 섹션에서 Knowledge Catalog 및 데이터 프로파일링 및 품질 로 이동합니다.
dq-scan을 찾습니다. 스캔이 완료되면 스캔을 클릭하여 결과를 확인합니다.
정리
이 튜토리얼에서 만든 리소스에 대해 정기 결제되는 요금을 방지하려면 리소스를 삭제하세요.
Knowledge Catalog 스캔 삭제
이 Codelab의 특정 스캔 이름을 사용하여 프로필 및 품질 스캔을 삭제합니다.
# Delete the Data Quality Scan
gcloud dataplex datascans delete dq-scan \
--location=us-central1 \
--project=$PROJECT_ID --quiet
# Delete the Data Profile Scans
gcloud dataplex datascans delete profile-scan-mv-ga4-user-session-flat \
--location=us-central1 \
--project=$PROJECT_ID --quiet
gcloud dataplex datascans delete profile-scan-mv-ga4-ecommerce-transactions \
--location=us-central1 \
--project=$PROJECT_ID --quiet
gcloud dataplex datascans delete profile-scan-mv-ga4-ecommerce-items \
--location=us-central1 \
--project=$PROJECT_ID --quiet
샘플 데이터 세트 삭제
임시 BigQuery 데이터 세트와 테이블을 삭제합니다.
bq rm -r -f --dataset $PROJECT_ID:kc_dq_codelab
로컬 파일 삭제
Python 가상 환경을 비활성화하고 클론된 저장소와 콘텐츠를 삭제합니다.
deactivate
cd ../../..
rm -rf devrel-demos
결론
축하합니다. 엔드 투 엔드 프로그래매틱 데이터 품질 및 메타데이터 보강 워크플로를 빌드했습니다.
Antigravity CLI 에이전트를 Knowledge Catalog와 페어링하면 AI 지원 메타데이터 보강을 위한 검증 가능한 기반을 설정할 수 있습니다. 이 접근 방식을 사용하면 선언적 규칙 생성이 가속화되므로 데이터 관리자는 인간 참여형 (HITL) 검증 및 비즈니스 로직에 대한 규칙 구체화에 집중할 수 있습니다. 이렇게 하면 데이터 카탈로그가 엔터프라이즈 AI 소비를 위한 신뢰할 수 있는 컨텍스트 엔진 역할을 합니다.
다음 단계
- AI 지원 거버넌스: 인간 감독으로 데이터 품질 가속화에서 이 아키텍처의 기본 철학에 대해 자세히 알아보세요.
- CI/CD 파이프라인을 만들어 데이터 품질을 코드로 관리합니다.
- 커스텀 SQL 규칙을 사용하여 비즈니스별 로직을 적용하는 방법을 알아봅니다.
- 필터와 샘플링으로 스캔을 최적화하여 비용을 절감합니다.
- Terraform으로 Knowledge Catalog 리소스를 프로비저닝하여 인프라를 자동화하여 데이터 품질 사양과 메타데이터 보강을 대규모로 관리합니다.
- Antigravity CLI 빠른 시작을 사용하여 자세히 알아보세요.
- 다른 Knowledge Catalog 사용 사례 사용해 보기