The MQTT job provides a way to subscribe for messages with an MQTT message broker. The messages are continuously read from one or multiple matching topics in CSV, JSON or plain text formats and stored as series, property, and message commands in the Axibase Time Series Database.

Job Settings

The connection to the target MQTT broker is set at the job level and applies to all configurations within the same job. The MQTT Broker setting at the job level specifies which MQTT broker to connect to. The list of brokers can be configured on the Data Sources > MQTT Brokers page or by clicking on the plus icon.

MQTT job settings

Job Configuration

The job may contain multiple configurations with each configuration representing a separate subscription.

Click Create Configuration to create a subscription.

Topic Filter

The Topic field contains the filter expression which can select a specific topic or match multiple topics using / as the level delimiter and # as the multi-level wildcard.


  • A/topic-1 - subscribe to the A/topic-1 topic.
  • A/# - subscribe to all topics under the A level, for example A/topic-1 and A/topic-2, but not B/topic-1.

Message Format

Format Description Supported Command Types
CSV Multi-line comma-separated text. Series, property, message.
TEXT Free-form text. Series, property, message.
JSON JSON document Series.


Format Description
NONE Payload message is processed as text, without decompression.
ZIP Payload message is decompressed with zip codec.
GZ Payload message is decompressed with gzip codec.

CSV Format

If CSV format is selected, the message is automatically split into lines and the expression in the Command Template field is applied to each line separately.


The following variables can be included in the command template and passed to functions:

Name Description
job Current job name.
configuration Current configuration Name.
topic Message source topic.
receiveTime Message delivery in Unix milliseconds.
host Broker host.
port Broker port.
text Message payload, the entire text consisting of all lines.
line Current line in the CSV document.


Name Description
cell(int n) n - column index, starts with 1 for the first column.
Returns the value of n-th cell in the current line by index.
Returns an empty string if the index is out of range.

Configuration Example

Sample message payload, consisting of two lines without a header:


Command template, applied to each line:

series d:${cell(2)} e:${cell(1)} t:topic=${topic} m:${cell(4)}=${cell(5)} m:${cell(6)}=${cell(7)}

Series commands produced by applying the template to each line:

series d:2019-04-16T11:16:59.189Z e:br-1116 t:topic=/test/bioreactor m:temperature=90.44 m:pressure=4.0
series d:2019-04-16T11:16:59.148Z e:br-1489 t:topic=/test/bioreactor m:temperature=30.31 m:pressure=4.6


JSON Format

If JSON format is selected, the payload is parsed as a JSON document and the ATSD series command fields are extracted from the named fields in the JSON document.


If the message payload is an array, each element in the array is processed as a separate JSON document.

    { -- document-1 > command-1 },
    { -- document-2 > command-2 }

Key-Value Maps

If the JSON document contains an object with paired names and values, use the Transformation section to extract the pairs into series tags.

"props": [
      { "pname": "Site", "pval": "NUR" },
      { "pname": "Building", "pval": "A-1" }

Entity Fields

Name Description
Field Entity name, specified literally or extracted from the specific field in the document.
Default Value Default value applied if the entity name cannot be extracted from the payload message.

The Default Value can include placeholders with the following variables, for example ${host}.

Name Description
job Current job name.
configuration Configuration name.
topic Topic name.
host Broker host.
port Broker port.

Time Fields

Name Description
Field Name of the JSON field containing the event date.
Format Date pattern applied when parsing the date.
Zone Timezone applied to the parsed date if the format lacks the timezone information, otherwise the Collector time zone is in effect.

Series Fields

Name Description
Metric Prefix Text added to the metric name.
Included Fields By default, all numeric fields from nested objects are included in the series command as metrics. To override, specify the list of included fields by name, separated by comma.
Excluded Fields List of field names excluded from the command. Applies when Included Fields is empty.
Annotation Fields List of field names whose values are saved as text annotation.
Name & Value Fields Name of the field containing the metric name and metric value.

MQTT JSON mapping settings

TEXT Format

If TEXT format is selected, enter an expression in the Command Template field to convert message text to a valid ATSD command.

All variables for CSV mode are available in TEXT mode as well except the line variable.