JSONL 파일 마스터하기: 구조, 사용 사례 및 주요 장점

JSONL 파일은 한 줄에 하나의 완전한 JSON 값을 가집니다. 공식 문서에서는 이를 "줄바꿈으로 구분된 JSON이라고도 하는 JSON Lines 텍스트 형식"이라고 부릅니다. 이 단 하나의 규칙 덕분에 스트리밍이 원활하게 이루어지고, 부분 읽기에서도 손상되지 않으며, 스프레드시트에서 열리지 않는 것입니다.

JSONL 파일이란 무엇인가요?

JSON Lines는 레코드를 위한 텍스트 형식입니다. 사양서에서는 이를 "한 번에 하나의 레코드씩 처리할 수 있는 구조화된 데이터를 저장하기에 편리한 형식"이라고 설명합니다.

이 문서는 이 형식이 어디에 적합한지 명확히 밝히고 있습니다. 이 형식은 "유닉스 스타일의 텍스트 처리 도구 및 셸 파이프라인과 잘 작동한다"고 설명하며, "로그 파일에 아주 적합한 형식"이라는 내용도 덧붙여져 있습니다. 또한 "협력 프로세스 간에 메시지를 전달하기 위한 유연한 형식"으로도 설명됩니다.

일반 JSON과의 차이점이 핵심입니다. 100만 개의 레코드가 담긴 JSON 배열은 하나의 값입니다. 즉, 구조가 완성되려면 판독기가 전체를 모두 읽어야 합니다. 반면 100만 개의 레코드가 담긴 JSONL 파일은 100만 개의 값이며, 각 줄이 독립적으로 존재합니다.

이와 밀접하게 관련된 두 번째 사양이 있습니다. NDJSON 사양은 이에 대해 "현재 스트림 프로토콜 내에서 JSON 텍스트 인스턴스를 전송하기 위한 표준은 없다"고 직접적으로 밝히고 있습니다. 명시된 사용 사례는 "TCP 또는 UNIX Pipes와 같은 스트리밍 프로토콜을 통해 여러 JSON 텍스트 인스턴스를 전달하는 것"입니다.

JSONL 파일의 구조

세 가지 요구사항

JSON Lines 문서에는 정확히 세 가지가 나열되어 있습니다. 첫 번째는 UTF-8 인코딩입니다. 여기에는 JSON 자체에서 차용한 경고 사항이 포함되어 있습니다. "JSON 표준과 마찬가지로 바이트 순서 표식(U+FEFF)을 포함해서는 안 된다"는 점입니다.

두 번째는 각 줄이 유효한 JSON 값이어야 한다는 점입니다. 해당 페이지에서는 "가장 일반적인 값은 객체나 배열이겠지만, 어떤 JSON 값도 허용된다"고 설명합니다. 그러면서 사람들이 흔히 실수하는 예외적인 상황을 언급합니다. "null은 유효한 값인 반면, 빈 줄은 유효하지 않다"는 것입니다.

세 번째는 줄 끝 종결자가 \n이어야 한다는 점입니다. Windows의 줄 바꿈도 여전히 작동합니다. 그 이유는 기계적인 부분에 있습니다. "JSON 값을 파싱할 때 주변의 공백은 암묵적으로 무시되므로 \r\n도 지원된다는 의미"이기 때문입니다.

줄 내부에서 나타나서는 안 되는 것

이것이 바로 이 형식을 작동하게 만드는 제약 조건입니다. NDJSON 사양에서는 이를 필수 요구사항으로 규정하고 있습니다. "JSON 텍스트에는 줄바꿈이나 캐리지 리턴이 포함되어서는 안 된다"는 점입니다.

일반적인 JSON 값은 들여쓰기를 사용하여 여러 줄에 걸쳐 작성할 수 있습니다. 하지만 줄바꿈으로 구분되는 파일에서는 줄바꿈이 레코드 구분자 역할을 하기 때문에 그렇게 할 수 없습니다. 모든 레코드는 반드시 하나의 물리적인 줄에 작성되어야 합니다.

마지막 줄과 빈 줄

두 사양 사이에는 두 가지 세부 사항이 다르며, 파일이 거부될 때 두 가지 모두 중요하게 작용합니다.

마지막 줄바꿈을 예로 들어보겠습니다. JSON Lines에서는 "파일의 마지막 JSON 값 뒤에 줄 끝 종결자를 포함하는 것을 강력히 권장하지만 필수는 아니다"라고 명시하고 있습니다.

빈 줄에 대해서는 두 사양이 서로 다릅니다. JSON Lines는 엄격합니다. 빈 줄은 유효한 값이 아닙니다. 반면 NDJSON은 관대하여 "파서가 빈 줄을 자동으로 무시할 수 있다"고 허용하면서도 "이러한 동작은 반드시 문서화되어야 한다"고 요구합니다.

확장자 및 미디어 유형

명명법 또한 나뉩니다. JSON Lines는 파일이 "파일 확장자 .jsonl로 저장될 수 있다"고 명시합니다. 미디어 유형에 대해서는 "MIME 유형이 application/jsonl일 수 있지만, 이는 아직 표준화되지 않았다"고 설명합니다. 반면 NDJSON은 미디어 유형이 "application/x-ndjson이어야 하며" 확장자는 ".ndjson이어야 한다"고 규정합니다.

압축의 경우, JSON Lines는 스트림 압축기를 권장합니다. "공간을 절약하기 위해 gzip 또는 bzip2가 권장되며, 그 결과 .jsonl.gz 또는 .jsonl.bz2 파일이 생성된다"고 설명합니다.

오류 메시지를 읽을 때 알아두면 좋은 작은 관례가 하나 있습니다. 텍스트 편집기에서는 첫 번째 줄을 "1행"이라고 부릅니다. 이 문서는 이를 확장하여 "JSON Lines 파일의 첫 번째 값 역시 '값 1'로 불러야 한다"고 덧붙입니다.

JSONL의 용도

일반적으로 다음과 같은 네 가지 상황 중 하나에서 .jsonl 파일을 접하게 됩니다.

로그 및 이벤트 파일. 이 형식의 자체 문서에서도 로그 파일을 언급하고 있는데, 그 이유는 작성자가 기존 내용을 다시 쓰지 않고도 한 번에 한 줄씩 추가할 수 있기 때문입니다.

웨어하우스 로드. Google의 BigQuery 문서는 이 형식의 공식적인 위상을 보여주는 좋은 예입니다. 이 서비스는 "Cloud Storage에서 줄바꿈으로 구분된 JSON(ndJSON) 데이터"를 로드하는 것을 지원하며, 파일 형식 선택기에는 이 옵션이 "JSONL(줄바꿈으로 구분된 JSON)"로 표시되어 있습니다.

중첩된 레코드의 API 내보내기. 열로 깔끔하게 평탄화되지 않는 데이터는 줄마다 중첩 구조를 유지합니다. 품목 수가 가변적인 주문 내역이 대표적인 사례입니다.

머신러닝 데이터셋. 학습 루프가 레코드를 한 번에 하나씩 읽기 때문에, 학습 및 평가 세트는 일반적으로 이 방식으로 배포됩니다.

공통적인 핵심은 스트리밍입니다. 파일이 점진적으로 생성되거나 점진적으로 소비될 때 이 형식은 당연한 선택이 됩니다.

JSONL vs JSON vs CSV 비교

	JSONL	JSON	CSV
파일 단위	줄당 하나의 값	전체 파일당 하나의 값	줄당 하나의 행
중첩 데이터	예, 레코드별	예	기본적으로 지원 안 함
레코드 추가	줄 추가	컨테이너 재작성	행 추가
부분 읽기 유용성	예	드묾	예
스프레드시트에서 열기	아니요	아니요	보통 가능
레코드 형태의 다양성	예	예	아니요, 열이 고정됨
편집기에서 사람이 읽을 수 있는지 여부	예, 각 레코드가 하나의 긴 줄로 표시됨	예, 들여쓰기 시 가능	예

가장 놀라운 부분은 밑에서 두 번째 행입니다. 동일한 JSONL 파일 내의 두 줄이 서로 다른 키를 가질 수 있습니다. 이것이 바로 이 형식에 유연성을 부여하는 요소이자, 단순하게 가져오기를 실행했을 때 열이 불규칙하게 어긋나는 원인이기도 합니다.

열 지향 바이너리 대안의 경우, Parquet 설명서에서 저장소 측면의 동일한 영역을 다룹니다. 가장 단순한 표 형식의 경우, TSV 분석에서 탭으로 구분된 텍스트를 다룹니다.

주요 장점

추가 전용 쓰기. 새로운 레코드는 새로운 줄이 됩니다. 파일의 이전 내용을 변경할 필요가 전혀 없습니다.

스트리밍 읽기. 소비자는 200만 번째 레코드가 작성되기 전에 첫 번째 레코드를 처리할 수 있습니다.

오류 허용성. 파일이 도중에 잘리더라도 마지막으로 완료된 줄까지는 여전히 읽을 수 있습니다. 반면 잘린 JSON 배열은 대개 전체를 읽을 수 없게 됩니다.

중첩 구조 유지. CSV라면 평탄화해야 했을 구조가 각 레코드 내부에서 그대로 유지됩니다.

셸 친화적. 줄 지향 파일은 줄 지향 도구와 함께 작동하기 때문에, 문서에서는 유닉스 스타일의 텍스트 처리 및 셸 파이프라인을 장점으로 꼽습니다.

웨어하우스 지원. BigQuery 문서에는 다음과 같이 강제하는 규칙이 명시되어 있습니다. "각 JSON 객체는 파일의 별도 줄에 있어야 합니다."

JSONL의 한계

이 형식은 전송과 추가 문제를 해결해 줍니다. 하지만 콘텐츠에 대해 가질 수 있는 의문점은 해결해 주지 못합니다.

압축은 대가 없이 얻을 수 있는 이득이라기보다는 실질적인 트레이드오프 관계에 가깝습니다. BigQuery 문서는 그 비용에 대해 단호하게 지적합니다. "gzip 압축을 사용하는 경우, BigQuery는 데이터를 병렬로 읽을 수 없습니다." 또한 "압축된 JSON 데이터를 BigQuery에 로드하는 것은 압축되지 않은 데이터를 로드하는 것보다 느립니다"라고 덧붙입니다. 이 형식의 자체 페이지에서는 공간 절약을 위해 gzip을 권장합니다. 두 가지 모두 사실이며, 서로 상반되는 방향을 가리키고 있습니다.

또한 장황합니다. 모든 줄마다 모든 키 이름이 반복되므로, 레코드 세트가 넓을 경우 동일한 데이터를 열 지향 형식으로 저장할 때보다 크기가 훨씬 커집니다.

그리고 일관성에 대해서는 아무것도 보장하지 않습니다. 서로 다른 형태의 레코드가 허용되므로, 파일 중간부터 특정 필드가 소리 없이 사라지더라도 아무런 오류가 발생하지 않습니다.

엔지니어가 아닌 경우 JSONL 파일을 다루는 방법

이것이 실무에서의 격차입니다. 비즈니스 도구는 행과 열을 요구하지만, .jsonl 파일은 CSV처럼 열리지 않습니다.

실용적인 방법은 변환 단계를 거치는 것입니다. 파일을 생성한 사람에게 필요한 필드만 평탄화한 CSV 또는 Excel 추출본을 요청하세요. 또는 JSON을 지원하는 도구를 사용하여 직접 평탄화할 수도 있습니다. 이 과정에서 중첩 구조는 사라지지만, 분석에 사용할 필드를 결정하고 나면 대개 이는 문제가 되지 않습니다.

그 이후부터는 일반적인 분석 작업입니다. Powerdrill Bloom의 요금제 페이지에는 Excel, CSV, PDF 및 문서 업로드가 나열되어 있으므로, 평탄화된 추출본을 바로 업로드할 수 있습니다. 쿼리를 작성하는 대신 자연어로 질문을 던질 수 있습니다. CSV AI assistant가 이 경로를 지원하며, 데이터를 내보내는 것보다 소스에서 직접 가져오는 것이 더 나은 경우에는 data connectors를 활용할 수 있습니다.

기억해야 할 차이점은 이것이 여러분의 작업 단계 이전에서 결정된 전송 방식이라는 점입니다. 파일이 여러분의 책상에 도달한 후 다른 형식으로 변환하는 것은 임시방편이 아니라 정상적인 과정입니다.

결론

JSONL은 한 줄에 하나의 완전한 JSON 값을 가지며 값 내부에는 줄바꿈이 없어야 한다는 단 하나의 규칙을 가진 텍스트 형식입니다. 이 규칙 덕분에 추가 가능성, 스트리밍, 부분 읽기 허용성을 확보할 수 있으며, 이것이 로그와 웨어하우스 로드에서 이 형식을 기본으로 사용하는 이유입니다.

하지만 이 형식이 테이블을 제공하는 것은 아닙니다. 파이프라인이 아니라 해답이 필요한 사람에게 파일이 도달하는 순간, 유용한 다음 단계는 평탄화된 추출본을 만들고 질문을 던지는 것입니다.

현재 그러한 상황에 처해 있다면, 변환된 파일로 Powerdrill Bloom을 사용해 보고, 먼저 차트로 변환하는 작업부터 시작해 보세요.

자주 묻는 질문

JSONL 파일은 어디에 사용되나요?

로그 파일, 이벤트 내보내기, 웨어하우스 로드, 머신러닝 데이터셋과 같은 레코드 스트림에 사용됩니다. 이 형식의 문서에서는 로그 파일과 셸 파이프라인을 구체적으로 언급하고 있습니다. 공통점은 레코드를 한 번에 하나씩 쓰거나 읽는다는 것입니다.

JSONL과 NDJSON의 차이점은 무엇인가요?

이들은 동일한 개념을 서로 다른 문서로 설명합니다. JSON Lines는 .jsonl 확장자를 사용하며 application/jsonl이 아직 표준화되지 않았다고 언급합니다. 반면 NDJSON은 .ndjson 및 application/x-ndjson을 지정하고, 파서가 빈 줄을 무시할 수 있도록 허용합니다.

JSONL 파일을 Excel에서 열 수 있나요?

더블 클릭해서 열 수는 없습니다. 각 줄이 셀 행이 아니라 JSON 값이기 때문입니다. 일반적인 방법은 필요한 필드를 먼저 CSV나 Excel로 평탄화하거나, 해당 형식을 직접 읽을 수 있는 도구를 사용하는 것입니다.

JSONL에서 레코드가 여러 줄에 걸쳐 있을 수 없는 이유는 무엇인가요?

줄바꿈 문자가 레코드 구분자이기 때문입니다. NDJSON 사양에서는 "JSON 텍스트에는 줄바꿈이나 캐리지 리턴이 포함되어서는 안 된다"고 명시하고 있습니다. 따라서 보기 좋게 서식이 지정된 JSON은 레코드당 한 줄로 축소되어야 합니다.

JSONL 파일에서 빈 줄이 허용되나요?

두 사양이 서로 다릅니다. JSON Lines는 "null은 유효한 값인 반면, 빈 줄은 유효하지 않다"고 명시합니다. 반면 NDJSON은 해당 동작이 문서화되어 있다면 파서가 빈 줄을 자동으로 무시할 수 있도록 허용합니다.