ETL 파이프라인

UBIST 처방조제 데이터를 엑셀 파일에서 PostgreSQL 데이터베이스로 적재하는 ETL(Extract-Transform-Load) 파이프라인의 구조와 실행 방법을 설명합니다.

UBIST 엑셀 구조

UBIST에서 제공하는 엑셀 파일은 Wide/Pivot 형태입니다.

차원 컬럼 (10개)

지표 컬럼 (3개 x 60개월)

Wide→Long 변환

ETL의 핵심은 Wide 형태(월이 컬럼)를 Long 형태(월이 행)로 변환하는 것입니다.

변환 전 (Wide)

제조사 | 제품 | ATC | 2025-01_처방건수 | 2025-01_처방액 | 2025-01_처방량 | 2025-02_처방건수 | ...
유니온 | A제품 | N02  | 150              | 5000000        | 300            | 160              | ...

변환 후 (Long)

제조사 | 제품 | ATC | 연월    | 처방건수 | 처방액   | 처방량
유니온 | A제품 | N02  | 2025-01 | 150     | 5000000 | 300
유니온 | A제품 | N02  | 2025-02 | 160     | 5200000 | 320

변환 규칙

• 3개 지표(처방건수, 처방액, 처방량)가 모두 0인 월은 제외합니다 (불필요한 제로 레코드 방지).
• 동일 배치 내 중복 키(제조사+제품+연월)가 존재하면 UPSERT로 최신 값을 유지합니다.
• D열(제조사 중복)은 무시합니다 (A열과 100% 동일).

실행 명령어

ETL 스크립트는 scripts/ubist_import.py입니다.

전체 적재

전체 데이터를 한 번에 적재합니다. 최초 실행 또는 전체 재적재 시 사용합니다.

python3 scripts/ubist_import.py --file "UBIST_D1 Sales.xlsx" --direct

특정 연도만 적재

특정 연도의 데이터만 적재합니다. 증분 업데이트 시 사용합니다.

python3 scripts/ubist_import.py --file "UBIST_D1 Sales.xlsx" --year 2025

드라이런 (테스트)

실제 DB에 적재하지 않고 변환 결과만 확인합니다. 새 파일 검증 시 사용합니다.

python3 scripts/ubist_import.py --file "UBIST_D1 Sales.xlsx" --dry-run

특정 연도 삭제

특정 연도의 UBIST 데이터를 DB에서 삭제합니다.

python3 scripts/ubist_import.py --delete-year 2021

실행 흐름

ETL 스크립트의 내부 처리 순서는 다음과 같습니다:

1. 엑셀 파일 로드 (openpyxl, read_only 모드로 메모리 효율화)
2. 헤더 파싱 (1~2행: 지표 그룹 + 월 헤더 매핑)
3. Wide→Long 변환 (행 x 월 조합을 개별 레코드로 분해)
4. 제로값 스킵 (3개 지표 모두 0이면 해당 레코드 제외)
5. 배치 내 중복 제거 (UPSERT 키 기준)
6. 벌크 UPSERT (psycopg2 execute_values, 5,000행 단위 배치)
7. 적재 완료 후 캐시 자동 갱신 (refresh_all_kpi_cache() 호출)

에러 처리

파일 관련 에러

DB 관련 에러

재실행 안전성

ETL 스크립트는 UPSERT(INSERT ON CONFLICT UPDATE) 방식으로 동작하므로, 같은 파일을 여러 번 실행해도 데이터가 중복되지 않습니다. 에러 발생 시 원인을 해결한 후 동일한 명령어로 재실행하면 됩니다.

의존성

ETL 스크립트 실행에 필요한 Python 패키지입니다.

pip install -r scripts/requirements.txt

환경변수

ETL 스크립트가 사용하는 환경변수입니다. 프로젝트 루트의 .env 파일에 설정합니다.

다음 단계

• 캐시 관리 — ETL 이후 캐시 갱신 전략
• 문제 해결 — ETL 실패 시 대응 방법