GA4 BigQuery event_params에서 값 추출하는 SQL 3단계

GA4 BigQuery의 event_params에서 특정 매개변수를 꺼내려면 배열 안에서 키를 찾고, 값이 저장된 필드를 선택합니다. 이벤트 한 행을 유지하며 값을 열로 추출하려면 키별 스칼라 서브쿼리를 사용할 수 있습니다. 매개변수 항목을 하나씩 확인하려면 UNNEST로 배열을 펼칩니다.

event_params 구조와 추출 방식

GA4 내보내기 테이블에서 event_params는 이벤트 매개변수의 반복 레코드입니다. 각 항목은 매개변수 이름인 key와 값을 담는 value로 구성됩니다. 값 필드에는 string_value, int_value, double_value가 있습니다. float_value도 스키마에 있지만 현재 사용되지 않는다고 Google이 안내하므로, 일반적인 실수 값을 추출할 때는 데이터에 맞는 double_value를 확인하세요. 상세한 필드 설명은 Google의 [GA4] BigQuery Export 스키마에서 확인할 수 있습니다.

사용자가 보낸 매개변수마다 BigQuery 테이블의 열이 새로 생기는 구조가 아니므로 배열 안에서 필요한 키를 찾아야 합니다. 결과 모양은 쿼리 방식에 따라 달라집니다. FROM 절에서 배열을 펼치면 매개변수 항목마다 결과 행이 생길 수 있습니다. 이벤트 한 행에 여러 값을 열로 붙이면 이벤트 단위 분석에 활용하기 편리합니다.

방법 1: 특정 키를 열로 추출하기

1단계: 테이블과 날짜 범위를 정합니다

아래 예시의 프로젝트·데이터세트 이름은 실제 GA4 내보내기 경로로 바꾸세요. 일별 테이블을 조회하는 와일드카드 테이블은 events_*로 지정하고, _TABLE_SUFFIX 조건으로 날짜를 제한합니다. GA4 일별 테이블 이름은 events_YYYYMMDD 형식입니다. 날짜 접미사 필터에 관한 설명은 Google의 와일드 카드 테이블을 사용하여 여러 테이블 쿼리 문서를 참고하세요.

2단계: 키와 값 필드를 지정합니다

각 매개변수 키를 조건으로 배열을 조회하고, 값 필드에는 매개변수의 실제 저장 형식을 지정합니다. 다음 예시는 page_view 이벤트에서 페이지 주소와 제목, 세션 ID를 이벤트 한 행에 함께 반환합니다.

SELECT
  event_date,
  event_name,
  user_pseudo_id,
  (SELECT value.string_value
   FROM UNNEST(event_params)
   WHERE key = 'page_location') AS page_location,
  (SELECT value.string_value
   FROM UNNEST(event_params)
   WHERE key = 'page_title') AS page_title,
  (SELECT value.int_value
   FROM UNNEST(event_params)
   WHERE key = 'ga_session_id') AS ga_session_id
FROM `my_project.analytics_123456789.events_*`
WHERE _TABLE_SUFFIX BETWEEN '20261001' AND '20261007'
  AND event_name = 'page_view';

각 서브쿼리는 해당 이벤트의 매개변수 배열 안에서 키를 찾습니다. 일치하는 항목이 없으면 스칼라 서브쿼리 결과는 NULL입니다. Google의 BigQuery 하위 쿼리 문서에 따르면, 스칼라 서브쿼리가 두 행 이상을 반환하면 쿼리가 오류를 냅니다.

3단계: 결과와 누락값을 점검합니다

날짜 범위와 이벤트 이름 조건이 의도한 데이터만 선택하는지 확인하세요. page_title이 NULL이라면 해당 이벤트에 키가 없거나, 선택한 값 필드에 값이 없을 수 있습니다. NULL만으로 수집 오류라고 단정하지 말고 원본 이벤트에서 키와 값 필드를 살펴보세요.

방법 2: UNNEST로 매개변수를 행으로 펼치기

매개변수 목록을 조사할 때

이벤트에 어떤 키가 들어오는지 확인하려면 배열을 펼쳐 키와 값 필드를 살펴봅니다. 다음 쿼리는 매개변수별로 별도 행을 반환합니다.

SELECT
  event_name,
  param.key AS param_key,
  param.value.string_value AS string_value,
  param.value.int_value AS int_value,
  param.value.double_value AS double_value
FROM `my_project.analytics_123456789.events_*`,
UNNEST(event_params) AS param
WHERE _TABLE_SUFFIX = '20261007'
  AND event_name = 'page_view';

UNNEST는 배열 요소마다 행을 반환합니다. 따라서 한 이벤트에 매개변수가 여러 개 있으면 해당 이벤트가 여러 행으로 나타날 수 있습니다. 키와 값의 목록을 조사할 때는 유용하지만, 결과 행 수를 이벤트 수처럼 세거나 이벤트 단위 지표를 그대로 합산하면 중복 집계가 생길 수 있습니다. BigQuery의 배열 작업 문서에서도 UNNEST가 배열 요소를 행으로 변환한다고 설명합니다.

값 형식과 중복 키 처리

실제 저장 형식에 맞는 필드를 고릅니다

문자열은 string_value, 정수는 int_value, 실수는 일반적으로 double_value에서 확인합니다. 숫자로 보이는 매개변수라도 수집 형식에 따라 저장 필드가 다를 수 있으므로 실제 스키마와 레코드를 살펴보세요. 잘못된 필드를 선택하면 값이 없는 것처럼 NULL로 나타날 수 있습니다.

중복 키가 있으면 선택 규칙을 정합니다

같은 이벤트의 배열에서 같은 키가 두 번 이상 발견되면 스칼라 서브쿼리는 여러 행을 반환해 오류가 날 수 있습니다. 먼저 중복 여부를 점검하고 어떤 값을 남길지 업무 규칙을 정하세요. 예를 들어 최대값이나 최소값이 필요한지, 항목을 모두 보존해야 하는지 목적에 맞춰 집계하거나 배열로 반환할 수 있습니다. ANY_VALUE는 특정한 최신 값이나 대표값을 보장하는 선택 규칙이 아닙니다.

실무 점검과 자주 하는 실수

• 조회 범위: 와일드카드 테이블에서는 날짜 접미사 조건으로 필요한 범위를 지정합니다.
• 행 개수: 배열을 펼친 결과의 행 수와 이벤트 수를 혼동하지 않도록 합니다.
• NULL 해석: 키 누락과 값 필드 선택 오류를 구분하려면 원본 매개변수 항목을 확인합니다.
• 중복 키: 스칼라 서브쿼리로 추출하기 전에 키가 한 이벤트 안에서 중복되는지 확인합니다.

캠페인별 세션 분석에서 이벤트 매개변수를 함께 사용할 계획이라면 GA4 BigQuery 캠페인별 세션 분석의 집계 단위도 확인하세요. 세션 단위와 이벤트 단위는 행의 의미가 다르므로, 결합 전에 어떤 단위의 결과를 만들지 정하는 편이 안전합니다.

기억할 기준: 이벤트당 한 행이 필요하면 키별 스칼라 서브쿼리를, 매개변수 항목을 점검하려면 UNNEST를 사용하세요. 쿼리 방식에 따라 결과 행 수가 달라집니다.

자주 묻는 질문

Q. event_params에서 값을 뽑을 때 반드시 UNNEST해야 하나요?

배열 안의 값을 키로 찾아 조회할 때는 UNNEST를 쓸 수 있습니다. 이를 키별 스칼라 서브쿼리 안에서 사용하면 이벤트 한 행을 유지할 수 있습니다. 매개변수마다 별도 행을 보고 싶다면 FROM 절에서 배열을 펼치면 됩니다.

Q. 추출 결과가 NULL인 이유는 무엇인가요?

해당 이벤트에 키가 없거나 실제 값이 선택한 필드에 없을 수 있습니다. 원본 배열을 펼쳐 키와 string_value, int_value, double_value 중 값이 들어 있는 필드를 확인하세요.

Q. 한 이벤트에서 매개변수 두 개를 동시에 추출할 수 있나요?

가능합니다. 예시처럼 키마다 스칼라 서브쿼리를 추가하면 값을 별도 열로 반환할 수 있습니다. 같은 키가 이벤트 안에서 중복될 가능성이 있다면 먼저 확인하고 선택 기준을 정하세요.

Q. UNNEST하면 왜 행 수가 증가하나요?

UNNEST는 배열의 각 요소를 별도 행으로 반환합니다. 이벤트에 매개변수가 여러 개라면 그 항목마다 결과 행이 생길 수 있으므로, 이벤트 단위 집계에서 중복 계산하지 않도록 주의하세요.

참고자료

• [GA4] BigQuery Export 스키마 – Google Support
• 배열 작업 – BigQuery, Google Cloud Documentation
• Subqueries – BigQuery, Google Cloud Documentation
• 와일드 카드 테이블을 사용하여 여러 테이블 쿼리 – BigQuery, Google Cloud Documentation