MQTT Protocol

1. Overview

MQTT (Message Queuing Telemetry Transport) is a lightweight messaging protocol designed for IoT and low-bandwidth environments. It operates on a Publish/Subscribe (Pub/Sub) model, enabling efficient and reliable bidirectional communication between devices. Its core objectives are low power consumption, minimal bandwidth usage, and high real-time performance, making it ideal for unstable networks or resource-constrained scenarios (e.g., sensors, mobile devices).

IoTDB provides deep integration with the MQTT protocol, fully compliant with MQTT v3.1 (OASIS International Standard). The IoTDB server includes a built-in high-performance MQTT Broker module, eliminating the need for third-party middleware. Devices can directly write time-series data into the IoTDB storage engine via MQTT messages.

2. Configuration

By default, the IoTDB MQTT service loads configurations from ${IOTDB_HOME}/${IOTDB_CONF}/iotdb-system.properties.

Property	Description	Default
enable_mqtt_service	Enable/ disable the MQTT service.	FALSE
mqtt_host	Host address bound to the MQTT service.	127.0.0.1
mqtt_port	Port bound to the MQTT service.	1883
mqtt_handler_pool_size	Thread pool size for processing MQTT messages.	1
mqtt_payload_formatter	Formatting method for MQTT message payloads. ​​Options: json (tree model), line (table model).	json
mqtt_max_message_size	Maximum allowed MQTT message size (bytes).	1048576

3. Write Protocol

• Line Protocol Syntax

<measurement>[,<tag_key>=<tag_value>[,<tag_key>=<tag_value>]][ <attribute_key>=<attribute_value>[,<attribute_key>=<attribute_value>]] <field_key>=<field_value>[,<field_key>=<field_value>] [<timestamp>]

• Example

myMeasurement,tag1=value1,tag2=value2 attr1=value1,attr2=value2 fieldKey="fieldValue" 1556813561098000000

4. Naming Conventions

• Database Name

The first segment of the MQTT topic (split by /) is used as the database name.

topic: stock/Legacy
databaseName: stock


topic: stock/Legacy/#
databaseName:stock

• Table Name

The table name is derived from the <measurement> in the line protocol.

• Type Identifiers

Filed Value	IoTDB Data Type
1 1.12	DOUBLE
1f 1.12f	FLOAT
1i 123i	INT64
1u 123u	INT64
1i32 123i32	INT32
"xxx"	TEXT
t,T,true,True,TRUE f,F,false,False,FALSE	BOOLEAN