Skip to content

Commit

Permalink
add doc of func
Browse files Browse the repository at this point in the history
  • Loading branch information
yangj1211 committed Oct 29, 2024
1 parent 32f4466 commit 9a4c2e3
Show file tree
Hide file tree
Showing 9 changed files with 231 additions and 0 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,14 @@ mysql> select now();
+----------------------------+
1 row in set (0.03 sec)

mysql> select now()+1;
+-------------------+
| now() + 1 |
+-------------------+
| 1730168483.512705 |
+-------------------+
1 row in set (0.00 sec)

mysql> select now(6);
+----------------------------+
| now(6) |
Expand Down
49 changes: 49 additions & 0 deletions docs/MatrixOne/Reference/Functions-and-Operators/Json/jq.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# **JQ()**

## **函数说明**

`JQ()` 函数用于根据 jq 表达式解析和转换 JSON 数据。与 [`TRY_JQ()`](./try_jq.md) 不同的是,`TRY_JQ()` 支持出错时返回空值,而 `JQ()` 遇到错误则直接抛出异常。

## **语法结构**

```sql
select jq(jsonDoc, pathExpression);
```

## **参数释义**

| 参数 | 说明 |
| ---- | ---- |
| jsonDoc | 这是包含 JSON 数据的列或表达式。|
| pathExpression | 用于指定如何从 JSON 数据中提取字段|

## **示例**

```sql
mysql> select jq('{"foo": 128}', '.foo');
+------------------------+
| jq({"foo": 128}, .foo) |
+------------------------+
| 128 |
+------------------------+
1 row in set (0.01 sec)

mysql> select jq(null, '.foo');
+----------------+
| jq(null, .foo) |
+----------------+
| NULL |
+----------------+
1 row in set (0.00 sec)

mysql> select jq('{"id": "sample", "10": {"b": 42}}', '{(.id): .["10"].b}');
+-----------------------------------------------------------+
| jq({"id": "sample", "10": {"b": 42}}, {(.id): .["10"].b}) |
+-----------------------------------------------------------+
| {"sample":42} |
+-----------------------------------------------------------+
1 row in set (0.00 sec)

mysql> select jq('[1, 2, 3]', '.foo & .bar');
ERROR 1105 (HY000): unexpected token "&"
```
33 changes: 33 additions & 0 deletions docs/MatrixOne/Reference/Functions-and-Operators/Json/json_row.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# **JSON_ROW()**

## **函数说明**

`JSON_ROW()` 用于将每一行转化为 json 数组。

## **语法结构**

```sql
select json_row(col) from tabl_name;
```

## **示例**

```sql
create table student(n1 int,n2 json);
insert into student values
(1,'{"name": "tom", "age": 18, "score": 90,"gender": "male"}'),
(2,'{"name": "bob", "age": 20, "score": 80,"gender": "male"}'),
(3,'{"name": "jane", "age": 17, "score": 95,"gender": "female"}'),
(4,'{"name": "lily", "age": 19, "score": 79,"gender": "female"}');

mysql> select json_row(null,n2) from student;
+---------------------------------------------------------------------+
| json_row(null, n2) |
+---------------------------------------------------------------------+
| [null,{"age": 18, "gender": "male", "name": "tom", "score": 90}] |
| [null,{"age": 20, "gender": "male", "name": "bob", "score": 80}] |
| [null,{"age": 17, "gender": "female", "name": "jane", "score": 95}] |
| [null,{"age": 19, "gender": "female", "name": "lily", "score": 79}] |
+---------------------------------------------------------------------+
4 rows in set (0.00 sec)
```
54 changes: 54 additions & 0 deletions docs/MatrixOne/Reference/Functions-and-Operators/Json/try_jq.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# **TRY_JQ()**

## **函数说明**

`TRY_JQ()` 函数用于根据 jq 表达式解析和转换 JSON 数据。与 [`JQ()`](./jq.md) 不同的是,`TRY_JQ()` 支持出错时返回空值,而 `JQ()` 遇到错误则直接抛出异常。

## **语法结构**

```sql
select try_jq(jsonDoc, pathExpression);
```

## **参数释义**

| 参数 | 说明 |
| ---- | ---- |
| jsonDoc | 这是包含 JSON 数据的列或表达式。|
| pathExpression | 用于指定如何从 JSON 数据中提取字段|

## **示例**

```sql
mysql> select try_jq('{"foo": 128}', '.foo');
+----------------------------+
| try_jq({"foo": 128}, .foo) |
+----------------------------+
| 128 |
+----------------------------+
1 row in set (0.00 sec)

mysql> select try_jq(null, '.foo');
+--------------------+
| try_jq(null, .foo) |
+--------------------+
| NULL |
+--------------------+
1 row in set (0.00 sec)

mysql> select try_jq('{"id": "sample", "10": {"b": 42}}', '{(.id): .["10"].b}');
+---------------------------------------------------------------+
| try_jq({"id": "sample", "10": {"b": 42}}, {(.id): .["10"].b}) |
+---------------------------------------------------------------+
| {"sample":42} |
+---------------------------------------------------------------+
1 row in set (0.00 sec)

mysql> select try_jq('[1, 2, 3]', '.foo & .bar');
+--------------------------------+
| try_jq([1, 2, 3], .foo & .bar) |
+--------------------------------+
| NULL |
+--------------------------------+
1 row in set (0.00 sec)
```
Original file line number Diff line number Diff line change
Expand Up @@ -174,11 +174,14 @@

| 函数名称 | 作用 |
| --------------------------------------------- | --------------------------------------- |
| [JQ()](./Json/jq.md) | 用于根据 jq 表达式解析和转换 JSON 数据|
| [JSON_EXTRACT()](./Json/json_extract.md) | 从 JSON 文档返回数据|
| [JSON_EXTRACT_FLOAT64()](./Json/json_extract_float64.md) | 从 JSON 数据中提取指定路径的数值的值|
| [JSON_EXTRACT_STRING()](./Json/json_extract_string.md) | 从 JSON 数据中提取指定路径的字符串的值|
| [JSON_QUOTE()](./Json/json_quote.md) | 引用 JSON 文档|
| [JSON_ROW()](./Json/json_row.md) | 用于将每一行转化为 json 数组|
| [JSON_UNQUOTE()](./Json/json_unquote.md) | 取消引用 JSON 文档|
| [TRY_JQ()](./Json/try_jq.md) | 用于根据 jq 表达式解析和转换 JSON 数据,并提供容错机制|

## 系统运维函数

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,7 @@
| [BINARY()](binary.md) | 将值转换为二进制字符串的函数 |
| [CAST()](cast.md) | 将值转换为特定类型,用于小数转数值和字符型 |
| [CONVERT()](convert.md) | 将值转换为特定类型,用于日期和时间值、小数之间进行转换 |
| [DECODE()](decode.md) | 用于对 ENCODE() 编码的数据进行解密 |
| [ENCODE()](encode.md) | 用于对字符串进行对称加密 |
| [SERIAL()](serial.md) | 将连接串序列化,不处理 NULL 值 |
| [SERIAL_FULL()](serial_full.md) | 将连接串序列化,处理 NULL 值 |
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# **DECODE()**

## **函数说明**

`DECODE()` 函数用于对 [`ENCODE()`](./encode.md) 编码的数据进行解密。

## **函数语法**

```
> DECODE(crypt_str, pass_str)
```

## **参数释义**

| 参数 | 说明 |
| --------------- | ------------------------------ |
| crypt_str | 通过 ENCODE() 编码后的加密字符串。 |
| pass_str | 用于解密的密码字符串,必须与加密时使用的密钥相同。 |

## **示例**

```SQL
mysql> SELECT DECODE(ENCODE('hello', 'mysecretkey'), 'mysecretkey');
+-------------------------------------------------+
| DECODE(ENCODE(hello, mysecretkey), mysecretkey) |
+-------------------------------------------------+
| hello |
+-------------------------------------------------+
1 row in set (0.00 sec)

CREATE TABLE users (
id INT AUTO_INCREMENT PRIMARY KEY,
username VARCHAR(255),
encrypted_password BLOB
);

INSERT INTO users (username, encrypted_password)
VALUES ('john', ENCODE('password123', 'mysecretkey'));

mysql> SELECT username, DECODE(encrypted_password, 'mysecretkey') AS decrypted_password FROM users WHERE username = 'john';
+----------+--------------------+
| username | decrypted_password |
+----------+--------------------+
| john | password123 |
+----------+--------------------+
1 row in set (0.00 sec)
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# **ENCODE()**

## **函数说明**

`ENCODE()` 函数用于对字符串进行对称加密。它通过结合一个秘钥来对字符串进行编码,并且解码时需要使用相同的密钥。需配合 [`DECODE()`](./decode.md) 解密。

## **函数语法**

```
> ENCODE (str, pass_str);
```

## **参数释义**

| 参数 | 说明 |
| --------------- | ------------------------------ |
| str | 要编码的原始字符串。 |
| pass_str | 用于加密的密码字符串(密钥)。 |

## **示例**

```SQL
mysql> SELECT ENCODE('hello', 'mysecretkey');
+----------------------------+
| ENCODE(hello, mysecretkey) |
+----------------------------+
| ?;? |
+----------------------------+
1 row in set (0.00 sec)
```
5 changes: 5 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -482,6 +482,8 @@ nav:
- BINARY: MatrixOne/Reference/Operators/operators/cast-functions-and-operators/binary.md
- CAST: MatrixOne/Reference/Operators/operators/cast-functions-and-operators/cast.md
- CONVERT: MatrixOne/Reference/Operators/operators/cast-functions-and-operators/convert.md
- DECODE: MatrixOne/Reference/Operators/operators/cast-functions-and-operators/decode.md
- ENCODE: MatrixOne/Reference/Operators/operators/cast-functions-and-operators/encode.md
- SERIAL: MatrixOne/Reference/Operators/operators/cast-functions-and-operators/serial.md
- SERIAL_FULL: MatrixOne/Reference/Operators/operators/cast-functions-and-operators/serial_full.md
- 比较函数和运算符:
Expand Down Expand Up @@ -654,11 +656,14 @@ nav:
- RANK(): MatrixOne/Reference/Functions-and-Operators/Window-Functions/rank.md
- ROW_NUMBER(): MatrixOne/Reference/Functions-and-Operators/Window-Functions/row_number.md
- JSON 函数:
- JQ(): MatrixOne/Reference/Functions-and-Operators/Json/jq.md
- JSON_EXTRACT(): MatrixOne/Reference/Functions-and-Operators/Json/json_extract.md
- JSON_EXTRACT_FLOAT64(): MatrixOne/Reference/Functions-and-Operators/Json/json_extract_float64.md
- JSON_EXTRACT_STRING(): MatrixOne/Reference/Functions-and-Operators/Json/json_extract_string.md
- JSON_QUOTE(): MatrixOne/Reference/Functions-and-Operators/Json/json_quote.md
- JSON_ROW(): MatrixOne/Reference/Functions-and-Operators/Json/json_row.md
- JSON_UNQUOTE(): MatrixOne/Reference/Functions-and-Operators/Json/json_unquote.md
- TRY_JQ(): MatrixOne/Reference/Functions-and-Operators/Json/try_jq.md
- 其他函数:
- LOAD_FILE: MatrixOne/Reference/Functions-and-Operators/Other/load_file.md
- SAVE_FILE: MatrixOne/Reference/Functions-and-Operators/Other/save_file.md
Expand Down

0 comments on commit 9a4c2e3

Please sign in to comment.