careerly-data-mcp 2.0.1 → 2.1.1

package/README.md

@@ -1,6 +1,33 @@
-# Careerly GA4 MCP Server
+# Careerly Data MCP Server
 
-Claude Code에서 자연어로 GA4 데이터를 분석하는 MCP(Model Context Protocol) 서버입니다.
+Claude Code에서 **자연어로 GA4와 BigQuery 데이터를 분석**하는 MCP(Model Context Protocol) 서버입니다.
+
+## 왜 MCP를 쓰나요? (vs API 직접 호출)
+
+### 기존 방식의 문제점
+
+```
+GA4 데이터 보고 싶다 → GA4 API 문서 읽기 → 인증 설정 → 코드 작성 → 결과 해석
+BigQuery 분석하고 싶다 → SQL 작성 → UNNEST 문법 검색 → 쿼리 수정 → 결과 해석
+```
+
+### MCP 방식
+
+```
+"지난 7일 세션수 보여줘" → 끝!
+"page_view → post_detail_view 전환율 분석해줘" → 끝!
+```
+
+### 핵심 장점
+
+| 기존 API 직접 호출 | MCP 사용 |
+|------------------|---------|
+| API 문서 읽고 코드 작성 필요 | 자연어로 질문하면 끝 |
+| GA4 event_params 추출 = 복잡한 UNNEST SQL | `bq_event_params` 도구로 한 줄 |
+| 퍼널 분석 = 10줄 이상 SQL | `bq_funnel` 도구로 자동 계산 |
+| 결과는 숫자만 | **인사이트 + 다음 액션 제안**까지 |
+
+---
 
 ## 빠른 시작
 
@@ -8,110 +35,189 @@ Claude Code에서 자연어로 GA4 데이터를 분석하는 MCP(Model Context P
 # 1. Service Account JSON 키 파일이 있는 폴더에서 실행
 cd /path/to/your/project
 
-# 2. 설정 실행 (키 파일 자동 탐지 + Claude Code 자동 등록!)
-npx careerly-ga4-mcp setup
+# 2. 설정 실행 (키 파일 자동 탐지 + Claude Code 자동 등록)
+npx careerly-data-mcp setup
 
 # 3. Claude Code 재시작 후 /mcp 확인!
 ```
 
 ### 자동 설정 기능
 
-`setup` 명령어는 다음을 자동으로 처리합니다:
-
-1. **Service Account 키 파일 자동 탐지** - 현재 폴더에서 JSON 파일 스캔
-2. **GA4 연결 테스트** - Property ID와 키 파일 검증
-3. **Claude Code MCP 자동 등록** - `claude mcp add` 명령어로 자동 설정
+`setup` 명령어가 알아서 처리합니다:
 
-```
-  Careerly GA4 MCP Server
-  ─────────────────────────────────────
+1. **Service Account 키 파일 자동 탐지** - 폴더에서 JSON 파일 스캔
+2. **GA4 + BigQuery 연결 테스트** - Property ID와 키 파일 검증
+3. **Claude Code MCP 자동 등록** - 재시작만 하면 바로 사용 가능
 
-✔ GA4 Property ID 517059569
-✔ 1개의 Service Account 키 파일 발견
-✔ 사용할 키 파일 선택 my-project-key.json (my-project-id)
-✔ 연결 성공!
-✔ Claude Code MCP 서버 등록 완료
-
-  ✓ 설정 완료!
-```
+---
 
-## 사전 준비
+## 사전 준비 (관리자)
 
 ### 1. Google Cloud 설정
 
 1. [Google Cloud Console](https://console.cloud.google.com/)에서 프로젝트 생성
 2. **Google Analytics Data API** 활성화
-3. **서비스 계정** 생성 후 JSON 키 다운로드
+3. **BigQuery API** 활성화
+4. **서비스 계정** 생성 후 JSON 키 다운로드
 
 ### 2. GA4 권한 설정
 
-1. [GA4 Admin](https://analytics.google.com/) > 속성 설정 > 속성 액세스 관리
-2. 서비스 계정 이메일 추가 (뷰어/읽기 전용 권한)
+- GA4 Admin > 속성 설정 > 속성 액세스 관리
+- 서비스 계정 이메일 추가 (뷰어 권한)
+
+### 3. BigQuery 권한 설정
+
+- IAM & Admin > 서비스 계정에 **BigQuery 데이터 뷰어** 역할 추가
+
+---
+
+## 제공 도구 (Tools)
+
+### GA4 Data API 도구
 
-> **Tip**: Service Account 이메일은 JSON 키 파일의 `client_email` 필드에서 확인할 수 있습니다.
+| Tool | 설명 | 언제 쓰나요? |
+|------|------|------------|
+| `ga4_query` | GA4 데이터 조회 + 인사이트 | 세션, 사용자, 전환 등 기본 지표 |
+| `ga4_metadata` | 지표/차원 목록 | 어떤 데이터를 볼 수 있는지 확인 |
+| `ga4_status` | 연결 상태 확인 | 연결 문제 진단 |
 
-## 기능
+### BigQuery 기본 도구
 
-| Tool | 설명 |
-|------|------|
-| `ga4_query` | GA4 데이터 조회 + 인사이트 생성 |
-| `ga4_metadata` | 지표/차원 목록 확인 |
-| `ga4_status` | 연결 상태 확인 |
+| Tool | 설명 | 언제 쓰나요? |
+|------|------|------------|
+| `bq_query` | BigQuery 테이블 조회 | 일반 테이블 데이터 조회 |
+| `bq_metadata` | 스키마/테이블 목록 | 데이터 구조 파악 |
+| `bq_status` | 연결 상태 확인 | 연결 문제 진단 |
+| `bq_ga4_events` | GA4 Export 이벤트 조회 | event_params 자동 추출 |
+
+### BigQuery 고급 도구 (v2.1.0 신규)
+
+| Tool | 설명 | 언제 쓰나요? |
+|------|------|------------|
+| `bq_raw_sql` | SQL 직접 실행 | 복잡한 JOIN, 윈도우 함수 등 |
+| `bq_event_params` | 이벤트 파라미터 추출 | page_location, page_title 등 쉽게 추출 |
+| `bq_user_journey` | 사용자 여정 분석 | 특정 사용자가 어떤 행동을 했는지 |
+| `bq_funnel` | 퍼널 분석 | 단계별 전환율 자동 계산 |
+
+---
 
 ## 사용 예시
 
-Claude Code에서 자연어로 질문:
+Claude Code에서 자연어로 질문하세요:
+
+### 기본 질의
 
 ```
 "지난 7일 세션수 보여줘"
 "채널별 전환수 알려줘"
 "어제 대비 오늘 트래픽 어때?"
 "랜딩 페이지별 이탈률 분석해줘"
-"캠페인별 성과 비교해줘"
 ```
 
+### 고급 질의 (v2.1.0)
+
+```
+"page_view 이벤트에서 page_location 파라미터 추출해줘"
+"사용자 ID 12345678의 행동 여정 보여줘"
+"page_view → post_detail_view → post_create_start 퍼널 분석해줘"
+"디바이스별 전환율 비교해줘"
+```
+
+### 실제 결과 예시 (퍼널 분석)
+
+```
+## 요약
+page_view → post_create_start 전환율: 2.3% | 1,215 → 28명
+
+## 인사이트
+1. 전체 전환율: 2.3% (1,215명 중 28명 완료)
+2. 최대 이탈 구간: page_view → post_detail_view (89.8% 이탈)
+3. post_detail_view → post_create_start: 22.8% 전환 (개선 필요)
+
+## 퍼널 시각화
+1. page_view            ██████████████████████████████ 1,215명 (100%)
+2. post_detail_view     ███░░░░░░░░░░░░░░░░░░░░░░░░░░░ 123명 (10.1%)
+3. post_create_start    █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 28명 (2.3%)
+```
+
+---
+
+## v2.1.0 주요 업데이트
+
+### 버그 수정
+
+- `bq_ga4_events` GROUP BY 오류 해결
+  - 이제 metrics 있을 때/없을 때 모두 정상 동작
+
+### 새 기능
+
+- **복합 필터 지원**: `filterLogic: "AND" | "OR"` 옵션 추가
+- **Raw SQL 실행**: 복잡한 쿼리도 직접 작성 가능 (SELECT만 허용)
+
+### 새 도구 4개 추가
+
+| 도구 | 하는 일 |
+|------|--------|
+| `bq_raw_sql` | SQL 직접 실행 (UNNEST, JOIN 등) |
+| `bq_event_params` | event_params 쉽게 추출 |
+| `bq_user_journey` | 사용자별 이벤트 시퀀스 분석 |
+| `bq_funnel` | 전환 퍼널 자동 계산 |
+
+---
+
 ## CLI 명령어
 
 ```bash
 # 인터랙티브 메뉴
-npx careerly-ga4-mcp
+npx careerly-data-mcp
 
-# 초기 설정 (자동 키 파일 탐지 + Claude Code 자동 등록)
-npx careerly-ga4-mcp setup
+# 초기 설정
+npx careerly-data-mcp setup
 
-# 서버 정보 확인
-npx careerly-ga4-mcp info
+# 연결 테스트
+npx careerly-data-mcp test-connection
 
-# GA4 연결 테스트
-npx careerly-ga4-mcp test-connection
+# 서버 정보
+npx careerly-data-mcp info
 
 # MCP 서버 시작 (수동)
-npx careerly-ga4-mcp serve
+npx careerly-data-mcp serve
 ```
 
-## 인터랙티브 메뉴
+> **별칭**: `careerly-ga4-mcp`, `careerly-ga4`도 동일하게 동작합니다.
 
-```bash
-npx careerly-ga4-mcp
-```
+---
 
-```
-  Careerly GA4 MCP Server
-  ─────────────────────────────────────
+## 문제 해결
+
+### MCP 서버가 `/mcp`에 안 보여요
+
+1. Claude Code 완전 종료 후 재시작
+2. `claude mcp list`로 등록 확인
+3. `npx careerly-data-mcp setup` 재실행
+
+### PERMISSION_DENIED 에러
+
+**GA4 권한 문제:**
+- GA4 Admin > 속성 액세스 관리 > Service Account 이메일 추가
+
+**BigQuery 권한 문제:**
+- IAM & Admin > Service Account에 "BigQuery 데이터 뷰어" 역할 추가
 
-Status:      ✓ connected
-Property ID: 123456789
-Credentials: ~/project/service-account.json
-Tools:       3 tools
+### MCP 제거
 
-? 선택하세요
-❯ View tools
-  Reconnect
-  Test connection
-  Disable
+```bash
+# CLI로 삭제
+claude mcp remove careerly-ga4 -s user
+
+# 또는 메뉴에서
+npx careerly-data-mcp
+# → Disable 선택
 ```
 
-## 수동 설정
+---
+
+## 수동 설정 (선택)
 
 ### Claude CLI로 추가
 
@@ -119,112 +225,52 @@ Tools:       3 tools
 claude mcp add careerly-ga4 \
   -s user \
   -e GA4_PROPERTY_ID=123456789 \
-  -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json \
-  -- npx -y careerly-ga4-mcp serve
+  -e BQ_PROJECT_ID=your-project-id \
+  -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json \
+  -- npx -y careerly-data-mcp serve
 ```
 
 ### 설정 파일 직접 수정
 
-`~/.claude/settings.local.json`에 직접 추가:
+`~/.claude/settings.local.json`:
 
 ```json
 {
   "mcpServers": {
     "careerly-ga4": {
       "command": "npx",
-      "args": ["-y", "careerly-ga4-mcp", "serve"],
+      "args": ["-y", "careerly-data-mcp", "serve"],
       "env": {
         "GA4_PROPERTY_ID": "123456789",
-        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
+        "BQ_PROJECT_ID": "your-project-id",
+        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/key.json"
       }
     }
   }
 }
 ```
 
-## 문제 해결
-
-### MCP 서버가 `/mcp`에 안 보여요
-
-1. Claude Code를 완전히 종료 후 재시작
-2. 설정 확인: `claude mcp list`
-3. 재설정: `npx careerly-ga4-mcp setup`
-
-### PERMISSION_DENIED 에러
-
-GA4에 Service Account 권한이 없습니다:
-
-1. GA4 Admin > 속성 설정 > 속성 액세스 관리
-2. Service Account 이메일 추가 (JSON의 `client_email`)
-3. 역할: 뷰어 (읽기 전용)
-
-### 설정 삭제
-
-```bash
-# Claude CLI로 삭제
-claude mcp remove careerly-ga4 -s user
-
-# 또는 인터랙티브 메뉴에서
-npx careerly-ga4-mcp
-# → Disable 선택
-```
-
-## Tool 스키마
-
-### ga4_query
-
-```typescript
-{
-  metrics: string[]      // 필수: ["sessions", "totalUsers", "conversions"]
-  dimensions?: string[]  // 선택: ["date", "sessionDefaultChannelGroup"]
-  startDate?: string     // 기본: "7daysAgo"
-  endDate?: string       // 기본: "today"
-  datePreset?: string    // "last_7_days", "last_30_days" 등
-  limit?: number         // 기본: 10
-}
-```
-
-### 지표 (Metrics)
+---
 
-| 지표 | 설명 |
-|------|------|
-| `sessions` | 세션 수 |
-| `totalUsers` | 전체 사용자 |
-| `newUsers` | 신규 사용자 |
-| `activeUsers` | 활성 사용자 |
-| `bounceRate` | 이탈률 |
-| `conversions` | 전환 수 |
-| `screenPageViews` | 페이지뷰 |
-| `engagementRate` | 참여율 |
+## 보안 원칙
 
-### 차원 (Dimensions)
+- `bq_raw_sql`은 **SELECT/WITH 문만 허용** (INSERT, DELETE 등 차단)
+- Service Account 키 파일은 **개인 로컬에서만 관리**
+- 민감 데이터 접근 시 권한 최소화 원칙 적용
 
-| 차원 | 설명 |
-|------|------|
-| `date` | 날짜 |
-| `sessionDefaultChannelGroup` | 채널 |
-| `sessionSourceMedium` | 소스/매체 |
-| `sessionCampaignName` | 캠페인 |
-| `landingPage` | 랜딩 페이지 |
-| `deviceCategory` | 디바이스 |
-| `country` | 국가 |
+---
 
 ## 개발
 
 ```bash
-# 의존성 설치
-npm install
-
-# 빌드
-npm run build
-
-# 개발 모드
-npm run dev
-
-# 타입 체크
-npm run typecheck
+npm install     # 의존성 설치
+npm run build   # 빌드
+npm run dev     # 개발 모드 (watch)
+npm run typecheck  # 타입 체크
 ```
 
+---
+
 ## 라이선스
 
 MIT

package/dist/bigquery/client.d.ts

@@ -2,7 +2,7 @@
  * BigQuery 클라이언트
  * @google-cloud/bigquery 래퍼
  */
-import type { BigQueryConfig, BigQueryRequest, BigQueryResponse, GA4EventsRequest, DatasetInfo, TableInfo } from "./types.js";
+import type { BigQueryConfig, BigQueryRequest, BigQueryResponse, GA4EventsRequest, RawSqlRequest, DatasetInfo, TableInfo } from "./types.js";
 export declare class BigQueryClient {
     private client;
     private projectId;
@@ -19,6 +19,11 @@ export declare class BigQueryClient {
      * 파라미터 기반 쿼리 실행
      */
     runQuery(request: BigQueryRequest): Promise<BigQueryResponse>;
+    /**
+     * Raw SQL 쿼리 실행 (고급 사용자용)
+     * 보안: SELECT 문만 허용, DML/DDL 차단
+     */
+    runRawQuery(request: RawSqlRequest): Promise<BigQueryResponse>;
     /**
      * GA4 Export 이벤트 쿼리 실행
      */
@@ -42,6 +47,8 @@ export declare class BigQueryClient {
     /**
      * GA4 Export 쿼리 빌드
      * CTE를 사용하여 event_params/user_properties 추출 후 집계
+     *
+     * 수정: GROUP BY 오류 해결 - metrics 유무에 따른 분기 처리 개선
      */
     private buildGA4EventsQuery;
     /**

package/dist/bigquery/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/bigquery/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,SAAS,EAKV,MAAM,YAAY,CAAC;AAIpB,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAS;gBAEb,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAW5C;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAoBtE;;OAEG;IACG,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA+BnE;;OAEG;IACG,iBAAiB,CACrB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,gBAAgB,CAAC;IA+B5B;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAqB5C;;OAEG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAgCzD;;OAEG;IACG,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,SAAS,CAAC;IAgCrB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA4ExB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAoK3B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAwCjC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAmE3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAsBxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAevB;;OAEG;IACH,OAAO,CAAC,WAAW;IAuDnB;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,WAAW,IAAI,MAAM;CAGtB;AAKD,wBAAgB,iBAAiB,CAC/B,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAC/B,cAAc,CAKhB;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/bigquery/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,SAAS,EAKV,MAAM,YAAY,CAAC;AAIpB,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAS;gBAEb,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAW5C;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAoBtE;;OAEG;IACG,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA+BnE;;;OAGG;IACG,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA4DpE;;OAEG;IACG,iBAAiB,CACrB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,gBAAgB,CAAC;IA+B5B;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAqB5C;;OAEG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAgCzD;;OAEG;IACG,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,SAAS,CAAC;IAgCrB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA6ExB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IA0L3B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAwCjC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAmE3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAsBxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAevB;;OAEG;IACH,OAAO,CAAC,WAAW;IAuDnB;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,WAAW,IAAI,MAAM;CAGtB;AAKD,wBAAgB,iBAAiB,CAC/B,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAC/B,cAAc,CAKhB;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}

package/dist/bigquery/client.js

@@ -68,6 +68,56 @@ export class BigQueryClient {
             throw this.handleError(error);
         }
     }
+    /**
+     * Raw SQL 쿼리 실행 (고급 사용자용)
+     * 보안: SELECT 문만 허용, DML/DDL 차단
+     */
+    async runRawQuery(request) {
+        try {
+            // SQL 검증: SELECT 문만 허용
+            const normalizedSql = request.sql.trim().toUpperCase();
+            if (!normalizedSql.startsWith("SELECT") && !normalizedSql.startsWith("WITH")) {
+                throw new BigQueryError("Raw SQL은 SELECT 또는 WITH 문만 지원합니다. INSERT, UPDATE, DELETE, DROP 등은 사용할 수 없습니다.", "INVALID_QUERY");
+            }
+            // 위험한 키워드 차단
+            const dangerousKeywords = [
+                "INSERT", "UPDATE", "DELETE", "DROP", "TRUNCATE",
+                "CREATE", "ALTER", "GRANT", "REVOKE", "MERGE"
+            ];
+            for (const keyword of dangerousKeywords) {
+                // 문장 시작에 있는 경우만 차단 (서브쿼리 내부는 허용)
+                if (normalizedSql.match(new RegExp(`^\\s*${keyword}\\s`, "i"))) {
+                    throw new BigQueryError(`${keyword} 문은 지원하지 않습니다. SELECT 문만 사용해주세요.`, "INVALID_QUERY");
+                }
+            }
+            // LIMIT 자동 추가 (없으면 기본값 적용)
+            let finalSql = request.sql.trim();
+            if (!normalizedSql.includes("LIMIT")) {
+                const limit = Math.min(request.limit || 1000, 10000);
+                finalSql = `${finalSql}\nLIMIT ${limit}`;
+            }
+            const [job] = await this.client.createQueryJob({
+                query: finalSql,
+                params: request.params,
+                location: this.location,
+                useLegacySql: false,
+            });
+            const [rows] = await job.getQueryResults();
+            const [metadata] = await job.getMetadata();
+            const headers = rows.length > 0 ? Object.keys(rows[0]) : [];
+            return {
+                headers,
+                rows: rows,
+                totalRows: rows.length,
+                jobId: job.id,
+                bytesProcessed: Number(metadata.statistics?.totalBytesProcessed || 0),
+                cacheHit: metadata.statistics?.query?.cacheHit || false,
+            };
+        }
+        catch (error) {
+            throw this.handleError(error);
+        }
+    }
     /**
      * GA4 Export 이벤트 쿼리 실행
      */
@@ -215,14 +265,15 @@ export class BigQueryClient {
         const projectId = request.projectId || this.projectId;
         const tableRef = `\`${projectId}.${request.datasetId}.${request.tableId}\``;
         parts.push(`FROM ${tableRef}`);
-        // WHERE
+        // WHERE (복합 필터 로직 지원)
         if (request.where?.length) {
             const conditions = request.where.map((w) => {
                 const result = this.buildWhereCondition(w, paramIndex, params);
                 paramIndex = result.nextIndex;
                 return result.condition;
             });
-            parts.push(`WHERE ${conditions.join(" AND ")}`);
+            const logic = request.filterLogic || "AND";
+            parts.push(`WHERE ${conditions.join(` ${logic} `)}`);
         }
         // GROUP BY
         if (request.groupBy?.length) {
@@ -250,12 +301,16 @@ export class BigQueryClient {
     /**
      * GA4 Export 쿼리 빌드
      * CTE를 사용하여 event_params/user_properties 추출 후 집계
+     *
+     * 수정: GROUP BY 오류 해결 - metrics 유무에 따른 분기 처리 개선
      */
     buildGA4EventsQuery(request) {
         const params = {};
         const projectId = request.projectId || this.projectId;
         const tableRef = `\`${projectId}.${request.datasetId}.events_*\``;
         let paramIndex = 0;
+        // metrics 유무에 따른 집계 모드 결정
+        const isAggregateMode = !!(request.metrics?.length);
         // WHERE 조건 구성
         const whereConditions = [];
         whereConditions.push(`_TABLE_SUFFIX BETWEEN '${request.startDate}' AND '${request.endDate}'`);
@@ -314,77 +369,88 @@ export class BigQueryClient {
   FROM ${tableRef}
   ${whereClause}
 )`;
-        // 메인 쿼리 SELECT 파트
-        const mainSelectParts = [];
-        const groupByParts = [];
-        let selectIndex = 1;
-        // event_name은 항상 포함
-        mainSelectParts.push("event_name");
-        groupByParts.push(String(selectIndex++));
-        // eventParams를 메인 쿼리에 추가 (집계하지 않을 경우 GROUP BY에도 추가)
+        // paramFilters 처리 (추출된 event_params에 대한 필터)
+        const mainWhereConditions = [];
+        if (request.paramFilters?.length) {
+            request.paramFilters.forEach((pf, idx) => {
+                const condition = this.buildParamFilterCondition(pf, paramIndex + idx, params);
+                if (condition) {
+                    mainWhereConditions.push(condition.condition);
+                    paramIndex = condition.nextIndex;
+                }
+            });
+        }
+        // 집계 모드: GROUP BY 사용
+        if (isAggregateMode) {
+            const mainSelectParts = [];
+            const groupByFields = [];
+            // event_name은 항상 GROUP BY에 포함
+            mainSelectParts.push("event_name");
+            groupByFields.push("event_name");
+            // dimensions는 GROUP BY에 포함
+            if (request.dimensions?.length) {
+                request.dimensions.forEach((dim) => {
+                    const alias = dim.includes(".") ? dim.replace(/\./g, "_") : dim;
+                    mainSelectParts.push(alias);
+                    groupByFields.push(alias);
+                });
+            }
+            // eventParams는 집계 모드에서 GROUP BY에 포함 안함 (집계 결과만)
+            // 대신 첫 번째 값만 보여주거나 제외
+            // 참고: 만약 eventParams를 GROUP BY에 포함하려면 dimensions에 추가해야 함
+            // metrics (집계)
+            request.metrics.forEach((agg) => {
+                mainSelectParts.push(this.buildAggregation(agg));
+            });
+            // 기본 이벤트 카운트도 추가
+            mainSelectParts.push("COUNT(*) AS event_count");
+            // 메인 쿼리 구성
+            let mainQuery = `SELECT
+  ${mainSelectParts.join(",\n  ")}
+FROM extracted_events`;
+            if (mainWhereConditions.length > 0) {
+                mainQuery += `\nWHERE ${mainWhereConditions.join("\n  AND ")}`;
+            }
+            mainQuery += `\nGROUP BY ${groupByFields.join(", ")}
+ORDER BY event_count DESC
+LIMIT ${Math.min(request.limit || 100, 10000)}`;
+            return { query: `${cte}\n${mainQuery}`, params };
+        }
+        // 비집계 모드: raw 데이터 반환 (GROUP BY 없음)
+        const mainSelectParts = [
+            "event_name",
+            "event_timestamp",
+            "user_pseudo_id",
+        ];
+        // eventParams 포함
         if (request.eventParams?.length) {
             request.eventParams.forEach((paramKey) => {
-                const safeKey = this.escapeIdentifier(paramKey);
-                mainSelectParts.push(safeKey);
-                // metrics가 없으면 GROUP BY에 포함
-                if (!request.metrics?.length) {
-                    groupByParts.push(String(selectIndex));
-                }
-                selectIndex++;
+                mainSelectParts.push(this.escapeIdentifier(paramKey));
             });
         }
-        // user_properties 추가
+        // userProperties 포함
         if (request.userProperties?.length) {
             request.userProperties.forEach((propKey) => {
-                const safeKey = this.escapeIdentifier(propKey);
-                mainSelectParts.push(`user_${safeKey}`);
-                if (!request.metrics?.length) {
-                    groupByParts.push(String(selectIndex));
-                }
-                selectIndex++;
+                mainSelectParts.push(`user_${this.escapeIdentifier(propKey)}`);
             });
         }
-        // dimensions 추가
+        // dimensions 포함
         if (request.dimensions?.length) {
             request.dimensions.forEach((dim) => {
                 const alias = dim.includes(".") ? dim.replace(/\./g, "_") : dim;
                 mainSelectParts.push(alias);
-                groupByParts.push(String(selectIndex++));
             });
         }
-        // metrics (집계)
-        if (request.metrics?.length) {
-            request.metrics.forEach((agg) => {
-                mainSelectParts.push(this.buildAggregation(agg));
-            });
-        }
-        else {
-            // 기본 집계: 이벤트 수
-            mainSelectParts.push("COUNT(*) AS event_count");
-        }
-        // paramFilters 처리 (추출된 event_params에 대한 필터)
-        const mainWhereConditions = [];
-        if (request.paramFilters?.length) {
-            request.paramFilters.forEach((pf, idx) => {
-                const condition = this.buildParamFilterCondition(pf, paramIndex + idx, params);
-                if (condition) {
-                    mainWhereConditions.push(condition.condition);
-                    paramIndex = condition.nextIndex;
-                }
-            });
-        }
-        // 메인 쿼리 구성
+        // 메인 쿼리 구성 (GROUP BY 없음)
         let mainQuery = `SELECT
   ${mainSelectParts.join(",\n  ")}
 FROM extracted_events`;
         if (mainWhereConditions.length > 0) {
             mainQuery += `\nWHERE ${mainWhereConditions.join("\n  AND ")}`;
         }
-        mainQuery += `\nGROUP BY ${groupByParts.join(", ")}
-ORDER BY event_count DESC
+        mainQuery += `\nORDER BY event_timestamp DESC
 LIMIT ${Math.min(request.limit || 100, 10000)}`;
-        const query = `${cte}\n${mainQuery}`;
-        return { query, params };
+        return { query: `${cte}\n${mainQuery}`, params };
     }
     /**
      * event_params 필터 조건 빌드