# Tabalyst documentation

> Tabalyst is an open-source, local-first toolkit that turns CSV, JSON and JSONL files into interactive HTML reports, JSON profiles, scan documents and samples. It has five tools: Tabalyst Report, Tabalyst Scan, Tabalyst Inspect, Tabalyst Sample and Tabalyst Generate. These pages describe version 0.6.2, in beta (JSON format 0.2.0); commands and JSON formats may still change. The documentation is in English only.

- Install: `pip install --upgrade tabalyst` (Python 3.11 to 3.14)
- Quick start: `tabalyst report data.csv` creates `data.html`, `data.json` and `executions.json` beside the source
- Every page below is Markdown. The whole documentation in one file: [llms-full.txt](https://docs.tabalyst.com/llms-full.txt)

## Overview

- [Tabalyst documentation](https://docs.tabalyst.com/index.md): Documentation of Tabalyst 0.6.2, the open-source toolkit for reports, scans, samples and synthetic CSV generation.

## Get started

- [Get started with Tabalyst](https://docs.tabalyst.com/get-started.md): Install Tabalyst, create a first report from a file of your own and browse finished examples, in three short steps.
- [Install Tabalyst](https://docs.tabalyst.com/get-started/install.md): Install or update Tabalyst from PyPI on Windows, macOS or Linux, and keep it up to date before each test.
- [Create your first report](https://docs.tabalyst.com/get-started/first-report.md): Tutorial that profiles a five-row CSV file with tabalyst report, opens the HTML report and reads the problems Tabalyst found.
- [Examples and demos](https://docs.tabalyst.com/get-started/examples.md): Synthetic example datasets and their generated reports, JSON profiles and column pages, to try Tabalyst before using your own data.

## Tabalyst Report

- [Tabalyst Report](https://docs.tabalyst.com/report.md): Overview of Tabalyst Report, the tool that turns a CSV, JSON, JSONL or Excel file into an interactive HTML report and a JSON profile, with commands, outputs and options.
- [Read a Tabalyst Report](https://docs.tabalyst.com/report/read-report.md): Read each table and indicator in a Tabalyst Report, including its purpose, columns and limits.
- [Report CSV files](https://docs.tabalyst.com/report/csv.md): Create HTML reports and JSON profiles from one or many CSV files with tabalyst report, choose output names, use column pages and understand the batch safety rules.
- [Report JSON and JSONL files](https://docs.tabalyst.com/report/json.md): Turn a JSON file into an interactive HTML report and a JSON profile with tabalyst report, one view per collection of records.
- [Report Excel workbooks](https://docs.tabalyst.com/report/excel.md): Turn an Excel workbook (.xlsx, .xlsm) into an interactive HTML report and a JSON profile with tabalyst report, one table per report, chosen automatically or with --collection.
- [JSON profile](https://docs.tabalyst.com/report/json-profile.md): Structure of the JSON profile written by tabalyst report, with its top-level fields, column profiles, issue codes and format versioning.
- [JSON profile changelog](https://docs.tabalyst.com/report/profile-changelog.md): Current format version and revisions of the JSON profile written by tabalyst report.

## Tabalyst Inspect

- [Tabalyst Inspect](https://docs.tabalyst.com/inspect.md): Overview of Tabalyst Inspect, the tool that finds which array of a JSON, JSONL or NDJSON file, or which sheet or table of an Excel workbook, holds its records and writes an editable Inspect file.
- [Inspect JSON and JSONL files](https://docs.tabalyst.com/inspect/json.md): Let tabalyst inspect find the collection of records of a JSON, JSONL or NDJSON file, then edit the Inspect file to choose how scan and report read it.
- [Inspect Excel workbooks](https://docs.tabalyst.com/inspect/excel.md): Let tabalyst inspect find which sheet or table of an Excel workbook (.xlsx, .xlsm) holds the data, then edit the Inspect file to choose the table and the header row that scan and report use.
- [Inspect format](https://docs.tabalyst.com/inspect/format.md): Structure of the Inspect file written by tabalyst inspect, with its zones, detection, warnings, the config you may edit, and how Tabalyst reads it.
- [Inspect format changelog](https://docs.tabalyst.com/inspect/format-changelog.md): Current format version and revisions of the JSON file written by tabalyst inspect.

## Tabalyst Scan

- [Tabalyst Scan](https://docs.tabalyst.com/scan.md): Overview of Tabalyst Scan, the analysis engine that describes every field of a CSV, JSON, JSONL or Excel file in one JSON document, with commands and pages.
- [Scan CSV and JSON files](https://docs.tabalyst.com/scan/files.md): Describe every field of a CSV, JSON, JSONL or Excel file in a complete JSON scan document with tabalyst scan, in one streaming pass.
- [Scan format](https://docs.tabalyst.com/scan/format.md): Structure of the JSON document written by tabalyst scan, with its top level, datasets, fields, measure envelopes, detectors and diagnostics.
- [Scan format changelog](https://docs.tabalyst.com/scan/format-changelog.md): Current format version and revisions of the JSON document written by tabalyst scan.
- [Manage query caches](https://docs.tabalyst.com/scan/cache.md): Inspect and clean the disposable query caches of Tabalyst DuckDB projects with tabalyst cache info and tabalyst cache clean.

## Tabalyst Sample

- [Tabalyst Sample](https://docs.tabalyst.com/sample.md): Create smaller first, last, random or stratified CSV samples with Tabalyst.

## Tabalyst Generate

- [Tabalyst Generate](https://docs.tabalyst.com/generate.md): How to create synthetic CSV datasets from a YAML definition or the packaged CRM and insurance examples.

## Reference

- [Reference](https://docs.tabalyst.com/reference.md): Reference pages of Tabalyst - command line, Python API, configuration file, execution history and glossary, with the JSON format references of each tool.
- [Command line (CLI)](https://docs.tabalyst.com/reference/cli.md): The tabalyst commands (report, scan, inspect, sample, generate, cache) and their shared conventions.
- [CLI: tabalyst report](https://docs.tabalyst.com/reference/cli/report.md): Every option of tabalyst report and examples for CSV, JSON and Excel files, including how to choose a table with --collection and report every table with --all-collections.
- [CLI: tabalyst scan](https://docs.tabalyst.com/reference/cli/scan.md): Every option of tabalyst scan and examples for CSV, JSON, JSONL and Excel files, including how to choose a JSON collection or an Excel table with --collection.
- [CLI: tabalyst inspect](https://docs.tabalyst.com/reference/cli/inspect.md): Every option of tabalyst inspect and examples for JSON, JSONL and Excel files, including the ready-to-run report commands it prints when several collections or tables are possible.
- [CLI: tabalyst sample](https://docs.tabalyst.com/reference/cli/sample.md): Every option of tabalyst sample and examples of first, last, random and stratified CSV samples, with fixed sizes, percentages and seeds.
- [CLI: tabalyst generate](https://docs.tabalyst.com/reference/cli/generate.md): The inputs, outputs and options of the tabalyst generate command.
- [CLI: tabalyst cache](https://docs.tabalyst.com/reference/cli/cache.md): The tabalyst cache info and tabalyst cache clean commands, which show and remove the disposable query caches of Tabalyst projects.
- [Python API](https://docs.tabalyst.com/reference/python-api.md): The public Python functions of Tabalyst for reports, scans, Inspect and sampling, with the conventions they share - batch results, errors, configuration files and progress callbacks.
- [Python API: reports](https://docs.tabalyst.com/reference/python-api/report.md): The Python functions that write or build Tabalyst reports - analyze, generate_reports, analyze_csv, analyze_scan and render_report - with their parameters, return values and examples for CSV, JSON and Excel files.
- [Python API: scans](https://docs.tabalyst.com/reference/python-api/scan.md): The Python functions that scan a CSV, JSON, JSONL or Excel source - scan and generate_scans - with their parameters, return values and examples.
- [Python API: Inspect](https://docs.tabalyst.com/reference/python-api/inspect.md): The Python functions that inspect a JSON, JSONL or Excel file - inspect and generate_inspections - with their parameters, return values and examples.
- [Python API: sampling](https://docs.tabalyst.com/reference/python-api/sample.md): The Python functions that write a smaller CSV file - sample_csv and generate_samples - with their parameters, return values and examples of first, last, random and stratified samples.
- [Types and patterns](https://docs.tabalyst.com/reference/types-and-patterns.md): Understand the native, inferred and semantic types and the value patterns shared by Tabalyst Scan and Report.
- [Native, inferred and semantic types](https://docs.tabalyst.com/reference/types-and-patterns/types.md): Define every source, inferred and semantic type and how Tabalyst Scan and Report select them.
- [Recognized patterns](https://docs.tabalyst.com/reference/types-and-patterns/patterns.md): Catalog every built-in Tabalyst detector, its accepted forms, configured patterns and evidence states.
- [Configuration](https://docs.tabalyst.com/reference/configuration.md): Reference for the JSON configuration file read by tabalyst report, tabalyst sample, tabalyst scan and the Python API.
- [Execution history](https://docs.tabalyst.com/reference/history.md): Reference for executions.json, the cumulative performance history written next to each report.
- [Glossary](https://docs.tabalyst.com/reference/glossary.md): Terms used in the Tabalyst documentation and report, with their French equivalents, and the names that are never translated.

## About Tabalyst

- [About Tabalyst](https://docs.tabalyst.com/about.md): What Tabalyst is and where to read more - concepts, known limitations, release notes, and how to contribute or report an issue.
- [Concepts](https://docs.tabalyst.com/about/concepts.md): How Tabalyst works - the toolkit and its four tools, the workflow from a file to a report, local-first processing, masking of sensitive values, experimental JSON formats and beta status.
- [Known limitations](https://docs.tabalyst.com/about/limitations.md): What Tabalyst does not do yet during its beta, including JSON report limits, the duplicate detection budget and experimental JSON formats.
- [Release notes](https://docs.tabalyst.com/about/releases.md): A short summary of what changed in each Tabalyst release from 0.1.x to 0.6.2.
- [Contributing and issues](https://docs.tabalyst.com/about/contributing.md): Where to report a defect, ask for a feature, find the source code, and the license of Tabalyst and of its documentation.

## Optional

- [Source code and issues](https://github.com/loribel-labs/tabalyst)
- [PyPI package](https://pypi.org/project/tabalyst/)
- [Website](https://tabalyst.com/)