Merge files

Merging combines several JSON or NDJSON files into one document, so you can search, query, and chart them together, for example a day’s worth of log files. The files themselves are not changed: JSON Digger writes the merged document to its cache folder and opens it read-only.

Merge files into one document

Choose File → Merge Files…, or run it from the command palette. You can also drop two or more JSON files, or two or more NDJSON files, on the window and select Merge….
Select Add files… to add files, if the list does not have them yet. Add at least two.
Put the files in order with Move up and Move down. The merged document follows the list from top to bottom. Remove takes a file off the list.
Choose the Output: NDJSON records or One JSON array. See Output formats.
Select Merge.

The list accepts JSON and NDJSON files, and .gz and .zst archives that contain them. Each row shows the file’s format and size. A file that cannot be merged, such as an empty file or a file that is not UTF-8, shows the reason in red, and Merge stays unavailable until you remove it. Problems further into a file are found when the merge runs.

Output formats

NDJSON records writes one record per line. One JSON array writes a single array with one element per record. When every file in the list is JSON, the dialog starts with One JSON array; otherwise it starts with NDJSON records.

Each file contributes to the output as follows:

File	NDJSON records	One JSON array
NDJSON	Each line becomes a record. Lines that are not valid JSON are kept and show as invalid records.	Each line becomes an element. A line that is not valid JSON stops the merge.
JSON whose root is an array	One record per element, written on one line. With Split JSON arrays into one record per element off, the whole array becomes one record.	Each element becomes an element of the merged array.
JSON with another root	The value becomes one record, written on one line.	Added as one element if Add a JSON file that is not an array as one element is on; otherwise the merge stops with an error.

Split JSON arrays into one record per element is on by default, and Add a JSON file that is not an array as one element is off by default.

Progress and errors

While the merge runs, a notice shows the progress, for example Merging 3 files… 40%, and says decompressing a source… while it unpacks an archive. Select Cancel on the notice to stop; nothing is opened.

Before it starts, JSON Digger checks that the drive of its cache folder has room for the merged document, and stops if it does not.

If a file turns out to be invalid during the merge, the dialog stays open and shows the file, the problem, and its position, for example orders.json: not a JSON array (turn on wrapping to add it as one element) at byte 0. Fix or remove the file, or change the options, and select Merge again.

The merged document

The merged document opens in a new tab named Merged (N files). Hover over the tab to see the list of files. In the Properties panel, the Document section shows the output format, the size, and each file with its number of records.

The views of the merged document are those of its output format: an NDJSON merge opens in the Tree, NDJSON, Table, and Chart views, and a JSON array in all the JSON views. Search, queries, and SQL work as on any file.

The merged document is a copy: later changes to the files do not reach it. It is read-only, and it is deleted when you close its tab. It is not reopened with your session.

Save the merged document

To keep the merged document, press Ctrl+Shift+S or choose File → Save As…, then open the saved file to work with it like any other. Editing is not available on the merged document itself: “Merged documents open read-only. Use Save As to keep the merged file.”

Save As writes the merged document as it is, every record or element included, and suggests the name merged.ndjson or merged.json.