docs: add docs for functions (#1895)

* add docs

Signed-off-by: yisaer <disxiaofei@163.com>

* address the comment

Signed-off-by: yisaer <disxiaofei@163.com>

* address the comment

Signed-off-by: yisaer <disxiaofei@163.com>

* address the comment

Signed-off-by: yisaer <disxiaofei@163.com>

---------

Signed-off-by: yisaer <disxiaofei@163.com>

docs/en_US/sqls/built-in_functions.md

@@ -179,6 +179,21 @@ When casting to datetime type, the supported column type and casting rule are:
 
 Currently, 'zlib', 'gzip', 'flate' and 'zstd' method are supported.
 
+## Array Functions
+
+| Function   | Example                   | Description                                                                                                                          |
+|------------|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
+| array_position | array_postion(array, value) | Return a 0-based index of the first occurrence of val if it is found within array. If val does not exist within array, it returns -1 |
+| element_at | element_at(array, index) | Returns element of array at index val. If val < 0, this function accesses elements from the last to the first                        |
+| array_contains | array_contains(array, value) | Returns true if array contains the element                                                                                           |
+| array_create | array_create(value1, ......) | Construct an array from literals                                                                                                     |
+
+## Object Functions
+
+| Function   | Example                   | Description                                                           |
+|------------|---------------------------|-----------------------------------------------------------------------|
+| keys | keys(map[string]interface{}) | Return an array containing the keys of the map |
+
 ## Analytic Functions
 
 Analytic functions always use state to do analytic jobs. In streaming processing, analytic functions are evaluated first so that they are not affected by predicates in WHERE clause.

docs/zh_CN/sqls/built-in_functions.md

@@ -179,6 +179,21 @@ eKuiper 具有许多内置函数，可以对数据执行计算。
 
 目前支持 'zlib', 'gzip', 'flate' 和 'zstd' 压缩算法。
 
+## 列表函数
+
+| 函数         | 示例                    | 说明              |
+|------------|-----------------------|-----------------|
+| array_position | array_postion(array, value) | 返回第二个参数在列表参数中的索引下标位置，索引下标从 0 开始，若该元素不存在，则返回 -1 |
+| element_at | element_at(array, index) | 返回列表参数中在给定索引下的元素，索引下标从 0 开始，若该索引小于 0，则该元素从列表末向列表头进行计数 |
+| array_contains | array_contains(array, value) | 返回给定元素是否存在列表参数中，存在则返回 true，否则返回 false |
+| array_create | array_create(value1, ......) | 将给定的元素参数们创建为一个列表元素 |
+
+## 对象函数
+
+| 函数         | 示例                        | 说明              |
+|------------|---------------------------|-----------------|
+| keys | keys(map[string]interface{}) | 返回的给定的 map 参数中的所有 key 值 |
+
 ## 分析函数
 
 分析函数会保持状态来做分析工作。在流式处理规则中，分析函数会首先被执行，这样它们就不会受到 WHERE 子句的影响而必不更新状态。

internal/binder/function/funcs_array.go

@@ -46,10 +46,10 @@ func registerArrayFunc() {
 			}
 			for i, item := range array {
 				if item == args[1] {
-					return i + 1, true
+					return i, true
 				}
 			}
-			return 0, true
+			return -1, true
 		},
 		val: func(ctx api.FunctionContext, args []ast.Expr) error {
 			return ValidateLen(2, len(args))
@@ -65,14 +65,11 @@ func registerArrayFunc() {
 				if err != nil {
 					return err, false
 				}
-				if index == 0 {
-					return fmt.Errorf("index should be larger or smaller than 0"), false
-				}
-				if index-1 >= len(array) || (-index)-1 >= len(array) {
+				if index >= len(array) || -index > len(array) {
 					return errorArrayIndex, false
 				}
-				if index > 0 {
-					return array[index-1], true
+				if index >= 0 {
+					return array[index], true
 				}
 				return array[len(array)+index], true
 			case map[string]interface{}:

internal/binder/function/funcs_array_test.go

@@ -57,7 +57,7 @@ func TestArrayFunctions(t *testing.T) {
 				[]interface{}{3, 2, 1},
 				1,
 			},
-			result: 3,
+			result: 2,
 		},
 		{
 			name: "array_position",
@@ -65,7 +65,7 @@ func TestArrayFunctions(t *testing.T) {
 				[]interface{}{3, 2, 1},
 				4,
 			},
-			result: 0,
+			result: -1,
 		},
 		{
 			name: "length",
@@ -84,13 +84,6 @@ func TestArrayFunctions(t *testing.T) {
 		{
 			name: "element_at",
 			args: []interface{}{
-				[]interface{}{1, 2, 3}, 0,
-			},
-			result: fmt.Errorf("index should be larger or smaller than 0"),
-		},
-		{
-			name: "element_at",
-			args: []interface{}{
 				[]interface{}{1, 2, 3}, 4,
 			},
 			result: errorArrayIndex,
@@ -107,7 +100,7 @@ func TestArrayFunctions(t *testing.T) {
 			args: []interface{}{
 				[]interface{}{1, 2, 3}, 1,
 			},
-			result: 1,
+			result: 2,
 		},
 		{
 			name: "element_at",