Skip to content
Tabular data visualization engine

vizb merge

Combine multiple dataset JSON files into a single dataset JSON file. Supports tag-based deep merging for history tracking.

Usage

Section titled “Usage”
Terminal window
vizb merge [files/directories...] [flags]

Input Types

Section titled “Input Types”
  • JSON files: one or more .json files generated by vizb <target-file> -o file.json
  • Directories: scans for all .json files in the directory
  • Mix: combine files and directories in a single command
Terminal window
# Specific files
vizb merge run1.json run2.json -o merged.json


# Entire directory
vizb merge ./results/ -o all.json


# Mix files and directories
vizb merge ./old_results/ latest.json -o comparison.json

Flags

Section titled “Flags”
Flag Short Default Description
--output -o (stdout) Output file path (always JSON)
--tag-axis -A n Where to inject tag: n (name), x (xAxis), y (yAxis), z (zAxis)

Outer Merge (Untagged)

Section titled “Outer Merge (Untagged)”

When merging dataset without tags, vizb concatenates all entries. Same-name datasets are deduplicated — newer timestamp wins; if timestamps are equal or absent, first occurrence wins.

Terminal window
vizb bench-a.txt -o a.json -n "Sort"
vizb bench-b.txt -o b.json -n "Hash"
vizb merge a.json b.json -o combined.json

Result: both dataset groups in one file.

Inner Merge (Tagged)

Section titled “Inner Merge (Tagged)”

When dataset share the same name but have different tags, vizb deep-merges them:

Terminal window
# Tag individual runs
vizb bench-v1.txt -o v1.json --tag v1 -n "Sort"
vizb bench-v2.txt -o v2.json --tag v2 -n "Sort"


# Merge
vizb merge v1.json v2.json -o comparison.json

The merge process:

  1. Same-tag replacement — same name + tag → replace only that tag’s data points on the inject axis (-A); older versions and history[] entries for other tags are kept. Newer timestamp wins for top-level metadata.
  2. Deep merge — different tags → single dataset with chronological data
  3. Legacy — untagged entries prepended before tagged data
Terminal window
# Re-run v1.8.0 into an accumulated merged.json — v1.3.0/v1.7.x data is preserved
vizb merge bench-v1.8.0.json merged.json -A x -o merged.json

Tag-Axis

Section titled “Tag-Axis”

Control which dimension receives the tag annotation:

Terminal window
# Inject tag into X-axis (versions on X-axis)
vizb merge v1.json v2.json -A x -o comparison.json
Value Target
n Name dimension (default)
x X-axis — use for version comparison
y Y-axis
z Z-axis — depth layer of a 3D chart (needs existing x + y)

If the inject dimension is missing from axes, merge adds it automatically (in canonical name / x / y / z order) so tag values appear in the chart.