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 a27ab5b7a4d add type conversion docs (#2735)
a27ab5b7a4d is described below
commit a27ab5b7a4d09f284b5d21f04dcb095f7455d427
Author: zclllyybb <[email protected]>
AuthorDate: Wed Aug 13 09:26:53 2025 +0800
add type conversion docs (#2735)
## Versions
- [x] dev
- [ ] 3.0
- [ ] 2.1
- [ ] 2.0
## Languages
- [x] Chinese
- [x] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
---
.../sql-data-types/conversion/overview.md | 111 +++++++++++++++++++++
.../sql-data-types/conversion/overview.md | 110 ++++++++++++++++++++
sidebars.json | 1 +
3 files changed, 222 insertions(+)
diff --git
a/docs/sql-manual/basic-element/sql-data-types/conversion/overview.md
b/docs/sql-manual/basic-element/sql-data-types/conversion/overview.md
new file mode 100644
index 00000000000..7130906c1f2
--- /dev/null
+++ b/docs/sql-manual/basic-element/sql-data-types/conversion/overview.md
@@ -0,0 +1,111 @@
+---
+{
+ "title": "Type Conversion",
+ "language": "en"
+}
+---
+
+In Doris, each expression has a type, such as `1`, `col1`, and
`from_unixtime(col2)` in the expression `select 1, col1, from_unixtime(col2)
from table1`. The process of converting an expression from one type to another
is called "type conversion."
+
+Type conversion occurs in two cases: explicit conversion and implicit
conversion.
+
+All type conversions follow specific rules. We describe the related rules
according to the **target type** of the conversion. For example, converting
from `INT` to `DOUBLE` and converting from `STRING` to `DOUBLE` are both
described in the [Conversion to FLOAT/DOUBLE](./float-double-conversion)
document.
+
+Whether a conversion can occur and whether the result is a nullable type
depends on whether strict mode is enabled (session variable
`enable_strict_cast`). Generally, when strict mode is enabled, data that fails
conversion will immediately cause an error and result in SQL failure. When
strict mode is disabled, data rows that fail conversion will result in `NULL`.
+
+## Explicit Conversion
+
+Explicit conversion is done through the `CAST` function, for example:
+
+`CAST(1.23 as INT)` converts the number 1.23 to INT type.
+
+`CAST(colA as DATETIME(6))` converts the column/expression colA to DATETIME(6)
type (i.e., a DATETIME type with microsecond precision).
+
+The following describes the type conversion relationships between different
types under strict mode (`enable_strict_cast = true`) and non-strict mode
(`enable_strict_cast = false`), including the following four cases:
+
+|Symbol|Meaning|
+|-|-|
+|x|Not allowed to convert|
+|P|The return type will be Nullable only when the input parameter is already a
Nullable type, i.e., the conversion **will not** convert non-Null values to
Null|
+|A|The return type is always Nullable. The conversion **may convert non-Null
values to Null**|
+|O|The return type is Nullable when the conversion from input type to output
type **may cause overflow**. For non-Null input values, if the conversion
actually causes overflow, the conversion result may be Null|
+
+The specific type conversion rules and Nullable properties, please check the
type conversion documents in the current directory.
+
+### Strict Mode
+
+| **From**\\**To** | bool | tinyint | smallint | int | bigint | largeint |
float | double | decimal | date | datetime | time | IPv4 | IPv6 | char |
varchar | string | bitmap | hll | json | array | map | struct | variant |
+| ---------------- | ---- | ------- | -------- | --- | ------ | -------- |
----- | ------ | ------- | ---- | -------- | ---- | ---- | ---- | ---- |
------- | ------ | ------ | --- | ---- | ----- | --- | ------ | ------- |
+| bool | P | P | P | P | P | P | P | P
| P | x | x | x | x | x | | | |
x | x | P | x | x | x | |
+| tinyint | P | P | P | P | P | P | P | P
| P | P | P | P | x | x | | | | x
| x | P | x | x | x | |
+| smallint | P | P | P | P | P | P | P | P
| P | P | P | P | x | x | | | | x
| x | P | x | x | x | |
+| int | P | P | P | P | P | P | P | P
| P | P | P | P | x | x | | | | x
| x | P | x | x | x | |
+| bigint | P | P | P | P | P | P | P | P
| P | P | P | P | x | x | | | | x
| x | P | x | x | x | |
+| largeint | P | P | P | P | P | P | P | P
| P | P | P | P | x | x | | | | x
| x | P | x | x | x | |
+| float | P | P | P | P | P | P | P | P
| P | P | P | P | x | x | | | | x
| x | P | x | x | x | |
+| double | P | P | P | P | P | P | P | P
| P | P | P | P | x | x | | | | x
| x | P | x | x | x | |
+| decimal | P | P | P | P | P | P | P | P
| P | P | P | P | x | x | | | | x
| x | P | x | x | x | |
+| date | x | x | x | P | P | P | x
| x | x | P | P | x | x | x | | |
| x | x | x | x | x | x | |
+| datetime | x | x | x | x | P | P | x
| x | x | P | P | P | x | x | | |
| x | x | x | x | x | x | |
+| time | x | P | P | P | P | P | x |
x | x | P | P | P | x | x | | |
| x | x | x | x | x | x | |
+| IPv4 | x | x | x | x | x | x | x
| x | x | x | x | x | P | P | | |
| x | x | x | x | x | x | |
+| IPv6 | x | x | x | x | x | x | x
| x | x | x | x | x | x | P | | |
| x | x | x | x | x | x | |
+| char | P | P | P | P | P | P | P | P
| P | P | P | P | P | P | | | | x
| x | P | P | P | P | |
+| varchar | P | P | P | P | P | P | P | P
| P | P | P | P | P | P | | | | x
| x | P | P | P | P | |
+| string | P | P | P | P | P | P | P | P
| P | P | P | P | P | P | | | | x
| x | P | P | P | P | |
+| bitmap | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | x | x |
x | P | x | x | x | x | x | |
+| hll | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | x | x |
x | x | P | x | x | x | x | |
+| json | A | A | A | A | A | A | A | A
| A | x | x | x | x | x | A | A | A | x
| x | P | A | x | A | |
+| array | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | | |
| x | x | P | P | x | x | |
+| map | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | | |
| x | x | x | x | P | x | |
+| struct | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | | |
| x | x | P | x | x | P | |
+| variant | | | | | | |
| | | | | | | | | |
| | | | | | | |
+
+### Non-strict Mode
+
+| **From**\\**To** | bool | tinyint | smallint | int | bigint | largeint |
float | double | decimal | date | datetime | time | IPv4 | IPv6 | char |
varchar | string | bitmap | hll | json | array | map | struct | variant |
+| ---------------- | ---- | ------- | -------- | --- | ------ | -------- |
----- | ------ | ------- | ---- | -------- | ---- | ---- | ---- | ---- |
------- | ------ | ------ | --- | ---- | ----- | --- | ------ | ------- |
+| bool | P | P | P | P | P | P | P | P
| O | x | x | x | x | x | | | |
x | x | P | x | x | x | |
+| tinyint | P | P | P | P | P | P | P | P
| O | A | A | A | x | x | | | | x
| x | P | x | x | x | |
+| smallint | P | A | P | P | P | P | P | P
| O | A | A | A | x | x | | | | x
| x | P | x | x | x | |
+| int | P | A | A | P | P | P | P | P
| O | A | A | A | x | x | | | | x
| x | P | x | x | x | |
+| bigint | P | A | A | A | P | P | P | P
| O | A | A | A | x | x | | | | x
| x | P | x | x | x | |
+| largeint | P | A | A | A | A | P | P | P
| O | A | A | A | x | x | | | | x
| x | P | x | x | x | |
+| float | P | A | A | A | A | A | P | P
| A | A | A | A | x | x | | | | x
| x | P | x | x | x | |
+| double | P | A | A | A | A | A | P | P
| A | A | A | A | x | x | | | | x
| x | P | x | x | x | |
+| decimal | P | O | O | O | O | O | P | P
| O | A | A | A | x | x | | | | x
| x | P | x | x | x | |
+| date | x | x | x | P | P | P | P |
P | x | P | P | x | x | x | | |
| x | x | x | x | x | x | |
+| datetime | x | x | x | x | P | P | P
| P | x | P | A | P | x | x | | |
| x | x | x | x | x | x | |
+| time | x | A | A | A | P | P | P | P
| x | P | P | A | x | x | | | | x
| x | x | x | x | x | |
+| IPv4 | x | x | x | x | x | x | x
| x | x | x | x | x | P | P | | |
| x | x | x | x | x | x | |
+| IPv6 | x | x | x | x | x | x | x
| x | x | x | x | x | x | P | | |
| x | x | x | x | x | x | |
+| char | A | A | A | A | A | A | A | A
| A | A | A | A | A | A | | | | x
| x | A | A | A | A | |
+| varchar | A | A | A | A | A | A | A | A
| A | A | A | A | A | A | | | | x
| x | A | A | A | A | |
+| string | A | A | A | A | A | A | A | A
| A | A | A | A | A | A | | | | x
| x | A | A | A | A | |
+| bitmap | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | x | x |
x | P | x | x | x | x | x | |
+| hll | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | x | x |
x | x | P | x | x | x | x | |
+| json | A | A | A | A | A | A | A | A
| A | x | x | x | x | x | A | A | A | x
| x | P | A | x | A | |
+| array | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | | |
| x | x | P | P | x | x | |
+| map | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | | |
| x | x | x | x | P | x | |
+| struct | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | | |
| x | x | P | x | x | P | |
+| variant | | | | | | |
| | | | | | | | | |
| | | | | | | |
+
+## Implicit Conversion
+
+Implicit conversion occurs in certain situations where the input SQL does not
explicitly specify, but Doris automatically plans the CAST expression. It
mainly occurs in scenarios such as:
+
+1. When a function call is made, the type of the actual parameter does not
match the type of the function signature.
+
+2. When the types on both sides of a mathematical expression are inconsistent.
+
+etc.
+
+### Conversion matrix
+
+TODO
+
+### Common Type
+
+When an implicit conversion is required due to the operands being used as
mathematical operations, the first step is to determine the common type. If the
operands on both sides are not consistent with the common type, each will plan
a CAST expression to the common type.
+
+TODO
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/conversion/overview.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/conversion/overview.md
new file mode 100644
index 00000000000..75c550a0763
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/conversion/overview.md
@@ -0,0 +1,110 @@
+---
+{
+ "title": "类型转换",
+ "language": "zh-CN"
+}
+---
+
+在 Doris 中，每个表达式均有其类型（例如 `select 1, col1, from_unixtime(col2) from table1` 中的
`1`，`col1`，`from_unixtime(col2)` 等）。将一个表达式从一种类型转换到另一种类型的过程称为“类型转换”。
+
+类型转换会在两种情况下发生，一是显式转换，二是隐式转换。
+
+所有类型转换均遵守特定的规则。我们根据转换的**目标类型**分类描述相关规则。例如，从 `INT` 转换到 `DOUBLE` 和 从 `STRING`
转换到 `DOUBLE`，均在 [转换为 FLOAT/DOUBLE](./float-double-conversion) 文档中描述。
+
+转换是否能发生，以及转换的结果是否为 Nullable 类型，与是否开启严格模式有关（session variable
`enable_strict_cast`）。一般来说，当开启严格模式时，转换失败的数据将会立即引发报错导致 SQL
失败。当关闭严格模式时，转换失败的数据行结果为 `NULL`。
+
+## 显式转换
+
+显式转换通过 `CAST` 函数进行，例如：
+
+`CAST(1.23 as INT)` 将数字 1.23 转换为 INT 类型。
+
+`CAST(colA as DATETIME(6))` 将列/表达式 colA 转换为 DATETIME(6) 类型（即拥有微秒精度的 DATETIME
类型）。
+
+以下分别描述在严格模式（`enable_strict_cast = true`）和非严格模式（`enable_strict_cast =
false`）下，类型之间的转换关系。包括以下四种情况：
+
+|符号|含义|
+|-|-|
+|x|不允许转换|
+|P|当入参已经为 Nullable 类型时，返回类型才会为 Nullable，即该转换**不会**将非 Null 值转换为 Null|
+|A|返回类型总是为 Nullable 类型。即该转换**有可能**将非 Null 值转换为 Null|
+|O|当输入类型转换到输出类型可能溢出时，返回类型总是为 Nullable 类型。对于非 Null 值输入，如果转换实际导致**溢出**，该转换结果可能为
Null|
+
+具体的类型转换规则与 Nullable 属性，请查看当前目录下的各个类型转换文档。
+
+### 严格模式
+
+| **From**\\**To** | bool | tinyint | smallint | int | bigint | largeint |
float | double | decimal | date | datetime | time | IPv4 | IPv6 | char |
varchar | string | bitmap | hll | json | array | map | struct | variant |
+| ---------------- | ---- | ------- | -------- | --- | ------ | -------- |
----- | ------ | ------- | ---- | -------- | ---- | ---- | ---- | ---- |
------- | ------ | ------ | --- | ---- | ----- | --- | ------ | ------- |
+| bool | P | P | P | P | P | P | P | P
| P | x | x | x | x | x | | | |
x | x | P | x | x | x | |
+| tinyint | P | P | P | P | P | P | P | P
| P | P | P | P | x | x | | | | x
| x | P | x | x | x | |
+| smallint | P | P | P | P | P | P | P | P
| P | P | P | P | x | x | | | | x
| x | P | x | x | x | |
+| int | P | P | P | P | P | P | P | P
| P | P | P | P | x | x | | | | x
| x | P | x | x | x | |
+| bigint | P | P | P | P | P | P | P | P
| P | P | P | P | x | x | | | | x
| x | P | x | x | x | |
+| largeint | P | P | P | P | P | P | P | P
| P | P | P | P | x | x | | | | x
| x | P | x | x | x | |
+| float | P | P | P | P | P | P | P | P
| P | P | P | P | x | x | | | | x
| x | P | x | x | x | |
+| double | P | P | P | P | P | P | P | P
| P | P | P | P | x | x | | | | x
| x | P | x | x | x | |
+| decimal | P | P | P | P | P | P | P | P
| P | P | P | P | x | x | | | | x
| x | P | x | x | x | |
+| date | x | x | x | P | P | P | x
| x | x | P | P | x | x | x | | |
| x | x | x | x | x | x | |
+| datetime | x | x | x | x | P | P | x
| x | x | P | P | P | x | x | | |
| x | x | x | x | x | x | |
+| time | x | P | P | P | P | P | x |
x | x | P | P | P | x | x | | |
| x | x | x | x | x | x | |
+| IPv4 | x | x | x | x | x | x | x
| x | x | x | x | x | P | P | | |
| x | x | x | x | x | x | |
+| IPv6 | x | x | x | x | x | x | x
| x | x | x | x | x | x | P | | |
| x | x | x | x | x | x | |
+| char | P | P | P | P | P | P | P | P
| P | P | P | P | P | P | | | | x
| x | P | P | P | P | |
+| varchar | P | P | P | P | P | P | P | P
| P | P | P | P | P | P | | | | x
| x | P | P | P | P | |
+| string | P | P | P | P | P | P | P | P
| P | P | P | P | P | P | | | | x
| x | P | P | P | P | |
+| bitmap | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | x | x |
x | P | x | x | x | x | x | |
+| hll | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | x | x |
x | x | P | x | x | x | x | |
+| json | A | A | A | A | A | A | A | A
| A | x | x | x | x | x | A | A | A | x
| x | P | A | x | A | |
+| array | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | | |
| x | x | P | P | x | x | |
+| map | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | | |
| x | x | x | x | P | x | |
+| struct | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | | |
| x | x | P | x | x | P | |
+| variant | | | | | | |
| | | | | | | | | |
| | | | | | | |
+
+### 非严格模式
+
+| **From**\\**To** | bool | tinyint | smallint | int | bigint | largeint |
float | double | decimal | date | datetime | time | IPv4 | IPv6 | char |
varchar | string | bitmap | hll | json | array | map | struct | variant |
+| ---------------- | ---- | ------- | -------- | --- | ------ | -------- |
----- | ------ | ------- | ---- | -------- | ---- | ---- | ---- | ---- |
------- | ------ | ------ | --- | ---- | ----- | --- | ------ | ------- |
+| bool | P | P | P | P | P | P | P | P
| O | x | x | x | x | x | | | |
x | x | P | x | x | x | |
+| tinyint | P | P | P | P | P | P | P | P
| O | A | A | A | x | x | | | | x
| x | P | x | x | x | |
+| smallint | P | A | P | P | P | P | P | P
| O | A | A | A | x | x | | | | x
| x | P | x | x | x | |
+| int | P | A | A | P | P | P | P | P
| O | A | A | A | x | x | | | | x
| x | P | x | x | x | |
+| bigint | P | A | A | A | P | P | P | P
| O | A | A | A | x | x | | | | x
| x | P | x | x | x | |
+| largeint | P | A | A | A | A | P | P | P
| O | A | A | A | x | x | | | | x
| x | P | x | x | x | |
+| float | P | A | A | A | A | A | P | P
| A | A | A | A | x | x | | | | x
| x | P | x | x | x | |
+| double | P | A | A | A | A | A | P | P
| A | A | A | A | x | x | | | | x
| x | P | x | x | x | |
+| decimal | P | O | O | O | O | O | P | P
| O | A | A | A | x | x | | | | x
| x | P | x | x | x | |
+| date | x | x | x | P | P | P | P |
P | x | P | P | x | x | x | | |
| x | x | x | x | x | x | |
+| datetime | x | x | x | x | P | P | P
| P | x | P | A | P | x | x | | |
| x | x | x | x | x | x | |
+| time | x | A | A | A | P | P | P | P
| x | P | P | A | x | x | | | | x
| x | x | x | x | x | |
+| IPv4 | x | x | x | x | x | x | x
| x | x | x | x | x | P | P | | |
| x | x | x | x | x | x | |
+| IPv6 | x | x | x | x | x | x | x
| x | x | x | x | x | x | P | | |
| x | x | x | x | x | x | |
+| char | A | A | A | A | A | A | A | A
| A | A | A | A | A | A | | | | x
| x | A | A | A | A | |
+| varchar | A | A | A | A | A | A | A | A
| A | A | A | A | A | A | | | | x
| x | A | A | A | A | |
+| string | A | A | A | A | A | A | A | A
| A | A | A | A | A | A | | | | x
| x | A | A | A | A | |
+| bitmap | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | x | x |
x | P | x | x | x | x | x | |
+| hll | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | x | x |
x | x | P | x | x | x | x | |
+| json | A | A | A | A | A | A | A | A
| A | x | x | x | x | x | A | A | A | x
| x | P | A | x | A | |
+| array | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | | |
| x | x | P | P | x | x | |
+| map | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | | |
| x | x | x | x | P | x | |
+| struct | x | x | x | x | x | x | x
| x | x | x | x | x | x | x | | |
| x | x | P | x | x | P | |
+| variant | | | | | | |
| | | | | | | | | |
| | | | | | | |
+
+## 隐式转换
+
+隐式转换是在某种情况下，输入 SQL 中未指明，但 Doris 自动规划产生的 CAST 表达式。主要产生于：
+
+1. 函数调用时，给定实参类型与函数签名类型不匹配
+2. 数学表达式两侧类型不一致
+
+等场景。
+
+### 转换矩阵
+
+TODO
+
+### 公共类型
+
+在因作为数学运算的操作数而需要发生隐式转换时，首先要确定转换的公共类型。两侧操作数如果与公共类型不一致，则会各自规划到公共类型的 CAST 表达式。
+
+TODO
diff --git a/sidebars.json b/sidebars.json
index e6f299b467b..0d79cf7afb0 100644
--- a/sidebars.json
+++ b/sidebars.json
@@ -1035,6 +1035,7 @@
"type": "category",
"label": "Conversion",
"items": [
+
"sql-manual/basic-element/sql-data-types/conversion/overview",
"sql-manual/basic-element/sql-data-types/conversion/array-conversion",
"sql-manual/basic-element/sql-data-types/conversion/boolean-conversion",
"sql-manual/basic-element/sql-data-types/conversion/date-conversion",
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
