Data Mapping

​

Overview

Data mapping defines how raw fields from your external data sources are transformed into entities and relationships in the knowledge graph. Mappings tell Experio how to interpret structured data (CSV, Excel, databases) and create the corresponding graph nodes and edges. Navigate to Model & Define > Data Mapping.

​

Viewing Mappings

The data mapping page shows a table of all configured mappings with server-side pagination. Each entry displays the mapping name, configuration details, and compatibility status against the current ontology revision. Filter to invalid or stale mappings when you need to clean up after an ontology change. See Ontology Compatibility.

​

Creating a Mapping

Click Create New Mapping to open the mapping editor. The mapping editor provides two modes:

​

Form Builder

A step-by-step form interface for defining:

1. Source Fields — Select which fields from your data source to use
2. Node Mappings — Define how source fields map to entity types in your ontology
3. Relationship Mappings — Define how relationships between entities are derived from the data

​

Visual Canvas

An interactive drag-and-drop canvas (powered by React Flow) for visually designing mappings:

• Drag source fields onto the canvas
• Connect fields to entity types and properties
• Draw relationship lines between entities
• Zoom and pan to navigate complex mappings

​

Mapping Components

​

Source Fields

Define the raw fields available from your data source. Each field has:

• Field name — The column or property name in the source data, written the way ingestion will find it (see below)
• Display name — A label for people; it can keep the header as written
• Data type — String, number, date, etc.

​

Column names for CSV and Excel sources

When ingestion reads a CSV or Excel file (and the top-level keys of a JSON file), it first normalizes every header: it removes a leading byte-order mark, lower-cases it, turns every character that is not a letter or a digit into _, and trims _ from both ends. Employee ID becomes employee_id, Hire Date becomes hire_date, and firstName becomes firstname. A field name is matched against the normalized header, so a name written any other way (Employee ID) finds nothing, and ingestion skips that field. Write the field name in its normalized form and keep the header as the Display name. A source that is an API is the exception: its records keep their keys exactly as the API sends them, so a field name for an API source is written as the API spells it. The page’s own Upload Excel or CSV File for Schema Detection names each column the same way, except that it does not trim _ from the ends. A header that starts or ends with a symbol, such as Amount (USD), comes out as amount__usd_, while ingestion looks for amount__usd: remove the trailing _ from that field’s name.

​

Node Mappings

Map source fields to entity properties: Each mapped property displays its ontology type (text, number, date, boolean, list, enum). You do not configure per-field transforms in the mapping UI — types come from the ontology definition for that entity.

​

Property types and graph writes

At ingestion time, Experio coerces mapped values to the ontology type before writing to the graph: Structured and unstructured ingestion share the same coercion path. Ensure source columns are parseable for the target type (for example, ISO or common date formats for date fields).

​

Relationship Mappings

Define how entities are connected:

​

Editing and Deleting

• Click any mapping row to edit its configuration
• Update turns on when you change the mapping, including a change to only the Record ID Column or the Timestamp Column (under Incremental Ingestion)
• Use the delete action to remove a mapping, or ask the copilot, which proposes a delete card you confirm (see Asking the copilot)

The mapping editor includes a compatibility panel. If node or relationship mappings point at ontology elements that no longer exist, the mapping is invalid until you update it and Re-validate. After a rename that already looks correct, Mark as reviewed clears stale status. You can also ask the copilot for either: it proposes a card that you confirm on the mapping list.

​

Asking the copilot

The Admin Copilot has a page pack for the mapping list, the create page and a mapping’s editor. Open it with the Copilot button or ⌘J. It knows the saved ontology, the other knowledge-model pages and the files you attach in the chat (see The knowledge-model copilot). In the editor it reads the mapping as you have it, including unsaved edits, with up to three sample values per source column (each cut at 80 characters). It can explain the mapping, check it, and propose changes as a card.

​

What a card can change

Everything a card maps to must already be in the saved ontology. When something is missing, the copilot proposes the ontology change first. You apply it and click Save on the Ontology page; for a mapping that is already saved, the copilot then proposes the mapping change it kept. The copilot checks and changes the default ontology’s data mappings only. Every card is checked on the server before you see it. The edits are applied to the mapping, the result goes through Save’s own validation (nothing is saved), every column a mapping refers to must exist, and the mapping is checked against the saved ontology before and after the change. A problem Save would refuse blocks the card. Any other problem blocks it only when the change causes it; one the mapping already had rides the card as a note (Separately, this data mapping already has a problem). Under When you click Save, the card lists what the page’s Save does on top of the change, when it applies:

• On the edit page, Save deletes and recreates every source column, node mapping and relation mapping row of the mapping (their ids change); what they hold is what the card shows.
• A node mapping that only creates is saved without its match fields: it keeps match property name and rule exact.
• Relation mappings’ start and end match rules are saved as exact.

​

Source columns from an attached CSV

Attach a CSV export of the table in the chat and ask the copilot to add its columns. The server reads the file’s header row and its first rows, and one card adds a source column for every header. The copilot does not retype the headers. It works in the mapping’s editor, and for a saved mapping from another page.

• The name is the header normalized the way ingestion does it (Employee ID becomes employee_id), and the display name keeps the header as written. Without this, ingestion would not find the column and would skip it. A mapping row can then name a column by its header, and the copilot resolves it to the column.
• The type is guessed from the first values: boolean, number, date, email, URL, or else text.
• The sample values are the first values of the column, at most three, each cut at 80 characters.
• At most 100 columns per card, each counting against the card’s edit limit. The card names the columns left over for a next card.
• Skipped, and named on the card: a column the mapping already has, a header with no letter or digit, and a header that normalizes to the same name as another.
• Which files: a CSV (a tab-separated file also reads). An Excel, JSON or PDF file is not read: export a CSV with the column headers in the first row.

When the mapping reads an API rather than a file, tell the copilot: it then keeps each name exactly as the API sends it. It cannot import columns from an API data source for you: that makes a live call to the customer’s API with its stored credentials, so only you do it, on the page.

​

Re-validating, reviewing and deleting a mapping

Ask the copilot to re-validate a mapping, mark it reviewed or delete it, and it makes a page-action card for the Data Mapping list, from any knowledge-model page. Apply on the list opens a confirmation, and only your own click on its confirm button performs the action (see Page-action cards). It needs Data Source Managers write access.

• Re-validate is offered when the mapping’s status is not valid, and Mark reviewed when it is stale or pending review. A mapping a re-check would leave as it is gets no card.
• Delete is destructive. The confirmation lists what goes with the mapping, counted when the card was made: the data sources that use it (named), with their filters, scan orders and their records, graph evaluation runs and the flow steps that scan them (the flows are named), and the mapping’s own source fields, node mappings and relation mappings. Nothing in the graph is removed.
• The card is refused if the mapping was saved or its status changed since it was made, and, for a review card, if the ontology was saved since.

​

Applying a card

• Apply puts the card’s version of the mapping into the editor (Applied to the editor — nothing is saved until you click Save). Click Save on the create page, or Update on the edit page, to keep it.
• A card holds the whole mapping as it would be after the change. If the editor changed since the card was made, Apply asks first, because the card replaces those edits too.
• On the edit page, a card can’t be applied until the mapping has loaded.
• Undo on the card puts back what the editor held before, until you edit on top of the applied change.

​

Cards made on another page

On the mapping list, in another mapping’s editor, and on the other knowledge-model pages (Ontology, Artifact Types, Enrichment Rules, Matching Strategies and Taxonomies), the copilot checks the mapping you name as saved and makes a card for it:

• The card reads Made for “Accounts” (Data Mapping) and has an Open “Accounts” button. It opens that mapping’s editor, where you apply the card and click Update.
• It is refused once the mapping has been saved again since the card was made (This data mapping was saved since this was proposed — ask the copilot again.), or once the ontology has (The ontology was saved since this was proposed — ask the copilot again.). If the editor has unsaved edits, Apply asks first.
• After an ontology Save that breaks a mapping, the copilot makes these cards by itself (see Continue after a Save).

Proposing needs the Data Source Managers role with write access, on top of the Graph Managers read access every knowledge-model tool needs. Without Data Source Managers read, the copilot has no data-mapping tools on any page. The copilot never saves, creates or duplicates a mapping, never fetches samples from a data source, and never starts a scan: your Save is the only writer of an edit. It re-validates, marks reviewed or deletes a mapping only as a page-action card that you confirm.