You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@doris.apache.org by yi...@apache.org on 2022/12/15 13:27:57 UTC
[doris] branch master updated: [DOCS](Decimalv3) Add document for Decimalv3 (#15108)
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.git
The following commit(s) were added to refs/heads/master by this push:
new 5ee5d70f51 [DOCS](Decimalv3) Add document for Decimalv3 (#15108)
5ee5d70f51 is described below
commit 5ee5d70f51c44620972d8ee130bfe38cf2e4e417
Author: Gabriel <ga...@gmail.com>
AuthorDate: Thu Dec 15 21:27:51 2022 +0800
[DOCS](Decimalv3) Add document for Decimalv3 (#15108)
* [DOCS](Decimalv3) Add document for Decimalv3
* update
---
.../sql-reference/Data-Types/DECIMALV3.md | 82 ++++++++++++++++++++++
docs/sidebars.json | 1 +
.../sql-reference/Data-Types/DECIMALV3.md | 79 +++++++++++++++++++++
3 files changed, 162 insertions(+)
diff --git a/docs/en/docs/sql-manual/sql-reference/Data-Types/DECIMALV3.md b/docs/en/docs/sql-manual/sql-reference/Data-Types/DECIMALV3.md
new file mode 100644
index 0000000000..2197507e57
--- /dev/null
+++ b/docs/en/docs/sql-manual/sql-reference/Data-Types/DECIMALV3.md
@@ -0,0 +1,82 @@
+---
+{
+ "title": "DECIMALV3",
+ "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.
+-->
+
+## DECIMALV3
+### Description
+DECIMALV3 (M [,D])
+
+High-precision fixed-point number, M represents the total number of significant digits, and D represents the scale.
+
+The range of M is [1, 38], and the range of D is [0, precision].
+
+The default value is DECIMALV3(9, 0).
+
+### Precision Deduction
+
+DECIMALV3 has a very complex set of type inference rules. For different expressions, different rules will be applied for precision inference.
+
+#### Arithmetic Expressions
+
+* Plus / Minus: DECIMALV3(a, b) + DECIMALV3(x, y) -> DECIMALV3(max(a - b, x - y) + max(b, y), max(b, y)). That is, the integer part and the decimal part use the larger value of the two operands respectively.
+* Multiply: DECIMALV3(a, b) + DECIMALV3(x, y) -> DECIMALV3(max(a, x), max(b, y)).
+* Divide: DECIMALV3(a, b) + DECIMALV3(x, y) -> DECIMALV3(a + y, b).
+
+#### Aggregation functions
+
+* SUM / MULTI_DISTINCT_SUM: SUM(DECIMALV3(a, b)) -> DECIMALV3(38, b).
+* AVG: AVG(DECIMALV3(a, b)) -> DECIMALV3(38, b).
+
+#### Default rules
+
+Except for the expressions mentioned above, other expressions use default rules for precision deduction. That is, for the expression `expr(DECIMALV3(a, b))`, the result type is also DECIMALV3(a, b).
+
+#### Adjust the result precision
+
+Different users have different accuracy requirements for DECIMALV3. The above rules are the default behavior of Doris. If users **have different accuracy requirements, they can adjust the accuracy in the following ways**:
+
+* If the expected result precision is greater than the default precision, you can adjust the result precision by adjusting the parameter's precision. For example, if the user expects to calculate `AVG(col)` and get DECIMALV3(x, y) as the result, where the type of `col` is DECIMALV3 (a, b), the expression can be rewritten to `AVG(CAST(col as DECIMALV3 (x, y))`.
+* If the expected result precision is less than the default precision, the desired precision can be obtained by approximating the output result. For example, if the user expects to calculate `AVG(col)` and get DECIMALV3(x, y) as the result, where the type of `col` is DECIMALV3(a, b), the expression can be rewritten as `ROUND(AVG(col), y)`.
+
+### Why DECIMALV3 is required
+
+DECIMALV3 in Doris is a real high-precision fixed-point number. Compared with the old version of Decimal, DecimalV3 has the following core advantages:
+1. It can represent a wider range. The value ranges of both precision and scale in DECIMALV3 have been significantly expanded.
+2. Higher performance. The old version of DECIMAL requires 16 bytes in memory and 12 bytes in storage, while DECIMALV3 has made adaptive adjustments as shown below.
+```
++----------------------+------------------------------+
+| precision | Space occupied (memory/disk) |
++----------------------+------------------------------+
+| 0 < precision <= 8 | 4 bytes |
++----------------------+------------------------------+
+| 8 < precision <= 18 | 8 bytes |
++----------------------+------------------------------+
+| 18 < precision <= 38 | 16 bytes |
++----------------------+------------------------------+
+```
+3. More complete precision deduction. For different expressions, different precision inference rules are applied to deduce the precision of the results.
+
+### keywords
+DECIMALV3
diff --git a/docs/sidebars.json b/docs/sidebars.json
index ee3d0d8b0c..16e734c3f6 100644
--- a/docs/sidebars.json
+++ b/docs/sidebars.json
@@ -945,6 +945,7 @@
"sql-manual/sql-reference/Data-Types/SMALLINT",
"sql-manual/sql-reference/Data-Types/TINYINT",
"sql-manual/sql-reference/Data-Types/DECIMAL",
+ "sql-manual/sql-reference/Data-Types/DECIMALV3",
"sql-manual/sql-reference/Data-Types/BIGINT",
"sql-manual/sql-reference/Data-Types/BOOLEAN",
"sql-manual/sql-reference/Data-Types/FLOAT",
diff --git a/docs/zh-CN/docs/sql-manual/sql-reference/Data-Types/DECIMALV3.md b/docs/zh-CN/docs/sql-manual/sql-reference/Data-Types/DECIMALV3.md
new file mode 100644
index 0000000000..e21b3ff357
--- /dev/null
+++ b/docs/zh-CN/docs/sql-manual/sql-reference/Data-Types/DECIMALV3.md
@@ -0,0 +1,79 @@
+---
+{
+ "title": "DECIMALV3",
+ "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.
+-->
+
+## DECIMALV3
+### description
+ DECIMALV3(M[,D])
+ 高精度定点数，M 代表一共有多少个有效数字(precision)，D 代表小数位有多少数字(scale)，
+ 有效数字 M 的范围是 [1, 38]，小数位数字数量 D 的范围是 [0, precision]。
+
+ 默认值为 DECIMALV3(9, 0)。
+
+### 精度推演
+
+DECIMALV3有一套很复杂的类型推演规则，针对不同的表达式，会应用不同规则进行精度推断。
+
+#### 四则运算
+
+* 加法 / 减法：DECIMALV3(a, b) + DECIMALV3(x, y) -> DECIMALV3(max(a - b, x - y) + max(b, y), max(b, y))，即整数部分和小数部分都分别使用两个操作数中较大的值。
+* 乘法：DECIMALV3(a, b) + DECIMALV3(x, y) -> DECIMALV3(max(a, x), max(b, y))。
+* 除法：DECIMALV3(a, b) + DECIMALV3(x, y) -> DECIMALV3(a + y, b)。
+
+#### 聚合运算
+
+* SUM / MULTI_DISTINCT_SUM：SUM(DECIMALV3(a, b)) -> DECIMALV3(38, b)。
+* AVG：AVG(DECIMALV3(a, b)) -> DECIMALV3(38, b)。
+
+#### 默认规则
+
+除上述提到的函数外，其余表达式都使用默认规则进行精度推演。即对于表达式 `expr(DECIMALV3(a, b))`，结果类型同样也是DECIMALV3(a, b)。
+
+#### 调整结果精度
+
+不同用户对DECIMALV3的精度要求各不相同，上述规则为当前Doris的默认行为，如果用户**有不同的精度需求，可以通过以下方式进行精度调整**：
+1. 如果期望的结果精度大于默认精度，可以通过调整入参精度来调整结果精度。例如用户期望计算`AVG(col)`得到DECIMALV3(x, y)作为结果，其中`col`的类型为DECIMALV3(a, b)，则可以改写表达式为`AVG(CAST(col as DECIMALV3(x, y)))`。
+2. 如果期望的结果精度小于默认精度，可以通过对输出结果求近似得到想要的精度。例如用户期望计算`AVG(col)`得到DECIMALV3(x, y)作为结果，其中`col`的类型为DECIMALV3(a, b)，则可以改写表达式为`ROUND(AVG(col), y)`。
+
+### 为什么需要DECIMALV3
+
+Doris中的DECIMALV3是真正意义上的高精度定点数，相比于老版本的Decimal，DecimalV3有以下核心优势：
+1. 可表示范围更大。DECIMALV3中precision和scale的取值范围都进行了明显扩充。
+2. 性能更高。老版本的DECIMAL在内存中需要占用16 bytes，在存储中占用12 bytes，而DECIMALV3进行了自适应调整（如下表格）。
+```
++----------------------+-------------------+
+| precision | 占用空间（内存/磁盘）|
++----------------------+-------------------+
+| 0 < precision <= 8 | 4 bytes |
++----------------------+-------------------+
+| 8 < precision <= 18 | 8 bytes |
++----------------------+-------------------+
+| 18 < precision <= 38 | 16 bytes |
++----------------------+-------------------+
+```
+3. 更完备的精度推演。对于不同的表达式，应用不同的精度推演规则对结果的精度进行推演。
+
+### keywords
+ DECIMALV3
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@doris.apache.org
For additional commands, e-mail: commits-help@doris.apache.org