연결 점검 — 인증키 보유 여부 + 소장자료 검색 API 실제 왕복 1회.

[소장자료 검색] 국립중앙도서관 소장자료를 검색한다.

kwd: 검색어. exact: True 면 큰따옴표 구문검색(토큰 인접 요구). 특정 자료를 정확히 찾을 때만 쓸 것 — 코퍼스 수집에는 부적합하다(아래 참조). srch_target: 실측 지원값 — title(제목) · author(저자) · publisher(발행자) · keyword(키워드) · total(전 필드). ⚠️ isbn·classNo·callNo 등 미지원 값은 오류가 나지 않고 조용히 전 필드 검색으로 폴백한다. ISBN 으로 찾았다고 믿으면 실제로는 전 필드 결과를 받는다 (실측: srchTarget=isbn&kwd=오욱환 이 저자 검색과 같은 36건을 반환). ISBN 을 찾으려면 srch_target="total" 로 두고 ISBN 문자열을 넣는 편이 정직하다. category: 도서·고문헌·학위논문·잡지/학술지·신문·기사·멀티미디어·장애인자료·웹사이트· 해외기록물·외부연계자료·기타. ⚠️ "전체" 는 오류(013) — 전체 검색은 생략할 것. rows: 반환 건수(1~100, 문맥 절약을 위한 도구 자체 상한. API 는 500까지 받는다). extra_params: 임의 API 파라미터 전달.

⚠️ 기본 검색은 제목 부분일치가 아니라 토큰 매칭 + 적합도 정렬이다. 교육불평등 은 교육·불평등 으로 쪼개져 둘 중 하나만 든 제목도 회수된다. ⚠️ exact=True 는 재현율을 크게 떨어뜨린다 — 실측 6개 검색어에서 평균 47% 손실, 최악 84%(교육형평성 31건 → 5건). 한국어 복합어가 표제에서 조사·수식어로 갈라지기 때문이다(교육의 형평성, 초중등교육의 형평성과) — 구문검색은 인접을 요구한다. 버려지는 것의 76%가 구성어를 모두 포함한 관련 문헌이었다. → 자료를 넓게 모을 때는 쓰지 말고, 전체 표제를 아는 특정 자료 조회에만 쓸 것. AND/OR/NOT 은 연산자가 아니라 그냥 토큰이다(AND 단독 검색 시 451,670건).

⚠️ total 은 국립중앙도서관이 보고한 전체 건수, truncated 는 이번 응답이 그보다 적다는 뜻. cap_hit=true 는 다르다 — total 이 500을 넘어 501번째부터는 어떤 페이징으로도 받을 수 없다(레코드 오프셋 기준 상한, 실측 확인). 그 경우 검색식을 쪼개야 한다. 빈 records 를 '자료 없음'으로 오독하지 말고 total 을 함께 볼 것.

[수집] 검색어들을 각각 조회해 합집합으로 모으고 파일로 저장한다.

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 가 비어 있다).