Освоение файлов JSONL: структура, варианты использования и ключевые преимущества

Файл JSONL содержит ровно одно полное значение JSON на строку. Официальная документация называет его «текстовым форматом JSON Lines, также известным как JSON с разделением новыми строками». Это единственное правило объясняет, почему он отлично подходит для потоковой передачи, почему он сохраняет целостность при частичном чтении и почему его невозможно открыть в табличном процессоре.

Что такое файл JSONL?

JSON Lines — это текстовый формат для записей. Спецификация описывает его как «удобный формат для хранения структурированных данных, которые могут обрабатываться по одной записи за раз».

В документации четко указана сфера его применения. Он «хорошо работает с инструментами обработки текста в стиле unix и конвейерами оболочки», а также на странице добавляется, что «это отличный формат для файлов журналов». Кроме того, он описывается как «гибкий формат для передачи сообщений между взаимодействующими процессами».

Суть заключается в контрасте с обычным JSON. Массив JSON из миллиона записей представляет собой одно значение: парсер должен прочитать его целиком, прежде чем структура будет сформирована. Файл JSONL из миллиона записей — это миллион значений, где каждая строка существует независимо.

Существует вторая, тесно связанная спецификация. Спецификация NDJSON прямо заявляет об этом: «в настоящее время не существует стандарта для передачи экземпляров текста JSON внутри протокола потоковой передачи». Заявленный сценарий ее использования — «доставка нескольких экземпляров текста JSON через протоколы потоковой передачи, такие как TCP или UNIX Pipes».

Как устроен файл JSONL

Три требования

Документация JSON Lines перечисляет ровно три требования. Первое — это кодировка UTF-8. Она содержит оговорку, заимствованную из самого JSON: «как и в стандарте JSON, маркер последовательности байтов (U+FEFF) НЕ должен быть включен».

Второе заключается в том, что каждая строка должна быть валидным значением JSON. На странице отмечается, что «наиболее распространенными значениями будут объекты или массивы, но допускается любое значение JSON». Затем приводится пограничный случай, на котором многие спотыкаются: «null является валидным значением, а пустая строка — нет».

Третье заключается в том, что символом конца строки является \n. Переносы строк Windows по-прежнему работают. Причина носит технический характер: «это означает, что \r\n также поддерживается, поскольку окружающие пробельные символы неявно игнорируются при парсинге значений JSON».

Что не должно находиться внутри строки

Это ограничение обеспечивает работоспособность формата. Спецификация 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 в одной из четырех ситуаций.

Файлы журналов и событий. Собственная документация формата упоминает файлы журналов, и причина в том, что программа записи может добавлять по одной строке за раз, ничего не перезаписывая.

Загрузка в хранилища данных. Документация BigQuery от Google — хороший пример официального статуса этого формата. Она поддерживает загрузку «данных JSON с разделением новыми строками (ndJSON) из Cloud Storage», а в меню выбора формата файлов этот вариант указан как «JSONL (Newline delimited JSON)».

Экспорт вложенных записей через API. Данные, которые невозможно аккуратно преобразовать в плоскую таблицу с колонками, сохраняют свою вложенность в каждой строке. Классический пример — строки заказов с переменным количеством позиций.

Наборы данных для машинного обучения. Обучающие и тестовые выборки часто распространяются в таком виде, поскольку цикл обучения считывает записи по одной за раз.

Общим связующим звеном является потоковая передача. Этот формат становится очевидным выбором, когда файл создается или считывается инкрементально.

JSONL против JSON против CSV

	JSONL	JSON	CSV
Единица файла	Одно значение на строку	Одно значение на весь файл	Одна строка на строку
Вложенные данные	Да, для каждой записи	Да	Изначально не поддерживается
Добавление записи	Добавить строку	Переписать весь контейнер	Добавить строку
Полезность частичного чтения	Да	Редко	Да
Открывается в табличном процессоре	Нет	Нет	Обычно да
Записи могут отличаться по структуре	Да	Да	Нет, колонки фиксированы
Удобочитаемость для человека в редакторе	Да, каждая запись в одну длинную строку	Да, при наличии отступов	Да

Строка, которая вызывает больше всего удивления, — предпоследняя. Две строки в одном и том же файле JSONL могут содержать разные ключи. Именно это делает формат гибким и именно из-за этого при простом импорте получаются неровные колонки.

Что касается колоночной бинарной альтернативы, в руководстве по Parquet эта же тема рассматривается со стороны хранения данных. Для простейшего табличного случая в разборе TSV описывается текст с разделением табуляцией.

Ключевые преимущества

Запись только в конец (append-only). Новая запись — это новая строка. Ничего из того, что было записано в файл ранее, менять не нужно.

Потоковое чтение. Потребитель может обработать первую запись еще до того, как будет записана двухмиллионная.

Отказоустойчивость. Усеченный файл все равно можно прочитать вплоть до последней полной строки. Усеченный массив JSON, как правило, становится полностью нечитаемым.

Сохранение вложенности. Структура, которую в CSV пришлось бы преобразовывать в плоский вид, остается нетронутой внутри каждой записи.

Удобство работы в консоли. Документация отмечает совместимость с обработкой текста в стиле unix и конвейерами оболочки, поскольку построчный файл отлично работает с построчными инструментами.

Поддержка хранилищами данных. Документация 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 (pretty-printed) должен быть свернут в одну строку для каждой записи.

Допускается ли пустая строка в файле JSONL?

Две спецификации различаются. В JSON Lines указано, что «null является валидным значением, а пустая строка — нет». NDJSON позволяет парсеру молча игнорировать пустые строки при условии, что это поведение задокументировано.