codebuff-agent 2.1.74__py3-none-any.whl

jupyter_ext/agent/skills/bigquery_oracle.md

@@ -0,0 +1,231 @@
+---
+name: bigquery_oracle
+description: Oracle(Exadata) → BigQuery SQL 변환. 구문 매핑, 실행 모델 비교, Hint 대체 전략.
+---
+
+# Oracle(Exadata) → BigQuery 변환 가이드
+
+### 구문 매핑 테이블
+
+| Oracle 구문 | BigQuery StandardSQL 대체 |
+|-------------|--------------------------|
+| `ROWNUM` | `ROW_NUMBER() OVER()` |
+| `NVL(a, b)` | `IFNULL(a, b)` / `COALESCE(a, b)` |
+| `NVL2(a, b, c)` | `IF(a IS NOT NULL, b, c)` |
+| `DECODE(a, v1, r1, ...)` | `CASE WHEN a = v1 THEN r1 ... END` |
+| `SYSDATE` | `CURRENT_TIMESTAMP()` |
+| `TO_DATE(s, fmt)` | `PARSE_DATE(fmt, s)` (포맷 문법 다름) |
+| `TO_CHAR(d, fmt)` | `FORMAT_DATE(fmt, d)` / `FORMAT_TIMESTAMP()` |
+| `(+)` outer join | `LEFT JOIN` / `RIGHT JOIN` |
+| `CONNECT BY / START WITH` | Recursive CTE (`WITH RECURSIVE`) |
+| `MINUS` | `EXCEPT DISTINCT` |
+| `FROM DUAL` | FROM 생략 가능 (BQ) |
+| `MERGE INTO` | `MERGE` (BQ DML, 구문 유사) |
+| `ROWID` | 없음 (partition/clustering으로 대체) |
+| `SEQUENCE` | `GENERATE_UUID()` / `ROW_NUMBER()` |
+| `DBMS_*` 패키지 | BQ scripting / UDF |
+| PL/SQL 프로시저 | BQ scripting (`DECLARE`, `SET`, `LOOP`, `IF`) |
+| Oracle hint (`/*+ PARALLEL */`) | 불필요 (BQ 자동 병렬화) |
+| `VARCHAR2(N)` | `STRING` |
+| `NUMBER(p,s)` | `NUMERIC` / `INT64` / `FLOAT64` |
+| `DATE` (Oracle은 timestamp 포함) | `TIMESTAMP` |
+| `CLOB` / `BLOB` | `STRING` / `BYTES` |
+
+### 성능 주의사항
+- **Exadata 물리 인덱스 의존 쿼리** → BQ partition/clustering 전략으로 재설계 필요
+- **Nested Loop Join 패턴** (Oracle index scan 기반) → BQ에서는 Hash Join으로 자동 전환, 대형 테이블 시 pre-filter 필수
+- **PL/SQL 커서 반복** → BQ SET 기반 처리 (벡터 연산)로 재작성
+- **Oracle Materialized View** → BQ Materialized View (구문/제약 다름, GROUP BY + 집계 함수만)
+
+### Oracle vs BigQuery 실행 모델 비교
+
+| 항목 | Oracle (Exadata) | BigQuery |
+|------|-----------------|----------|
+| **스토리지 구조** | Row-store + Smart Scan (column projection) | 완전 Columnar (Capacitor 포맷) |
+| **인덱스** | B-tree, Bitmap, Function-based 등 | 없음 — Partition Pruning + Clustering으로 대체 |
+| **JOIN 전략** | Nested Loop (index), Hash Join, Sort-Merge | Hash Join (shuffle/broadcast) — optimizer 자동 선택 |
+| **정렬** | Index-ordered scan으로 sort 회피 가능 | 항상 명시적 sort (shuffle 필요), LIMIT 없으면 전체 데이터 정렬 |
+| **병렬화** | `/*+ PARALLEL(N) */` hint로 수동 제어 | 자동 (슬롯 기반 분산), hint 불필요 |
+| **캐싱** | Buffer Cache (SGA), Result Cache | 24시간 결과 캐시 (동일 쿼리 + 테이블 미변경 시) |
+| **파티셔닝** | Range, List, Hash, Composite | 시간/정수 Range, Ingestion-time 파티션 |
+| **통계 수집** | `DBMS_STATS`, `/*+ GATHER_PLAN_STATISTICS */` | 자동 (INFORMATION_SCHEMA.JOBS에 job_stages 포함) |
+| **실행 계획** | `EXPLAIN PLAN`, SQL Monitor (`/*+ MONITOR */`) | 쿼리 실행 후 `INFORMATION_SCHEMA.JOBS.job_stages` 또는 Web UI |
+
+### Oracle Hint → BQ 대체 전략
+
+| Oracle Hint | Oracle 목적 | BQ 대체 전략 |
+|-------------|-----------|-------------|
+| `/*+ PARALLEL(N) */` | 병렬 실행 DOP 지정 | 불필요 — BQ 자동 슬롯 분배 |
+| `/*+ FULL(t) */` | Full Table Scan 강제 | 불필요 — BQ 기본이 Full Scan (파티션 프루닝으로 범위 제한) |
+| `/*+ INDEX(t idx) */` | 특정 인덱스 사용 강제 | 파티션 필터 + 클러스터링으로 scan 범위 축소 |
+| `/*+ USE_HASH(t) */` | Hash Join 강제 | BQ 기본 전략, 작은 테이블은 broadcast join 자동 적용 |
+| `/*+ USE_NL(t) */` | Nested Loop Join 강제 | BQ 미지원 — Hash Join으로 자동 대체 |
+| `/*+ LEADING(t1 t2) */` | JOIN 순서 지정 | 불필요 — BQ optimizer 자동 결정 |
+| `/*+ MONITOR */` | SQL Monitor 실시간 추적 | `INFORMATION_SCHEMA.JOBS`가 모든 쿼리 자동 기록 |
+| `/*+ GATHER_PLAN_STATISTICS */` | 실행 통계 수집 | `job_stages` 필드에 stage별 통계 자동 포함 |
+| `/*+ RESULT_CACHE */` | 결과 캐시 활성화 | BQ 24시간 자동 캐시 (동일 쿼리 + 테이블 미변경) |
+| `/*+ NO_RESULT_CACHE */` | 캐시 우회 | `SELECT` 뒤에 `@{cache=false}` 힌트 사용 |
+| `/*+ APPEND */` | Direct-path insert | BQ `INSERT`/`LOAD` 기본 동작 (append) |
+| `/*+ PUSH_PRED */` | 조건 predicate pushdown | BQ optimizer 자동 적용 |
+
+### 변환 시 Anti-Pattern 체크
+
+Oracle에서 문제없지만 BQ에서 anti-pattern이 되는 패턴:
+
+| Oracle 패턴 | BQ에서의 문제 | 권고 |
+|------------|-------------|------|
+| `ORDER BY col DESC` (LIMIT 없음) | BQ에서 전체 데이터 shuffle sort → 대량 slot 소비 | 반드시 `LIMIT N` 추가, 없으면 anti-pattern 경고 |
+| `SELECT *` | Oracle은 row-store라 영향 적음, BQ는 columnar → 불필요 컬럼도 전부 scan | 필요 컬럼만 명시 (bytes_processed 대폭 감소) |
+| `VARCHAR2` 컬럼 JOIN key | Oracle은 인덱스로 고속 매칭, BQ는 STRING Hash → 느림 | 가능하면 INT64 surrogate key 사용, 불가 시 클러스터링 적용 |
+
+### 변환 시 Mermaid 시각화 예시
+
+```
+graph LR
+    subgraph "Oracle 구문"
+        O1["ROWNUM <= 10"]
+        O2["NVL(col, 0)"]
+        O3["DECODE(status, 'A', 'Active')"]
+        O4["table_a a, table_b b<br/>WHERE a.id = b.id(+)"]
+    end
+
+    subgraph "변환 규칙"
+        R1["ROW_NUMBER() OVER()"]
+        R2["IFNULL / COALESCE"]
+        R3["CASE WHEN"]
+        R4["LEFT JOIN"]
+    end
+
+    subgraph "BigQuery 구문"
+        B1["ROW_NUMBER() OVER() <= 10"]
+        B2["IFNULL(col, 0)"]
+        B3["CASE WHEN status='A'<br/>THEN 'Active' END"]
+        B4["table_a a LEFT JOIN<br/>table_b b ON a.id=b.id"]
+    end
+
+    O1 --> R1 --> B1
+    O2 --> R2 --> B2
+    O3 --> R3 --> B3
+    O4 --> R4 --> B4
+
+    style O1 fill:#EA4335,color:#fff
+    style O2 fill:#EA4335,color:#fff
+    style O3 fill:#EA4335,color:#fff
+    style O4 fill:#EA4335,color:#fff
+    style B1 fill:#34A853,color:#fff
+    style B2 fill:#34A853,color:#fff
+    style B3 fill:#34A853,color:#fff
+    style B4 fill:#34A853,color:#fff
+```
+
+---
+
+## ⚠️ 필수 출력 규칙
+
+**모든 Oracle→BQ 변환 응답에는 반드시 ```mermaid 다이어그램을 포함하세요.**
+- Oracle 실행 흐름 다이어그램 (graph TD)
+- BigQuery 실행 흐름 다이어그램 (graph TD)
+- 두 흐름의 비교가 시각적으로 드러나야 합니다.
+- 다이어그램 없는 응답은 불완전한 응답입니다.
+
+## 변환 예시 (Oracle 계층형 쿼리)
+
+### 변환 개요
+Oracle `CONNECT BY / START WITH` 계층형 쿼리를 BigQuery `WITH RECURSIVE` CTE로 변환합니다.
+주요 변경사항:
+- `START WITH ... CONNECT BY PRIOR` → `WITH RECURSIVE` CTE (base case + recursive step)
+- `LEVEL` 의사컬럼 → CTE 내부 `depth` 컬럼으로 수동 계산
+- `LPAD(' ', 2*(LEVEL-1))` → `REPEAT('  ', depth)` 로 대체
+- `ORDER SIBLINGS BY` → BQ에서 직접 대응 없음, `path` 컬럼으로 정렬 구현
+
+```sql
+-- Oracle CONNECT BY → BigQuery WITH RECURSIVE 변환
+WITH RECURSIVE org_tree AS (
+  -- Base case: 루트 노드 (manager_id IS NULL)
+  SELECT
+    employee_id,
+    employee_name,
+    manager_id,
+    0 AS depth,
+    -- 형제 정렬용 path (ORDER SIBLINGS BY 대체)
+    CAST(employee_name AS STRING) AS sort_path
+  FROM `project.dataset.employees`
+  WHERE manager_id IS NULL
+
+  UNION ALL
+
+  -- Recursive step: 자식 노드
+  SELECT
+    e.employee_id,
+    e.employee_name,
+    e.manager_id,
+    t.depth + 1,
+    CONCAT(t.sort_path, '/', e.employee_name)
+  FROM `project.dataset.employees` e
+  JOIN org_tree t ON e.manager_id = t.employee_id
+)
+SELECT
+  depth + 1 AS level,
+  CONCAT(REPEAT('  ', depth), employee_name) AS tree_name,
+  employee_id,
+  manager_id
+FROM org_tree
+ORDER BY sort_path
+```
+
+### 구문 매핑 상세
+
+| Oracle 구문 | BigQuery 대체 | 동작 차이 및 주의사항 |
+|-------------|--------------|---------------------|
+| `START WITH condition` | CTE base case `WHERE` | 동일한 필터 역할. BQ는 CTE 첫 번째 SELECT에 배치 |
+| `CONNECT BY PRIOR a = b` | `JOIN org_tree t ON ...` | Oracle은 엔진 내부 트리 순회, BQ는 반복 JOIN |
+| `LEVEL` | 수동 `depth` 컬럼 | Oracle은 자동 생성, BQ는 base=0에서 +1 누적 |
+| `ORDER SIBLINGS BY name` | `sort_path` + `ORDER BY` | Oracle은 같은 부모 내 정렬 보장, BQ는 경로 문자열로 구현 |
+| `LPAD(' ', 2*(LEVEL-1))` | `REPEAT('  ', depth)` | `LPAD`은 BQ에도 있지만 `REPEAT`이 가독성 우수 |
+
+#### `ORDER SIBLINGS BY` 구현 상세
+Oracle의 `ORDER SIBLINGS BY`는 **동일 부모(parent) 내에서만** 정렬을 보장합니다.
+BQ의 `WITH RECURSIVE`에는 이 기능이 없으므로, `sort_path` 컬럼에 루트부터의 경로를 `/`로 연결하여 전체 트리를 사전순 정렬합니다.
+단, 이름에 `/`가 포함된 경우 구분자 충돌 가능 → 해시나 zero-width 구분자 사용을 고려하세요.
+
+### 실행 흐름 비교
+
+#### Oracle 실행 흐름
+```mermaid
+graph TD
+    A[START WITH 조건으로 루트 행 선택] --> B[CONNECT BY PRIOR로 자식 행 탐색]
+    B --> C{자식 행 존재?}
+    C -->|Yes| D[LEVEL 자동 증가 + 트리에 추가]
+    D --> B
+    C -->|No| E[ORDER SIBLINGS BY로 형제 정렬]
+    E --> F[결과 반환]
+```
+
+#### BigQuery 실행 흐름
+```mermaid
+graph TD
+    A[Base CTE: WHERE manager_id IS NULL] --> B[depth=0 결과 임시 저장]
+    B --> C[Recursive step: employees JOIN org_tree]
+    C --> D{새 행 생성됨?}
+    D -->|Yes| E[depth+1, sort_path 연결]
+    E --> F[셔플 → 임시 저장]
+    F --> C
+    D -->|No| G[전체 결과 UNION ALL]
+    G --> H[ORDER BY sort_path]
+    H --> I[결과 반환]
+```
+
+| 항목 | Oracle | BigQuery |
+|------|--------|----------|
+| 실행 방식 | 내부 트리 순회 엔진 (O(n)) | 반복 JOIN (각 depth마다 전체 스캔) |
+| 깊이 제한 | `CONNECT BY` 기본 1000 | `max_recursion_depth` 기본 500 |
+| 메모리 | 작업 메모리에서 트리 구축 | 각 반복 결과를 셔플 저장 |
+| 성능 영향 | 인덱스 활용 가능 | 파티션 pruning 불가 (recursive CTE) |
+
+**주의**: 직원 수 10만+ 이상의 대규모 조직에서는 BQ recursive CTE가 느려질 수 있습니다.
+이 경우 `max_recursion_depth` 설정을 확인하고, 필요 시 반복 깊이를 제한하세요.
+
+### BQ 최적화 권고
+1. **employees 테이블 클러스터링**: `manager_id`로 클러스터링하면 recursive step의 JOIN 성능 향상
+2. **깊이 제한**: `WHERE depth < 10` 등으로 무한 재귀 방지
+3. **매터리얼라이즈드 뷰**: 조직도가 자주 조회되면 결과를 MV로 캐싱 고려

jupyter_ext/agent/skills/bigquery_tuning.md

@@ -0,0 +1,307 @@
+---
+name: bigquery_tuning
+description: BigQuery 900-slot 쿼리 튜닝, anti-pattern 탐지, 비용 최적화, INFORMATION_SCHEMA 참조.
+---
+
+# BigQuery Query Analysis & Optimization Guide
+
+BigQuery 쿼리 분석, 튜닝, 비용 최적화 시 참고하는 레퍼런스 가이드입니다.
+
+---
+
+## 1. INFORMATION_SCHEMA.JOBS 핵심 컬럼
+
+데이터는 `creation_time` 기준 파티셔닝, `project_id`와 `user_email`으로 클러스터링. 180일 보관.
+
+### 핵심 식별/성능 컬럼
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `job_id` | STRING | Unique job identifier |
+| `query` | STRING | SQL text |
+| `total_slot_ms` | INT64 | Total slot-milliseconds consumed |
+| `total_bytes_processed` | INT64 | Bytes processed |
+| `total_bytes_billed` | INT64 | Bytes billed (min 10MB, rounded up to MB) |
+| `cache_hit` | BOOL | Whether results from cache |
+| `job_stages` | RECORD (REPEATED) | Execution stage array |
+| `creation_time` | TIMESTAMP | Job creation time |
+| `start_time` | TIMESTAMP | Execution start |
+| `end_time` | TIMESTAMP | Execution end |
+| `reservation_id` | STRING | Reservation name |
+| `priority` | STRING | INTERACTIVE or BATCH |
+| `referenced_tables` | RECORD (REPEATED) | Tables read |
+| `destination_table` | RECORD | Target table |
+| `statement_type` | STRING | SELECT, INSERT, MERGE, etc. |
+
+---
+
+## 2. job_stages RECORD 스키마
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | INT64 | Stage identifier |
+| `name` | STRING | Human-readable stage name |
+| `slot_ms` | INT64 | Slot-ms used by stage |
+| `records_read` | INT64 | Records read |
+| `records_written` | INT64 | Records written |
+| `shuffle_output_bytes` | INT64 | Bytes written to shuffle |
+| `shuffle_output_bytes_spilled` | INT64 | Bytes spilled to disk |
+| `compute_ms_avg` | INT64 | Avg compute ms per shard |
+| `compute_ms_max` | INT64 | Max compute ms per shard |
+| `wait_ms_avg` | INT64 | Avg wait ms |
+| `wait_ms_max` | INT64 | Max wait ms |
+| `input_stages` | INT64 (REPEATED) | IDs of input stages |
+| `steps` | RECORD (REPEATED) | Operations (kind + substeps) |
+| `parallel_inputs` | INT64 | Number of parallel input segments |
+
+**steps sub-record**: `kind` (READ, COMPUTE, AGGREGATE, WRITE, HASH, SORT, JOIN, USER_DEFINED_FUNCTION) + `substeps` (STRING REPEATED)
+
+---
+
+## 3. Anti-Pattern 탐지 규칙
+
+| # | Anti-Pattern | Detection | Severity | Fix |
+|---|-------------|-----------|----------|-----|
+| 1 | `SELECT *` | `SELECT\s+\*` regex | HIGH | 필요 컬럼만 명시 |
+| 2 | Self-join | 같은 테이블이 FROM과 JOIN에 | HIGH | Window/Analytic 함수 또는 PIVOT |
+| 3 | Missing partition filter | 파티션 컬럼 WHERE 조건 없음 | HIGH | 파티션 컬럼 필터 추가 |
+| 4 | `ORDER BY` without `LIMIT` | ORDER BY 있고 LIMIT 없음 | MEDIUM | LIMIT 추가 |
+| 5 | `COUNT(DISTINCT)` high-cardinality | 대규모 데이터에 COUNT(DISTINCT) | MEDIUM | `APPROX_COUNT_DISTINCT()` 사용 |
+| 6 | `NOT IN` subquery | NOT IN + 서브쿼리 | MEDIUM | `NOT EXISTS` 또는 `LEFT JOIN ... IS NULL` |
+| 7 | Cross-join | inequality JOIN 조건 | HIGH | equi-join으로 재구성 |
+| 8 | Repeated CTE | 동일 CTE 2회+ 참조 | LOW | TEMP TABLE로 물리화 |
+| 9 | Leading wildcard `LIKE '%x'` | LIKE 앞에 % | LOW | 가능하면 suffix 검색 회피 |
+| 10 | `UNION` vs `UNION ALL` | 불필요한 중복 제거 | LOW | `UNION ALL` 사용 |
+
+참고 도구: `GoogleCloudPlatform/bigquery-antipattern-recognition` (ZetaSQL 기반 AST 분석)
+
+---
+
+## 4. 비용 추정 공식
+
+### On-Demand 가격
+- **$6.25 / TiB** processed (US multi-region)
+- 첫 1 TiB/월 무료
+- 최소 10MB billing, MB 단위 올림
+
+```
+cost_usd = (total_bytes_billed / 1024^4) × 6.25
+```
+
+### 900-slot Enterprise Reservation
+- **PAYG**: 900 × 730h × $0.06 = **~$39,420/월**
+- **1-yr**: ~$35,478/월
+- **3-yr**: ~$31,536/월
+
+```
+capacity_cost = (total_slot_ms / 3,600,000) × price_per_slot_hour
+```
+
+### 비용 절감액 계산 (튜닝 시 필수 출력)
+```
+on_demand_saving = (bytes_before - bytes_after) / 1024^4 × 6.25
+monthly_saving = daily_executions × on_demand_saving × 30
+annual_saving = monthly_saving × 12
+```
+
+---
+
+## 5. Mermaid 다이어그램 템플릿
+
+### Color Coding Convention
+
+| Color | Hex | Meaning | When to Apply |
+|-------|-----|---------|---------------|
+| Blue | #4285F4 | READ stages | Input/scan |
+| Red | #EA4335 | Bottleneck | slot_ms > 50% of total, or high skew |
+| Orange | #FF6D01 | Data skew | compute_ms_max/avg > 3x |
+| Yellow | #FBBC04 | Shuffle spill | spilled > 0 |
+| Green | #34A853 | WRITE/output | Final output |
+| Gray | #9AA0A6 | Idle/waiting | wait_ratio_avg > 0.5 |
+
+### Stage Flowchart 템플릿
+
+```
+graph TD
+    S0["Stage 0: READ<br/>table_name<br/>records: N<br/>slot_ms: N"]
+    S1["Stage 1: HASH JOIN<br/>shuffle: N GB<br/>slot_ms: N"]
+    S2["Stage 2: AGGREGATE<br/>GROUP BY col<br/>slot_ms: N"]
+    S3["Stage 3: WRITE<br/>output<br/>records: N"]
+
+    S0 -->|"N rows"| S1
+    S1 -->|"N rows"| S2
+    S2 -->|"N rows"| S3
+
+    style S0 fill:#4285F4,color:#fff
+    style S1 fill:#EA4335,color:#fff
+    style S2 fill:#FBBC04,color:#000
+    style S3 fill:#34A853,color:#fff
+```
+
+### As-Is vs To-Be 비교 레이아웃
+
+```
+graph LR
+    subgraph "AS-IS (before tuning)"
+        A0["READ: full scan<br/>bytes: 500GB"]
+        A1["JOIN: shuffle 50GB"]
+        A2["OUTPUT"]
+        A0 --> A1 --> A2
+    end
+
+    subgraph "TO-BE (after tuning)"
+        B0["READ: partition pruned<br/>bytes: 20GB"]
+        B1["JOIN: broadcast<br/>shuffle: 0"]
+        B2["OUTPUT"]
+        B0 --> B1 --> B2
+    end
+
+    style A0 fill:#EA4335,color:#fff
+    style A1 fill:#EA4335,color:#fff
+    style B0 fill:#34A853,color:#fff
+    style B1 fill:#34A853,color:#fff
+```
+
+---
+
+## 6. 900-Slot 최적화 가이드
+
+### 핵심 메트릭
+```
+avg_slots = total_slot_ms / wall_time_ms
+slot_utilization = avg_slots / 900
+contention = period_estimated_runnable_units > 0
+```
+
+### 최적화 전략
+1. **Slot hog 식별**: `total_slot_ms > 300,000` (5분 이상 slot 소비)
+2. **BATCH priority**: 비긴급 쿼리는 `@{priority: "BATCH"}` 사용
+3. **Stagger batch jobs**: 대형 쿼리 동시 실행 회피
+4. **Partition/Clustering**: 파티션 프루닝 + 클러스터링으로 scan 범위 축소
+5. **Materialized View**: 반복 집계를 MV로 사전 계산
+6. **JOIN 최적화**: broadcast join 유도 (작은 테이블 필터링), skew salting
+
+### Slot Pressure 판단 기준
+| Metric | 정상 | 주의 | 위험 |
+|--------|------|------|------|
+| P50 slots | < 450 | 450-720 | > 720 |
+| P99 slots | < 720 | 720-900 | > 900 |
+| Queued units | 0 | 간헐적 | 5분+ 지속 |
+| Spill bytes | 0 | 간헐적 | 상시 |
+
+---
+
+## 7. 유용한 INFORMATION_SCHEMA 쿼리
+
+### Top Expensive Queries (24시간)
+```sql
+SELECT job_id, user_email, query, total_bytes_processed, total_bytes_billed,
+  total_slot_ms, TIMESTAMP_DIFF(end_time, start_time, SECOND) AS duration_sec, cache_hit
+FROM `region-us`.INFORMATION_SCHEMA.JOBS
+WHERE creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 24 HOUR)
+  AND job_type = 'QUERY' AND state = 'DONE' AND error_result IS NULL
+ORDER BY total_bytes_processed DESC LIMIT 20;
+```
+
+### Slot Pressure (900-slot 초과 여부)
+```sql
+WITH slot_usage AS (
+  SELECT TIMESTAMP_TRUNC(period_start, SECOND) AS sec,
+    SUM(period_slot_ms) / 1000 AS slots_used,
+    MAX(period_estimated_runnable_units) AS runnable_units
+  FROM `region-us`.INFORMATION_SCHEMA.JOBS_TIMELINE
+  WHERE period_start > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 24 HOUR)
+  GROUP BY sec
+)
+SELECT COUNTIF(slots_used > 900) AS seconds_over_900, COUNT(*) AS total_seconds,
+  ROUND(COUNTIF(slots_used > 900) / COUNT(*) * 100, 2) AS pct_over_capacity,
+  MAX(slots_used) AS peak_slots,
+  APPROX_QUANTILES(slots_used, 100)[OFFSET(50)] AS p50,
+  APPROX_QUANTILES(slots_used, 100)[OFFSET(90)] AS p90,
+  APPROX_QUANTILES(slots_used, 100)[OFFSET(99)] AS p99
+FROM slot_usage;
+```
+
+### Skew Detection
+```sql
+SELECT job_id, stage.name, stage.id, stage.slot_ms,
+  stage.compute_ms_max, stage.compute_ms_avg,
+  SAFE_DIVIDE(stage.compute_ms_max, NULLIF(stage.compute_ms_avg, 0)) AS skew_ratio,
+  stage.shuffle_output_bytes_spilled
+FROM `region-us`.INFORMATION_SCHEMA.JOBS, UNNEST(job_stages) AS stage
+WHERE creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 24 HOUR)
+  AND job_type = 'QUERY' AND state = 'DONE' AND total_slot_ms > 60000
+ORDER BY skew_ratio DESC LIMIT 50;
+```
+
+### Anomaly Detection (Z-score)
+```sql
+WITH query_patterns AS (
+  SELECT REGEXP_REPLACE(REGEXP_REPLACE(query, r"'[^']*'", "'?'"), r'\b\d+\b', '?') AS template,
+    total_slot_ms, TIMESTAMP_DIFF(end_time, start_time, SECOND) AS duration_sec, job_id
+  FROM `region-us`.INFORMATION_SCHEMA.JOBS
+  WHERE creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
+    AND job_type = 'QUERY' AND state = 'DONE' AND error_result IS NULL
+),
+stats AS (
+  SELECT template, AVG(total_slot_ms) AS avg_slot_ms, STDDEV(total_slot_ms) AS std_slot_ms,
+    AVG(duration_sec) AS avg_dur, STDDEV(duration_sec) AS std_dur
+  FROM query_patterns GROUP BY template HAVING COUNT(*) >= 5
+)
+SELECT p.job_id, p.duration_sec, s.avg_dur,
+  ROUND((p.duration_sec - s.avg_dur) / NULLIF(s.std_dur, 0), 2) AS dur_z,
+  ROUND((p.total_slot_ms - s.avg_slot_ms) / NULLIF(s.std_slot_ms, 0), 2) AS slot_z
+FROM query_patterns p JOIN stats s ON p.template = s.template
+WHERE ABS((p.total_slot_ms - s.avg_slot_ms) / NULLIF(s.std_slot_ms, 0)) > 3
+ORDER BY slot_z DESC LIMIT 20;
+```
+
+---
+
+## 8. 추가 기능 가이드
+
+### Schema Analysis
+```sql
+-- 테이블 크기/행 수
+SELECT table_name, total_rows,
+  ROUND(total_logical_bytes / POW(1024, 3), 2) AS size_gb,
+  ROUND(total_physical_bytes / NULLIF(total_logical_bytes, 0), 2) AS compression_ratio
+FROM `project.dataset`.INFORMATION_SCHEMA.TABLE_STORAGE
+ORDER BY total_logical_bytes DESC;
+
+-- 컬럼 메타데이터 (파티션/클러스터 확인)
+SELECT column_name, data_type, is_partitioning_column, clustering_ordinal_position
+FROM `project.dataset`.INFORMATION_SCHEMA.COLUMNS
+WHERE table_name = 'target_table' ORDER BY ordinal_position;
+```
+
+### Data Lineage (테이블 의존관계)
+```sql
+SELECT ref.project_id, ref.dataset_id, ref.table_id,
+  COUNT(*) AS query_count, COUNT(DISTINCT user_email) AS users
+FROM `region-us`.INFORMATION_SCHEMA.JOBS, UNNEST(referenced_tables) AS ref
+WHERE creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
+  AND job_type = 'QUERY' AND state = 'DONE'
+GROUP BY 1, 2, 3 ORDER BY query_count DESC LIMIT 30;
+```
+
+### Dry-Run 비용 사전 추정 (Python)
+```python
+from google.cloud import bigquery
+client = bigquery.Client()
+job_config = bigquery.QueryJobConfig(dry_run=True, use_query_cache=False)
+query_job = client.query("SELECT ...", job_config=job_config)
+bytes_processed = query_job.total_bytes_processed
+cost_estimate = (bytes_processed / (1024**4)) * 6.25
+print(f"Estimated cost: ${cost_estimate:.4f}")
+```
+
+---
+
+## ⚠️ 필수 출력 규칙
+
+**모든 튜닝/오류수정 응답에는 반드시 ```mermaid 다이어그램을 포함하세요.**
+- 튜닝: AS-IS vs TO-BE 실행 흐름 비교 (위 템플릿 참조)
+- 오류 수정: 에러 발생 흐름 → 수정 후 정상 흐름
+- 위 Color Coding Convention을 반드시 적용하세요.
+- 다이어그램 없는 응답은 불완전한 응답입니다.

jupyter_ext/agent/skills/classification_evaluation.md

@@ -0,0 +1,11 @@
+---
+name: classification_evaluation
+description: 'Classification Evaluation Template. 이런 요청에 쓴다: classification, 분류, confusion matrix, 혼동행렬, roc'
+---
+## Classification Evaluation Template
+1. **Confusion Matrix**: `confusion_matrix()` → `ConfusionMatrixDisplay`
+2. **Classification Report**: `classification_report()` (precision, recall, F1)
+3. **ROC Curve**: `roc_curve()` → `RocCurveDisplay` with AUC score
+4. **Precision-Recall Curve**: For imbalanced datasets
+5. **Cross-Validation**: Stratified K-Fold to ensure class balance
+6. **Error Analysis**: Examine misclassified samples for patterns

jupyter_ext/agent/skills/clustering_analysis.md

@@ -0,0 +1,12 @@
+---
+name: clustering_analysis
+description: 'Clustering Analysis Template. 이런 요청에 쓴다: clustering, k-means, dbscan, silhouette, 군집, 클러스터링'
+---
+## Clustering Analysis Template
+1. **Data Scaling**: `StandardScaler()` — critical for distance-based methods
+2. **Optimal K**: Elbow method (`inertia_`) + Silhouette score (`silhouette_score()`)
+3. **Algorithm Selection**: K-Means, DBSCAN, Hierarchical — based on data shape
+4. **Fit & Predict**: `labels = model.fit_predict(X_scaled)`
+5. **Evaluation**: Silhouette, Calinski-Harabasz, Davies-Bouldin scores
+6. **Visualization**: PCA/t-SNE 2D scatter colored by cluster labels
+7. **Cluster Profiling**: Aggregate stats per cluster, identify distinguishing features

jupyter_ext/agent/skills/comprehensive_eda.md

@@ -0,0 +1,11 @@
+---
+name: comprehensive_eda
+description: 'EDA Workflow Template. 이런 요청에 쓴다: eda, 탐색적 데이터 분석, exploratory, 데이터 탐색, 데이터 분석'
+---
+## EDA Workflow Template
+1. **Data Overview**: `df.shape`, `df.info()`, `df.describe()`, `df.dtypes`
+2. **Missing Values**: `df.isnull().sum()`, visualize with `msno.matrix(df)`
+3. **Distributions**: Histograms for numerical, value_counts for categorical
+4. **Correlations**: `df.corr()` heatmap with `sns.heatmap()`
+5. **Outliers**: Box plots, IQR method, z-score analysis
+6. **Target Analysis**: Distribution, class balance, relationship with features