diff --git a/docs/reference/sql/functions/json.md b/docs/reference/sql/functions/json.md new file mode 100644 index 000000000..d3af9ae9d --- /dev/null +++ b/docs/reference/sql/functions/json.md @@ -0,0 +1,121 @@ + +# JSON Functions + +This page lists all json type related functions in GreptimeDB. + + +## Conversion + +Conversion between JSON and other types. + +* `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} | ++----------------------------------------------------------+ +``` + +## Extraction + +Extracts values with specific types from JSON values through specific paths. + +* `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. +* `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 | `$.*` | +| `.` | Selecting element that match the name in an Object | `$.event` | +| `:` | Alias of `.` | `$:event` | +| `[""]` | Alias of `.` | `$["event"]` | +| `[*]` | Selecting all elements in an Array | `$[*]` | +| `[, ..]` | Selecting 0-based `n-th` elements in an Array | `$[1, 2]` | +| `[last - , ..]` | Selecting `n-th` element before the last element in an Array | `$[0, last - 1]` | +| `[ to , ..]` | Selecting all elements of a range in an Array | `$[1 to last - 2]` | +| `?()` | 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 | ++-----------------------------------------------------------------------+ +``` + +## Validation + +Check the type of a JSON value. + +* `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 | ++---------------------------------------+ +``` + +* `json_path_exists(json, path)` to check whether a path exists in a JSON value. + +If the path is invalid, the function will return an error. + +If the path or the JSON value is `NULL`, the function will return a `NULL` value. + +```sql +SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), 'a'); + ++------------------------------------------------------------------+ +| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),Utf8("a")) | ++------------------------------------------------------------------+ +| 1 | ++------------------------------------------------------------------+ + +SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), 'c.d'); + ++--------------------------------------------------------------------+ +| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),Utf8("c.d")) | ++--------------------------------------------------------------------+ +| 0 | ++--------------------------------------------------------------------+ + +SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), NULL); + ++-------------------------------------------------------------+ +| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),NULL) | ++-------------------------------------------------------------+ +| NULL | ++-------------------------------------------------------------+ +``` diff --git a/docs/reference/sql/functions/overview.md b/docs/reference/sql/functions/overview.md index 11670ead4..f23ca8578 100644 --- a/docs/reference/sql/functions/overview.md +++ b/docs/reference/sql/functions/overview.md @@ -228,111 +228,7 @@ GreptimeDB provides `ADMIN` statement to run the administration functions, pleas ### 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. -* `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 | `$.*` | -| `.` | Selecting element that match the name in an Object | `$.event` | -| `:` | Alias of `.` | `$:event` | -| `[""]` | Alias of `.` | `$["event"]` | -| `[*]` | Selecting all elements in an Array | `$[*]` | -| `[, ..]` | Selecting 0-based `n-th` elements in an Array | `$[1, 2]` | -| `[last - , ..]` | Selecting `n-th` element before the last element in an Array | `$[0, last - 1]` | -| `[ to , ..]` | Selecting all elements of a range in an Array | `$[1 to last - 2]` | -| `?()` | 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 | -+---------------------------------------+ -``` - -* `json_path_exists(json, path)` to check whether a path exists in a JSON value. - -If the path is invalid, the function will return an error. - -If the path or the JSON value is `NULL`, the function will return a `NULL` value. - -```sql -SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), 'a'); - -+------------------------------------------------------------------+ -| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),Utf8("a")) | -+------------------------------------------------------------------+ -| 1 | -+------------------------------------------------------------------+ - -SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), 'c.d'); - -+--------------------------------------------------------------------+ -| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),Utf8("c.d")) | -+--------------------------------------------------------------------+ -| 0 | -+--------------------------------------------------------------------+ - -SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), NULL); - -+-------------------------------------------------------------+ -| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),NULL) | -+-------------------------------------------------------------+ -| NULL | -+-------------------------------------------------------------+ -``` +GreptimeDB provide functions for jsons. [Learn more about these functions](./json.md) ## Geospatial Functions diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/functions/json.md b/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/functions/json.md new file mode 100644 index 000000000..8734586bb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/functions/json.md @@ -0,0 +1,121 @@ + +# 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 中提取值。 + +* `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)` | +| `.*` | 选择对象中的所有元素 | `$.*` | +| `.` | 选择对象中匹配名称的元素 | `$.event` | +| `:` | `.` 的别名 | `$:event` | +| `[""]` | `.` 的别名 | `$["event"]` | +| `[*]` | 选择数组中的所有元素 | `$[*]` | +| `[, ..]` | 选择数组中基于0的第 `n` 个元素 | `$[1, 2]` | +| `[last - , ..]` | 选择数组中最后一个元素之前的第 `n` 个元素 | `$[0, last - 1]` | +| `[ to , ..]` | 选择数组中某个范围内的所有元素 | `$[1 to last - 2]` | +| `?()` | 选择所有匹配过滤表达式的元素 | `$?(@.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 值的类型。 + +* `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 | ++---------------------------------------+ +``` + +* `json_path_exists(json, path)` 检查 JSON 中是否存在指定的路径。 + +如果 `path` 是无效的，函数将返回错误。 + +如果 `path` 或 `json` 是 `NULL`，函数将返回 `NULL`。 + +```sql +SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), 'a'); + ++------------------------------------------------------------------+ +| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),Utf8("a")) | ++------------------------------------------------------------------+ +| 1 | ++------------------------------------------------------------------+ + +SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), 'c.d'); + ++--------------------------------------------------------------------+ +| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),Utf8("c.d")) | ++--------------------------------------------------------------------+ +| 0 | ++--------------------------------------------------------------------+ + +SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), NULL); + ++-------------------------------------------------------------+ +| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),NULL) | ++-------------------------------------------------------------+ +| NULL | ++-------------------------------------------------------------+ +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/functions/overview.md b/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/functions/overview.md index c1121462d..b426d4d07 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/functions/overview.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/functions/overview.md @@ -221,111 +221,7 @@ GreptimeDB 提供了 `ADMIN` 语句来执行管理函数，请阅读 [ADMIN](/re ### 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)` | -| `.*` | 选择对象中的所有元素 | `$.*` | -| `.` | 选择对象中匹配名称的元素 | `$.event` | -| `:` | `.` 的别名 | `$:event` | -| `[""]` | `.` 的别名 | `$["event"]` | -| `[*]` | 选择数组中的所有元素 | `$[*]` | -| `[, ..]` | 选择数组中基于0的第 `n` 个元素 | `$[1, 2]` | -| `[last - , ..]` | 选择数组中最后一个元素之前的第 `n` 个元素 | `$[0, last - 1]` | -| `[ to , ..]` | 选择数组中某个范围内的所有元素 | `$[1 to last - 2]` | -| `?()` | 选择所有匹配过滤表达式的元素 | `$?(@.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 | -+---------------------------------------+ -``` - -* `json_path_exists(json, path)` 检查 JSON 中是否存在指定的路径。 - -如果 `path` 是无效的，函数将返回错误。 - -如果 `path` 或 `json` 是 `NULL`，函数将返回 `NULL`。 - -```sql -SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), 'a'); - -+------------------------------------------------------------------+ -| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),Utf8("a")) | -+------------------------------------------------------------------+ -| 1 | -+------------------------------------------------------------------+ - -SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), 'c.d'); - -+--------------------------------------------------------------------+ -| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),Utf8("c.d")) | -+--------------------------------------------------------------------+ -| 0 | -+--------------------------------------------------------------------+ - -SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), NULL); - -+-------------------------------------------------------------+ -| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),NULL) | -+-------------------------------------------------------------+ -| NULL | -+-------------------------------------------------------------+ -``` +[了解 GreptimeDB 中 JSON 相关的函数](./json.md)。 ### 地理函数 diff --git a/sidebars.ts b/sidebars.ts index 1dd9f1431..e2769dd64 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -398,6 +398,7 @@ const sidebars: SidebarsConfig = { 'reference/sql/functions/overview', 'reference/sql/functions/df-functions', 'reference/sql/functions/geo', + 'reference/sql/functions/json', 'reference/sql/functions/vector', ] }, 'reference/sql/admin',