JSON Toolkit

Node.js에서 큰 JSON 읽기: stream-json 스트리밍 파싱과 배압 실전

핵심 요약: 186MB JSON 배열을 readFileSync + JSON.parse로 읽으면 피크 메모리가 612MB에 달합니다. stream-json의 streamArray로 한 건씩 소비하도록 바꾸면 104MB에서 일정하게 유지됩니다. 이 글은 네 가지 읽기 방식의 실측 비교를 제시하고, for await가 왜 자연스럽게 배압을 만드는지, data 이벤트가 배압을 어떻게 잃는지, 쓰기 측의 highWaterMark와 drain 설정 방법을 설명합니다.

중급약 5분 소요2026-11-17 발행2026-11-17 업데이트
Node.js로 큰 JSON 파일을 스트리밍 파싱하는 모습: streamArray 파이프라인과 배압 실측 비교

186MB JSON 파일 하나를 임포트했을 뿐인데 프로세스 메모리가 600MB에 도달한다면, 파일이 크기 때문이 아니라 JSON.parse가 텍스트 전체를 객체 그래프 전체로 한 번에 교환했기 때문입니다. 읽는 방식을 바꾸면 메모리 곡선은 평평해집니다.

하나, 증상: 186MB 파일의 612MB 피크

서버 측 임포트 작업에서 이 문제가 가장 자주 발생합니다: 정기 주문 동기화, 로그 정제, 이력 데이터 벌크 적재. 전형적인 구현은 다음과 같습니다.

const fs = require('fs');
const raw = fs.readFileSync('./orders.json', 'utf8');
const orders = JSON.parse(raw);
for (const order of orders) await saveToDb(order);

이 패턴을 Node 22.13에서 실측했습니다. 샘플은 480,000건의 주문 레코드 객체 배열, 파일 186MB(문자열, 중첩 객체, 배열을 포함하는 실무형 구조). /usr/bin/time -v로 측정한 결과 읽기는 1.3초 만에 끝나지만 Maximum resident set size는 612MB — 파일의 3.3배입니다. V8 구세대 기본 한도가 1.4~2GB이므로 이런 작업이 몇 개만 병행돼도 컨테이너는 OOM Kill을 기다리게 됩니다.

구성은 단순합니다: 원문 텍스트가 메모리에 한 부(약 186MB), parse 결과 객체 그래프가 또 한 부(문자열 키, 중첩 객체 헤더, 배열에 각각 추가 비용), 그리고 파싱 과정의 임시 할당까지 쌓여 600MB에 도달하는 것은 자연스러운 일입니다.

둘, 원인: JSON.parse는 전체 텍스트를 전체 그래프로 교환한다

JSON.parse의 계약은 "완전한 텍스트를 주면 완전한 객체 그래프를 돌려준다"입니다. 파싱 시작 전에 전체 텍스트가 준비되기를 요구하고, 파싱이 끝난 뒤에야 결과를 한꺼번에 넘겨줍니다. 중간에 "먼저 첫 1,000건만" 같은 기회는 전혀 없습니다.

객체 그래프 비용은 JSON의 메모리 계산에서 항목별로 측정했습니다: 문자열은 실제 공간을 차지하고, 객체는 키마다 슬롯을 잡으며, 배열은 요소 종류에 따라 폭이 결정됩니다. 십수 MB의 JSON이 파싱 후 3~5배가 되는 것이 상례이고 피크는 그 위에 더해집니다.

그러나 대부분의 임포트 작업에는 전체 그래프가 필요 없습니다: 한 건씩 저장하고, 한 건씩 필터링하고, 한 건씩 변환하면 처리된 레코드는 즉시 가비지 컬렉션 대상이 됩니다. 필요한 것은 "한 건 파싱하면 한 건 넘겨준다"는 능력 — 바로 스트리밍 파싱의 정의입니다.

셋, 해법: streamArray로 한 건씩 소비하고, for await가 자연스럽게 배압을 만든다

stream-json은 파서를 Transform 스트림으로 구현해 토큰 단위로 파싱하므로 파일 전체를 기다리지 않습니다. 최상위가 배열이면 streamArray()는 각 요소의 파싱이 끝나는 순간 {key, value}를 발행합니다:

const fs = require('fs');
const { chain } = require('stream-chain');
const { parser } = require('stream-json');
const { streamArray } = require('stream-json/streamers/StreamArray');

async function importOrders(filePath) {
  const pipeline = chain([
    fs.createReadStream(filePath, { highWaterMark: 64 * 1024 }),
    parser(),
    streamArray(),
  ]);
  for await (const { key, value } of pipeline) {
    await saveToDb(value);
  }
}

같은 186MB, 같은 48만 건에서 이 방식의 피크 RSS는 104MB로 전 구간 일정했습니다. 메모리에는 "현재 요소 + 파서 상태"만 존재하고, 처리가 끝난 요소는 즉시 회수됩니다.

놓치기 쉬운 세부 사항: for await는 saveToDb가 완료되기 전에는 파서에서 다음 레코드를 끌어오지 않으므로, 파서는 파일 읽기를 중단합니다. DB가 느릴수록 읽기도 느려집니다 — 이것이 배압이며, 추가 코드 없이 자연스럽게 형성됩니다. dev.to의 4GB 시정 교통 로그 수집 사례도 같은 체인을 쓰며, pick({filter:'data'})를 추가해도 메모리 곡선은 마찬가지로 평평했습니다.

넷, 쓰기 측 실패: 일시정지하지 않는 data 이벤트가 메모리를 되밀어 올린다

스트리밍 파싱은 읽기 측만 다스립니다. 쓰기 측이 배압을 받아주지 않으면 메모리는 다시 올라갑니다. 가장 전형적인 실패 패턴은 data 이벤트 안에서 비동기 쓰기를 하면서 쓰기 버퍼를 무시하는 것입니다:

// 잘못됨: data 이벤트 + 비동기 쓰기, 배압 완전 상실
readable.on('data', async (chunk) => {
  await slowWrite(chunk); // 스트림은 기다리지 않고 버퍼는 계속 부풀어 오른다
});

data 모드에서는 스트림이 계속 흐르므로 slowWrite가 아무리 느려도 상류는 멈추지 않고, 밀린 데이터가 모두 쓰기 버퍼에 쌓입니다. 같은 186MB 샘플로 100번째 청크마다 1ms 지연되는 느린 Writable에 연결해 비교한 결과, 배압을 무시한 방식은 피크 RSS 407MB, write()가 false를 반환할 때 await once(sink, 'drain')으로 일시정지한 방식은 161MB였습니다 — 차이인 246MB는 말 그대로 쓰기 버퍼에 쌓인 데이터입니다.

// 올바름: write()가 false를 반환하면 일시정지, drain 후 재개
for await (const { value } of pipeline) {
  if (!sink.write(value)) {
    await once(sink, 'drain');
  }
}

두 가지 추가 경험: 스트림 체인을 수동으로 조립할 때는 각 스트림에 highWaterMark를 명시적으로 설정하세요(objectMode 기본값 16은 큰 객체에는 과합니다). 그리고 pipe() 대신 pipeline()(stream/promises)을 우선 사용하면 오류 전파와 정리를 맡길 수 있습니다.

다섯, 실측 비교: 네 가지 방식의 피크 메모리

방식 샘플 피크 RSS 소요 시간 적용
readFileSync + JSON.parse 186MB / 48만 건 612MB 1.3s 작은 파일, 랜덤 액세스
streamArray + for await + 느린 DB 쓰기(건당 0.5ms) 동일 104MB(일정) DB 속도에 따름 건별 적재·변환
streamArray + data 이벤트 쓰기, 배압 없음 동일 407MB 약 10s 반면교사
streamArray + write()/drain 배압 동일 161MB 약 10s 결과 저장/전송

환경: Node 22.13, /usr/bin/time -v로 Maximum resident set size 측정. 샘플은 합성 데이터이며 단일 실행 값입니다. 수치는 이 샘플에서의 자릿수 결론일 뿐 보편 상수가 아닙니다.

주목할 두 가지 수치: 첫 번째와 두 번째의 차이는 6배의 메모리이고, 대가는 "1.3초"가 "DB 속도를 따름"으로 바뀌는 것입니다. 세 번째와 네 번째의 차이는 2.5배로, 읽기 측만 스트리밍하고 쓰기 측 배압을 소홀히 하면 절반만 해결된다는 뜻입니다.

여섯, 진단: 배압이 실제로 작동하는지 확인하기

운영 환경의 메모리 문제는 감으로 해결할 수 없습니다. Tencent Cloud의 배압 진단 글이 실용적인 절차를 제시합니다:

  1. 핵심 스트림에 임시로 'pause'와 'resume' 로그를 겁니다. 대용량 링크에서 pause가 한 번도 나오지 않는다면 어딘가 데이터를 메모리에 쌓고 있다고 단정할 수 있습니다;
  2. writable.writableLength(쓰기 버퍼 바이트 수)를 확인합니다. 계속 증가한다면 소화되지 않는 것입니다;
  3. process.memoryUsage()로 RSS를 주기 샘플링해 곡선을 그리고, "상승형"(축적)과 "톱니형 안정"(정상 회수)을 구분합니다.

for await에서는 pause와 resume 로그가 반드시 교차로 나타납니다. 전혀 나오지 않는다면 data 리스너 혼입이나 await 누락을 의심하세요.

일곱, 스트리밍이 필요 없는 때

스트리밍이 기본 답은 아닙니다. 수십 MB 이내에서 키 기반 랜덤 액세스가 필요하면 JSON.parse 한 번이 오히려 간편합니다. 브라우저에서 큰 파일을 여는 것은 별개의 문제 영역이며, 큰 JSON 파일 여는 법에서 뷰어 선택 사다리를 다룹니다. 스트리밍 파싱의 적용 경계는 명확합니다:

  • 최상위가 배열(또는 JSONL로 행 분할 가능)이고 소비가 순차 처리이며 앞 내용을 다시 참조할 필요가 없음;
  • 파일 크기가 통제 불가이거나 힙 여유를 크게 초과하여, 한 번의 임포트로 메모리를 두 배로 만들 수 없음;
  • 소비자에게 자연스러운 속도 차(DB 쓰기, 하위 API 호출)가 있어 전속력 주입이 아닌 배압이 필요.

최상위 구조가 불규칙하면 먼저 JSON 파싱·포맷팅 도구에서 구조를 확인한 뒤 읽는 방식을 고르세요. 명령줄 처리 경로는 jq로 큰 JSON 다루기에서, jq --stream과 streamArray는 같은 발상의 서로 다른 런타임 구현입니다.

자주 묻는 질문

stream-json은 JSON.parse보다 얼마나 느린가요?

순수 파싱 속도는 JSON.parse가 빠릅니다: 186MB 샘플 기준 1.3초 대비, 쓰기 지연 없는 streamArray는 약 7초(토큰 파싱 + 레코드별 객체 구축 비용). 스트리밍의 이득은 전부 메모리 측에 있습니다: 피크가 612MB에서 104MB로. 임포트 작업의 병목은 어차피 DB 쓰기이므로 몇 초의 파싱 비용으로 6배의 메모리 여유를 사는 것이 보통은 합리적인 거래입니다. 밀리초급 API 응답 안에서는 부적합합니다.

for await의 배압과 수동 pause/resume은 같은 것인가요?

의미상 동등합니다: for await는 루프 본문이 미완료인 동안 읽기 스트림을 자동 일시정지하며, 이는 write()가 false를 반환할 때 pause()를, drain에서 resume()를 호출하는 것과 같습니다. 차이는 언어 메커니즘에 위임되어 누락되지 않는 점이고, 수동 구현은 한 곳만 놓쳐도 체인 전체의 배압이 끊깁니다.

최상위가 배열이 아니라 하나의 거대한 객체라면?

stream-json은 streamObject()(키별 발행)와 Pick 필터(지정된 하위 트리만 파싱)를 제공합니다. 몇 개 필드만 필요하다면 Pick과 JSONPath로 전체 객체 그래프를 필요한 하위 그래프로 줄일 수 있습니다. 다중 문서 혼합(JSON Lines, JSON Seq)은 먼저 행으로 분할해 행 단위 독립 JSON으로 처리하는 것을 권합니다.

결과를 JSONL로 기록하거나 하류로 전달하려면?

쓰기 측도 같은 배압 문제입니다: fs.createWriteStream이나 http.request는 write() 반환값을 확인하고 false이면 await once(stream, 'drain')을 기다리거나, 쓰기 스트림을 pipeline()에 연결해 Node에 관리시킵니다. 검증은 실행 후 RSS 곡선이 안정적인지, writableLength가 지속 증가하지 않는지 확인하는 것으로 충분합니다.

임포트 작업에 빠르게 메모리 모니터링을 추가하려면?

최소 구성은 100ms마다 process.memoryUsage().rss를 배열에 수집하고 종료 시 최댓값 출력입니다. 더 정확하게는 /usr/bin/time -v node task.js로 Maximum resident set size를 직접 확인하세요. 컨테이너에서는 경고선을 메모리 한도의 70%로 설정해 GC 여유를 남겨둡니다.

참고 자료

관련 도구

관련 문서

jq로 다루는 대용량 JSON: -s가 메모리를 터뜨리는 이유와 스트리밍 작성법

수백 MB짜리 JSON 로그를 jq -s로 집계하면 시스템에 의해 종료되지만, reduce inputs로 바꾸면 같은 통계를 몇 MB의 메모리로 처리할 수 있습니다. 220MB, 200만 행 샘플로 두 방식의 실행 시간과 메모리 피크를 실측하고, -s와 전체 파싱이 메모리를 잡아먹는 메커니즘, JSONL 행 단위 처리의 정석, --stream 경로 이벤트, 그리고 -n --stream이 조용히 빈 출력으로 끝나는 함정 등 세 가지 실제 함정을 설명합니다.

심화약 6분 소요2026-11-12 업데이트

대용량 JSON 파일이 안 열릴 때: 크기별 도구 고르기

수십 MB짜리 JSON 내보내기는 텍스트 편집기와 온라인 도구에서 자주 멈추지만, 파싱 자체는 수백 밀리초면 끝납니다. 45MB·50만 레코드 샘플로 각 단계의 시간과 메모리를 실측해 진짜 비용이 줄 수와 노드 수임을 보이고, 파일 크기별 도구 선택표를 제시합니다. 온라인 보기, 명령줄 추출, 스트리밍 처리, 데스크톱 앱의 역할 구분까지 정리했습니다.

중급약 6분 소요2026-11-07 업데이트