Create your first report
In this tutorial you create a small CSV file, run tabalyst report on it, open
the HTML report and read the problems Tabalyst detects. It takes about five
minutes. You need Tabalyst installed and up to date: see
Install Tabalyst. If it is already installed, update it
first, since the output shown here comes from the latest release:
pip install --upgrade tabalyst1. Create a CSV file
Section titled “1. Create a CSV file”In your working folder, create a file named orders.csv with this content:
id,name,amount,joined,active,notes001,Alice,12.50,2026-01-01,true,First order002,Bob,,2026-02-01,false,003,Charlie,25.00,2026-03-01,true,"Two items, one order"003,Charlie,25.00,2026-03-01,true,"Two items, one order"004,Dana,not available,2026-04-01,true,Pending reviewThis file contains deliberate problems: a repeated row, empty cells and a text value in a numeric column.
2. Run the report
Section titled “2. Run the report”tabalyst report orders.csvTabalyst prints a summary and the location of the report:
Analyzed 5 rows and 6 columns.Report: C:\work\orders.htmlSecond pass (automatic): 7 analyses, 7 computed, 0 reused.The second pass is an extra step that Tabalyst runs by itself when it finds an analysis useful and cheap. The line says what it did.
Three files now sit beside orders.csv:
orders.csvorders.html the interactive reportorders.json the JSON profile, for scripts and other toolsexecutions.json the history of the runs in this folder3. Open the report
Section titled “3. Open the report”Open orders.html in your web browser, by double-clicking it or from the
terminal:
start orders.html # Windowsopen orders.html # macOSxdg-open orders.html # LinuxThe report works offline. Add --details to the command to create an
independent HTML page per column under orders/. The Columns table then
links to those pages. In each column page, Overview shows the stored values
with counts and all detected formats directly. The files contain values from
your data: share them accordingly.
4. Read what Tabalyst found
Section titled “4. Read what Tabalyst found”The report is organized in numbered sections, listed in the bar at the top: Overview, Summary, Observations, Columns, Transformations, Dates, Strings, Detectors, Patterns, Insights, Second pass, Data sample and Analysis settings. A section appears only when the data has something to show: a file with a numeric column also gets Numeric, and a Limits section appears when the scan stopped a measure at a limit.
Overview
Section titled “Overview”The Overview section sums up the file: 5 rows, 6 columns, 2 missing cells (6.67 %) and 1 duplicate row. Under it:
- Finding types has two figures: no Error type and 1 Issue type in 1 column, with the most
affected column under them (
amount, one finding). - Errors and Issues lists the kinds of finding. Here there is one Issue:
Mixed types (1 value outside the closest type, in
amount). The catalogue of kinds lists the others. - Column types counts the columns by family and type.
An Error is a value that a rule proves invalid, such as a date that does not exist. An Issue is an ambiguity or a deviation worth a look. Nothing here is an Error: no rule proves a value invalid in this file.
Summary
Section titled “Summary”The Summary table has one row per column, with its type, a sentence about its
values, the missing share and its Errors and Issues. In orders.csv:
| Column | Type | What the row says |
|---|---|---|
id | Identifier, ID | 4 distinct values; an Issue: 1 repetition beyond the first (003) |
name | Text, Very short | Median length of 5 characters, no finding |
amount | Other, Mixed | Numbers and text together; an Issue: 1 value outside the closest type (not available); 1 missing |
joined | Temporal, Date | Dates from 2026-01-01 to 2026-04-01, in one format |
active | Categorical, Boolean | true holds 80 % of the values |
notes | Text, Short | Median length of 17 characters; 1 missing |
Click an Issue to see what it counts, out of how many values, how exact the count is and a few examples.
Observations
Section titled “Observations”Observations lists what the scan found from its facts: the repeated row
(record 4 repeats record 3 exactly), the mixed column amount, and the two empty
cells (amount and notes, record 2), which are remarks and not problems.
Look at the types too:
idis an identifier, not an integer: values such as001have leading zeros, so Tabalyst keeps them as text and reads the column as an ID.joinedis a date in theYYYY-MM-DDformat.activeis a boolean (true/false).
Types are descriptive hints: Tabalyst never modifies your CSV file.
5. Run it again
Section titled “5. Run it again”Run the same command a second time:
tabalyst report orders.csvTabalyst refuses to replace the existing report:
Error: Report output already exists. Use --force to replace it: orders.html orders.jsonAdd --force when replacing the report is intentional:
tabalyst report orders.csv --forceexecutions.json is not replaced: each run adds an entry to it.
What you learned
Section titled “What you learned”tabalyst report FILE.csvcreates an HTML report and a JSON profile beside the source file.- The report shows detected types, missing values, duplicates and other problems, without changing your data.
- Existing reports are protected unless you pass
--force.
Next steps
Section titled “Next steps”- Choose the output name with
-o, or process several files at once withtabalyst report *.csv -d reports/. Runtabalyst report --helpfor all options. - Use the JSON profile in your own scripts.
- Adapt the analysis with a configuration file.