---
tags: [research, rag, robeing, metadata, front-matter, jsonb]
type: research
status: closed
closed_date: 2026-03-22
closed_reason: 설계 목적 달성, 200개 대상 구현 완료, Unresolved는 3차 계획 또는 후속 문서로 이관
research_target: front matter와 JSONB에 공통 적용할 메타데이터 구조 정리
---

# Front Matter 메타데이터 설계 리서치

## 상태

- proposed

**작성일**: 2026-03-20  
**목적**: Markdown front matter와 PostgreSQL JSONB에 공통 반영 가능한 메타데이터 구조를 정리한다.

---

## 1. 설계 목표

- 검색에 도움이 되는 메타와 운영 동기화에 필요한 메타를 함께 담는다.
- 사람이 읽는 front matter와 DB의 JSONB가 서로 크게 어긋나지 않도록 한다.
- OCR, 임베딩, 그래프 연결 같은 후속 처리를 메타만 보고 판단할 수 있게 한다.

## 2. 메타 항목 분류

### 2.1 기본 식별

- `title`
- `source_path`
- `md_path`
- `file_type`
- `file_ext`
- `folder_path`
- `source_hash`

### 2.2 시간/작성자

- `created_at`
- `modified_at`
- `indexed_at`
- `author`
- `owner`

### 2.3 내용 통계

- `text_length`
- `image_count`
- `table_count`
- `graph_count`
- `page_count`
- `sheet_count`
- `slide_count`
- `duration_seconds`

### 2.4 검색/추론 보조

- `tags`
- `keywords`
- `summary`
- `language`
- `entities`
- `related`
- `priority`

### 2.5 처리 상태

- `status`
- `ocr_status`
- `embedding_status`
- `sync_status`
- `deleted_at`
- `last_error`

## 3. 최소 필수 메타

- `title`
- `source_path`
- `file_type`
- `modified_at`
- `status`
- `text_length`
- `tags`
- `summary`

## 4. 추천 front matter 예시

```yaml
---
title: 오늘전통 사업계획서
source_path: /mnt/nas/workspace/6.Company X/.../사업계획서_컴퍼니엑스.pdf
md_path: /mnt/nas/indexed_md/.../사업계획서_컴퍼니엑스_pdf.md
file_type: pdf
file_ext: .pdf
folder_path: /mnt/nas/workspace/6.Company X/...
created_at: 2025-01-23T10:21:00+09:00
modified_at: 2026-03-20T11:15:00+09:00
indexed_at: 2026-03-20T13:40:00+09:00
author: Company X
text_length: 12450
image_count: 7
table_count: 4
graph_count: 2
page_count: 28
tags: [companyx, rag, accelerator, yellowpunch]
keywords: [오늘전통, 옐로펀치, 공동 컨소시엄, 액셀러레이터]
summary: 오늘전통 사업계획서 내 협력기관 및 공동 지원 구조를 설명하는 PDF.
related:
  - /mnt/nas/indexed_md/.../TalkFile_MOU_옐로펀치X컴퍼니엑스_pdf.md
status: active
ocr_status: pending
embedding_status: indexed
sync_status: synced
---
```

## 5. 내가 추천하는 메타 활용 방식

- `text_length`, `image_count`, `table_count`는 OCR 대상을 고르는 기준으로 쓴다.
- `status`, `sync_status`는 생성/수정/삭제 동기화 판단에 쓴다.
- `tags`, `keywords`, `summary`는 검색 랭킹과 후속 LLM 컨텍스트에 직접 쓴다.
- `related`는 PostgreSQL 그래프 확장의 직접 입력으로 쓴다.

## 6. front matter와 JSONB의 관계

- front matter는 사람이 읽고 수정하기 쉬운 레이어다.
- JSONB는 SQL 필터, 운영 상태 업데이트, 검색 최적화를 위한 레이어다.
- 둘을 완전 동일하게 유지할 필요는 없지만, 핵심 키는 동일하게 가져가는 편이 낫다.

## 7. 주의점

- 메타 항목이 너무 많아도 초기 구축이 느려진다.
- 작성자, 생성 시간 같은 항목은 원본 포맷별 추출 정확도가 다르므로 nullable로 두는 편이 맞다.
- `graph_count`처럼 완전 정확한 추출이 어려운 항목은 "추정치"가 아니라 "현재 파이프라인 기준 값"으로 다뤄야 한다.

## 8. 이번 단계 추천

- 최소 필수 메타로 먼저 시작한다.
- OCR/요약/그래프 연결이 붙을 때 메타를 확장한다.
- 메타 확장의 기준은 "검색 품질이나 운영 자동화에 실제 도움이 되는가"로 잡는다.

## 현재 상태 보정 (2026-03-22)

- 실제 MD front matter: `title`, `source_path`, `md_path`, `file_type`, `file_size`, `modified_at`, `status`, `text_length`, `summary`.
- DB 운영 테이블: team_document(1,174건) / team_document_chunk(3,474건). 설계 별칭 document_files = team_document, document_chunks = team_document_chunk.
- `ocr_status`, `embedding_status`, `sync_status`, `related`는 MD 전면 적용 안 됨.
- 임베딩: Gemini Embedding 2, 768d.

## Unresolved

- 권장 메타 중 무엇을 MD front matter에 두고 무엇을 DB JSONB 전용으로 둘지 최종 경계가 고정되지 않았다.
- 실제 메타와 권장 메타의 갭을 언제 어떤 배치로 메울지 계획이 부족하다.

## 9. 관련 문서

- [Markdown 중간표현 SSOT 설계 리서치](./260320_MD_중간표현_SSOT_설계_리서치.md)
- [OCR 선별 적용 정책 리서치](./260320_OCR_선별적용_정책_리서치.md)
- [PGVector·JSONB RAG 스키마 설계 리서치](./260320_PGVector_JSONB_RAG_스키마_설계_리서치.md)
