How does field mapping work when importing data?

Field mapping is how the platform translates your data source's format into the internal format it needs. Every data source has different column names, field structures, and conventions — field mapping bridges that gap.

What gets mapped

When you import data (file upload, API connection, webhook, or email), the AI analyzes your source and creates mappings between:

Source fields — the column names or JSON keys in your data (e.g., "Total_kWh", "Reading_Timestamp", "Meter_ID")
Target fields — the platform's internal fields (e.g., "value", "timestamp", "external_id")

Each mapping also records the data type (number, datetime, string) and any transform needed (e.g., date format conversion, unit scaling).

How field mapping happens

You select a data category (Energy, Water, Gas, Climate, Solar, Parking, Waste, or Custom)
The platform sends category-specific field hints to the AI — keywords that help it identify relevant columns
The AI analyzes your source and returns field mappings, each with a confidence score (0–100%)
You review the detected fields and meters before confirming

Field hints and ignore hints

Each data category has built-in hints that guide the AI:

Field hints (include): Keywords the AI looks for when identifying relevant columns. For energy: kWh, consumption, active_power, demand, meter_reading. For water: m³, volume, flow, liters. For climate: temperature, humidity, CO2, air_quality.
Ignore hints (exclude): Fields the AI should skip. For energy: reactive power, phase voltage, harmonics. These are electrically relevant but not consumption data.

For the Custom category, you can type your own field hints as a comma-separated list.

After mapping — discovered meters

When the AI maps your fields, it also identifies distinct meters in the source data. These appear as "discovered meters" with:

External ID: The meter's identifier in the source system
Suggested name: A readable name the AI inferred
Meter type: Main meter, sub-meter, production, virtual, or check meter
Energy carrier: Electricity, heating, water, gas, cooling, etc.
Unit: kWh, m³, kW, etc.
Confidence score: How certain the AI is about this meter's mapping

What to do after import

After the AI completes, a review modal shows the discovered meters. You can:

Assign each meter to a building or a specific local (unit/space) within a building
Skip meters you do not need
See which meters already exist (duplicate detection by external ID)

Once confirmed, the meters are created and linked to the data import, and readings begin flowing into charts.

If field mapping fails or looks wrong

Choose a more specific data category (e.g., "Water" instead of "Custom") to give the AI better hints
For Custom imports, add descriptive field hints that match your source column names
Check the confidence scores — anything below 70% should be reviewed carefully
For API imports, provide a more complete Swagger/OpenAPI spec or add API notes describing the response structure

Where to start: Analytics → Data Import → select your import method → choose a data category → follow the setup steps.