This is an automated email from the ASF dual-hosted git repository.
jiangtian pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iotdb-docs.git
The following commit(s) were added to refs/heads/main by this push:
new 0dd1e470 Add a note regarding client_id in the MQTT documentation.
(#833)
0dd1e470 is described below
commit 0dd1e470f6dd060ecf7cce516eb7cdd4d0604139
Author: wenyanshi-123 <[email protected]>
AuthorDate: Thu Jul 17 09:35:43 2025 +0800
Add a note regarding client_id in the MQTT documentation. (#833)
Co-authored-by: shiwenyan <[email protected]>
---
src/UserGuide/Master/Table/API/Programming-MQTT.md | 14 +++++++++++++-
src/UserGuide/Master/Tree/API/Programming-MQTT.md | 12 +++++++++++-
src/zh/UserGuide/Master/Table/API/Programming-MQTT.md | 15 +++++++++++++++
src/zh/UserGuide/Master/Tree/API/Programming-MQTT.md | 13 +++++++++++++
4 files changed, 52 insertions(+), 2 deletions(-)
diff --git a/src/UserGuide/Master/Table/API/Programming-MQTT.md
b/src/UserGuide/Master/Table/API/Programming-MQTT.md
index 0a1ba4ec..91dec2b8 100644
--- a/src/UserGuide/Master/Table/API/Programming-MQTT.md
+++ b/src/UserGuide/Master/Table/API/Programming-MQTT.md
@@ -230,4 +230,16 @@ Then, in your server:
5. Now IoTDB will use your implementation to parse the MQTT message.
More: the message format can be anything you want. For example, if it is a
binary format,
-just use `payload.forEachByte()` or `payload.array` to get bytes content.
\ No newline at end of file
+just use `payload.forEachByte()` or `payload.array` to get bytes content.
+
+## 7. Caution
+
+To avoid compatibility issues caused by a default client_id, always explicitly
supply a unique, non-empty client_id in every MQTT client.
+Behavior varies when the client_id is missing or empty. Common examples:
+1. Explicitly sending an empty string
+• MQTTX: When client_id="", IoTDB silently discards the message.
+• mosquitto_pub: When client_id="", IoTDB receives the message normally.
+2. Omitting client_id entirely
+• MQTTX: IoTDB accepts the message.
+• mosquitto_pub: IoTDB rejects the connection.
+Therefore, explicitly assigning a unique, non-empty client_id is the simplest
way to eliminate these discrepancies and ensure reliable message delivery.
\ No newline at end of file
diff --git a/src/UserGuide/Master/Tree/API/Programming-MQTT.md
b/src/UserGuide/Master/Tree/API/Programming-MQTT.md
index fdb32543..df230ecd 100644
--- a/src/UserGuide/Master/Tree/API/Programming-MQTT.md
+++ b/src/UserGuide/Master/Tree/API/Programming-MQTT.md
@@ -178,5 +178,15 @@ Then, in your server:
More: the message format can be anything you want. For example, if it is a
binary format,
just use `payload.forEachByte()` or `payload.array` to get bytes content.
-
+## 6. Caution
+
+To avoid compatibility issues caused by a default client_id, always explicitly
supply a unique, non-empty client_id in every MQTT client.
+Behavior varies when the client_id is missing or empty. Common examples:
+1. Explicitly sending an empty string
+ • MQTTX: When client_id="", IoTDB silently discards the message.
+ • mosquitto_pub: When client_id="", IoTDB receives the message normally.
+2. Omitting client_id entirely
+ • MQTTX: IoTDB accepts the message.
+ • mosquitto_pub: IoTDB rejects the connection.
+ Therefore, explicitly assigning a unique, non-empty client_id is the
simplest way to eliminate these discrepancies and ensure reliable message
delivery.
diff --git a/src/zh/UserGuide/Master/Table/API/Programming-MQTT.md
b/src/zh/UserGuide/Master/Table/API/Programming-MQTT.md
index 0a8b08d5..56b0261b 100644
--- a/src/zh/UserGuide/Master/Table/API/Programming-MQTT.md
+++ b/src/zh/UserGuide/Master/Table/API/Programming-MQTT.md
@@ -232,3 +232,18 @@ public class CustomizedLinePayloadFormatter implements
PayloadFormatter {
More: MQTT 协议的消息不限于 line，你还可以用任意二进制。通过如下函数获得：
`payload.forEachByte()` or `payload.array`。
+
+## 7. 注意事项
+
+为避免因缺省client_id引发的兼容性问题，强烈建议在所有MQTT客户端中始终显式地提供唯一且非空的 client_id。
+不同客户端在client_id缺失或为空时的表现并不一致，常见示例如下：
+1. 显式传入空字符串
+• MQTTX：client_id=""时，IoTDB会直接丢弃消息；
+• mosquitto_pub：client_id=""时，IoTDB能正常接收消息。
+2. 完全不传client_id
+• MQTTX：消息可被IoTDB正常接收；
+• mosquitto_pub：IoTDB拒绝连接。
+由此可见，显式指定唯一且非空的client_id是消除上述差异、确保消息可靠投递的最简单做法。
+
+
+
diff --git a/src/zh/UserGuide/Master/Tree/API/Programming-MQTT.md
b/src/zh/UserGuide/Master/Tree/API/Programming-MQTT.md
index c291b1e6..9bcff388 100644
--- a/src/zh/UserGuide/Master/Tree/API/Programming-MQTT.md
+++ b/src/zh/UserGuide/Master/Tree/API/Programming-MQTT.md
@@ -176,3 +176,16 @@ public class CustomizedJsonPayloadFormatter implements
PayloadFormatter {
More: MQTT 协议的消息不限于 json，你还可以用任意二进制。通过如下函数获得：
`payload.forEachByte()` or `payload.array`。
+
+
+## 6. 注意事项
+
+为避免因缺省client_id引发的兼容性问题，强烈建议在所有MQTT客户端中始终显式地提供唯一且非空的 client_id。
+不同客户端在client_id缺失或为空时的表现并不一致，常见示例如下：
+1. 显式传入空字符串
+ • MQTTX：client_id=""时，IoTDB会直接丢弃消息；
+ • mosquitto_pub：client_id=""时，IoTDB能正常接收消息。
+2. 完全不传client_id
+ • MQTTX：消息可被IoTDB正常接收；
+ • mosquitto_pub：IoTDB拒绝连接。
+ 由此可见，显式指定唯一且非空的client_id是消除上述差异、确保消息可靠投递的最简单做法。
\ No newline at end of file
