This is an automated email from the ASF dual-hosted git repository.
yiguolei pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 86ea2a4a42f [doc]
sort_json_object_keys/normalize_json_numbers_to_double function (#2927)
86ea2a4a42f is described below
commit 86ea2a4a42f3f75a1412da4d1e856a793f2abf8e
Author: Mryange <[email protected]>
AuthorDate: Sun Oct 12 15:01:41 2025 +0800
[doc] sort_json_object_keys/normalize_json_numbers_to_double function
(#2927)
## Versions
- [x] dev
- [ ] 3.0
- [ ] 2.1
- [ ] 2.0
## Languages
- [x] Chinese
- [x] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
---
.../normalize-json-numbers-to-double.md | 141 ++++++++++++++++++++
.../json-functions/sort-json-object-keys.md | 107 +++++++++++++++
.../normalize-json-numbers-to-double.md | 145 +++++++++++++++++++++
.../json-functions/sort-json-object-keys.md | 107 +++++++++++++++
sidebars.json | 2 +
5 files changed, 502 insertions(+)
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/normalize-json-numbers-to-double.md
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/normalize-json-numbers-to-double.md
new file mode 100644
index 00000000000..6fbfbf35df9
--- /dev/null
+++
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/normalize-json-numbers-to-double.md
@@ -0,0 +1,141 @@
+---
+{
+ "title": "NORMALIZE_JSON_NUMBERS_TO_DOUBLE",
+ "language": "en"
+}
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+## Description
+
+The `NORMALIZE_JSON_NUMBERS_TO_DOUBLE` function converts all numeric values in
a JSON to double-precision floating-point type. This function takes a JSON
value as input and returns a new JSON value with all numeric types converted to
double-precision values.
+
+## Syntax
+
+```sql
+NORMALIZE_JSON_NUMBERS_TO_DOUBLE(json_value)
+```
+
+## Alias
+
+`NORMALIZE_JSONB_NUMBERS_TO_DOUBLE`
+
+## Parameters
+
+**json_value** - The JSON value to be processed. Must be of JSON type.
+
+## Return Value
+
+Returns a new JSON value with all numeric types converted to double-precision
floating-point (double) type.
+
+When the input is NULL, the function returns NULL.
+
+## Purpose
+
+Since the JSON standard does not specify the underlying type for Number, most
systems implement Number type based on IEEE 754-2008 binary 64-bit
(double-precision) floating-point numbers (such as the double type in C++).
+To ensure data accuracy, Doris has extended the Number type with more refined
types, supporting more precise types like Int128 and DECIMAL.
+However, this can lead to differences when compared to other systems.
+
+For example, for the following JSON string:
+```text
+'{"abc": 18446744073709551616}'
+```
+
+In systems that use Double as the underlying type for JSON Numbers, such as
MySQL, you would get:
+```text
++-----------------------------------------------+
+| cast('{"abc": 18446744073709551616}' as json) |
++-----------------------------------------------+
+| {"abc": 1.8446744073709552e19} |
++-----------------------------------------------+
+```
+
+But since Doris's JSON Number has types with higher precision, it would return:
+```text
++-----------------------------------------------+
+| cast('{"abc": 18446744073709551616}' as json) |
++-----------------------------------------------+
+| {"abc":18446744073709551616} |
++-----------------------------------------------+
+```
+
+To be compatible with other systems, you can use
`NORMALIZE_JSON_NUMBERS_TO_DOUBLE`:
+```text
++---------------------------------------------------------------------------------+
+| normalize_json_numbers_to_double(cast('{"abc": 18446744073709551616}' as
json)) |
++---------------------------------------------------------------------------------+
+| {"abc":1.8446744073709552e+19}
|
++---------------------------------------------------------------------------------+
+```
+
+## Examples
+
+### Basic Number Conversion
+
+```sql
+SELECT
normalize_json_numbers_to_double(cast('{"b":1234567890123456789,"b":456,"a":789}'
as json));
+```
+
+```text
++---------------------------------------------------------------------------------------------+
+|
normalize_json_numbers_to_double(cast('{"b":1234567890123456789,"b":456,"a":789}'
as json)) |
++---------------------------------------------------------------------------------------------+
+| {"b":1.2345678901234568e+18,"b":456,"a":789}
|
++---------------------------------------------------------------------------------------------+
+```
+
+### Processing Nested JSON
+
+```sql
+SELECT
normalize_json_numbers_to_double(cast('{"object":{"int":123,"bigint":1234567890123456789},"array":[123,456,789]}'
as json));
+```
+
+```text
++-----------------------------------------------------------------------------------------------------------------------------+
+|
normalize_json_numbers_to_double(cast('{"object":{"int":123,"bigint":1234567890123456789},"array":[123,456,789]}'
as json)) |
++-----------------------------------------------------------------------------------------------------------------------------+
+| {"object":{"int":123,"bigint":1.2345678901234568e+18},"array":[123,456,789]}
|
++-----------------------------------------------------------------------------------------------------------------------------+
+```
+
+### Processing NULL Values
+
+```sql
+SELECT normalize_json_numbers_to_double(null);
+```
+
+```text
++----------------------------------------+
+| normalize_json_numbers_to_double(null) |
++----------------------------------------+
+| NULL |
++----------------------------------------+
+```
+
+## Notes
+
+1. The `NORMALIZE_JSON_NUMBERS_TO_DOUBLE` function has an alias
`NORMALIZE_JSONB_NUMBERS_TO_DOUBLE`, both functions have identical
functionality.
+
+2. This function converts all numeric types in JSON (including integers,
floating-point numbers, and DECIMALs) to double-precision floating-point
representation.
+
+3. For particularly large integers, conversion to double-precision
floating-point may result in precision loss, as shown in the example where
1234567890123456789 is converted to 1.2345678901234568e+18.
+
+4. This function does not alter the structure of JSON, it only modifies the
numeric representations within it.
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/sort-json-object-keys.md
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/sort-json-object-keys.md
new file mode 100644
index 00000000000..8bcb37b71f6
--- /dev/null
+++
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/sort-json-object-keys.md
@@ -0,0 +1,107 @@
+---
+{
+ "title": "SORT_JSON_OBJECT_KEYS",
+ "language": "en"
+}
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+## Description
+
+`SORT_JSON_OBJECT_KEYS` sorts the keys of a JSON object. This function takes a
JSON object as input and returns a new JSON object with keys sorted in
lexicographical order.
+
+Note that according to the JSON standard, JSON objects are unordered
collections. However, this function is useful when you need to ensure
consistency in key ordering, for example, when comparing two JSON objects for
identical content.
+
+## Syntax
+
+```sql
+SORT_JSON_OBJECT_KEYS(json_value)
+```
+
+## Alias
+
+SORT_JSONB_OBJECT_KEYS
+
+## Parameters
+
+**json_value** - The JSON value whose keys need to be sorted. Must be of JSON
type.
+
+## Return Value
+
+Returns a new JSON object with keys sorted in lexicographical order. The
return type matches the input JSON type.
+
+When the input is NULL, the function returns NULL.
+
+## Examples
+
+### Basic key sorting
+
+```sql
+SELECT sort_json_object_keys(cast('{"b":123,"b":456,"a":789}' as json));
+```
+
+```text
++------------------------------------------------------------------+
+| sort_json_object_keys(cast('{"b":123,"b":456,"a":789}' as json)) |
++------------------------------------------------------------------+
+| {"a":789,"b":123} |
++------------------------------------------------------------------+
+```
+
+### Handling nested JSON arrays
+
+```sql
+SELECT
sort_json_object_keys(cast('[{"b":123,"b":456,"a":789},{"b":123},{"b":456},{"a":789}]'
as json));
+```
+
+```text
++----------------------------------------------------------------------------------------------------+
+| sort_json_object_keys(cast('[{"b":123,"b":456,"a":789}
,{"b":123},{"b":456},{"a":789} ]' as json)) |
++----------------------------------------------------------------------------------------------------+
+| [{"a":789,"b":123},{"b":123},{"b":456},{"a":789}]
|
++----------------------------------------------------------------------------------------------------+
+```
+
+### Handling NULL values
+
+```sql
+SELECT sort_json_object_keys(null);
+```
+
+```text
++-----------------------------+
+| sort_json_object_keys(null) |
++-----------------------------+
+| NULL |
++-----------------------------+
+```
+
+## Notes
+
+1. `SORT_JSON_OBJECT_KEYS` function has an alias `SORT_JSONB_OBJECT_KEYS`,
both functions have identical functionality.
+
+2. This function only sorts the keys of objects, without modifying their
associated values.
+
+3. The function only sorts objects but not arrays, as the standard specifies
that arrays are ordered collections.
+
+4. Duplicate keys in JSON objects will be merged when converted to Doris JSON
type, preserving only the first key-value pair.
+
+5. This function is primarily used to ensure JSON object keys are presented in
a consistent order for comparison or debugging purposes, as by default Doris
JSON type does not guarantee key ordering.
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/normalize-json-numbers-to-double.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/normalize-json-numbers-to-double.md
new file mode 100644
index 00000000000..000a9a80699
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/normalize-json-numbers-to-double.md
@@ -0,0 +1,145 @@
+---
+{
+ "title": "NORMALIZE_JSON_NUMBERS_TO_DOUBLE",
+ "language": "zh-CN"
+}
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+## 描述
+
+`NORMALIZE_JSON_NUMBERS_TO_DOUBLE` 函数用于将 JSON 中的所有数值类型转换为双精度浮点数（double）类型。
+该函数接受一个 JSON 值作为输入，并返回一个新的 JSON 值，其中所有数值类型都被转换为双精度浮点数。
+
+
+## 语法
+
+```sql
+NORMALIZE_JSON_NUMBERS_TO_DOUBLE(json_value)
+```
+
+## 别名
+
+`NORMALIZE_JSONB_NUMBERS_TO_DOUBLE`
+
+## 参数
+
+**json_value** - 需要处理的 JSON 值。必须是 JSON 类型。
+
+## 返回值
+
+返回一个新的 JSON 值，其中所有数值类型都被转换为双精度浮点数（double）类型。
+
+当输入为 NULL 时，函数返回 NULL。
+
+
+## 用途
+
+由于 JSON 标准并没有规定 Number 的底层类型，而大多数系统中 Number 类型的实现基于 IEEE 754-2008 二进制 64
位（双精度）浮点数（如 C++ 中的 double 类型）。
+Doris 为了保证数据准确性，对 Number 类型进行了更精细的扩展。支持了 Int128、DECIMAL 等更精确的类型。
+但是这样可能会和其他系统存在差异。
+
+例如对于这样的 JSON 字符串：
+```text
+'{"abc": 18446744073709551616}'
+```
+
+在一些使用 Double 作为 JSON 的 Number 底层类型的系统，例如 MySQL，会得到这样的结果：
+```text
++-----------------------------------------------+
+| cast('{"abc": 18446744073709551616}' as json) |
++-----------------------------------------------+
+| {"abc": 1.8446744073709552e19} |
++-----------------------------------------------+
+```
+
+但是因为 Doris 的 JSON 的 Number 有精度更高的类型，所以会得到：
+```text
++-----------------------------------------------+
+| cast('{"abc": 18446744073709551616}' as json) |
++-----------------------------------------------+
+| {"abc":18446744073709551616} |
++-----------------------------------------------+
+```
+
+为了和其他系统兼容，可以使用 `NORMALIZE_JSON_NUMBERS_TO_DOUBLE`：
+```text
++---------------------------------------------------------------------------------+
+| normalize_json_numbers_to_double(cast('{"abc": 18446744073709551616}' as
json)) |
++---------------------------------------------------------------------------------+
+| {"abc":1.8446744073709552e+19}
|
++---------------------------------------------------------------------------------+
+```
+
+
+## 示例
+
+### 基本数值转换
+
+```sql
+SELECT
normalize_json_numbers_to_double(cast('{"b":1234567890123456789,"b":456,"a":789}'
as json));
+```
+
+```text
++---------------------------------------------------------------------------------------------+
+|
normalize_json_numbers_to_double(cast('{"b":1234567890123456789,"b":456,"a":789}'
as json)) |
++---------------------------------------------------------------------------------------------+
+| {"b":1.2345678901234568e+18,"b":456,"a":789}
|
++---------------------------------------------------------------------------------------------+
+```
+
+### 处理嵌套 JSON
+
+```sql
+SELECT
normalize_json_numbers_to_double(cast('{"object":{"int":123,"bigint":1234567890123456789},"array":[123,456,789]}'
as json));
+```
+
+```text
++-----------------------------------------------------------------------------------------------------------------------------+
+|
normalize_json_numbers_to_double(cast('{"object":{"int":123,"bigint":1234567890123456789},"array":[123,456,789]}'
as json)) |
++-----------------------------------------------------------------------------------------------------------------------------+
+| {"object":{"int":123,"bigint":1.2345678901234568e+18},"array":[123,456,789]}
|
++-----------------------------------------------------------------------------------------------------------------------------+
+```
+
+### 处理 NULL 值
+
+```sql
+SELECT normalize_json_numbers_to_double(null);
+```
+
+```text
++----------------------------------------+
+| normalize_json_numbers_to_double(null) |
++----------------------------------------+
+| NULL |
++----------------------------------------+
+```
+
+## 注意事项
+
+1. `NORMALIZE_JSON_NUMBERS_TO_DOUBLE` 函数有一个别名
`NORMALIZE_JSONB_NUMBERS_TO_DOUBLE`，两者功能完全相同。
+
+2. 此函数将 JSON 中的所有数值类型（包括整数、浮点数、DECIMAL）都转换为双精度浮点数表示形式。
+
+3. 对于特别大的整数，转换为双精度浮点数可能会导致精度损失，如示例中的 1234567890123456789 被转换为
1.2345678901234568e+18。
+
+4. 此函数不会改变 JSON 的结构，只会修改其中的数值表示形式。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/sort-json-object-keys.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/sort-json-object-keys.md
new file mode 100644
index 00000000000..bdbe0bd4955
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/sort-json-object-keys.md
@@ -0,0 +1,107 @@
+---
+{
+ "title": "SORT_JSON_OBJECT_KEYS",
+ "language": "zh-CN"
+}
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+## 描述
+
+`SORT_JSON_OBJECT_KEYS` 函数对 JSON 对象的键进行排序。该函数接受一个 JSON 对象作为输入，并返回一个新的 JSON
对象，其中键按字典顺序排序。
+
+需要注意的是，根据 JSON 标准，JSON 对象是无序的集合。然而，此函数可以在需要确保键顺序一致时使用，例如在比较两个 JSON 对象是否包含相同内容时。
+
+## 语法
+
+```sql
+SORT_JSON_OBJECT_KEYS(json_value)
+```
+
+## 别名
+
+SORT_JSONB_OBJECT_KEYS
+
+## 参数
+
+**json_value** - 需要对键进行排序的 JSON 值。必须是 JSON 类型。
+
+## 返回值
+
+返回一个新的 JSON 对象，其中键按字典顺序排序。返回类型与输入的 JSON 类型相同。
+
+当输入为 NULL 时，函数返回 NULL。
+
+## 示例
+
+### 基本键排序
+
+```sql
+SELECT sort_json_object_keys(cast('{"b":123,"b":456,"a":789}' as json));
+```
+
+```text
++------------------------------------------------------------------+
+| sort_json_object_keys(cast('{"b":123,"b":456,"a":789}' as json)) |
++------------------------------------------------------------------+
+| {"a":789,"b":123} |
++------------------------------------------------------------------+
+```
+
+### 处理嵌套 JSON 数组
+
+```sql
+SELECT
sort_json_object_keys(cast('[{"b":123,"b":456,"a":789},{"b":123},{"b":456},{"a":789}]'
as json));
+```
+
+```text
++----------------------------------------------------------------------------------------------------+
+| sort_json_object_keys(cast('[{"b":123,"b":456,"a":789}
,{"b":123},{"b":456},{"a":789} ]' as json)) |
++----------------------------------------------------------------------------------------------------+
+| [{"a":789,"b":123},{"b":123},{"b":456},{"a":789}]
|
++----------------------------------------------------------------------------------------------------+
+```
+
+### 处理 NULL 值
+
+```sql
+SELECT sort_json_object_keys(null);
+```
+
+```text
++-----------------------------+
+| sort_json_object_keys(null) |
++-----------------------------+
+| NULL |
++-----------------------------+
+```
+
+## 注意事项
+
+1. `SORT_JSON_OBJECT_KEYS` 函数有一个别名 `SORT_JSONB_OBJECT_KEYS`，两者功能完全相同。
+
+2. 此函数仅排序对象的键，而不会修改键对应的值。
+
+3. 只会排序对象而不会排序数组，因为标准规定数组是一个有序的集合。
+
+4. JSON 对象中的重复键会在转换为 Doris 的 JSON 类型时进行合并，仅保留第一个键值对。
+
+5. 此函数主要用于确保 JSON 对象的键以一致的顺序呈现，便于比较或调试，因为默认情况下 Doris 的 JSON 类型不保证键的顺序。
diff --git a/sidebars.json b/sidebars.json
index a549faac741..7f272398f2a 100644
--- a/sidebars.json
+++ b/sidebars.json
@@ -1607,6 +1607,8 @@
"sql-manual/sql-functions/scalar-functions/json-functions/json-type",
"sql-manual/sql-functions/scalar-functions/json-functions/json-unquote",
"sql-manual/sql-functions/scalar-functions/json-functions/json-valid",
+
"sql-manual/sql-functions/scalar-functions/json-functions/normalize-json-numbers-to-double",
+
"sql-manual/sql-functions/scalar-functions/json-functions/sort-json-object-keys",
"sql-manual/sql-functions/scalar-functions/json-functions/to-json"
]
},
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
