관세청 무역통계 DB

DB 구축

계층을 어떻게 나누었고 스키마를 어떻게 짰는지, HS 개정을 어떻게 연결했고 커버리지와 검증은 어디까지 확인했는지 밝힌다.

계층 분리

fact 스키마 (관세청 raw)

fact는 실제 거래 수치가 담기는 핵심 테이블이다. 다섯 종류가 있다. fact_trade는 국가 × HS10 품목 × 월 단위의 세밀한 거래 행이고, fact_total은 품목 구분 없이 국가 × 월로 합산된 총계 행이다. fact_nqi는 같은 통관 실적을 신성질별 × 국가 × 월로 관세청이 직접 집계한 것으로, HS 개정에 흔들리지 않는 계열이 필요할 때 쓴다(이 표만 2005년부터다). 넷째 fact_temper는 같은 실적을 성질별 × 월로 집계한 것으로, 10일 자료의 10대 품목이 이 분류로 정의된다(이 표만 1995년부터다). 다섯째 fact_exp10d는 다른 API에서 오는 10일 단위 잠정치로, 수출·수입 각각의 주요품목별과 주요국가별 네 계열이 series 열로 갈려 담긴다. 월 자료보다 훨씬 빠른 대신 항목이 열 개씩뿐이고 중량이 없다. 다섯 다 관세청이 준 필드만 담으며 우리가 계산해 넣은 컬럼은 없다.

총계 행은 응답에 국가코드가 없어 stat_cd를 파일명에서 추출한다 — 이것이 DB 전체에서 유일하게 허용하는 파생이다.

셋째 fact는 분류 체계가 다르다. fact_nqi는 같은 통관 실적을 HS가 아니라 관세청 신성질별로 집계한 것이다. HS 컬럼이 없고 그 자리에 nqi5(세세분류 코드)가 온다. 응답은 수출과 수입이 세로로 나뉘어 오는데(impexp 필드) fact_trade와 같은 가로 형태로 돌려 담았다 — 값은 그대로이고 모양만 바꾼 것이다. bal_payments는 응답에 없어 담지 않는다.

넷째 fact는 기간이 가장 길다. fact_temper는 같은 실적을 관세청 성질별로 집계한 것으로 1995년 1월부터 있다 — fact_trade보다 열두 해, fact_nqi보다 열 해 앞선다. 이 표를 받은 이유는 따로 있다. 10일 잠정치의 10대 품목이 바로 이 분류의 마디로 정의되어 있어, 부호를 묶으면 10일 자료를 품목 단위로 맞대 볼 수 있는 유일한 계열이 된다. 수출과 수입은 부호 체계가 서로 다르다 — 수출 153개, 수입 181개이고 나무가 아예 달라 같은 부호 11201이 수출에서는 기타 육류, 수입에서는 쌀이다. 그래서 fact_nqi처럼 가로로 눕히지 않고 imexp를 키에 둔 세로 형태로 담는다.

다섯째 fact는 성격이 다르다. fact_exp10d는 관세청이 상순분을 11일, 중순분을 21일, 월 전체를 익월 1일에 내는 10일 단위 잠정치다(2016.01부터). 네 계열이 함께 들어 있다 — exp_item(수출 주요품목별), exp_cnty(수출 주요국가별), imp_item(수입 주요품목별), imp_cnty(수입 주요국가별). 월 자료가 나오기 전에 방향을 읽을 수 있다는 것이 값어치이고, 대신 각 계열이 열 항목과 총계뿐이며 중량이 없다. 뷰를 쓸 때 series를 반드시 걸러야 한다 — 안 그러면 품목과 국가가 섞여 총계가 두 배가 된다. 값은 누적치(1~10일, 1~20일, 1~말일)이고 단위는 천 달러이며, 원본 그대로 담는다. 구간 증분과 억 달러 환산은 뷰 v_exp10d_seg가 맡는다. 열 항목은 바로 위 신성질별이 아니다 — 관세청 현행 수출 성질별 분류에서 따온 것이고, 그것도 한 계층이 아니라 철강제품은 3단위, 반도체·석유제품·가전제품은 소분류, 나머지는 세분류에서 딴다. 두 분류는 같은 엑셀(15049720)에 나란히 들어 있어 헷갈리기 쉽다. 이름이 겹치는 것은 반도체와 선박뿐이고 승용차·자동차부품 같은 이름은 신성질별에 아예 없다.

fact_exp10d 16,852행(계열당 4,213행). 이 자료는 같은 시점을 여러 번 관측한다 — 당월은 잠정이고 전월까지는 신고 정정·취하를 반영해 갱신되기 때문이다. 그래서 값이 바뀔 때마다 새 행을 쌓고 fetched_at으로 구분한다. 나중에 "그때 알 수 있었던 값"으로 예측 성능을 정직하게 재려면 이 이력이 있어야 한다. 값이 그대로면 행을 만들지 않는다.

dim 스키마 (연결·참조)

dim은 fact의 코드에 의미를 붙여 주는 참조 테이블이다. fact에는 stat_cd(국가코드)나 hs10(품목코드) 같은 코드만 있고 이름이 없다. 어느 나라인지, 무슨 품목인지, 개정 전 코드는 무엇이었는지를 알려면 아래 dim 테이블과 조인한다. 핵심은 fact를 훼손하지 않고 이름·연결을 옆에 병기한다는 점이다.

HS 개정 연결

커버리지

커버리지는 "fact의 코드가 dim에서 얼마나 이름·연결을 얻는가"를 나타내는 지표다. 국가는 전부 매칭되고, 기간도 빠짐없이 이어진다. 다만 품목코드는 100%가 아니다 — 그 이유와 실제 영향은 아래에서 설명한다.

검증 — 04_validate 5계층

DB를 다 만든 뒤, 단일 스크립트(04_validate.py)가 다섯 계층(스키마 / 값 / 적재 / dim / concordance)을 자동 점검한다. 예컨대 "우리가 만들지 않기로 한 파생 컬럼이 섞여 들지 않았는가", "수집된 데이터가 하나도 빠짐없이 적재됐는가", "bal_payments = exp_dlr − imp_dlr 항등식이 전 행에서 성립하는가"를 확인한다. 결과는 네 등급으로 표시된다.

PASS는 통과, FAIL은 반드시 고쳐야 할 무결성 위반, WARN은 주의가 필요하나 결함은 아닌 항목, INFO는 참고 사항이다. FAIL이 0이라는 것이 가장 중요하다 — 무결성 위반이 하나도 없다는 뜻이다. WARN 4는 전부 원자료(관세청 공개자료) 자체의 한계(품목 커버리지 등)이지 DB가 잘못 만들어진 것이 아니다. INFO 1은 음수 중량 19행(관세청의 사후 정정 원본이므로 보존). 참고로 bal_payments 항등식은 거래 행 전체에서 위반 0으로 통과했다.

HS 연계

개정으로 끊긴 품목 시계열을 어떻게 이었는지 밝힌다. 6자리는 공표된 사실이고, 10자리는 우리가 만든 추정이다.

왜 필요한가

두 층위는 성격이 다르다

이 DB는 개정 연결을 두 해상도로 제공한다. 둘을 하나로 합치지 않고 테이블을 나눈 이유는 근거의 성격이 다르기 때문이다. 6자리 연계는 관세청이 공표한 표를 그대로 옮긴 것이고, 10자리 연계는 공식 표가 없어 우리가 추정한 것이다. 아래 표는 그 차이를 정리한 것이다.

HS6 연계 (2026-07 구축)

HS10 연계 (2026-08 구축)

공식 승계표는 어디에도 없다

자료 — 연도별 별표 전문

lawSearch.do?OC=test&target=admrul&type=XML&query=관세·통계통합품목분류표&nw=2
lawService.do?OC=test&target=admrul&ID=<행정규칙일련번호>&type=XML
law.go.kr/flDownload.do?flSeq=<첨부일련번호>

절차

구축은 scripts/03c_build_hs10_concordance.py 한 스크립트가 처음부터 끝까지 수행한다. 여섯 단계다.

검증 — 단차가 줄었다는 것은 검증이 아니다

완성도

파서와 결과물을 각각 독립된 기준으로 확인했다. 파서는 공식 수치·공식 대비표와 대조했고, 결과물은 총액 보존·가중치 정합·커버리지·개별 계열 연속성으로 확인했다.

• 파서 대조. 2012년 공식 신구대비표와 맞대면, 공식 폐지 646건 중 627건(97.1%)이 2011년 별표에 있고 개정 후 별표에는 하나도 남지 않는다. 공식 신설 1,009건은 100% 개정 전 별표에 없다. 역방향으로, 별표 차이로 잡은 폐지 636건 중 627건(98.6%)과 신설 970건 중 968건(99.8%)이 공식 목록에 있다.
• 큰 이동의 타당성. 2022년 개정에서 금액이 가장 큰 이동은 8517701023 → 8524122000(39.20억 달러), 2841909000 → 2841909020·2841909030(니켈코발트망간·알루미늄 산화물의 리튬염, 41.49억 달러), 8517129090 → 8517130000(신설된 스마트폰 세번, 24.23억 달러)이다. 모두 개정 내용과 맞는다.
• 계열 연속성. 원자료에서 2022년 1월에 무에서 생겨나던 코드들이 과거로 이어진다(아래 표).

2021년까지가 되짚은 값이고 2022년부터가 원자료다. 원자료만 보면 네 계열 모두 2022년 1월 이전이 비어 있다.

한계

• 나뉜 비율은 관측값이 아니다. 하나의 코드가 여럿으로 갈릴 때 그 비율은 개정 직후 여섯 달의 수출액 분포에서 나온다. 그때 어느 한쪽이 부진했다면 그 왜곡이 과거 전체에 실린다. 창 길이 6개월도 관행일 뿐 근거가 있는 것은 아니다.
• 수출액으로만 조정했다. 수입과 중량에는 다른 비율이 맞을 수 있다. 수출이 없고 수입만 있는 코드는 행합이 사실상 0이라 품명 유사도가 그대로 가중치가 된다.
• 2011년 이전에 사라진 코드는 6자리 해상도로만 잇는다. 2007~2011년 수출액의 5.61%가 여기 해당한다(9013801030 253.79억 달러, 8517701020 177.09억 달러 등). 국가법령정보센터에 2011년보다 옛 고시가 없다. method='hs6_fallback'이 이 몫이다.
• 국가별 자료에는 아직 적용해 보지 않았다. 목적지 수·확산·집중도는 국가 × HS10 수준에서 계산되므로, 코드 수준 가중치를 국가별로 그대로 써도 되는지는 따로 확인해야 한다.

덤 — 폐지코드 품명을 되찾다

별표를 파싱하면서 오래 막혀 있던 문제 하나가 함께 풀렸다. dim_hs10의 품명 커버리지는 72.8%다. 관세청 HS부호 파일이 2026년 유효 코드만 담아, 2007~2021년에만 존재하다 폐지된 4,194종의 이름이 비어 있었다. 과거 스냅샷은 공공데이터포털에 없어 미해결로 남아 있던 항목이다. 그런데 별표에는 그해 유효했던 코드 전부의 품명이 있으므로, 그중 3,738종(89.1%, 폐지코드 거래액의 94.1%)을 되찾을 수 있었다.

다만 dim_hs10에 열로 넣지는 않았다. 품명이 판본에 따라 변하기 때문이다 — 15,255종 가운데 4,806종(31.5%)이 판본별로 다른 품명을 갖는다. 표기를 다듬은 것만이 아니라 젖소가 번식용으로, 우모분이 깃털가루로, 골분이 뼛가루로 바뀐다. dim_hs10의 키는 hs10 하나이므로 열로 넣으면 여러 참값 중 하나만 남고 나머지는 사라진다. 어느 해에 이름이 바뀌었는지도 자료다.

그래서 (hs10, 별표연도)를 키로 하는 별도 테이블 dim_hs10_name_hist(72,129행)에 원문 그대로 쌓았다. dim_hs10은 손대지 않았으므로 "정직한 NULL" 정책도, 기존 쿼리도 그대로다. 관세청 dim_hs10과 2022년 별표가 겹치는 11,267종에서 품명이 98.5% 일치한다 — 출처가 달라도 같은 값을 준다.

-- 폐지코드를 포함해 아무 HS10이나 이름을 얻는다(가장 최근 판본 우선)
SELECT hs10, name_ko FROM dim_hs10_name_hist
QUALIFY ROW_NUMBER() OVER (PARTITION BY hs10 ORDER BY byeolpyo_year DESC) = 1;

덮지 못한 456종은 대부분 2011년 이전에 폐지된 코드다. 별표가 2011년부터라 그 이전에 사라진 것은 이름을 얻을 수 없다.

쓰는 법

과거 자료에 그 시점의 판본을 붙여 조인하고, 금액에 weight를 곱한 뒤 hs2022로 다시 집계한다. 2022년 이후 자료는 이미 현행 체계이므로 변환하지 않고 그대로 이어 붙인다. 10자리 해상도가 필요하면 method='chain'으로 걸러야 한다 — hs6_fallback은 6자리로 흩뿌린 보완분이다.

-- 과거 코드 체계를 현행(2022) 위로 옮겨 HS10 시계열을 잇는다
SELECT c.hs2022, f.yyyymm, SUM(f.exp_dlr * c.weight) AS exp_dlr
FROM fact_trade f
JOIN dim_hs10_to_2022 c
  ON c.hs_past = f.hs10
 AND c.past_version = CASE WHEN f.yyyymm < 201201 THEN '2007'
                           WHEN f.yyyymm < 201701 THEN '2012' ELSE '2017' END
WHERE f.yyyymm < 202201 AND c.method = 'chain'
GROUP BY 1, 2
UNION ALL
SELECT hs10, yyyymm, SUM(exp_dlr) FROM fact_trade
WHERE yyyymm >= 202201 GROUP BY 1, 2;

6자리로 충분한 분석이라면 SUBSTR(hs10,1,6)으로 자른 뒤 dim_hs6_concordance를 쓰는 편이 낫다. 공표된 자료이므로 추정을 설명할 필요가 없다.

데이터 함정

DB를 만들며 실측으로 확인한, 모르고 쓰면 결과를 틀리게 만드는 지점들을 모았다.

받기·사용

DB를 받아 로컬 주피터에서 분석하려는 연구자에게 필요한 것을 안내한다.

먼저 알아둘 것 — 받을 것이 둘로 나뉜다. 이 DB는 두 부분으로 배포된다. 하나는 분석 코드·노트북·폴더 구조가 담긴 GitHub 저장소이고, 다른 하나는 DB 파일 자체(kcsdb.duckdb)다. DB 파일은 용량이 커서 GitHub 저장소에 넣을 수 없기 때문에(100MB 한도), 저장소는 clone으로 받고 DB 파일은 Releases에서 따로 받아 저장소 안 정해진 자리에 놓는 방식이다.

전체 흐름은 네 단계다 — 패키지 설치 → 저장소 받기 → DB 파일 받아 배치 → 주피터에서 열기. DB를 재구축하는 것이 아니라 이미 만들어진 DB를 받아 분석만 하므로 준비물은 가볍다(파이썬 패키지 4개). 순서대로 따라 하면 된다.

내려받기 v1.0-202607.2 · 2026-09-13 게시

1. 패키지 설치

   터미널(명령 프롬프트 / PowerShell / 터미널)에서 아래를 실행한다. 분석만 하므로 이 4개면 충분하다 — conda나 특정 파이썬 버전은 필요 없다.

   pip install duckdb pandas matplotlib jupyter

2. 저장소 받기 (코드·노트북)

   GitHub에서 이 저장소를 clone(또는 ZIP 다운로드 후 압축 해제)하면 KCSDB2/ 폴더가 생긴다. 분석에 필요한 것이 모두 이 안에 들어 있다.

   git clone https://github.com/pilsunchoi/KCSDB2.git

   • notebooks/analysis_start.ipynb — 시작용 분석 노트북 (4단계에서 연다)
   • scripts/ · docs/ · data/external/ — 파이프라인 스크립트·문서·외부 참조자료
   • data/processed/ — 지금은 비어 있는 폴더. 다음 단계에서 받을 DB를 여기에 놓는다.

   즉 노트북은 이 저장소에 함께 들어 있어 따로 받을 필요가 없다. 오직 용량이 큰 DB 파일만 저장소에 없어서 다음 단계에서 따로 받는다.

3. DB 파일 받아서 배치

   앞 단계에서 저장소를 받았으니 data/processed/ 폴더는 이미 있다(비어 있음). 이제 Releases 페이지에서 압축된 DB kcsdb.duckdb.gz를 받아 압축을 풀고, 그 파일을 data/processed/kcsdb.duckdb 자리에 놓는다.

   • Windows: 7-Zip 등으로 .gz 압축 해제
   • Mac / Linux: 터미널에서 gunzip kcsdb.duckdb.gz

   노트북은 이 data/processed/kcsdb.duckdb 경로에서 DB를 읽으므로, 파일 이름과 위치를 그대로 맞춰 두는 것이 중요하다.

4. 주피터에서 열기

   준비가 끝났다. 저장소 루트(KCSDB2/)에서 아래를 실행하면 브라우저에 주피터가 열린다. 2단계에서 함께 받은 notebooks/analysis_start.ipynb를 열고 셀을 위에서부터 차례로 실행하면, DB 접속 → 구조 확인 → 기술통계 시연이 순서대로 나온다.

   jupyter notebook

기본 접속 코드

DuckDB는 파일 하나에 접속하는 방식이라 서버가 필요 없다. 아래처럼 read_only=True로 열면 실수로 원본을 바꿀 염려 없이 안전하게 조회만 할 수 있다. 여러 사람이 같은 파일을 동시에 읽을 때도 이 옵션이 안전하다. 작업이 끝나면 con.close()로 닫는다.

import duckdb
con = duckdb.connect("data/processed/kcsdb.duckdb", read_only=True)
print(con.sql("SELECT COUNT(*) FROM fact_trade").fetchone())
con.close()

무엇이 들어 있나 — 표 전체 목록

이 DB는 관세청 공공데이터 여덟 갈래와 외부 참조 셋을 한 파일에 모은 것이다. 아래 표가 전부다. 행수와 기간은 DB를 직접 읽어 자동으로 채우므로 이 페이지가 실물보다 낡을 일이 없다. fact는 관세청이 준 실적을 그대로 담고, dim은 코드에 이름과 연결을 붙이며, mart는 이 저장소가 계산한 지표다. 계산한 것과 받은 것을 이름으로 갈라 두었으니 접두어만 보고 근거의 성격을 알 수 있다.

기간이 표마다 다르다. 월 실적(fact_trade)은 2007년부터, 신성질별 공식 실적(fact_nqi)은 2005년부터, 성질별 공식 실적(fact_temper)은 1995년부터, 10일 단위 잠정치는 2016년부터, 조업일수 달력은 2027년까지 미리 만들어 두었다.

어디서 받았나

원천은 공공데이터포털의 관세청 OpenAPI가 중심이고, 여기에 분류·달력 자료와 국가데이터처 KOSIS의 참조 통계가 더해진다. 모두 무료이며 활용신청은 자동승인이다(15049720은 신청도 필요 없다). 아래 표의 번호는 공공데이터포털 데이터셋 번호이고, KOSIS는 통계표 번호다.

위 안내는 이미 만들어진 DB를 받아 쓰는 연구자를 위한 것이다. 반대로 DB를 만들어 나눠 주는 배포자(관리자)—예컨대 새 월 데이터를 반영해 DB를 갱신하고 배포하는 사람—는 할 일이 다르다. DB 파일을 .gz로 압축하고, 그것을 GitHub Release에 첨부해 올리며, 관세청 API 인증키가 저장소에 실수로 올라가지 않도록 관리(.gitignore 처리)해야 한다. 이 배포 절차는 저장소 docs/배포자_안내.md에 정리돼 있다.