Merge pull request #2689 from emqx/add-undefined-vars-as-null

update(integration): Add "Undefined Vars as Null" config

Author: zmstone

en_US/data-integration/data-bridge-clickhouse.md

@@ -139,6 +139,18 @@ This section demonstrates how to create a rule in Dashboard for processing messa
 
     Here, `${data}` and `${timestamp}` represent the message content and timestamp, respectively, which will be configured later in the rules for message forwarding. EMQX will replace them with the corresponding content before forwarding the message.
 
+    If a placeholder variable is undefined in the SQL template, you can toggle the **Undefined Vars as Null** switch above the **SQL template** to define the rule engine behavior:
+
+    - **Disabled** (default): The rule engine can insert the string `undefined` into the database.
+
+    - **Enabled**: Allow the rule engine to insert `NULL` into the database when a variable is undefined.
+
+      ::: tip
+
+      If possible, this option should always be enabled; disabling the option is only used to ensure backward compatibility.
+
+      :::
+
 11. Advanced settings (optional): See [Advanced Configurations](#advanced-configurations).
 
 12. Before clicking **Create**, you can click the **Test Connectivity** button to ensure that you can connect to the ClickHouse server.

en_US/data-integration/data-bridge-dynamo.md

@@ -152,6 +152,18 @@ This section demonstrates how to create a rule in the Dashboard for processing m
 
    :::
 
+   If a placeholder variable is undefined in the SQL template, you can toggle the **Undefined Vars as Null** switch above the **SQL template** to define the rule engine behavior:
+
+   - **Disabled** (default): The rule engine can insert the string `undefined` into the database.
+
+   - **Enabled**: Allow the rule engine to insert `NULL` into the database when a variable is undefined.
+
+     ::: tip
+
+     If possible, this option should always be enabled; disabling the option is only used to ensure backward compatibility.
+
+     :::
+
 4. Click the + **Add Action** button to define an action that will be triggered by the rule. With this action, EMQX sends the data processed by the rule to DynamoDB.
 
 5. Select `DynamoDB` from the **Type of Action** dropdown list. Keep the **Action** dropdown with the default `Create Action` value. You can also select a Sink if you have created one. This demonstration will create a new Sink.

en_US/data-integration/data-bridge-mysql.md

@@ -164,6 +164,18 @@ This demonstration assumes that you run both EMQX and MySQL on the local machine
    )
    ```
 
+   If a placeholder variable is undefined in the SQL template, you can toggle the **Undefined Vars as Null** switch above the **SQL template** to define the rule engine behavior:
+
+   - **Disabled** (default): The rule engine can insert the string `undefined` into the database.
+
+   - **Enabled**: Allow the rule engine to insert `NULL` into the database when a variable is undefined.
+
+     ::: tip
+
+     If possible, this option should always be enabled; disabling the option is only used to ensure backward compatibility.
+
+     :::
+
 9. Advanced settings (optional):  See [Advanced Configurations](#advanced-configurations).
 
 10. Click the **Create** button to complete the Sink configuration. A new Sink will be added to the **Action Outputs.**

en_US/data-integration/data-bridge-sqlserver.md

@@ -271,6 +271,18 @@ This section demonstrates how to create a rule in the Dashboard for processing m
    insert into t_mqtt_msg(msgid, topic, qos, payload) values ( ${id}, ${topic}, ${qos}, ${payload} )
    ```
 
+   If a placeholder variable is undefined in the SQL template, you can toggle the **Undefined Vars as Null** switch above the **SQL template** to define the rule engine behavior:
+   
+   - **Disabled** (default): The rule engine can insert the string `undefined` into the database.
+   
+   - **Enabled**: Allow the rule engine to insert `NULL` into the database when a variable is undefined.
+   
+     ::: tip
+   
+     If possible, this option should always be enabled; disabling the option is only used to ensure backward compatibility.
+   
+     :::
+   
 9. Advanced settings (optional):  For details, see [Features of Sink](./data-bridges.md#features-of-sink).
 
 10. Before clicking **Create**, you can click **Test Connectivity** to test that the Sink can be connected to the Microsoft SQL Server.

en_US/data-integration/data-bridge-tdengine.md

@@ -140,6 +140,18 @@ This section demonstrates how to create a rule in the Dashboard for processing m
 
    :::
 
+   If a placeholder variable is undefined in the SQL template, you can toggle the **Undefined Vars as Null** switch above the **SQL template** to define the rule engine behavior:
+   
+   - **Disabled** (default): The rule engine can insert the string `undefined` into the database.
+   
+   - **Enabled**: Allow the rule engine to insert `NULL` into the database when a variable is undefined.
+   
+     ::: tip
+   
+     If possible, this option should always be enabled; disabling the option is only used to ensure backward compatibility.
+   
+     :::
+   
 4. Click the + **Add Action** button to define an action to be triggered by the rule. With this action, EMQX sends the data processed by the rule to TDengine.
 
 5. Select `TDengine` from the **Type of Action** dropdown list. Keep the **Action** dropdown with the default `Create Action` value. You can also select a TDengine Sink if you have created one. This demonstration will create a new Sink.

zh_CN/data-integration/data-bridge-clickhouse.md

@@ -124,6 +124,18 @@ ClickHouse 数据集成是 EMQX 中的开箱即用功能，旨在结合 MQTT 的
 
    :::
 
+   如果在模板中使用未定义的占位符变量，您可以切换**未定义变量作为 NULL** 开关（位于 **SQL 模板** 上方）来定义规则引擎的行为：
+
+   - **关闭**（默认）：规则引擎可以将字符串 `undefined` 插入数据库。
+
+   - **启用**：允许规则引擎在变量未定义时将 `NULL` 插入数据库。
+
+     ::: tip
+
+     如果可能，此选项应始终启用；禁用该选项仅用于确保向后兼容性。
+
+     :::
+
 5. 点击右侧的**添加动作**按钮，为规则在被触发的情况下指定一个动作。通过这个动作，EMQX 会将经规则处理的数据发送到 ClickHouse。
 
 6. 在**动作类型**下拉框中选择 `ClickHouse`，保持**动作**下拉框为默认的`创建动作`选项，您也可以选择一个之前已经创建好的 ClickHouse Sink。此处我们创建一个全新的 Sink 并添加到规则中。

zh_CN/data-integration/data-bridge-dynamo.md

@@ -146,6 +146,18 @@ docker run --rm -e AWS_ACCESS_KEY_ID=root -e AWS_SECRET_ACCESS_KEY=public -e AWS
      "t/#"
    ```
 
+   如果在模板中使用未定义的占位符变量，您可以切换**未定义变量作为 NULL** 开关（位于 **SQL 模板** 上方）来定义规则引擎的行为：
+
+   - **关闭**（默认）：规则引擎可以将字符串 `undefined` 插入数据库。
+
+   - **启用**：允许规则引擎在变量未定义时将 `NULL` 插入数据库。
+
+     ::: tip
+
+     如果您初次使用 SQL，可以点击 **SQL 示例** 和**启用调试**来学习和测试规则 SQL 的结果。
+
+     :::
+
    ::: tip
 
    如果您初次使用 SQL，可以点击 **SQL 示例** 和**启用调试**来学习和测试规则 SQL 的结果。

zh_CN/data-integration/data-bridge-mysql.md

@@ -136,6 +136,18 @@ CREATE TABLE emqx_client_events (
 
    :::
 
+   如果在模板中使用未定义的占位符变量，您可以切换**未定义变量作为 NULL** 开关（位于 **SQL 模板** 上方）来定义规则引擎的行为：
+
+   - **关闭**（默认）：规则引擎可以将字符串 `undefined` 插入数据库。
+
+   - **启用**：允许规则引擎在变量未定义时将 `NULL` 插入数据库。
+
+     ::: tip
+
+     如果您初次使用 SQL，可以点击 **SQL 示例**和**启用调试**来学习和测试规则 SQL 的结果。
+
+     :::
+
 4. 点击右侧的**添加动作**按钮，为规则在被触发的情况下指定一个动作。通过这个动作，EMQX 会将经规则处理的数据发送到 MySQL。
 
 5. 在**动作类型**下拉框中选择 MySQL，保持**动作**下拉框为默认的“创建动作”选项，您也可以选择一个之前已经创建好的 MySQL Sink。此处我们创建一个全新的 Sink 并添加到规则中。

zh_CN/data-integration/data-bridge-sqlserver.md

@@ -255,6 +255,18 @@ FileUsage   = 1
 
    :::
 
+   如果在模板中使用未定义的占位符变量，您可以切换**未定义变量作为 NULL** 开关（位于 **SQL 模板** 上方）来定义规则引擎的行为：
+   
+   - **关闭**（默认）：规则引擎可以将字符串 `undefined` 插入数据库。
+   
+   - **启用**：允许规则引擎在变量未定义时将 `NULL` 插入数据库。
+   
+     ::: tip
+   
+     如果您初次使用 SQL，可以点击 **SQL 示例** 和**启用调试**来学习和测试规则 SQL 的结果。
+   
+     :::
+   
 4. 点击右侧的**添加动作**按钮，为规则在被触发的情况下指定一个动作。通过这个动作，EMQX 会将经规则处理的数据发送到 Microsoft SQL Server。
 
 5. 在**动作类型**下拉框中选择 `Microsoft SQL Server`，保持**动作**下拉框为默认的`创建动作`选项，您也可以选择一个之前已经创建好的 Microsoft SQL Server Sink。此示例将创建一个全新的 Sink 并添加到规则中。

zh_CN/data-integration/data-bridge-tdengine.md

@@ -130,6 +130,18 @@ CREATE TABLE emqx_client_events (
      "t/#"
    ```
 
+   如果在模板中使用未定义的占位符变量，您可以切换**未定义变量作为 NULL** 开关（位于 **SQL 模板** 上方）来定义规则引擎的行为：
+
+   - **关闭**（默认）：规则引擎可以将字符串 `undefined` 插入数据库。
+
+   - **启用**：允许规则引擎在变量未定义时将 `NULL` 插入数据库。
+
+     ::: tip
+
+     如果您初次使用 SQL，可以点击 **SQL 示例** 和**启用调试**来学习和测试规则 SQL 的结果。
+
+     :::
+
    ::: tip
 
    如果您初次使用 SQL，可以点击 **SQL 示例**和**启用调试**来学习和测试规则 SQL 的结果。