Automatic column mapping for CSV imports
Automatic column mapping matches the columns in an uploaded file to the fields your system
expects — so a column headed E-mail Address, Email, or e_mail all land on your email
field without the user aligning each one by hand. It’s the step that makes or breaks a CSV
import: get it wrong and bad data flows straight into your database.
Most importers treat mapping as either a brittle exact-string match (reject anything that isn’t a perfect header match) or an opaque AI guess (can’t tell you why it mapped what it did). Mildport takes a third path: score it deterministically, show the score, and only ask AI about the columns that are genuinely ambiguous.
How Mildport maps columns
Section titled “How Mildport maps columns”- Header + value scoring. The matcher looks at both the column header and the actual cell
values, scoring each candidate against every target field. A column of
@-bearing strings scores asemaileven if the header is unhelpful. - Deterministic by design. The same file produces the same mapping every time — no run-to-run drift. See How it works.
- Visible scores. Every suggested mapping carries a score you can see, so it’s auditable rather than magic.
- AI only for the uncertain tail. An optional, evidence-gated AI judge re-ranks just the columns the deterministic scores leave ambiguous — your model, off by default. More on that in AI CSV import.
- Human confirmation is the gate. Mappings appear in a review grid; a person confirms or overrides before anything is applied.
Why explainable mapping matters
Section titled “Why explainable mapping matters”A silent mis-map is the most expensive kind of import bug — it doesn’t error, it just writes the wrong data. When every mapping decision has a visible score and a rationale, and the pipeline is event-sourced and replayable, you can answer “why did this column map there?” months later. That’s the difference between an importer you trust with customer data and one you don’t.
The matcher is also shipped as a package — @capitality-io/import-suite-matcher — so the same
deterministic header → field logic runs everywhere, including before the engine is even involved.
What is automatic column mapping?
The import step that matches an uploaded file’s columns to the fields your system expects (e.g.
E-mail Address → email), so users don’t align every column by hand.
How does Mildport map columns automatically? A deterministic matcher scores header similarity and the actual cell values against each target field, producing a ranked mapping with visible scores. The same file always maps the same way; an optional AI judge handles only the uncertain columns.
Can I correct or override an automatic column mapping? Yes — mappings are suggestions shown in a review grid with score and rationale. A person can confirm or override before the import is applied, and the pipeline is replayable.
Map your own messy file in the live demo — mildport.com — or see the embeddable importer it’s part of.