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 13917b03ad6 [doc] add cast expr doc (#2884)
13917b03ad6 is described below
commit 13917b03ad66d6bb01f7116e70d52b43eca1c888
Author: Mryange <[email protected]>
AuthorDate: Sun Sep 28 10:24:55 2025 +0800
[doc] add cast expr doc (#2884)
## 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/cast-expr.md | 124 +++++++++++++++++++++
.../sql-data-types/conversion/cast-expr.md | 121 ++++++++++++++++++++
sidebars.json | 1 +
3 files changed, 246 insertions(+)
diff --git
a/docs/sql-manual/basic-element/sql-data-types/conversion/cast-expr.md
b/docs/sql-manual/basic-element/sql-data-types/conversion/cast-expr.md
new file mode 100644
index 00000000000..ec31ce44e57
--- /dev/null
+++ b/docs/sql-manual/basic-element/sql-data-types/conversion/cast-expr.md
@@ -0,0 +1,124 @@
+---
+{
+ "title": "CAST expression",
+ "language": "en"
+}
+---
+
+## Introduction
+
+CAST converts a value of one data type into another data type.
+TRY_CAST is a safe type conversion mechanism that returns a SQL NULL value
instead of throwing an error when the conversion might fail.
+
+## Syntax
+
+```sql
+CAST( <source_expr> AS <target_data_type> )
+TRY_CAST( <source_expr> AS <target_data_type> )
+```
+
+## Arguments
+
+- source_expr
+ Expression of any supported data type to be converted into a different data
type.
+- target_data_type
+ The target data type. If the type supports additional properties (for
example, precision and scale for DECIMAL(p, s)), include them as needed.
+
+## Strict Mode
+
+Before Doris 4.0, Doris's CAST behavior followed database systems like MySQL,
trying to avoid CAST operations from raising errors. For example, in MySQL
executing the following SQL:
+
+```sql
+select cast('abc' as signed);
+```
+
+Would result in:
+```
+0
+```
+
+Starting from Doris 4.0, we've adopted a more rigorous approach, following
PostgreSQL's practice: when encountering invalid conversions, Doris will
directly report an error rather than generating potentially confusing results.
+
+Doris 4.0 introduced a new variable `enable_strict_cast`, which can be enabled
with:
+
+```sql
+set enable_strict_cast = true;
+```
+
+In strict mode, illegal CAST operations will directly result in errors:
+
+```sql
+mysql> select cast('abc' as int);
+ERROR 1105 (HY000): errCode = 2, detailMessage = abc can't cast to INT in
strict mode.
+```
+
+The advantages of strict mode are:
+1. It prevents users from getting unexpected values during CAST operations
+2. The system can assume that all data can be successfully type-converted
(illegal data will directly cause errors), enabling better optimization during
computation
+
+## Examples
+
+### Normal CAST Conversion
+
+```sql
+SELECT CAST('123' AS INT);
+```
+
+```text
++--------------------+
+| cast('123' as int) |
++--------------------+
+| 123 |
++--------------------+
+```
+
+### Using TRY_CAST to Handle Potentially Failed Conversions
+
+When conversions might fail, using TRY_CAST can prevent query errors by
returning NULL instead:
+
+```sql
+SELECT TRY_CAST('abc' AS INT);
+```
+
+```text
++------------------------+
+| try_cast('abc' as int) |
++------------------------+
+| NULL |
++------------------------+
+```
+
+## Behavior
+
+We categorize CAST by the target_data_type:
+
+- [Cast to ARRAY](./array-conversion.md)
+- [Cast to BOOLEAN](./boolean-conversion.md)
+- [Cast to DATE](./date-conversion.md)
+- [Cast to TIME](./time-conversion.md)
+- [Cast to DATETIME](./datetime-conversion.md)
+- [Cast to integers (INT, etc.)](./int-conversion.md)
+- [Cast to floating point (FLOAT/DOUBLE)](./float-double-conversion.md)
+- [Cast to DECIMAL](./decimal-conversion.md)
+- [Cast to JSON / From JSON to other types](./json-conversion.md)
+- [Cast to MAP](./map-conversion.md)
+- [Cast to STRUCT](./struct-conversion.md)
+- [Cast to IP](./ip-conversion.md)
+
+## Implicit CAST
+
+Some functions may trigger implicit CASTs, which can lead to unexpected
behavior in certain cases.
+You can use the EXPLAIN statement to check whether an implicit CAST occurs:
+
+```sql
+EXPLAIN SELECT length(123);
+```
+
+```text
+...
+length(CAST(123 AS varchar(65533)))
+...
+```
+
+You can see from the execution plan above that the system automatically
performs a CAST conversion, converting the integer 123 to a string type. This
is an example of implicit CAST.
+
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/conversion/cast-expr.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/conversion/cast-expr.md
new file mode 100644
index 00000000000..1d65ca2f026
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/conversion/cast-expr.md
@@ -0,0 +1,121 @@
+---
+{
+ "title": "CAST 表达式",
+ "language": "zh-CN"
+}
+---
+
+## 介绍
+
+CAST 表达式用于将一种数据类型的值转换为另一种数据类型。而 TRY_CAST 是一种安全的类型转换方式，它在转换可能发生错误时不会抛出异常，而是返回
SQL NULL 值。
+
+## 语法
+
+```sql
+CAST( <source_expr> AS <target_data_type> )
+TRY_CAST( <source_expr> AS <target_data_type> )
+```
+
+## 参数
+
+- source_expr
+ - 任意受支持的数据类型表达式，作为待转换的源值。
+- target_data_type
+ - 目标数据类型。如果该类型支持额外属性（例如 DECIMAL(p, s) 的精度与小数位数），可以一并指定。
+
+## 严格模式
+
+在 Doris 4.0 之前，Doris 的 CAST 行为参考了 MySQL 等数据库系统，会尽可能避免 CAST 操作报错。例如，在 MySQL
中执行以下 SQL：
+
+```sql
+select cast('abc' as signed);
+```
+
+会得到结果：
+```
+0
+```
+
+从 Doris 4.0 开始，我们采用了更严谨的方式，参考 PostgreSQL 的做法：当遇到不合法的转换时，直接报错而不是生成可能令人困惑的结果。
+
+Doris 4.0 引入了新变量 `enable_strict_cast`，可以通过以下命令开启严格模式的 CAST：
+
+```sql
+set enable_strict_cast = true;
+```
+
+在严格模式下，非法的 CAST 会直接报错：
+
+```sql
+mysql> select cast('abc' as int);
+ERROR 1105 (HY000): errCode = 2, detailMessage = abc can't cast to INT in
strict mode.
+```
+
+严格模式的优势在于：
+1. 避免用户在 CAST 时产生非预期的值
+2. 系统可以假设所有数据都能顺利完成类型转换（不合法的数据会直接报错），从而在计算时实现更好的优化
+
+## 示例
+
+### 正常的 CAST 转换
+
+```sql
+select cast('123' as int);
+```
+
+```text
++--------------------+
+| cast('123' as int) |
++--------------------+
+| 123 |
++--------------------+
+```
+
+### 使用 TRY_CAST 处理可能失败的转换
+
+当转换可能失败时，使用 TRY_CAST 可以避免查询报错，而是返回 NULL：
+
+```sql
+select try_cast('abc' as int);
+```
+
+```text
++------------------------+
+| try_cast('abc' as int) |
++------------------------+
+| NULL |
++------------------------+
+```
+
+## 行为说明
+
+下面按照目标数据类型（target_data_type）对 CAST 的行为进行详细分类：
+
+- [转换为 ARRAY](./array-conversion.md)
+- [转换为 BOOLEAN](./boolean-conversion.md)
+- [转换为 DATE](./date-conversion.md)
+- [转换为 TIME](./time-conversion.md)
+- [转换为 DATETIME](./datetime-conversion.md)
+- [转换为整数（INT 等）](./int-conversion.md)
+- [转换为浮点（FLOAT/DOUBLE）](./float-double-conversion.md)
+- [转换为 DECIMAL](./decimal-conversion.md)
+- [转换为 JSON / 从 JSON 转换到其他类型](./json-conversion.md)
+- [转换为 MAP](./map-conversion.md)
+- [转换为 STRUCT](./struct-conversion.md)
+- [转换为 IP](./ip-conversion.md)
+
+## 隐式 CAST
+
+某些函数可能会触发隐式 CAST（类型转换），这在特定情况下可能导致非预期的行为。您可以通过 EXPLAIN 语句来检查是否发生了隐式 CAST：
+
+```sql
+explain select length(123);
+```
+
+```text
+...
+length(CAST(123 AS varchar(65533)))
+...
+```
+
+从上述执行计划可以看到，系统自动将整数 123 转换为字符串类型，这就是一个隐式 CAST 的例子。
diff --git a/sidebars.json b/sidebars.json
index 8fc2d4b4bff..7e14da833ab 100644
--- a/sidebars.json
+++ b/sidebars.json
@@ -1074,6 +1074,7 @@
"label": "Conversion",
"items": [
"sql-manual/basic-element/sql-data-types/conversion/overview",
+
"sql-manual/basic-element/sql-data-types/conversion/cast-expr",
"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]
