nl_collect
Collect Korean academic literature metadata from the National Library of Korea by searching multiple terms, merging results, and saving to files; auto-partitioning overcomes the 500-record limit.
Instructions
[수집] 검색어들을 각각 조회해 합집합으로 모으고 파일로 저장한다.
terms: 변형어 목록(각각 개별 검색 후 합집합). 검색어를 쪼갤수록 500건 상한을 덜 받으므로
넓은 말 하나보다 좁은 말 여럿이 회수량이 많다.
kwd: 단일 검색어(terms 대신).
exact: 🔴 코퍼스 수집에는 쓰지 말 것. 구문검색은 토큰 인접을 요구해 한국어 복합어가
조사·수식어로 갈라진 표제(교육의 형평성)를 전부 놓친다. 실측 재현율 손실 평균 47%,
최악 84%(교육형평성 31→5건)이고 버려진 것의 76%가 관련 문헌이었다.
변형어를 늘려도 회복되지 않는다(12/31). 자료를 넓게 모으려면 False 로 두고 걸러내기는
contains 후처리로 하라. exact 는 전체 표제를 아는 특정 자료 조회용이다.
category: 도서·학위논문·잡지/학술지·기사 등. ⚠️ "전체" 는 오류(013) — 생략할 것.
auto_partition: 500 상한 우회. 검색어가 상한에 걸리고 category 를 지정하지 않았으면
서버측 축으로 재귀 분할해 재수집한다. 축은 실측으로 찾은 3개다 —
category → manageName(둘 다 완전분할) → licYn(값이 빈 레코드는 못 잡음).
상한에 걸린 조각만 다음 축으로 더 쪼개고, 부모 조각도 합집합에 넣어 불완전한
축을 써도 손해가 나지 않게 한다.
partition_depth: 분할 깊이(1~3, 기본 2). 실측 회복량(교육복지 전체 7,028건):
분할 없음 500(7%) → 깊이1 2,134(30%) → 깊이2 3,265(46%) → 깊이3 4,722(67%).
⚠️ 호출 수가 함께 는다(13 → 25 → 60회). 깊이 3은 코퍼스 전수성이 중요할 때만.
⚠️ 전수는 여전히 불가능하다. meta.axes[].partition.unreachable 과
still_capped 가 못 받은 건수와 남은 조각을 보고한다.
contains: 결과 텍스트 부분일치 후처리. year_from/year_to: 발행연도 필터.
formats: xlsx/csv/json/sqlite (기본 3종). save=false 면 저장 없이 미리보기만.
out_dir 미지정 시 홈의 nl-output/. extra_params: 임의 API 파라미터 전달.
⚠️ year_from/year_to/contains 는 로컬 후처리다 — 이미 받은 레코드에만 걸린다.
500건 상한을 풀어주지 않는다. 서버측 연도 필터는 존재하지 않는다(실측:
startPubYear·pubYearStart 등 11개 후보 전부 무시됨). 연도로 상한을 우회할 수는 없다.
⚠️ meta.cap_hit_terms 에 검색어가 있으면 그 검색어는 500건에서 잘린 것이다.
max_records 를 올려도 해결되지 않는다 — 검색어를 좁히거나 category 로 쪼갤 것.
meta.year_missing_dropped 는 발행연도가 비어 연도 필터에서 탈락한 건수다
(실측 5.2%의 레코드는 pubYearInfo 가 비어 있다).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kwd | No | ||
| name | No | ||
| save | No | ||
| exact | No | ||
| terms | No | ||
| formats | No | ||
| out_dir | No | ||
| year_to | No | ||
| category | No | ||
| contains | No | ||
| year_from | No | ||
| max_records | No | ||
| srch_target | No | title | |
| extra_params | No | ||
| auto_partition | No | ||
| partition_depth | No |