sq/cli/output/jsonw/README.md

Package jsonw

Package jsonw implements JSON output writers.

Note that there are three implementations of output.RecordWriter.

• NewStdRecordWriter returns a writer that outputs in "standard" JSON.
• NewArrayRecordWriter outputs each record on its own line as an element of a JSON array.
• NewObjectRecordWriter outputs each record as a JSON object on its own line.

These RecordWriters correspond to the --json, --jsona, and --jsonl flags (where jsonl means "JSON Lines"). There are also other writer implementations, such as an output.ErrorWriter and an output.MetadataWriter.

Standard JSON --json:

[
  {
    "actor_id": 1,
    "first_name": "PENELOPE",
    "last_name": "GUINESS",
    "last_update": "2020-06-11T02:50:54Z"
  },
  {
    "actor_id": 2,
    "first_name": "NICK",
    "last_name": "WAHLBERG",
    "last_update": "2020-06-11T02:50:54Z"
  }
]

JSON Array --jsona:

[1, "PENELOPE", "GUINESS", "2020-06-11T02:50:54Z"]
[2, "NICK", "WAHLBERG", "2020-06-11T02:50:54Z"]

Object aka JSON Lines --jsonl:

{"actor_id": 1, "first_name": "PENELOPE", "last_name": "GUINESS", "last_update": "2020-06-11T02:50:54Z"}
{"actor_id": 2, "first_name": "NICK", "last_name": "WAHLBERG", "last_update": "2020-06-11T02:50:54Z"}

Notes

At the time of development there was not a JSON encoder library available that provided the functionality that sq required. These requirements:

• Optional colorization
• Optional pretty-printing (indentation, spacing)
• Preservation of the order of record fields (columns).

For the RecordWriter implementations, given the known "flat" structure of a record, it was relatively straightforward to create custom writers for each type of JSON output.

For general-purpose JSON output (such as metadata output), it was necessary to modify an existing JSON library to provide colorization (and also on-the-fly indentation). After benchmarking, the segmentio.io encoder was selected as the base library. Rather than a separate forked project (which probably would not make sense to ever merge with its parent project), the modified encoder is found in jsonw/internal/jcolorenc.