Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: json related functions #1196

Merged
merged 2 commits into from
Sep 26, 2024
Merged

docs: json related functions #1196

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0d565b2
docs: json related functions
CookiePieWw Sep 25, 2024
dd7fca7
docs: add supported json op
CookiePieWw Sep 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 77 additions & 1 deletion docs/reference/sql/functions/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -247,4 +247,80 @@ select database();

### Admin Functions

GreptimeDB provides `ADMIN` statement to run the administration functions, please refer to [ADMIN](.(/reference/sql/admin.md) reference.
GreptimeDB provides `ADMIN` statement to run the administration functions, please refer to [ADMIN](.(/reference/sql/admin.md) reference.

### JSON Functions

GreptimeDB provides the following JSON functions to deal with values of JSON type:

* `parse_json(string)` to parse a JSON string into a JSON value. Illegal JSON strings will return an error.
* `json_to_string(json)` to convert a JSON value to a string.

```sql
SELECT json_to_string(parse_json('{"a": 1, "b": 2}'));

+----------------------------------------------------------+
| json_to_string(parse_json(Utf8("{\"a\": 1, \"b\": 2}"))) |
+----------------------------------------------------------+
| {"a":1,"b":2} |
+----------------------------------------------------------+
```

* `json_get_bool(json, path)` to extract a boolean value from a JSON value by the path.
* `json_get_int(json, path)` to extract an integer value from a JSON value by the path, while boolean values will be converted to integers.
* `json_get_float(json, path)` to extract a float value from a JSON value by the path, while integer and boolean values will be converted to floats.
WenyXu marked this conversation as resolved.
Show resolved Hide resolved
* `json_get_string(json, path)` to extract a string value from a JSON value by the path. All valid JSON values will be converted to strings, including null values, objects and arrays.

`path` is a string that select and extract elements from a json value. The following operators in the path are supported:

| Operator | Description | Examples |
|--------------------------|--------------------------------------------------------------|--------------------|
| `$` | The root element | `$` |
| `@` | The current element in the filter expression | `$.event?(@ == 1)` |
| `.*` | Selecting all elements in an Object | `$.*` |
| `.<name>` | Selecting element that match the name in an Object | `$.event` |
| `:<name>` | Alias of `.<name>` | `$:event` |
| `["<name>"]` | Alias of `.<name>` | `$["event"]` |
| `[*]` | Selecting all elements in an Array | `$[*]` |
| `[<pos>, ..]` | Selecting 0-based `n-th` elements in an Array | `$[1, 2]` |
| `[last - <pos>, ..]` | Selecting `n-th` element before the last element in an Array | `$[0, last - 1]` |
| `[<pos1> to <pos2>, ..]` | Selecting all elements of a range in an Array | `$[1 to last - 2]` |
| `?(<expr>)` | Selecting all elements that matched the filter expression | `$?(@.price < 10)` |

If the path is invalid, the function will return a NULL value.

```sql
SELECT json_get_int(parse_json('{"a": {"c": 3}, "b": 2}'), 'a.c');

+-----------------------------------------------------------------------+
| json_get_int(parse_json(Utf8("{"a": {"c": 3}, "b": 2}")),Utf8("a.c")) |
+-----------------------------------------------------------------------+
| 3 |
+-----------------------------------------------------------------------+
```

* `json_is_null(json)` to check whether a JSON value is a null value.
* `json_is_bool(json)` to check whether a JSON value is a boolean value.
* `json_is_int(json)` to check whether a JSON value is an integer value.
* `json_is_float(json)` to check whether a JSON value is a float value.
* `json_is_string(json)` to check whether a JSON value is a string value.
* `json_is_object(json)` to check whether a JSON value is an object value.
* `json_is_array(json)` to check whether a JSON value is an array value.

```sql
SELECT json_is_array(parse_json('[1, 2, 3]'));

+----------------------------------------------+
| json_is_array(parse_json(Utf8("[1, 2, 3]"))) |
+----------------------------------------------+
| 1 |
+----------------------------------------------+

SELECT json_is_object(parse_json('1'));

+---------------------------------------+
| json_is_object(parse_json(Utf8("1"))) |
+---------------------------------------+
| 0 |
+---------------------------------------+
```
78 changes: 77 additions & 1 deletion i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/functions/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -240,4 +240,80 @@ select database();

### 管理函数

GreptimeDB 提供了 `ADMIN` 语句来执行管理函数，请阅读 [ADMIN](/reference/sql/admin.md) 文档。
GreptimeDB 提供了 `ADMIN` 语句来执行管理函数，请阅读 [ADMIN](/reference/sql/admin.md) 文档。

### JSON 函数

GreptimeDB 提供了以下 JSON 相关函数来处理 JSON 类型的数据：

* `parse_json(string)` 尝试将字符串解析为 JSON 类型。非法的 JSON 字符串将返回错误。
* `json_to_string(json)` 将 JSON 类型的值转换为字符串。

```sql
SELECT json_to_string(parse_json('{"a": 1, "b": 2}'));

+----------------------------------------------------------+
| json_to_string(parse_json(Utf8("{\"a\": 1, \"b\": 2}"))) |
+----------------------------------------------------------+
| {"a":1,"b":2} |
+----------------------------------------------------------+
```

* `json_get_bool(json, path)` 按照路径 `path` 从 JSON 中获取布尔值。
* `json_get_int(json, path)` 按照路径 `path` 从 JSON 中获取整数值。布尔值将被转换为整数。
* `json_get_float(json, path)` 按照路径 `path` 从 JSON 中获取浮点数值。布尔值、整数值将被转换为浮点数。
* `json_get_string(json, path)` 按照路径 `path` 从 JSON 中获取字符串。所有类型的 JSON 值都将被转换为字符串，包括数组、对象和 null。

`path` 是一个用于从 JSON 值中选择和提取元素的字符串。`path` 中支持的操作符有：

| 操作符 | 描述 | 示例 |
|--------------------------|--------------------------------------------------------------|--------------------|
| `$` | 根元素 | `$` |
| `@` | 过滤表达式中的当前元素 | `$.event?(@ == 1)` |
| `.*` | 选择对象中的所有元素 | `$.*` |
| `.<name>` | 选择对象中匹配名称的元素 | `$.event` |
| `:<name>` | `.<name>` 的别名 | `$:event` |
| `["<name>"]` | `.<name>` 的别名 | `$["event"]` |
| `[*]` | 选择数组中的所有元素 | `$[*]` |
| `[<pos>, ..]` | 选择数组中基于0的第 `n` 个元素 | `$[1, 2]` |
| `[last - <pos>, ..]` | 选择数组中最后一个元素之前的第 `n` 个元素 | `$[0, last - 1]` |
| `[<pos1> to <pos2>, ..]` | 选择数组中某个范围内的所有元素 | `$[1 to last - 2]` |
| `?(<expr>)` | 选择所有匹配过滤表达式的元素 | `$?(@.price < 10)` |

如果 `path` 是无效的，函数将返回 `NULL`。

```sql
SELECT json_get_int(parse_json('{"a": {"c": 3}, "b": 2}'), 'a.c');

+-----------------------------------------------------------------------+
| json_get_int(parse_json(Utf8("{"a": {"c": 3}, "b": 2}")),Utf8("a.c")) |
+-----------------------------------------------------------------------+
| 3 |
+-----------------------------------------------------------------------+
```

* `json_is_null(json)` 检查 JSON 中的值是否为 `NULL`。
* `json_is_bool(json)` 检查 JSON 中的值是否为布尔值。
* `json_is_int(json)` 检查 JSON 中的值是否为整数。
* `json_is_float(json)` 检查 JSON 中的值是否为浮点数。
* `json_is_string(json)` 检查 JSON 中的值是否为字符串。
* `json_is_array(json)` 检查 JSON 中的值是否为数组。
* `json_is_object(json)` 检查 JSON 中的值是否为对象。

```sql
SELECT json_is_array(parse_json('[1, 2, 3]'));

+----------------------------------------------+
| json_is_array(parse_json(Utf8("[1, 2, 3]"))) |
+----------------------------------------------+
| 1 |
+----------------------------------------------+

SELECT json_is_object(parse_json('1'));

+---------------------------------------+
| json_is_object(parse_json(Utf8("1"))) |
+---------------------------------------+
| 0 |
+---------------------------------------+
```
Loading