[LangChain RAG 구축 시리즈 Ep.15] 📄 Iceberg metadata.json 로딩 및 텍스트화

이 글에서는 Iceberg의 metadata.json 파일을 읽고
자연어 기반 설명 문서로 변환한 후, .txt 파일로 저장하는 과정을 구성합니다.
이 텍스트 문서는 향후 벡터화 및 검색을 위한 기본 재료가 됩니다.

---

🎯 목표

• Iceberg 메타데이터(JSON) 파싱
• 자연어 기반 설명 문서로 변환
• .txt 파일로 저장

---

🗂️ 디렉토리 구조 예시

rag-iceberg-project/
├── data/products_metadata.json        ← Iceberg 메타데이터 파일
├── docs/products.txt                  ← 변환된 텍스트 문서 저장 위치
└── src/load_json.py                   ← 이 글에서 작성할 Python 파일

---

🧾 Step 1. 샘플 metadata.json 예시 (💬 라인별 상세 주석 포함)

{
  "table-name": "products",                      // Iceberg 테이블 이름
  "schema": {
    "fields": [                                  // 컬럼(필드) 정의 목록
      { "id": 1, "name": "product_id", "type": "long" },     // 컬럼 1: 상품 ID
      { "id": 2, "name": "product_name", "type": "string" }, // 컬럼 2: 상품명
      { "id": 3, "name": "category", "type": "string" }      // 컬럼 3: 카테고리
    ]
  },
  "partition-spec": [                            // 파티션 구성 정보
    {
      "source-id": 3,                            // 파티션 대상 컬럼 ID
      "name": "category",                        // 파티션 컬럼 이름
      "transform": "identity"                    // 파티션 방식 (identity: 변환 없음)
    }
  ]
}

---

🧠 Step 2. JSON → 자연어 문서로 변환 함수

# src/load_json.py

import json  # JSON 파일을 읽기 위한 내장 모듈

def convert_metadata_to_text(json_data: dict) -> str:
    """
    Iceberg metadata JSON 객체를 받아서 자연어 텍스트로 변환합니다.
    """

    # 1. 테이블명을 가져오며, 없을 경우 기본값 'unknown' 사용
    table = json_data.get("table-name", "unknown")

    # 2. 컬럼 정보 추출 (없으면 빈 리스트 반환)
    fields = json_data.get("schema", {}).get("fields", [])

    # 3. 파티션 정보 추출 (없으면 빈 리스트 반환)
    partitions = json_data.get("partition-spec", [])

    # 4. 결과 텍스트 초기화
    text = f"📂 테이블명: {table}\n🧾 컬럼 목록:\n"

    # 5. 각 컬럼을 자연어 형식으로 나열
    for field in fields:
        # ex) - product_id (long)
        text += f"- {field['name']} ({field['type']})\n"

    # 6. 파티션 정보가 있다면 출력
    if partitions:
        # 파티션 컬럼 이름만 추출
        partition_names = [p['name'] for p in partitions]
        # ex) 🧩 파티션 컬럼: category
        text += f"🧩 파티션 컬럼: {', '.join(partition_names)}\n"

    # 7. 완성된 자연어 문서 반환
    return text

---

📄 Step 3. JSON 파일을 로딩하고 .txt로 저장

# src/load_json.py 에 이어서 작성

def load_and_convert_json_file(json_path: str, save_path: str):
    """
    JSON 파일을 읽고 자연어 문서로 변환한 뒤, .txt 파일로 저장합니다.
    """

    # 1. 지정된 경로의 JSON 파일 열기
    with open(json_path, 'r', encoding='utf-8') as f:
        metadata = json.load(f)  # JSON 파싱

    # 2. JSON → 자연어 문서로 변환
    text = convert_metadata_to_text(metadata)

    # 3. 변환된 문서를 .txt 파일로 저장
    with open(save_path, 'w', encoding='utf-8') as f:
        f.write(text)

    # 4. 완료 메시지 출력
    print(f"✅ 변환 완료: {save_path}")

---

▶️ Step 4. main.py에서 실행 테스트

# main.py

from src.load_json import load_and_convert_json_file  # 함수 임포트

# ✅ metadata.json 경로와 저장할 텍스트 파일 경로 지정
load_and_convert_json_file(
    json_path="data/products_metadata.json",  # 원본 JSON 위치
    save_path="docs/products.txt"             # 출력할 .txt 위치
)

 

✅ 실행 시 결과:

✅ 변환 완료: docs/products.txt

💡 docs/products.txt 안에는 다음과 같은 문서가 저장됩니다:

📂 테이블명: products
🧾 컬럼 목록:
- product_id (long)
- product_name (string)
- category (string)
🧩 파티션 컬럼: category

---

📎 요약 및 핵심 정리

• Iceberg의 metadata.json을 자연어 설명 문서로 변환하여 .txt로 저장했습니다.
• 이 .txt 문서는 이후 벡터 임베딩과 검색 시스템에서 사용됩니다.
• 분리된 함수로 구성하여 여러 JSON 파일에도 재활용 가능하도록 설계했습니다.