# 마트 컬럼의 의미·출처를 사람에게서 문서로 옮기기

평탄화 마트를 만들고 나면 ‘이 컬럼이 무슨 뜻이고 어디서 왔는지’를 적어 둔 테이블 정의서(데이터 딕셔너리)가 필요해집니다. 정의서가 없을 때 생기는 문제, 테이블·컬럼 단위로 무엇을 적는지, 단일 진실 공급원·지표 계보 추적 같은 효과, 그리고 BigQuery description·위키·스키마 파일로 정의서를 어디에 두고 어떻게 최신으로 유지하는지를 비개발자도 따라올 수 있게 정리합니다.

- 카테고리: BigQuery
- 소요 시간: 약 7분
- 난이도: 입문
- 업데이트: 2026.06.05
- 원문: /wiki/playbook/bigquery-checklist/why-table-definition-doc

## 목차

- [정의서가 없으면 벌어지는 일](#pain)
- [정의서에 무엇을 적나](#what)
- [실제 정의서는 이렇게 생겼다](#sample)
- [정의서가 만드는 네 가지](#effects)
- [어디에 두고 어떻게 유지하나](#where)
- [정의서로 AI 에이전트에 맥락 주기](#agent-context)
- [자주 묻는 질문](#faq)

[평탄화 마트](/wiki/playbook/bigquery-checklist/why-flatten-ga4-bigquery-data)를 만들고 나면 곧장 따라오는 질문이 있습니다 — “**이 컬럼이 정확히 무슨 뜻이고, 어디서 온 값이지?**” 테이블 정의서(데이터 딕셔너리)는 그 답을 한곳에 적어 둔 문서입니다. 이 글은 정의서가 왜 필요한지, 무엇을 적는지, 그리고 어디에 두고 어떻게 최신으로 유지하는지를 비개발자도 따라올 수 있게 정리합니다. `Event_Flat`·`Item_Performance` 같은 개별 마트의 실제 컬럼 정의는 시리즈 후반 글에서 다룹니다.

## 정의서가 없으면 벌어지는 일

마트 테이블은 한 번 만들면 끝이 아니라 ‘여러 사람이 매일 들여다보는 공용 자산’이 됩니다. 그런데 그 컬럼이 무슨 뜻인지가 사람 머릿속에만 있으면, 시간이 지날수록 아래 같은 일이 반복됩니다.

| 상황 | 정의서가 없을 때 |
| --- | --- |
| 새로 합류한 마케터가 마트를 열어 봄 | `revenue`가 부가세 포함인지, 환불 반영인지, 어느 통화인지 알 수 없어 만든 사람을 찾아 물어봐야 함. |
| 같은 지표를 두 사람이 각자 계산 | 한 명은 `session_engaged = true`만, 다른 한 명은 전체를 세어 ‘세션 수’가 서로 다르게 나옴. |
| 리포트 숫자가 갑자기 튐 | 어떤 컬럼이 어느 이벤트·파라미터에서 왔는지 적혀 있지 않아, 어디서 어긋났는지 추적이 막힘. |
| 컬럼을 추가·변경 | 바뀐 의미가 공유되지 않아, 이미 그 컬럼을 쓰던 Looker Studio 차트가 조용히 잘못된 값을 보여 줌. |

공통점은 하나입니다 — **‘정의가 사람에게 묶여 있다’**는 것. 그 사람이 자리를 비우거나 기억이 흐려지면 마트는 ‘아무도 자신 있게 설명 못 하는 표’가 됩니다. 정의서는 그 정의를 사람에게서 떼어 문서로 옮겨 두는 일입니다.

## 정의서에 무엇을 적나

정의서는 두 층으로 적습니다 — **테이블 한 개를 설명하는 정보**와 **그 안의 컬럼 하나하나를 설명하는 정보**입니다.

### 테이블 단위 — 이 표는 무엇인가

| 항목 | 적는 내용(예) |
| --- | --- |
| 테이블 이름 | `mart.Event_Flat` |
| 용도(한 줄) | “GA4 이벤트를 한 행 = 한 이벤트로 펼친 분석용 마트” |
| 원본(소스) | `analytics_<property_id>.events_*` |
| 갱신 주기·방식 | 매일 1회, GA4 export 도착 시 예약 쿼리로 자동 갱신(그날치 삭제 후 재적재) |
| 파티션·기준 컬럼 | `date`(DATE) 기준 파티션 |
| 보관 기간 | 최근 90일(원본 raw는 별도 영구 보관) |
| 담당 | 데이터팀 / 마지막 갱신일 |

### 컬럼 단위 — 각 칸은 무슨 값인가

컬럼마다 ‘이름·타입’만 적는 게 아니라, ‘무슨 뜻이고 어디서 왔는지’까지 적는 게 핵심입니다.

- **컬럼명 / 타입 / 모드** — `page_location` · STRING · NULLABLE.
- **의미** — 사람이 읽는 한 줄 설명. “이벤트가 발생한 페이지 전체 URL.”
- **출처** — 어느 이벤트·파라미터에서 왔는지. “`event_params`의 `page_location` 값.” 이게 있어야 숫자 ↔ 태그 ↔ 코드까지 계보를 따라갈 수 있습니다.
- **예시값** — 실제로 어떤 값이 들어오는지 한두 개. “`https://example.com/pricing`.”
- **주의/규칙** — null이 언제 생기는지, 단위·통화, 집계 시 빼야 할 값 등. “봇 트래픽은 이미 제외됨”, “금액은 부가세 제외·KRW.”

> **팁**
>
> **가장 중요한 칸은 ‘의미’와 ‘출처’입니다.** 이름·타입은 BigQuery 스키마만 봐도 알 수 있지만, ‘이 값이 무슨 뜻이고 어디서 왔는지’는 만든 사람만 압니다. 정의서의 존재 이유가 바로 이 두 칸입니다.

## 실제 정의서는 이렇게 생겼다

`Event_Flat` 마트의 컬럼 일부를 정의서로 적으면 다음과 같은 표가 됩니다. 형식은 시트든 위키든 상관없고, ‘컬럼마다 의미·출처가 한 줄로 붙어 있다’가 본질입니다.

| 컬럼 | 타입 | 의미 | 출처 |
| --- | --- | --- | --- |
| `date` | DATE | 이벤트가 일어난 날짜(파티션 기준) | `event_date`를 DATE로 변환 |
| `event_name` | STRING | 이벤트 이름 | `event_name` |
| `user_pseudo_id` | STRING | 브라우저·기기 단위 익명 사용자 ID | `user_pseudo_id` |
| `page_location` | STRING | 이벤트가 발생한 페이지 전체 URL | `event_params.page_location` |
| `ga_session_id` | INT64 | 세션 식별자(사용자별 세션 시작 시각 기반) | `event_params.ga_session_id` |
| `session_engaged` | BOOL | 참여 세션 여부(10초+ 또는 전환·2페이지+) | `event_params.session_engaged` |

여기에 ‘의미’ 한 줄이 붙어 있으면, 처음 보는 사람도 `session_engaged`가 무엇을 세는지 묻지 않고 바로 씁니다. ‘출처’가 붙어 있으면, 값이 이상할 때 곧장 해당 파라미터·태그로 거슬러 올라갑니다.

## 정의서가 만드는 네 가지

- **단일 진실 공급원** — “세션 수가 뭐냐”는 질문에 모두가 같은 한 줄을 봅니다. 사람마다 다른 계산 → 같은 정의로 수렴.
- **지표 계보 추적** — Looker Studio 차트 → 마트 컬럼 → 정의서의 출처 → 태그 사양 → 실제 코드까지 한 줄로 이어집니다. 숫자가 틀어졌을 때 어디서 어긋났는지 빠르게 짚어냅니다.
- **온보딩 비용 절감** — 새 합류자가 사람을 붙잡지 않고도 마트를 혼자 이해합니다. ‘아는 사람’ 의존이 사라집니다.
- **안전한 변경 관리** — 컬럼을 바꾸기 전에 정의서를 먼저 고치는 순서가 자리 잡으면, 변경이 ‘조용히’ 퍼지지 않고 기록으로 남아 영향 범위를 미리 봅니다.

> **주의**
>
> **정의서는 ‘문서 작업’이 아니라 ‘운영 장치’입니다.** 한 번 쓰고 방치하면 금세 실제 테이블과 어긋나 오히려 헷갈리게 만듭니다. 그래서 ‘어디에 두고 어떻게 동기화하느냐’가 정의서를 살리느냐 죽이느냐를 가릅니다.

## 어디에 두고 어떻게 유지하나

정의서를 두는 자리는 크게 셋입니다. 실무에서 권장하는 조합은 **정의서 본체는 별도 스프레드시트**에 두고(의미·출처·예시·집계 규칙·변경 이력까지 풍부하게), 그 핵심을 **BigQuery 각 컬럼의 description**에 동기화하는 방식입니다.

| 두는 곳 | 장점 / 한계 |
| --- | --- |
| **BigQuery 테이블·컬럼 description** | 스키마 바로 옆에 의미가 붙어 BigQuery Studio·도구에서 즉시 보임. ‘출처·예시·규칙’까지 길게 적기엔 좁음. |
| **위키 / 스프레드시트** | 의미·출처·예시·변경 이력까지 풍부하게. 대신 실제 스키마와 따로 놀기 쉬움(동기화가 숙제). |
| **코드(스키마 파일)와 함께** | 마트 생성 SQL·스키마 정의 옆에 두어 ‘코드 = 정의서’가 됨. 버전 관리·리뷰에 강함. |

최신으로 유지하는 핵심 원칙은 **“정의서를 먼저 고치고, 그 다음 테이블을 고친다”**입니다. 컬럼을 추가할 때도 정의서에 한 줄 → 평탄화 SQL의 SELECT에 식 추가 → [예약 쿼리 자동 갱신](/wiki/playbook/bigquery-checklist/how-to-trigger-scheduled-query-on-ga4-export) 순서를 지키면, 정의서와 실제 마트가 어긋날 틈이 줄어듭니다.

**컬럼 description을 SQL로 함께 박아 두기(예)**
```sql
ALTER TABLE `mart.Event_Flat`
  ALTER COLUMN session_engaged
  SET OPTIONS (description = '참여 세션 여부(10초+ 또는 전환/2페이지+). 출처: event_params.session_engaged');
```

이렇게 하면 컬럼 설명이 BigQuery 스키마에 직접 붙어, ‘테이블을 고치면 정의도 같이 고치는’ 습관이 코드 레벨에서 강제됩니다. 풍부한 맥락(출처·예시·집계 규칙·변경 이력)은 스프레드시트 정의서가, 스키마에 박히는 한 줄 설명은 description이 맡는 셈입니다.

## 정의서로 AI 에이전트에 맥락 주기

BigQuery 컬럼 description에 의미를 박아 두면, 사람만 읽는 게 아닙니다 — 이 설명은 **AI 에이전트가 그대로 읽어 쓸 수 있는 맥락**이 됩니다. 자연어를 SQL로 바꿔 주는 ‘text-to-SQL’ 류의 데이터 에이전트는 테이블·컬럼 이름만으로는 의미를 정확히 알지 못해 엉뚱한 컬럼을 고르기 쉬운데, 컬럼마다 description이 붙어 있으면 그걸 단서로 더 정확한 쿼리를 만듭니다.

- **이름만 보면 헷갈리는 컬럼을 구분** — `revenue`가 부가세 포함인지, 어느 통화인지 description에 적혀 있으면 에이전트가 집계 규칙까지 반영합니다.
- **올바른 테이블 선택** — “세션 수” 질문에 raw `events_`가 아니라 평탄화 마트의 `ga_session_id`를 쓰도록, 테이블 용도 설명이 길잡이가 됩니다.
- **스프레드시트 정의서를 함께 투입** — description에 다 못 담은 출처·집계 규칙은 정의서 스프레드시트를 에이전트의 추가 컨텍스트로 붙여 주면, 사람에게 설명하듯 에이전트도 같은 기준으로 답합니다.

BigQuery의 컬럼 설명은 도구·API에서 스키마와 함께 조회되므로(예: `INFORMATION_SCHEMA.COLUMN_FIELD_PATHS`의 `description`), 에이전트가 테이블을 붙일 때 이 설명을 함께 읽도록 구성하면 됩니다. 결국 **정의서를 잘 적어 두는 일이 곧 ‘에이전트를 잘 가르치는 일’**이 됩니다 — 사람의 온보딩 문서가 그대로 에이전트의 온보딩 문서로 쓰이는 셈입니다.

> **팁**
>
> **순서는 똑같습니다 — 사람이 이해할 수 있게 적으면 에이전트도 이해합니다.** 정의서·description을 ‘에이전트용’으로 따로 쓸 필요 없이, 의미·출처·집계 규칙을 평이한 말로 적어 두면 사람과 에이전트가 같은 문서를 공유합니다.

## 자주 묻는 질문

### 스키마(컬럼 이름·타입)만 있으면 정의서가 따로 필요 없지 않나요?

스키마는 ‘어떤 칸이 있는지’만 알려 줍니다. 정작 분석에 필요한 건 ‘그 칸이 무슨 뜻이고, 어디서 왔고, 어떻게 세야 하는지’인데 그건 스키마에 안 적힙니다. 정의서는 스키마에 **의미·출처·규칙**을 덧붙인 문서라고 보면 됩니다.

### 정의서를 누가 써야 하나요?

마트를 만든 사람(보통 데이터팀)이 컬럼을 추가·변경할 때 그 자리에서 한 줄씩 적는 게 가장 정확하고 부담이 적습니다. ‘나중에 몰아서’가 아니라 ‘만들 때 같이’가 원칙입니다.

### 정의서 양식이 정해져 있나요?

표준 양식은 없습니다. 최소한 **컬럼명·타입·의미·출처** 네 칸만 있으면 정의서 구실을 합니다. 이커머스라면 금액·통화·세금 포함 여부, 환불 반영 여부 같은 ‘집계 규칙’ 칸을 더하면 좋습니다.

### 정의서가 실제 테이블과 어긋나면요?

가장 흔한 실패가 이겁니다. 그래서 ‘정의서 먼저, 테이블 나중’ 순서를 지키고, 가능하면 컬럼 설명을 BigQuery `description`이나 스키마 파일에 함께 박아 ‘테이블을 바꾸면 정의도 같이 바뀌게’ 만드는 게 좋습니다. 사람이 기억으로 맞추는 구조는 결국 어긋납니다.

### 작은 사이트도 정의서가 필요할까요?

혼자, 한두 개 컬럼만 쓰는 단계라면 BigQuery 컬럼 `description` 한 줄로 충분합니다. 다만 ‘보는 사람이 둘 이상’이 되거나 ‘컬럼이 10개를 넘어가는’ 순간부터는 별도 정의서가 빠르게 본전을 뽑습니다.

### 정의서를 자동으로 만들 수는 없나요?

스키마(컬럼·타입) 부분은 마트 정의에서 자동 생성할 수 있습니다. 다만 ‘의미·출처·집계 규칙’은 사람이 판단해 적어야 하는 영역이라, 자동 생성한 스키마 골격 위에 사람이 의미를 채우는 방식이 현실적입니다.

## Navigation

- [전체 플레이북 Markdown sitemap](/wiki/playbook/sitemap.md)

### BigQuery

- [BigQuery](/wiki/playbook/bigquery-checklist)
- [BigQuery 온보딩](/wiki/playbook/bigquery-checklist/bigquery-onboarding-guide)
- [BigQuery 인증 설정](/wiki/playbook/bigquery-checklist/how-to-set-up-bigquery-authentication)
- [BigQuery 데이터셋·테이블 설계](/wiki/playbook/bigquery-checklist/bigquery-dataset-and-table-design-guide)
- [BigQuery 쿼리·비용 제어](/wiki/playbook/bigquery-checklist/bigquery-query-and-cost-control-guide)
- [BigQuery 쓰기·MERGE·CDC](/wiki/playbook/bigquery-checklist/bigquery-data-write-and-cdc-guide)
- [BigQuery 코드 예제 모음](/wiki/playbook/bigquery-checklist/bigquery-code-examples)
- [BigQuery로 들어오는 GA4 데이터](/wiki/playbook/bigquery-checklist/what-is-ga4-data-in-bigquery)
- [BigQuery Studio 인터페이스 이해하기](/wiki/playbook/bigquery-checklist/what-is-bigquery-studio-interface)
- [BigQuery 예상 비용](/wiki/playbook/bigquery-checklist/how-to-estimate-bigquery-costs)
- [무료 버전(샌드박스) 해제해야 하는 이유](/wiki/playbook/bigquery-checklist/why-upgrade-from-bigquery-sandbox)
- [GA4 BigQuery 데이터를 왜 평탄화해야 하나](/wiki/playbook/bigquery-checklist/why-flatten-ga4-bigquery-data)
- [Log Router란?](/wiki/playbook/bigquery-checklist/what-is-log-router)
- [Pub/Sub이란?](/wiki/playbook/bigquery-checklist/what-is-pubsub)
- [Cloud Functions이란?](/wiki/playbook/bigquery-checklist/what-is-cloud-function-and-run)
- [GA4 export 시점에 예약 쿼리 자동 실행하기](/wiki/playbook/bigquery-checklist/how-to-trigger-scheduled-query-on-ga4-export)
- [테이블 정의서는 왜 필요한가](/wiki/playbook/bigquery-checklist/why-table-definition-doc) (현재 문서)
- [Event_Flat 테이블 이해하기](/wiki/playbook/bigquery-checklist/what-is-event-flat-table)
- [Item_Performance 테이블 이해하기](/wiki/playbook/bigquery-checklist/what-is-item-performance-table)