# 场景联动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地址