quality

Answers "is this file fit for use?" in one report: every field's empty values, distinct values, top values, type and type conformance; differences from an expected schema; rule violations by severity; and a pass/fail verdict from your thresholds. The command exits with 1 when a threshold fails (0 otherwise), so the report doubles as a data contract in CI.

undatum quality data.csv
undatum quality data.csv --rules rules.yml -o report.html
undatum quality data.csv --json

undatum quality deliveries/2026-10.csv --schema expected.json --rules rules.yml \
  --thresholds quality.yml -o report.html

The report format follows --format-out / -O (markdown, html, json) or the --output extension; Markdown goes to stdout by default. HTML is a single file without external resources. --json prints the undatum.quality/1 document with summary, fields, schema_check, violations and verdict.

Thresholds

# quality.yml
min_rows: 1000
max_null_rate:
  email: 0.01        # at most 1% empty e-mail addresses
  "*": 0.2           # every other field
min_type_conformance:
  amount: 0.99       # 99% of amounts are numbers
max_error_violations: 0
max_warning_violations: 50
schema: additive     # strict: no added, removed or retyped fields; additive: new fields allowed

Key	Checks
min_rows, max_rows	number of records
max_null_rate	share of empty values ("", n/a, null, - count as empty); a number for every field or a mapping with * as the default
min_type_conformance	share of values that fit the field's type (from --schema, else the type most values have)
max_error_violations, max_warning_violations	rule violations from --rules
schema	strict or additive comparison with --schema

Unknown keys and out-of-range values stop the run with exit code 2. A threshold for a field the file does not have fails.

--schema takes undatum schema FILE --json output, a JSON Schema, a Frictionless table schema or a reference data file (see schema drift); --rules takes a rule file.

In CI

# .github/workflows/data.yml
- name: Check the delivery
  run: |
    pip install undatum
    undatum quality data/delivery.csv --rules rules.yml --thresholds quality.yml -o report.html
- name: Keep the report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: quality-report
    path: report.html

From Python, Dataset.read("data.csv").quality(rules="rules.yml") returns the same report as a dict. In a pipeline, use command: quality.

Reference

Reads: any readable format · Writes: a Markdown, HTML or JSON report · Memory: DuckDB profiles CSV/JSON/Parquet out of core; other formats are loaded into DuckDB · Engines: python

undatum quality [OPTIONS] INPUT_FILE

Argument	Description
INPUT_FILE	Path to input file. (required)

Option	Description	Default
--rules TEXT	Validation rule file (YAML/JSON) to apply.
--schema TEXT	Expected schema: undatum schema --json output, JSON Schema, Frictionless schema or a reference data file.
--thresholds TEXT	Thresholds file (YAML/JSON); a failed one exits with 1.
-O, --format-out TEXT	Report format: markdown (default), html, json.
-o, --output TEXT	Write the report here (format from the extension).
-F, --format-in TEXT	Override input format detection.
--table, --sheet TEXT	Table or sheet name for multi-table sources (Excel, SQLite, lakehouse).
--json	Print the result as one JSON document (same as --format-out json).

See also shared options.