MQTT Recorder Module - Usage and Configuration

After installing MQTT Recorder, you can configure a database connection and define how incoming records are written to database tables.

How MQTT Recorder Works

MQTT Recorder receives records from MQTT Engine and automatically stores them in a configured database.

Records are published using Sparkplug record topics such as:

spBv1.0/group/NRECORD/edgenode
spBv1.0/group/DRECORD/edgenode/device

Each record contains a Record Type and associated fields that MQTT Recorder uses to create database tables and insert rows automatically.

For example, a record may contain information for events, alarms, or historical process data received from remote devices.

---

Configure Settings

Enable MQTT Recorder

1. Navigate to Platform → MQTT Recorder → Settings.
2. Verify that Enabled is selected.
3. Click Save Changes.

Select a Database Connection

1. Select a database connection from the Datasource dropdown.

The list of available datasources is populated from the database connections configured in the Ignition Gateway.

Table Partition Period

The Table Partition Period setting controls how MQTT Recorder creates database tables over time, and can be useful when storing large volumes of historical data.

Partition Period	Example Table Name
None	alarm
Hourly	alarm_2022_12_10_02
Daily	alarm_2022_12_10
Weekly	alarm_2022_49
Monthly	alarm_2022_12
Yearly	alarm_2022

---

Configure Table Mappings

The Tables tab controls how records are mapped to database tables.

• By default, MQTT Recorder creates a single table definition: rs_${type}

With this configuration, a separate database table is automatically created for each unique Record Type.

Create a Custom Table Mapping

You can create custom table names using dynamic tokens.

Available Tokens

Token	Description
${type}	Record Type
${group}	Sparkplug Group ID
${edgenode}	Sparkplug Edge Node ID
${device}	Sparkplug Device ID
${field:<name>}	Value of a record field

Table Settings

Each table mapping can optionally filter records before inserting them into a database table.

Setting	Description
Enabled	Enables or disables the table definition.
Record Type	Only records matching the specified Record Type are inserted.
Group ID	Only records from the specified Sparkplug Group ID are inserted.
Edge Node ID	Only records from the specified Edge Node ID are inserted.
Device ID	Only records from the specified Device ID are inserted.
Field Filters	Filters records based on field values.

Configure Field Filters

Field Filters allow records to be routed to tables based on field values.

Field filters use one of the following formats:

• {<field>:<operator>:<value>}
• {<field>:NULL}
• {<field>:NOTNULL}

Supported operators:

• ==
• !=
• >
• <
• >=
• <=

❗ Values containing :, ;, or \ must be escaped with a leading backslash (\).

Verify Operation

After MQTT Recorder is enabled:

1. Confirm records are being received by MQTT Engine.
2. Verify that tables are created in the configured database.
3. Confirm that new rows are being inserted as records are received.

The table names and structure are automatically generated based on the configured table mappings and incoming record data.

---

Tags

MQTT Recorder automatically creates a set of tags used for signature validation.

MQTT Recorder Control

Signature Validation

The Signature Validation tags can be used to verify that records stored in the database were written using the expected hashing algorithm and have not been modified.

Name	Data Type	Description
Request Hashing Algorithm	String	Writable tag used to specify the hashing algorithm for validation.
Request Index Start	Long	First record index included in the validation request.
Request Index End	Long	Last record index included in the validation request.
Request Password	String	Database password used during validation.
Request Table Name	String	Name of the table containing the records to validate.
Result	Dataset	Dataset containing validation results for each record.
Status	String	Indicates whether the validation request completed successfully. If the value is Success, the Result dataset contains validation details.
Validate	Boolean	Writable tag that triggers signature validation.

Result Dataset

The Result dataset contains the following columns:

Column Name	Data Type	Description
index	Long	Record index.
signature	String	Record signature.
validated	Boolean	Indicates whether the record signature matches the calculated signature.
error	String	Error message generated during validation, if any.