Skip to content
Beta · version 0.8.1 · commands and the JSON format may still change.

Tabalyst Sample

Use tabalyst sample to create a smaller CSV without changing the source file.

Terminal window
tabalyst sample customers.csv --smart --rows 1000

This creates customers.sample.csv beside customers.csv.

  • Kept as is: header, column order, raw cell values and configured encoding.
  • Size: choose exactly one of --rows (fixed count) or --percent. stratified-balanced is the exception: it takes --per-value and its size follows from the data.
  • Safety: existing files are replaced only with --force; the source can never be overwritten.
MethodUse it whenReadings
smart (recommended)You need every value of the small columns, the extremes and the odd cases2 at most (1 with a current scan)
randomYou need a quick sample that keeps the proportions of the file1
stratifiedYou need a sample of a given size that keeps the proportions of one field, or of a few, with a row of each value2
stratified-balancedYou need up to N rows of each value, so the rare values are well represented1
first, lastYou only need the start or the end of the file1
mixedYou want the start, the end and a random draw of the rest in one sample2

--smart is short for --sample-method smart. The other methods are chosen with --sample-method.

  • Size: a percentage rounds up to the next whole row. A 100% sample contains every data record; a header-only CSV gives a header-only output.
  • Options: an option the chosen method does not read is an error (exit code 2), never silently ignored.
  • Validation: every CSV record is checked for header, quoting and field count.
  • Reading time: reading a large file can take minutes. See the smart sample for the estimate and confirmation.

Use -o for the complete output filename when sampling one source:

Terminal window
tabalyst sample customers.csv --sample-method first --rows 100 -o test.csv

Use -d to put samples from one or more sources in a directory. Wildcards are resolved by Tabalyst, including on shells that do not expand them:

Terminal window
tabalyst sample *.csv --sample-method random --percent 5 -d samples/
  • Outputs are named customers.sample.csv, orders.sample.csv, and so on.
  • -o accepts only one resolved input; -o and -d cannot be combined.
  • Recursive ** patterns are not supported.

The default delimiter is a comma and the default encoding accepts UTF-8 with or without a byte-order mark. Override either when necessary:

Terminal window
tabalyst sample data.csv --sample-method random --rows 100 --delimiter ";" --encoding cp1252

--config reads the same strict JSON configuration as tabalyst report; --delimiter and --encoding override its CSV settings.