head

Extracts the first N rows from a data file. Useful for quick data inspection.

Without --output, rows go to stdout in the input's text format (CSV in, CSV out; JSON Lines for binary inputs); -O/--format-out overrides it. With --output, the format follows the file extension. Use - as the input to read standard input.

# First 10 rows (default) on stdout, in the input format
undatum head data.csv

# Extract first 20 rows
undatum head data.jsonl --limit 20

# CSV in, JSON Lines out
undatum head data.csv -n 5 -O jsonl

# Save to file (not a positional path)
undatum head data.csv --limit 5 --output output.csv

# Named Excel sheet
undatum head workbook.xlsx --table Sheet2 --limit 5

# Nested JSONL: unfold dict fields onto dotted paths
undatum head nested.jsonl --flatten-nested --limit 5

# First 3 rows matching a SQL condition
undatum head data.csv -n 3 --where "status = 'active'"

Reference

Reads: any readable format · Writes: any writable format; CSV/TSV/JSON/JSON Lines on stdout · Memory: bounded: the first --limit rows · Engines: auto, duckdb, python

undatum head [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.
-n, --limit INTEGER	Number of rows to extract (default: 10).	10
-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 input file format detection (e.g., 'csv', 'jsonl').
--table, --sheet TEXT	Table or sheet name for multi-table sources (Excel, SQLite, lakehouse).
--start-page INTEGER	Sheet index (0-based) for Excel files.	0
--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.
--where TEXT	Keep records where this SQL condition is true (DuckDB syntax), e.g. "amount > 100 AND city = 'Berlin'". Text values are typed automatically.
-O, --format-out TEXT	Output format (e.g. csv, jsonl, parquet). Defaults to the --output extension, or to the input's text format on stdout.

Deprecated spellings (removed in 2.0): --n → --limit.

See also shared options.