Claude-skill-registry bigquery-object-table-agent

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

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/bigquery-object-table-agent" ~/.claude/skills/majiayu000-claude-skill-registry-bigquery-object-table-agent && rm -rf "$T"

manifest: skills/data/bigquery-object-table-agent/SKILL.md

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: 기술 심층 분석.