[Doc] Docs for DECIMAL256 (StarRocks#61579)

絵空事スピリット · web-flow · commit b7db3caa792d · 2025-08-11T12:57:49.000+08:00
diff --git a/docs/en/sql-reference/data-types/numeric/DECIMAL.md b/docs/en/sql-reference/data-types/numeric/DECIMAL.md
@@ -6,31 +6,84 @@ displayed_sidebar: docs
 
 DECIMAL(P[,S]) is a high-precision fixed-point value. `P` stands for the total number of significant numbers (precision). `S` stands for the maximum number of decimal points (scale).
 
-If `P` is omitted, the default is 10. If `S` is omitted, the default is 0.
+If `P` is omitted, the default value is 10. If `S` is omitted, the default value is 0.
 
-* Decimal V2
+- For versions earlier than v4.0, StarRocks supports DECIMAL128 based on [Fast DECIMAL](#fast-decimal).
+- For v4.0 and later versions, StarRocks supports [DECIMAL256](#decimal256).
 
-  The range of `P` is [1,27] and the range of `S` is [0,9]. `P` must be greater than or equal to the value of `S`. The default value of `S` is 0.
+## Features
 
-* Fast Decimal (Decimal V3)
+### Fast DECIMAL
 
-  The range of `P` is [1,38] and the range of `S` is [0, P]. The default value of `S` is 0. Fast Decimal provides a higher precision.
-  
-  Major optimizations:
-  
-  ​1. Fast Decimal uses variable-width integers to express decimals. For example, it uses 64-bit integers to express decimals whose precision is less than or equal to 18. Whereas, Decimal V2 uses 128-bit integers uniformly for all decimals. Arithmetic operations and conversion operations on 64-bit processors use fewer instructions, which greatly improves performance.
-  
-  ​2. Compared with Decimal V2, Fast Decimal made significant optimizations in some algorithms, especially in multiplication, which improves performance by about 4 times.
+Controlled by the FE dynamic parameter `enable_decimal_v3`, Fast DECIMAL is enabled by default.
 
-Fast Decimal is controlled by the FE dynamic parameter `enable_decimal_v3`, which is `true` by default.
+For Fast DECIMAL, the range of `P` is [1,38] and the range of `S` is [0, P]. The default value of `S` is 0.
+
+Fast DECIMAL uses variable-width integers to express decimals.
+
+- Decimal(P &le; 18, S)
+  - LogicalType: Decimal64
+  - Stored as: int64
+  - Delegate LogicalType: BIGINT
+
+- Decimal(P &gt; 18 & P &le; 38, S)
+  - LogicalType: Decimal128
+  - Stored as: int128
+  - Delegate LogicalType: LARGEINT
 
 From v3.1 onwards, StarRocks supports Fast Decimal entries in [ARRAY](../semi_structured/Array.md), [MAP](../semi_structured/Map.md), and [STRUCT](../semi_structured/STRUCT.md).
-  
+
+## DECIMAL256
+
+StarRocks introduces DECIMAL256 from v4.0 onwards.
+
+For DECIMAL256, the range of `P` is (38,76] and the range of `S` is [0, P]. The default value of `S` is 0.
+
+DECIMAL256 expands the upper limit of precision to 76 bits. Its numerical capacity is 10³⁸ times higher than that of DECIMAL128, reducing the probability of overflow to a negligible level.
+
+DECIMAL256 uses the same strategy to express decimals as that of Fast DECIMAL. In addition to the two decimal types mentioned above, it supports:
+
+- Decimal(P &gt; 38 & P &le; 76, S)
+  - LogicalType: Decimal256
+  - Stored as: int256
+  - Delegate LogicalType: INT_256
+
+The actual representable range of DECIMAL256 is `-57896044618658097711785492504343953926634992332820282019728792003956564819968` to `57896044618658097711785492504343953926634992332820282019728792003956564819967`.
+
+#### Type casting operations
+
+DECIMAL256 supports bidirectional type conversion between all types listed below:
+
+| Source Type     | Target Types                                                      |
+| --------------- | ----------------------------------------------------------------- |
+| TYPE_DECIMAL256 | BOOL                                                              |
+| TYPE_DECIMAL256 | TYPE_TINYINT, TYPE_SMALLINT, TYPE_INT, TYPE_BIGINT, TYPE_LARGEINT |
+| TYPE_DECIMAL256 | TYPE_FLOAT, TYPE_DOUBLE                                           |
+| TYPE_DECIMAL256 | TYPE_VARCHAR                                                      |
+
+#### Aggregate functions
+
+Currently, DECIMAL256 supports these aggregation functions: `COUNT`, `COUNT DISTINCT`, `SUM`, `SUM DISTINCT`, `AVG`, `AVG DISTINCT`, `MAX`, `MIN`, and `ABS`.
+
+#### Limitations
+
+DECIMAL256 has the following limitations:
+
+- Currently, DECIMAL256 does not support automatic precision scale-up for decimal operations.
+
+  For example, `DECIMAL128 * DECIMAL128` will not be automatically scaled up to DECIMAL256. DECIMAL256 features are only applied when `DECIMAL256` is explicitly specified as the operand either in the CREATE TABLE statement or using CAST (`SELECT CAST(p38s10 as DECIMAL(70, 30))`).
+
+- DECIMAL256 does not support window functions.
+
+- Aggregate tables do not support DECIMAL256 type.
+
 ## Examples
 
+### Fast DECIMAL example
+
 Define DECIMAL columns when creating a table.
 
-```sql
+```SQL
 CREATE TABLE decimalDemo (
     pk BIGINT(20) NOT NULL COMMENT "",
     account DECIMAL(20,10) COMMENT ""
@@ -54,6 +107,40 @@ SELECT * FROM decimalDemo;
 +------+-----------------+
 ```
 
-## keywords
+### DECIMAL256 example
+
+Create a table with a DECIMAL256 type column.
+
+```SQL
+CREATE TABLE test_decimal256(
+    p50s48 DECIMAL(50, 48) COMMENT ""
+);
+```
+
+INSERT different values:
+
+```SQL
+INSERT INTO test_decimal256(p50s48) SELECT 1.222222;
+```
+
+This statement succeeds with the values written correctly.
+
+```SQL
+INSERT INTO test_decimal256(p50s48) SELECT 11111111111111111111111111111111111111111111.222222;
+```
+
+This statement succeeds with the values written as NULL. Because the integer part and decimal part (which has 44 digits) with the specified scale (which is `48`) together exceed the maximum integer that can be represented by 256 bits, FE directly casts the value to NULL.
+
+```SQL
+INSERT INTO test_decimal256(p50s48) SELECT 333;
+```
+
+This statement will be returned with an error `ERROR 1064 (HY000): Insert has filtered data`. Because the integer part and decimal part with the specified scale (which is `48`) together exceed the maximum value represented by a 50-digit integer, BE returns the error.
+
+## Usage notes
+
+You can set the system variable `sql_mode` to `ERROR_IF_OVERFLOW` to allow the system to return an error instead of NULL in the case of arithmetic overflow.
+
+## Keywords
 
-decimal, decimalv2, decimalv3, fast decimal
+decimal, decimalv3, fast decimal, decimal128, decimal256
diff --git a/docs/en/sql-reference/data-types/semi_structured/Array.md b/docs/en/sql-reference/data-types/semi_structured/Array.md
@@ -60,7 +60,6 @@ The following limits apply when you create ARRAY columns in StarRocks tables:
 - In versions earlier than v2.1, you can create ARRAY columns only in Duplicate Key tables. From v2.1 onwards, you can also create ARRAY columns in other types of tables (Primary Key, Unique Key, Aggregate). Note that in an Aggregate table, you can create an ARRAY column only when the function used to aggregate data in that column is replace() or replace_if_not_null(). For more information, see [Aggregate table](../../../table_design/table_types/aggregate_table.md).
 - ARRAY columns cannot be used as key columns.
 - ARRAY columns cannot be used as partition keys (included in PARTITION BY) or bucketing keys (included in DISTRIBUTED BY).
-- DECIMAL V3 is not supported in ARRAY.
 - An array can have a maximum of 14-level nesting.
 
 ## Construct arrays in SQL
diff --git a/docs/ja/sql-reference/data-types/numeric/DECIMAL.md b/docs/ja/sql-reference/data-types/numeric/DECIMAL.md
@@ -4,37 +4,86 @@ displayed_sidebar: docs
 
 # DECIMAL
 
-## 説明
+DECIMAL(P[,S]) は高精度の固定小数点値です。`P` は有効桁数（精度）を表します。`S` は小数点以下の最大桁数（スケール）を表します。
 
-DECIMAL(P[,S])
+`P` が省略された場合、デフォルト値は10です。`S` が省略された場合、デフォルト値は0です。
 
-高精度の固定小数点値です。`P` は有効数字の総数（精度）を表します。`S` は小数点以下の最大桁数（スケール）を表します。
+- バージョン v4.0 より前のバージョンでは、StarRocks は [Fast DECIMAL](#fast-decimal) に基づく DECIMAL128 をサポートしています。
+- バージョン v4.0 以降では、StarRocks は [DECIMAL256](#decimal256) をサポートしています。
 
-`P` を省略した場合、デフォルトは10です。`S` を省略した場合、デフォルトは0です。
+## 機能
 
-* Decimal V2
+### Fast DECIMAL
 
-  `P` の範囲は [1,27] で、`S` の範囲は [0,9] です。`P` は `S` の値以上でなければなりません。`S` のデフォルト値は0です。
+FE の動的パラメータ `enable_decimal_v3` によって制御され、Fast DECIMAL はデフォルトで有効になっています。
 
-* Fast Decimal (Decimal V3)
+Fast DECIMAL の場合、`P` の範囲は [1,38] で、`S` の範囲は [0, P] です。`S` のデフォルト値は0です。
 
-  `P` の範囲は [1,38] で、`S` の範囲は [0, P] です。`S` のデフォルト値は0です。Fast Decimal はより高い精度を提供します。
-  
-  主な最適化:
-  
-  ​1. Fast Decimal は可変幅の整数を使用して小数を表現します。例えば、精度が18以下の小数を表現するために64ビット整数を使用します。一方、Decimal V2 はすべての小数に対して128ビット整数を一様に使用します。64ビットプロセッサ上での算術演算や変換操作は、より少ない命令を使用し、パフォーマンスを大幅に向上させます。
-  
-  ​2. Decimal V2 と比較して、Fast Decimal はいくつかのアルゴリズム、特に乗算において大幅な最適化を行い、パフォーマンスを約4倍向上させました。
+Fast DECIMAL は可変幅の整数を使用して小数を表現します。
 
-Fast Decimal は FE の動的パラメータ `enable_decimal_v3` によって制御され、デフォルトでは `true` です。
+- Decimal(P &le; 18, S)
+  - LogicalType: Decimal64
+  - 保存形式: int64
+  - Delegate LogicalType: BIGINT
 
-バージョン 3.1 以降、StarRocks は [ARRAY](../semi_structured/Array.md)、[MAP](../semi_structured/Map.md)、および [STRUCT](../semi_structured/STRUCT.md) における Fast Decimal エントリをサポートしています。
+- Decimal(P &gt; 18 & P &le; 38, S)
+  - LogicalType: Decimal128
+  - 保存形式: int128
+  - Delegate LogicalType: LARGEINT
+
+バージョン v3.1 以降、StarRocks は [ARRAY](../semi_structured/Array.md)、[MAP](../semi_structured/Map.md)、および [STRUCT](../semi_structured/STRUCT.md) における Fast Decimal エントリをサポートしています。
+
+## DECIMAL256
+
+StarRocks はバージョン v4.0 以降で DECIMAL256 を導入しています。
+
+DECIMAL256 の場合、`P` の範囲は (38,76] で、`S` の範囲は [0, P] です。`S` のデフォルト値は0です。
+
+DECIMAL256 は精度の上限を76ビットに拡張します。その数値容量は DECIMAL128 の 10³⁸ 倍であり、オーバーフローの可能性を無視できるレベルにまで低減します。
+
+DECIMAL256 は Fast DECIMAL と同じ戦略を使用して小数を表現します。上記の2つの小数タイプに加えて、次のものをサポートします：
+
+- Decimal(P &gt; 38 & P &le; 76, S)
+  - LogicalType: Decimal256
+  - 保存形式: int256
+  - Delegate LogicalType: INT_256
+
+DECIMAL256 の実際の表現可能な範囲は `-57896044618658097711785492504343953926634992332820282019728792003956564819968` から `57896044618658097711785492504343953926634992332820282019728792003956564819967` です。
+
+#### 型変換操作
+
+DECIMAL256 は以下にリストされたすべての型との双方向の型変換をサポートします：
+
+| ソースタイプ     | ターゲットタイプ                                                      |
+| --------------- | ----------------------------------------------------------------- |
+| TYPE_DECIMAL256 | BOOL                                                              |
+| TYPE_DECIMAL256 | TYPE_TINYINT, TYPE_SMALLINT, TYPE_INT, TYPE_BIGINT, TYPE_LARGEINT |
+| TYPE_DECIMAL256 | TYPE_FLOAT, TYPE_DOUBLE                                           |
+| TYPE_DECIMAL256 | TYPE_VARCHAR                                                      |
+
+#### 集計関数
+
+現在、DECIMAL256 は次の集計関数をサポートしています：`COUNT`、`COUNT DISTINCT`、`SUM`、`SUM DISTINCT`、`AVG`、`AVG DISTINCT`、`MAX`、`MIN`、および `ABS`。
+
+#### 制限事項
+
+DECIMAL256 には以下の制限があります：
+
+- 現在、DECIMAL256 は小数演算における自動精度スケールアップをサポートしていません。
+
+  例えば、`DECIMAL128 * DECIMAL128` は自動的に DECIMAL256 にスケールアップされません。DECIMAL256 の機能は、`DECIMAL256` が CREATE TABLE ステートメントで明示的にオペランドとして指定されるか、CAST を使用する場合（`SELECT CAST(p38s10 as DECIMAL(70, 30))`）にのみ適用されます。
+
+- DECIMAL256 はウィンドウ関数をサポートしていません。
+
+- 集計テーブルは DECIMAL256 タイプをサポートしていません。
 
 ## 例
 
-テーブルを作成する際に DECIMAL 列を定義します。
+### Fast DECIMAL の例
+
+テーブルを作成する際に DECIMAL カラムを定義します。
 
-```sql
+```SQL
 CREATE TABLE decimalDemo (
     pk BIGINT(20) NOT NULL COMMENT "",
     account DECIMAL(20,10) COMMENT ""
@@ -58,6 +107,40 @@ SELECT * FROM decimalDemo;
 +------+-----------------+
 ```
 
+### DECIMAL256 の例
+
+DECIMAL256 タイプのカラムを持つテーブルを作成します。
+
+```SQL
+CREATE TABLE test_decimal256(
+    p50s48 DECIMAL(50, 48) COMMENT ""
+);
+```
+
+異なる値を挿入します：
+
+```SQL
+INSERT INTO test_decimal256(p50s48) SELECT 1.222222;
+```
+
+このステートメントは、値が正しく書き込まれて成功します。
+
+```SQL
+INSERT INTO test_decimal256(p50s48) SELECT 11111111111111111111111111111111111111111111.222222;
+```
+
+このステートメントは、値が NULL として書き込まれて成功します。整数部分と小数部分（44桁）が指定されたスケール（`48`）と共に、256ビットで表現可能な最大整数を超えているため、FE は直接値を NULL にキャストします。
+
+```SQL
+INSERT INTO test_decimal256(p50s48) SELECT 333;
+```
+
+このステートメントはエラー `ERROR 1064 (HY000): Insert has filtered data` と共に返されます。整数部分と小数部分が指定されたスケール（`48`）と共に、50桁の整数で表現される最大値を超えているため、BE はエラーを返します。
+
+## 使用上の注意
+
+システム変数 `sql_mode` を `ERROR_IF_OVERFLOW` に設定することで、算術オーバーフローの場合にシステムが NULL の代わりにエラーを返すようにすることができます。
+
 ## キーワード
 
-decimal, decimalv2, decimalv3, fast decimal
+decimal, decimalv3, fast decimal, decimal128, decimal256
diff --git a/docs/ja/sql-reference/data-types/semi_structured/Array.md b/docs/ja/sql-reference/data-types/semi_structured/Array.md
@@ -60,7 +60,6 @@ StarRocks テーブルで ARRAY カラムを作成する際には、次の制限
 - v2.1 より前のバージョンでは、ARRAY カラムは重複キーテーブルでのみ作成できます。v2.1 以降では、他のタイプのテーブル（Primary Key、Unique Key、Aggregate）でも ARRAY カラムを作成できます。ただし、集計テーブルでは、そのカラムでデータを集計するために使用される関数が replace() または replace_if_not_null() の場合にのみ ARRAY カラムを作成できます。詳細は [集計テーブル](../../../table_design/table_types/aggregate_table.md) を参照してください。
 - ARRAY カラムはキー カラムとして使用できません。
 - ARRAY カラムはパーティションキー（PARTITION BY に含まれる）またはバケッティングキー（DISTRIBUTED BY に含まれる）として使用できません。
-- DECIMAL V3 は ARRAY でサポートされていません。
 - 配列は最大 14 レベルのネストが可能です。
 
 ## SQL での配列の構築
diff --git a/docs/zh/sql-reference/data-types/numeric/DECIMAL.md b/docs/zh/sql-reference/data-types/numeric/DECIMAL.md
diff --git a/docs/zh/sql-reference/data-types/semi_structured/Array.md b/docs/zh/sql-reference/data-types/semi_structured/Array.md
