name: bigquery-object-table-agent description: BigQuery Object Tables를 활용한 비정형 데이터(오디오, 이미지 등) 분석 및 Audio Analytics Agent 구축 가이드. GCS 데이터 연동, 메타데이터 캐싱, AI 모델 통합, ADK 에이전트 구현 패턴을 다룹니다.

BigQuery Object Table Agent

Purpose

BigQuery Object Tables를 활용하여 GCS에 저장된 비정형 데이터(오디오, 이미지, 문서 등)를 SQL로 분석하고, 이를 전담하는 ADK 기반 Audio Analytics Agent를 구축하기 위한 가이드입니다. docs/feature/bigquery-object-table-agent의 내용을 바탕으로 작성되었습니다.

When to Use

다음과 같은 상황에서 자동 활성화됩니다:

• BigQuery Object Table 또는 비정형 데이터 분석 언급
• GCS 데이터의 SQL 쿼리 또는 메타데이터 분석 필요 시
• Audio Analytics Agent 구현 또는 오디오 데이터 분석 시
• metadata_cache_mode, max_staleness 등 Object Table 최적화 설정 시

Manual activation: BigQuery Object Table 설정 방법이나 Audio Analytics Agent 구조에 대해 질문하세요.

Core Concepts

BigQuery Object Tables

GCS의 비정형 데이터를 BigQuery의 구조화된 테이블처럼 조회할 수 있게 해주는 기능입니다.

• BigLake 기반: 스토리지와 컴퓨팅의 분리, 통합 보안 관리.
• SQL 인터페이스: uri, size, updated, metadata 등의 가상 컬럼 제공.
• AI 통합: Cloud Vision, Speech-to-Text, Vertex AI 모델을 SQL 함수(ML.PREDICT 등)로 직접 호출 가능.

Architecture

graph LR
    GCS[GCS Bucket\n(Unstructured Data)] -->|BigLake Metadata| BQ[BigQuery Object Table]
    BQ -->|SQL Query| User[User / Agent]
    BQ -->|Remote Function| AI[Vertex AI / Cloud APIs]

Setup Workflow

1. 사전 요구사항

• APIs: bigquery.googleapis.com, bigqueryconnection.googleapis.com, storage.googleapis.com
• IAM: roles/bigquery.admin, roles/bigquery.connectionAdmin, roles/storage.objectViewer

2. Connection 생성

BigQuery가 GCS에 접근하기 위한 권한 위임 통로입니다.

bq mk --connection --location=asia-northeast3 --project_id=PROJECT_ID \
    --connection_type=CLOUD_RESOURCE gcs_audio_connection

생성 후 serviceAccountId를 확인하여 GCS 버킷에 Storage Object Viewer 권한을 부여해야 합니다.

3. Object Table 생성 (DDL)

CREATE EXTERNAL TABLE `project.dataset.audio_object_table`
WITH CONNECTION `project.region.gcs_audio_connection`
OPTIONS (
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket/path/*.mp3'],
  metadata_cache_mode = 'AUTOMATIC',  -- 성능 핵심
  max_staleness = INTERVAL 1 HOUR
);

Agent Implementation

Audio Analytics Agent

alyac_family_domain_expert.py 패턴을 따르는 도메인 전문가 에이전트입니다.

Specs:

• Role: Audio Analytics Specialist
• Tools:
  • analyze_audio_metadata: GCS 메타데이터 통계 (크기, 분포 등)
  • generate_transcription_report: STT 품질 및 언어 분석
  • analyze_user_behavior: Firestore 로그 기반 청취 패턴 분석
  • BigQuery 표준 도구 (list_templates, execute, dry_run 등)

Instruction Guidelines:

• 시간 필터: TIMESTAMP_SUB 사용 시 반드시 DAY 단위 사용 (MONTH 지원 안 함).
• JOIN 전략: audio_object_table.uri와 Firestore의 audio_url을 조인 키로 사용.
• 비정형 데이터: 파일 크기(size), 스토리지 클래스(storage_class) 등을 활용한 비용/성능 최적화 제안.

Custom Tools (audio_analysis.py)

def analyze_audio_metadata(project_id, dataset_id, table_id):
    """
    Object Table을 쿼리하여 스토리지 클래스별 파일 수, 용량, 평균 크기 등을 분석.
    """
    # ... (BigQuery Client 활용)

Performance & Optimization

Metadata Caching

대량의 파일(수천 개 이상)이 있는 경우 필수입니다.

• 설정: metadata_cache_mode = 'AUTOMATIC'
• 효과: 쿼리 시 GCS 파일 목록을 매번 스캔하지 않고 캐시된 메타데이터 사용 (수 분 -> 수 초 단축).
• 갱신: max_staleness 주기에 따라 자동 갱신되거나, 수동으로 테이블을 재생성하여 갱신.

Query Optimization

• Partitioning: 날짜 기반 파티셔닝을 통해 스캔 비용 절감.
• Pseudo-columns: size, updated 등 메타데이터 컬럼만 조회 시 데이터 스캔 비용 무료(또는 매우 저렴).
• Filter Early: WHERE 절을 사용하여 불필요한 파일 처리를 사전에 차단.

Reference Documents

상세 내용은 docs/feature/bigquery-object-table-agent/ 디렉토리를 참조하세요.

• README.md: 프로젝트 개요 및 빠른 시작.
• setup_guide.md: 상세 구축 가이드 및 트러블슈팅.
• audio_analytics_agent_plan.md: 에이전트 설계 및 구현 계획.
• bigquery_object_tables_analysis.md: 기술 심층 분석.