Skip to main content

Map many fields to one target

The MapCraft walkthrough mapped fields one-to-one. But plenty of real targets are composites: an address built from street + city + state + postalCode, a total summed from line amounts, or a phone coalesced from mobile/home/work variants. Many-to-one (N→1) mapping lets several source fields converge on a single target, with a combined rule — written in natural language — deciding how their values merge.

There are two ways to get there, and this page covers both: let Auto-map propose the combine for you, or draw the edges yourself and write the rule by hand.

By the end of this page you will have:

  • Run Auto-map and accepted an AI-proposed N→1 combine.
  • Manually converged two or more source fields onto one target.
  • Written a combined rule in natural language and watched it verify.
  • Read the ƒx chip states so you know when a combine needs attention.
  • Edited an AI-authored combine and confirmed your edit survives an Auto-map re-run.
You'll need
  • A MapCraft project open at /mapcraft/{projectId} with source and target schemas attached (see the walkthrough or Connect a source via the Source Picker).
  • A target schema containing at least one composite field — e.g. a single address or full_name target where the source keeps the parts separate.

Step 1 — Let Auto-map propose the combine​

Click Auto-map in the toolbar. Beyond the 1:1 suggestions you already know, Auto-map now detects many-to-one candidates in two tiers:

TierCostWhat it catches
HeuristicFree, deterministicShared-parent clusters (address.street, address.city, … → address) and built-in composite templates: full-name concat, total sum, phone/email coalesce.
Open-ended LLMOne model callTemplated-format and conditional combines the templates don't cover.

Each accepted proposal persists all contributor edges plus a combined rule with its merge logic already written out — so a composite target arrives mapped and explained instead of being left unmatched.

On the canvas, a converged target shows a pill-shaped ƒx chip with an N→1 badge (e.g. 3→1) sitting between the contributor edges and the target. The rule's short summary is the chip label.

Where did the logic come from?

Hover the chip: AI-authored combines show their rule summary (Combined rule: <summary> — click to edit). The rule text itself is plain natural language — open it and read exactly what the AI decided.

Step 2 — Or converge fields manually​

When Auto-map doesn't propose the combine you want:

  1. Drag a connection from the first source field to the target, as usual.
  2. Drag a second source field onto the same target. Both edges persist — MapCraft only blocks exact duplicates of the same source→target pair.
  3. As soon as two or more edges share a target, a dashed Combine chip (ƒx, 2→1 badge) appears to the left of the target. No rule exists yet — the contributor edges still run straight to the target.

Repeat for as many contributors as the target needs.

Step 3 — Write the combined rule​

Click the Combine chip. The combined-rule editor opens, headed Combined N→1 → <target.path> with the contributor list (from street, city, state, postalCode) underneath.

Type the merge logic in natural language, for example:

concatenate street, city, state, postalCode with ", "

MapCraft plans the rule into executable logic and verifies it against sample data, exactly like a per-edge rule.

Two things to know about how combined rules compose:

  • Per-edge rules still apply first. If street has its own trim/uppercase rule, the combined rule receives the transformed value.
  • The rule applies to the merged output of all contributors — you don't reference each contributor edge separately.

Once the rule saves, the chip is promoted to a junction: contributor edges now flow into the chip, and a single bold merged-output edge runs from the chip to the target.

Step 4 — Read the chip states​

The ƒx chip doubles as the combine's status indicator:

ChipMeaning
Dashed border, CombineConvergent target, no rule yet.
Indigo, Verifying…Rule submitted; planner + verifier still running.
Green, rule summaryVerified OK.
Amber, ReviewVerifier flagged something — open the rule and check.
Rose, FailedVerification failed; the logic needs re-wording.

The same chip appears in the Table view: every row that shares a convergent target shows it in the Transform column, and clicking it opens the identical editor as a popover.

Step 5 — Edit or delete a combine (and keep your edits)​

Open any combine chip — the rule list shows each rule with a status dot. Hover a row for the edit (pencil) action: edits re-run the plan-and-verify pipeline and refresh the chip. Delete removes a rule after a one-click confirm.

Origin tracking is the part worth understanding:

  • Rules authored by Auto-map carry origin = "ai".
  • The moment you edit one, it flips to origin = "manual".
  • Re-running Auto-map regenerates only the ai rules. Your edited combines — and anything you wrote by hand — are left untouched.

So it's always safe to re-run Auto-map after schema changes: it refreshes its own proposals without clobbering your work.

Verify​

Your N→1 mapping is working end-to-end if:

CheckWhere to look
All contributor edges persistCanvas shows one edge per source field converging toward the target; Table view shows one row per contributor sharing the target path.
The chip is a junctionContributor edges terminate at the ƒx chip and one bold edge continues to the target.
The rule verifiedChip is green with a short rule summary; the rule row in the editor shows a green status dot.
Auto-map respects your editsEdit an AI combine, re-run Auto-map, re-open the chip — your wording is unchanged.

Troubleshooting​

The chip says "Failed" (rose). The verifier rejected the generated logic against sample data. Click the chip, read the rule, and re-word it — being explicit about separators, ordering, or null handling usually resolves it.

The chip is stuck on "Verifying…". The plan-and-verify round trip hasn't returned. If it persists, re-open the editor and re-save the rule to re-trigger verification.

Auto-map didn't propose a combine I expected. The heuristic tier only fires on shared-parent clusters and the built-in templates (full name, totals, phone/email coalesce); the LLM tier only sees fields still unmatched after earlier tiers. Converge the fields manually (Step 2) — the result is identical.

I want different merge logic per contributor. Put the per-field logic in each contributor's own per-edge rule (it runs first), and keep the combined rule focused on how the transformed values merge.

What's next​