# 场景联动 SQL 参考

# 快速入门

FogCloud 场景联动支持一种类似 SQL 的语法来定义场景触发规则。SQL 语句由SELECT，FROM，WHERE三种子句构成。

子句	是否必须	说明
SELECT	必填	从传入的 MQTT 消息中提取信息并执行转换。使用的消息来自 FROM 子句中指定的 MQTT 主题。
FROM	必填	MQTT 消息主题筛选条件，支持 MQTT 主题通配符。
WHERE	可选	用于确定是否执行规则指定操作的条件逻辑。

SQL 语句示例如下：

SELECT params.brightness as brightness FROM 'fogcloud/+/+/thing/up/property/post' WHERE params.switch = 1

MQTT 消息示例如下：

{
  "id": 1,
  "method": "property.post",
  "params": {
    "brightness": 100,
    "switch": 1
  }
}

如果此消息在主题fogcloud/0e37a28c/00000001/thing/up/property/post上发布，则会触发该 SQL，如果 switch 属性等于 1，SQL 语句将输出如下结果：

{
  "brightness": 100
}

此 SQL 输出会发送给规则引擎-场景联动的执行动作中指定的 webhook 地址。发送内容如下：

{
  "scene_name": "string",
  "scene_id": "string",
  "timestamp": "int",
  "trigger_uri": "trigger/sql",
  "payload": {"brightness":100} //SQL输出的JSON对象
}

字段	类型	说明
scene_name	string	场景联动名称
scene_id	string	场景联动唯一标识
timestamp	int	时间戳，单位秒
trigger_uri	string	当触发类型为 SQL 时，固定为`trigger/sql`
payload	object	SQL 输出

# SELECT 子句

FogCloud SELECT 子句与 ANSI SQL SELECT 子句语法类似，支持数据类型、运算符、函数和二进制数据（不支持case when语句）。您可以使用 SELECT 子句从传入的 MQTT 消息中提取信息。

您可以使用 SELECT * 来获取整个传入的消息有效载荷，例如：

# 一条mqtt消息的topic是 'fogcloud/pk1/dn1/thing/ota/down'，
# 消息体是：{"version": "1.2.5", "module": "mcu"}
# SQL语句为：
SELECT * FROM 'fogcloud/pk1/dn1/thing/ota/down'
# 输出为：{"version": "1.2.5", "module": "mcu"}

如果消息体是 JSON 格式数据，你可以引用对象的字段，例如：

# 一条mqtt消息的topic是 'fogcloud/pk1/dn1/thing/ota/down'，
# 消息体是：{"version": "1.2.5", "module": "mcu"}
# SQL语句为：
SELECT version, module as a FROM 'fogcloud/pk1/dn1/thing/ota/down'
# 输出为：{"version": "1.2.5", "a": "mcu"}

您可以使用'.'语法来获取嵌套的 JSON 对象键值对，例如：

# 一条mqtt消息的topic是 'fogcloud/pk1/dn1/thing/property/post'，
# 消息体是：{"id": 1, "params": {"brightness": 100,"switch": 1}}
# SQL语句为：
SELECT params.brightness as brightness, id FROM 'fogcloud/pk1/dn1/thing/property/post'
# 输出为：{"brightness": 100, "id": 1}

您可以使用函数来对消息体进行转换，例如：

# 一条mqtt消息的topic是 'fogcloud/pk1/dn1/thing/property/post'，
# 消息体是：{"id": 1, "params": {"brightness": 100,"switch": 1}}
# SQL语句为：
SELECT (params.brightness * 2 - 10) as brightness, id FROM 'fogcloud/pk1/dn1/thing/property/post'
# 输出为：{"brightness": 190, "id": 1}

您可以使用get_base64_raw_payload()来获取 base64 编码后的二进制数据，例如：

# 一条mqtt消息的topic是 'fogcloud/pk1/dn1/thing/property/post'，
# 消息体是：hello,world
# SQL语句为：
SELECT get_base64_raw_payload() as raw FROM 'fogcloud/pk1/dn1/thing/property/post'
# 输出为：{"raw": "aGVsbG8sd29ybGQ="}

# FROM 子句

FROM 子句会按指定的 MQTT 主题过滤消息，主题需要括在单引号（'）内。您设备上报的所有匹配到指定主题的消息都会触发该规则。您可以再主题中使用通配符：+和#

#通配符：匹配一个或多个主题路径
+通配符：匹配单个主题路径

# WHERE 子句

WHERE 子句确定是否执行规则指定的操作。如果 WHERE 子句的计算结果为 true，则执行规则操作。否则，不执行规则操作。

# 数据类型

数据类型	说明
int	整型数，最大 48 位
decimal	浮点数，精度为 34 位小数
boolean	true or false
string	utf-8 编码的字符串
array	具有相同类型的数据集合
object	由键和值组成的 JSON 值。键必须是字符串。值可以是任何类型
null	JSON 定义的 Null。它是代表值缺失的实际值。您可以通过在 SQL 语句中使用 Null 关键字显式创建 Null 值。例如：“SELECT NULL AS n FROM '主题/子主题'”

# 运算符

运算符	语法	输出
and	{expression} and {expression}	boolean
or	{expression} or {expression}	boolean
not	not {expression}	boolean
in	{expression} in {expression}	boolean
>	{expression} > {expression}	boolean
>=	{expression} >= {expression}	boolean
<	{expression} < {expression}	boolean
<=	{expression} <= {expression}	boolean
!=	{expression} != {expression}	boolean
=	{expression} = {expression}	boolean
+	{expression} + {expression}	int/decimal
-	{expression} - {expression}	int/decimal
*	{expression} * {expression}	int/decimal
/	{expression} / {expression}	int/decimal
%	{expression} % {expression}	int/decimal

# 函数

函数名	入参	返回值	说明
# current_timestamp()	undefined	int	返回服务器当前时间戳，单位秒
# lower(string)	string	string	返回入参字符串的小写版本
# clientid()	undefined	string	返回当前 MQTT 消息发送方的 clientid
# topic()	undefined	string	返回当前 MQTT 消息的主题
# username()	undefined	string	返回当前 MQTT 消息发送方的 username
# get_base64_raw_payload()	undefined	string	返回当前 MQTT 消息体的 base64 编码后的字符串
# ipaddr()	undefined	string	返回当前 MQTT 消息发送方的 ip 地址