`frequency`

Calculates frequency distribution for specified fields. --fields is required.

Default stdout format is CSV. Use --format-out json (or an --output path ending in .json) for JSON.

undatum frequency --fields category data.jsonl
undatum frequency --fields status,region data.csv
undatum frequency --fields city --format-out json --output freq.json data.csv
undatum frequency --fields city workbook.xlsx --table Sheet2
undatum frequency --fields capital_city.lat nested.jsonl --flatten-nested

Reference

Reads: any readable format · Writes: any writable format; CSV/TSV/JSON/JSON Lines on stdout · Memory: grows with the number of distinct values · Engines: auto, duckdb, python

undatum frequency [OPTIONS] INPUT_FILE

Argument	Description
`INPUT_FILE`	Path to input file. (required)

Option	Description	Default
`-o`, `--output` TEXT	Optional output file path. If not specified, prints to stdout.
`-f`, `--fields` TEXT	Comma-separated list of field names to calculate frequency for.
`-d`, `--delimiter` TEXT	CSV delimiter character (auto-detected when omitted).
`--quotechar` TEXT	CSV quote character (iterabledata default '"' when omitted).
`--encoding` TEXT	File encoding (e.g., 'utf8', 'latin1').
`--verbose` / `--no-verbose`	Enable verbose logging output.	`--no-verbose`
`-F`, `--format-in` TEXT	Override file type detection (e.g., 'csv', 'jsonl', 'xlsx').
`--start-page` INTEGER	Sheet index (0-based) for Excel files.	`0`
`--table`, `--sheet` TEXT	Table or sheet name for multi-table sources (Excel, SQLite, lakehouse).
`--trust`	Acknowledge pickle deserialization risk when reading pickle sources.
`--on-error` TEXT	Parse-error policy: raise (default), skip, or warn.
`--error-log` TEXT	Append parse errors as JSONL (use with --on-error skip or warn).
`--flatten-nested`	Unfold nested dict / array-of-dict fields into dotted paths (e.g. city.lat).
`--max-nested-depth` INTEGER	With --flatten-nested, maximum nest depth to unfold (engine default 5).
`--keep-nested-parents` / `--no-keep-nested-parents`	With --flatten-nested, keep parent dict/array fields alongside dotted children.	`--keep-nested-parents`
`-e`, `--engine` [auto\|duckdb\|python]	Processing engine: auto (default), duckdb, or python.
`--threads` INTEGER	Worker processes for Python/iterable-engine frequency counting. Omit for sequential. For DuckDB, use --duckdb-threads.
`--duckdb-threads` INTEGER	Number of threads for DuckDB engine.
`--duckdb-memory` TEXT	Memory limit for DuckDB (e.g., '4GB', '512MB').
`--duckdb-temp-dir` TEXT	Temporary directory for DuckDB.
`--filter`, `--filter-expr` TEXT	Filter expression to apply before counting frequencies.
`-O`, `--format-out` TEXT	Output format: 'csv' (default) or 'json' (also inferred from --output).
`--json`	Print the result as one JSON document (same as --format-out json).

Deprecated spellings (removed in 2.0): --filetype → --format-in.

Reference​

Reference