smartjoin-py 0.1.2

Deterministic key and join discovery for structured datasets.

Stop guessing how your tables connect

---

smartjoin helps you understand how unfamiliar datasets fit together — without schema docs, manual SQL detective work, or opaque guesses.

It scans structured data, profiles columns, discovers likely keys, infers candidate joins, and generates an interactive explorer so you can inspect the results.

Supports .csv, .xlsx, .json, .parquet input files.

Example

Given a folder like:

• orders.csv
• customers.xlsx
• payments.parquet
• shipments.json

smartjoin can infer relationships such as:

Source	Target	Type	Confidence	Origin
orders.customer_id	customers.id	many_to_one	98%	Direct
payments.order_id	orders.order_id	many_to_one	95%	Derived
shipments.order_ref	orders.order_id	one_to_one	89%	Direct

Quickstart

Installation

pip install smartjoin-py

Run

smartjoin run <path> <out_dir>

This analyzes the structured datasets in <path> and writes results to <out_dir>.

Outputs

• report.json — full structured analysis output
• relationships.csv — flat table of discovered joins and scoring signals
• explorer/index.html — interactive explorer UI
• explorer/data.json — explorer payload

Generate demo datasets

To explore smartjoin on deterministic synthetic data:

smartjoin generate-test-datasets --output-dir <output-dir>

Limitations

smartjoin identifies candidate relationships across structured datasets. It does not guarantee semantic correctness.

Always review inferred joins before using them downstream. Domain meaning may still require human interpretation, and output quality depends on the structure and consistency of the input data.

Roadmap

Future development may include:

• stronger semantic matching across columns and tables
• optional AI-assisted reasoning and scoring
• improved explorer and debugging capabilities
• broader support for real-world edge cases and heterogeneous datasets

Contributing

See CONTRIBUTING.md.

License

Licensed under the MIT License