sample
Randomly selects rows from a data file using reservoir sampling. Either --limit (-n) or --percent is required; without them the command exits with 1.
Write with --output. A trailing path is not a positional argument.
# Sample fixed number of rows
undatum sample data.csv --limit 1000 --output output.csv
# Sample by percentage
undatum sample data.jsonl --percent 10 --output output.jsonl
# Sample among the rows matching a SQL condition
undatum sample data.csv --limit 2 --where "amount > 50"
Reference
Reads: any readable format · Writes: any writable format; CSV/TSV/JSON/JSON Lines on stdout · Memory: bounded: --limit rows (reservoir); --percent counts the file first · Engines: auto, duckdb, python
undatum sample [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 sample. | |
--percent FLOAT | Percentage of rows to sample (0-100). | |
-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'). | |
-e, --engine [auto|duckdb|python] | Processing engine: auto (default), duckdb, or python. | |
--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. | |
--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 |
--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.