StructScan walkthrough
This walkthrough takes a small but realistic CSV through StructScan end-to-end. The same dataset is used in the MapCraft walkthrough and the FlowBridge walkthrough, so the three tutorials read continuously.
- Access to a DataChord workspace (you are signed in and on the Dashboard).
- The sample CSV from the next section, saved locally as
customer_orders.csv.
Sample data: customer_orders.csv
Fifteen rows of plausibly-messy commerce data. The columns are
order_id, customer_email, order_date, country, total_amount, currency, status.
Copy and save the block below as customer_orders.csv.
order_id,customer_email,order_date,country,total_amount,currency,status
ORD-1001,[email protected],2026-03-14,United Kingdom,142.50,GBP,paid
ORD-1002,[email protected],03/15/2026,US,89.00,USD,paid
ORD-1003,[email protected],2026-03-15,United Kingdom,210.00,GBP,paid
ORD-1004,,14-Mar-2026,United States,57.25,USD,refunded
ORD-1005,[email protected],2026-03-16,Finland,99.99,EUR,paid
ORD-1006,[email protected],03/16/2026,USA,318.40,USD,paid
ORD-1007,[email protected],2026-03-17,US,45.00,USD,pending
ORD-1008,[email protected],17-Mar-2026,United States,-5.00,USD,refunded
ORD-1009,,2026-03-18,Germany,72.10,EUR,paid
ORD-1010,[email protected],2026-03-18,DE,150.00,,paid
ORD-1011,[email protected],03/19/2026,United Kingdom,88.50,GBP,paid
ORD-1012,[email protected],2026-03-19,Netherlands,205.75,EUR,paid
ORD-1013,[email protected],2026-03-20,France,310.20,EUR,paid
ORD-1014,[email protected],03/20/2026,Switzerland,180.00,CHF,paid
ORD-1015,[email protected],2026-03-21,India,2450.00,INR,paid
- Mixed date formats:
2026-03-14,03/15/2026,14-Mar-2026. - Mixed country representations:
US,United States,USA,GB,United Kingdom,DE,Germany. - Two rows with missing
customer_email(ORD-1004, ORD-1009). - One negative
total_amount(ORD-1008). - One missing
currency(ORD-1010).
StructScan should flag each of these. MapCraft will fix them in the next walkthrough.
Step 1 — Open StructScan
From the Dashboard, click the StructScan card. You will land on
/structscan. The page opens on the upload zone — a dotted drop target
with a button that says Choose file.
Step 2 — Upload the file
Drag customer_orders.csv onto the drop zone, or click Choose file.
You will see three quick UI states in succession:
- Uploading — a progress bar.
- Detected — the file type appears as a chip (
CSV · 1.6 KB). - Analyzing your data... — the profiling has started.
StructScan returns immediately from the upload and starts a background profiling task. The UI polls for status. For a file this small, expect the "Analyzing" state to clear within a couple of seconds. Larger files may take longer; you can leave the page open or come back to it.
Step 3 — Read the results
When profiling completes, the page switches to the three-pane layout. From left to right: the Raw tree, the Analysis pane, and the AI chat rail.
┌──────────────────────── customer_orders.csv ─────────────────────────────┐
│ Raw tree │ Field profiles │ AI chat │
│ │ │ │
│ ▸ Headers (7) │ order_id STRING 15/15 │ Hi! Ask me about │
│ ▸ Rows (15) │ customer_email STRING 13/15 ⚠ │ this file. │
│ │ order_date DATE mixed ⚠ │ │
│ │ country STRING mixed ⚠ │ ▾ Suggested │
│ │ total_amount NUMBER neg ⚠ │ prompts │
│ │ currency STRING 14/15 ⚠ │ │
│ │ status ENUM 15/15 │ │
│ │ │ │
│ │ Quality summary │ │
│ │ ──────────────── │ │
│ │ Overall: 72 / 100 (watch) │ [Push to │
│ │ Completeness: 91 / 100 │ MapCraft] │
│ │ Consistency: 58 / 100 │ │
└──────────────────────────────────────────────────────────────────────────┘
Step 3a — Inspect order_date
Click order_date in the Analysis pane. The detail drawer opens with:
- Detected type:
DATE(with amixed-formatwarning). - Samples:
2026-03-14,03/15/2026,14-Mar-2026, … - Suggestion: "Normalise to ISO 8601 (
YYYY-MM-DD)."
Step 3b — Inspect customer_email
- Detected type:
STRING. - Completeness:
13 / 15(87%). - Quality flags:
null-values: 2. - Suggestion: "Require non-null at the target if email is identity."
Step 3c — Inspect total_amount
- Detected type:
NUMBER. - Range:
min: -5.00,max: 2450.00. - Quality flags:
negative-value: 1. - Suggestion: "Add a non-negative constraint at the target, or treat negatives as refunds and split into a signed field."
Step 4 — Read the quality summary
The Quality summary block at the bottom of the Analysis pane is the fastest way to know whether this file is mappable as-is.
Expected quality_summary JSON (click to expand)
{
"overall_score": 72,
"band": "watch",
"completeness": 91,
"consistency": 58,
"issues": [
{ "field": "customer_email", "code": "null-values", "count": 2 },
{ "field": "order_date", "code": "mixed-format", "count": 3 },
{ "field": "country", "code": "mixed-representation", "count": 7 },
{ "field": "total_amount", "code": "negative-value", "count": 1 },
{ "field": "currency", "code": "null-values", "count": 1 }
]
}
A score of 72 lands in the watch band. The file is mappable, but you should plan on adding at least:
- a transformation rule for
order_date(mixed-format → ISO), - a lookup table for
country(representations → ISO-3166 alpha-2), and - a target-side validation for
total_amount(non-negative).
You will do all three in the MapCraft walkthrough.
Step 5 — Ask the AI chat rail
The right-hand rail is a chat surface scoped to this profile. It already has the field profiles and quality summary in context, so you can ask focused questions without re-uploading anything.
- What has quality problems?
- What target schema fits?
- Are there duplicates?
You: Which fields in this file have quality problems and what should I do about them?
AI: Five fields are flagged.
customer_emailhas two nulls — decide whether email is identity.order_datemixes three formats; normalise to ISO 8601.countrymixes long names, short codes, and "USA" with "US"; use a lookup keyed on the variants.total_amounthas one negative outlier (ORD-1008) — likely a refund; either constrain at the target or split into a signed field.currencyhas one null (ORD-1010) — decide if a default or a hard reject is correct.
You: What target schema would fit this data?
AI: A canonical Order shape:
order_id(string, required),customer_email(RFC 5322 email, nullable),order_date(ISO 8601 date, required),country_code(ISO-3166 alpha-2, required),total_amount(decimal, ≥ 0, required),currency(ISO-4217, required),status(enum ofpaid | pending | refunded). I suggest you mapcountrythrough a lookup tocountry_coderather than store the free-text form.
You: Are there duplicate order IDs?
AI: No — all 15
order_idvalues are unique. Cardinality is15 / 15with no collisions on case or whitespace.
Step 6 — Push to MapCraft
Click Push to MapCraft in the top-right of the AI rail. A modal opens with a single decision:
┌─────────── Push to MapCraft ──────────────┐
│ Project name: Customer orders ingest │
│ Lane: ◉ Warehouse ○ Document │
│ ○ Both │
│ │
│ ✔ Auto-generate source schema from profile │
│ ✔ Pre-link this SourceProfile to project │
│ │
│ [ Cancel ] [ Create ] │
└────────────────────────────────────────────┘
Pick Warehouse, leave both checkboxes ticked, and click Create. DataChord:
- Creates a new
ProjectinDRAFTstatus, scoped to your organisation. - Generates a
Schema(role:SOURCE) from the field profiles — same types, same nullability flags. - Attaches the
SourceProfileto the project so MapCraft can refer back to samples and quality flags.
You will be redirected to /mapcraft/{projectId}. That is exactly where
the MapCraft walkthrough picks up.
What you produced
- One
UploadedFile—customer_orders.csv. - One
SourceProfilewith sevenFieldProfiles and a quality score of 72. - One
Project(created via Push to MapCraft) with an auto-generated sourceSchema.
Continue: MapCraft walkthrough →