A guide to Data Mapping in IXON Cloud

In modern IoT architectures, a single database is rarely enough. To provide a rich user experience while maintaining high-performance data ingestion, we split the responsibility between two worlds:

Relational: Stores human-readable names, relationships, and configurations (e.g. publicId of an agent or of a dataSource).
Time-Series: Stores high-speed, raw time-series data points (e.g. a sensor's temperature as value at a specific time) using optimized IDs.

This article explains how these two worlds are connected; this knowledge is particularly useful to understand the mechanisms behind data retrieval via direct InfluxDB access.

1. The Relational Architecture

In our relational database, data is organized hierarchically. This allows for strict validation and easy navigation of the structure of our Cloud. Here are a few brief definitions of the actors involved:

Agent: The physical hardware gateway.
DataSource: The specific protocol or device (e.g., a PLC) connected to the Agent.
Tag: The specific data point being tracked.
Variable: Defines the "flavor" of the data (Boolean, Integer, etc.).

Limitations

While this structure is great for organization, querying billions of rows in this nested format would be incredibly slow. This is why we "flatten" this data when it moves to the time'series database instance, only storing relevant IDs as Field Keys and Timestamps.

2. The Time-Series Architecture

As we already implied in the previous paragraph, InfluxDB doesn't care about "Names" or "Relationships"; it cares about Keys and Timestamps. To keep InfluxDB lean, we avoid storing strings like "Main Conveyor Belt" for every data point. Instead, we use IDs.

The connection is made via a generated Field Key. By combining the Variable Type and the Tag ID, we create a unique identifier that tells InfluxDB exactly what kind of data it is holding without needing to perform a "Join" with the relational database.

3. Actor Mapping: Who Lives Where?

Use this table to understand where each piece of information is mastered and how it is referenced across databases.

Actor	Found in MariaDB API?	Found in InfluxDB?	Role in the Flow
Agent	Yes	No	Its `publicId` (`string`) is retrieved and used to find one or more data source(s).
Data Source	Yes	Yes (as Reference)	Its `publicId` (`string`) is used as the `device` tag filter.
Tag	Yes	Yes (as Derived ID)	Its `tagId` (`int`) is the suffix of the Influx field, unique on a data-source basis (e.g. `37`).
Variable	Yes	Yes (as Type Prefix)	Its `type` (`string`) is the prefix of the Influx field (e.g. `"bool"`, `"int"`).
Retention Policy	Yes	Yes	A piece of text (`string`) that determines how long data is kept (e.g. `"260w"`, meaning "260 weeks").

4. The Structure of a TagID as Field Key

This table shows exactly how the information you see in your API results translates into the keys you need for an InfluxDB query.

If your API metadata returns...	Your Code Logic	InfluxDB Field Key
Type: `bool`, TagID: `37`	`bool` + `_` + `37`	`bool_37`
Type: `float`, TagID: `102`	`float` + `_` + `102`	`float_102`
Type: `int`, TagID: `5`	`int` + `_` + `5`	`int_5`

Example Implementation

When your application wants to display a graph for "Temperature," the underlying logic looks like this:

API Context: You find that "Temperature" has a tagId of 42 and a type of float.
Mapping: Your code generates the field name float_42.
Query: You run SELECT "float_42" FROM "device" WHERE "device" = 'YOUR_DATASOURCE_ID'.

Conclusion

By separating Configuration (Relations) from Data (InfluxDB), IXON Cloud ensures that your metadata remains rich and searchable while your historical data remains lightning-fast.