Skip to content

CSV enrichment

timeglyph csv reads a CSV and writes it back with timestamp columns rendered to human-readable UTC. It works two ways, which can be combined.

Auto-detect (default)

With no other options, every numeric column is examined and, when it confidently looks like one timestamp format, a rendered column is appended to its right:

$ timeglyph csv events.csv
name,ts,ts_unix,count
a,1577836800,2020-01-01T00:00:00Z,5

Auto-detection is deliberately conservative — it only enriches a column when:

  • every non-empty cell is an integer at or above ~10⁸ (so counts, ids, and years are skipped — count above is left untouched), and
  • the cells share one confident, in-window, non-sentinel top interpretation.

If a column is ambiguous, it is left alone rather than guessed — consistent with the engine's "never a single verdict" stance.

Explicit conversion

Convert a specific column under a chosen format with --convert COLUMN:FORMAT (repeatable):

$ timeglyph csv files.csv --convert created:filetime --convert modified:unix
id,created,created_filetime,modified,modified_unix
1,132223104000000000,2020-01-01T00:00:00Z,1577836800,2020-01-01T00:00:00Z

The new column is named <column>_<format> and sits immediately to the right of its source.

Replace in place

Use --replace to overwrite the source column instead of adding one:

$ timeglyph csv files.csv --convert created:filetime --replace
id,created
1,2020-01-01T00:00:00Z

Options

Option Effect
(none) auto-detect numeric timestamp columns
--convert COL:FMT convert column COL under format FMT (repeatable)
--auto force auto-detect in addition to --convert
--replace overwrite the source column instead of adding one
-o, --output FILE write to FILE (default: stdout)
path of - read the CSV from stdin

See also