docs/en_US/json_expr.md

docs/zh_CN/json_expr.md

@@ -120,6 +120,65 @@ SELECT followers->Group1[:1]->first FROM demo
 }
 ```
 
+# Json Path functions
+
+Kuiper provides a list of functions to allow to execute json path over struct or array columns or values. The functions are:
+
+```tsql
+json_path_exists(col, jsonpath)
+json_path_query(col, jsonpath)
+json_path_query_first(col, jsonpath)
+```
+
+Please refer to [json functions](sqls/built-in_functions.md#json-functions) for detail.
+
+All these functions share the same parameter signatures, among which, the second parameter is a jsonpath string. The jsonpath grammer used by Kuiper is based on [JsonPath](https://goessner.net/articles/JsonPath/).  
+
+The basic grammar of those expressions is to use the keys part of the JSON objects combined with some elements:
+
+- Dots `.` to move into a tree
+- Brackets `[]` for access to a given array member coupled with a position. It can also access to a map field.
+- Variables, with `$` representing a JSON text and `@` for result path evaluations.
+
+So for example, when applied to the previous JSON data sample we can reach the following parts of the tree with these expressions:
+
+- `$.age` refers to 37.
+- `$.friends.first` refers to “dale”.
+- `$.friends` refers to the full array of friends.
+- `$.friends[0]` refers to the first friend listed in the previous array (contrary to arrays members are zero-based).
+- `$.friends[0][lastname]` refers to the lastname of the first friend listed. Use bracket if [there are reserved words](sqls/lexical_elements.md) or special characters (such as space ' ', '.' and Chinese etc) in the field key.
+- `$.friends[? @.age>60].first` or `$.friends[? (@.age>60)].first` refers to the first name of the friends whose age is bigger than 60. Notice that the space between ? and the condition is required even the condition is with braces.
+
+Developers can use the json functions in the SQL statement. Here are some examples.
+
+- Select the lastname of group1 followers
+```tsql
+SELECT json_path_query(followers, "$.Group1[*].last") FROM demo
+
+["Shavor","Miller"]
+```
+
+- Select the lastname if any of the group1 followers is older than 60
+```tsql
+SELECT name->last FROM demo where json_path_exists(followers, "$.Group1[? @.age>30]")
+
+"Anderson"
+```
+
+- Select the follower's lastname from group1 whose age is bigger than 30
+```tsql
+SELECT json_path_exists(followers, "$.Group1[? @.age>30].last") FROM demo
+
+["Miller"]
+```
+
+- Assume there is a field in follows with reserved words or chars like dot `my.follower`, use bracket to access it.
+```tsql
+SELECT json_path_exists(followers, "$[\"my.follower\"]") FROM demo
+
+["Miller"]
+```
+
 
 
 # *映射*

docs/zh_CN/sqls/built-in_functions.md

@@ -85,10 +85,19 @@ Kuiper具有许多内置函数，可以对数据执行计算。
 | sha384   | sha384(col1) | 参数的哈希值 |
 | sha512   | sha512(col1) | 参数的哈希值 |
 
+## JSON Functions
+| Function | Example     | Description                                    |
+| -------- | ----------- | ---------------------------------------------- |
+| json_path_exists      | json_path_exists(col1, "$.name")   | Checks whether JSON path returns any item for the specified JSON value. Return bool value.                   |
+| json_path_query     | json_path_query(col1, "$.name")  | Gets all items returned by JSON path for the specified JSON value.              |
+| json_path_query_first  | json_path_query_first(col1, "$.name")| Gets the first item returned by JSON path for the specified JSON value.                  |
+
+**Please refer to [json path functions](../json_expr.md#json-path-functions) for how to compose a json path.**  
 ## 其它函数
 | 函数      | 示例         | Description                                                  |
 | --------- | ------------ | ------------------------------------------------------------ |
 | isNull    | isNull(col1) | 如果参数为空值，则返回true。                                 |
 | newuuid   | newuuid()    | 返回一个随机的16字节UUID。                                   |
 | timestamp | timestamp()  | 返回当前时间戳，以1970年1月1日星期四00:00:00协调世界时（UTC）为单位。 |
-
+| mqtt      | mqtt(topic)  | Returns the MQTT meta-data of specified key. The current supported keys<br />- topic: return the topic of message.  If there are multiple stream source, then specify the source name in parameter. Such as ``mqtt(src1.topic)``<br />- messageid: return the message id of message. If there are multiple stream source, then specify the source name in parameter. Such as ``mqtt(src2.messageid)`` |
+| meta      | meta(topic)  | Returns the meta-data of specified key. The key could be:<br/> - a standalone key if there is only one source in the from clause, such as ``meta(device)``<br />- A qualified key to specify the stream, such as ``meta(src1.device)`` <br />- A key with arrow for multi level meta data, such as ``meta(src1.reading->device->name)`` This assumes reading is a map structure meta data.|