This is an automated email from the ASF dual-hosted git repository.
leonard pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/flink.git
The following commit(s) were added to refs/heads/master by this push:
new a9605906aa0 [FLINK-26588][docs] Translate the new CAST documentation
to Chinese
a9605906aa0 is described below
commit a9605906aa0a4c9157717b7221ef38eeb70f5525
Author: Chengkai Yang <[email protected]>
AuthorDate: Tue May 10 10:25:27 2022 +0800
[FLINK-26588][docs] Translate the new CAST documentation to Chinese
This closes #19498.
---
docs/content.zh/docs/dev/table/types.md | 152 ++++++++++++++++++++++++--------
1 file changed, 116 insertions(+), 36 deletions(-)
diff --git a/docs/content.zh/docs/dev/table/types.md
b/docs/content.zh/docs/dev/table/types.md
index 333376de284..c9471c215e3 100644
--- a/docs/content.zh/docs/dev/table/types.md
+++ b/docs/content.zh/docs/dev/table/types.md
@@ -142,42 +142,6 @@ val t: DataType =
DataTypes.ARRAY(DataTypes.INT().notNull()).bridgedTo(classOf[A
API is extended. Users of predefined sources/sinks/functions do not need to
define such hints. Hints within
a table program (e.g. `field.cast(TIMESTAMP(3).bridgedTo(Timestamp.class))`)
are ignored.
-{{< tabs "table" >}}
-{{< tab "Java/Scala" >}}
-The default planner supports the following set of SQL types:
-
-| Data Type | Remarks for Data Type |
-|:----------|:----------------------|
-| `CHAR` | |
-| `VARCHAR` | |
-| `STRING` | |
-| `BOOLEAN` | |
-| `BYTES` | `BINARY` and `VARBINARY` are not supported yet. |
-| `DECIMAL` | Supports fixed precision and scale. |
-| `TINYINT` | |
-| `SMALLINT` | |
-| `INTEGER` | |
-| `BIGINT` | |
-| `FLOAT` | |
-| `DOUBLE` | |
-| `DATE` | |
-| `TIME` | Supports only a precision of `0`. |
-| `TIMESTAMP` | |
-| `TIMESTAMP_LTZ` | |
-| `INTERVAL` | Supports only interval of `MONTH` and `SECOND(3)`. |
-| `ARRAY` | |
-| `MULTISET` | |
-| `MAP` | |
-| `ROW` | |
-| `RAW` | |
-| structured types | Only exposed in user-defined functions yet. |
-
-{{< /tab >}}
-{{< tab "Python" >}}
-N/A
-{{< /tab >}}
-{{< /tabs >}}
-
List of Data Types
------------------
@@ -191,6 +155,36 @@ For the Python Table API, those types are available in
`pyflink.table.types.Data
{{< /tab >}}
{{< /tabs >}}
+The default planner supports the following set of SQL types:
+
+| Data Type | Remarks for Data Type |
+|:-----------------|:---------------------------------------------------|
+| `CHAR` | |
+| `VARCHAR` | |
+| `STRING` | |
+| `BOOLEAN` | |
+| `BINARY` | |
+| `VARBINARY` | |
+| `BYTES` | |
+| `DECIMAL` | Supports fixed precision and scale. |
+| `TINYINT` | |
+| `SMALLINT` | |
+| `INTEGER` | |
+| `BIGINT` | |
+| `FLOAT` | |
+| `DOUBLE` | |
+| `DATE` | |
+| `TIME` | Supports only a precision of `0`. |
+| `TIMESTAMP` | |
+| `TIMESTAMP_LTZ` | |
+| `INTERVAL` | Supports only interval of `MONTH` and `SECOND(3)`. |
+| `ARRAY` | |
+| `MULTISET` | |
+| `MAP` | |
+| `ROW` | |
+| `RAW` | |
+| Structured types | Only exposed in user-defined functions yet. |
+
### Character Strings
#### `CHAR`
@@ -1487,6 +1481,92 @@ Not supported.
{{< /tab >}}
{{< /tabs >}}
+<a name="casting"></a>
+
+CAST 方法
+-------
+
+Flink Table API 和 Flink SQL 支持从 `输入` 数据类型 到 `目标` 数据类型的转换。有的转换
+无论输入值是什么都能保证转换成功，而有些转换则会在运行时失败（即不可能转换为 `目标` 数据类型对应的值）。
+例如，将 `INT` 数据类型的值转换为 `STRING` 数据类型一定能转换成功，但无法保证将 `STRING` 数据类型转换为 `INT` 数据类型。
+
+在生成执行计划时，Flink 的 SQL 检查器会拒绝提交那些不可能直接转换为 `目标` 数据类型的SQL，并抛出
`ValidationException` 异常，
+例如从 `TIMESTAMP` 类型转化到 `INTERVAL` 类型。
+然而有些查询即使通过了 SQL 检查器的验证，依旧可能会在运行期间转换失败，这就需要用户正确处理这些失败了。
+
+在 Flink Table API 和 Flink SQL 中，可以用下面两个内置方法来进行转换操作：
+
+* `CAST`：定义在 SQL 标准的 CAST
方法。在某些容易发生转换失败的查询场景中，当实际输入数据不合法时，作业便会运行失败。类型推导会保留输入类型的可空性。
+* `TRY_CAST`：常规 CAST 方法的扩展，当转换失败时返回 `NULL`。该方法的返回值允许为空。
+
+例如：
+
+```sql
+CAST('42' AS INT) --- 结果返回数字 42 的 INT 格式（非空）
+CAST(NULL AS VARCHAR) --- 结果返回 VARCHAR 类型的空值
+CAST('non-number' AS INT) --- 抛出异常，并停止作业
+
+TRY_CAST('42' AS INT) --- 结果返回数字 42 的 INT 格式
+TRY_CAST(NULL AS VARCHAR) --- 结果返回 VARCHAR 类型的空值
+TRY_CAST('non-number' AS INT) --- 结果返回 INT 类型的空值
+COALESCE(TRY_CAST('non-number' AS INT), 0) --- 结果返回数字 0 的 INT 格式（非空）
+```
+
+下表展示了各个类型的转换程度，"Y" 表示支持，"!" 表示转换可能会失败，"N" 表示不支持：
+
+| 输入类型\目标类型 |
`CHAR`¹/<br/>`VARCHAR`¹/<br/>`STRING` |
`BINARY`¹/<br/>`VARBINARY`¹/<br/>`BYTES` | `BOOLEAN` | `DECIMAL` | `TINYINT` |
`SMALLINT` | `INTEGER` | `BIGINT` | `FLOAT` | `DOUBLE` | `DATE` | `TIME` |
`TIMESTAMP` | `TIMESTAMP_LTZ` | `INTERVAL` | `ARRAY` | `MULTISET` | `MAP` |
`ROW` | `STRUCTURED` | `RAW` |
+|:---------------------------------------|:-------------------------------------:|:----------------------------------------:|:---------:|:---------:|:---------:|:----------:|:---------:|:--------:|:-------:|:--------:|:------:|:------:|:-----------:|:---------------:|:----------:|:-------:|:----------:|:-----:|:-----:|:------------:|:-----:|
+| `CHAR`/<br/>`VARCHAR`/<br/>`STRING` | Y
| ! | ! | ! | !
| ! | ! | ! | ! | ! | ! | ! |
! | ! | N | N | N | N | N
| N | N |
+| `BINARY`/<br/>`VARBINARY`/<br/>`BYTES` | Y
| Y | N | N | N
| N | N | N | N | N | N | N |
N | N | N | N | N | N | N
| N | N |
+| `BOOLEAN` | Y
| N | Y | Y | Y
| Y | Y | Y | Y | Y | N | N |
N | N | N | N | N | N | N
| N | N |
+| `DECIMAL` | Y
| N | N | Y | Y
| Y | Y | Y | Y | Y | N | N |
N | N | N | N | N | N | N
| N | N |
+| `TINYINT` | Y
| N | Y | Y | Y
| Y | Y | Y | Y | Y | N | N |
N² | N² | N | N | N | N | N
| N | N |
+| `SMALLINT` | Y
| N | Y | Y | Y
| Y | Y | Y | Y | Y | N | N |
N² | N² | N | N | N | N | N
| N | N |
+| `INTEGER` | Y
| N | Y | Y | Y
| Y | Y | Y | Y | Y | N | N |
N² | N² | Y⁵ | N | N | N | N
| N | N |
+| `BIGINT` | Y
| N | Y | Y | Y
| Y | Y | Y | Y | Y | N | N |
N² | N² | Y⁶ | N | N | N | N
| N | N |
+| `FLOAT` | Y
| N | N | Y | Y
| Y | Y | Y | Y | Y | N | N |
N | N | N | N | N | N | N
| N | N |
+| `DOUBLE` | Y
| N | N | Y | Y
| Y | Y | Y | Y | Y | N | N |
N | N | N | N | N | N | N
| N | N |
+| `DATE` | Y
| N | N | N | N
| N | N | N | N | N | Y | N |
Y | Y | N | N | N | N | N
| N | N |
+| `TIME` | Y
| N | N | N | N
| N | N | N | N | N | N | Y |
Y | Y | N | N | N | N | N
| N | N |
+| `TIMESTAMP` | Y
| N | N | N | N
| N | N | N | N | N | Y | Y |
Y | Y | N | N | N | N | N
| N | N |
+| `TIMESTAMP_LTZ` | Y
| N | N | N | N
| N | N | N | N | N | Y | Y |
Y | Y | N | N | N | N | N
| N | N |
+| `INTERVAL` | Y
| N | N | N | N
| N | Y⁵ | Y⁶ | N | N | N | N |
N | N | Y | N | N | N | N
| N | N |
+| `ARRAY` | Y
| N | N | N | N
| N | N | N | N | N | N | N |
N | N | N | !³ | N | N | N
| N | N |
+| `MULTISET` | Y
| N | N | N | N
| N | N | N | N | N | N | N |
N | N | N | N | !³ | N | N
| N | N |
+| `MAP` | Y
| N | N | N | N
| N | N | N | N | N | N | N |
N | N | N | N | N | !³ | N
| N | N |
+| `ROW` | Y
| N | N | N | N
| N | N | N | N | N | N | N |
N | N | N | N | N | N | !³
| N | N |
+| `STRUCTURED` | Y
| N | N | N | N
| N | N | N | N | N | N | N |
N | N | N | N | N | N | N
| !³ | N |
+| `RAW` | Y
| ! | N | N | N
| N | N | N | N | N | N | N |
N | N | N | N | N | N | N
| N | Y⁴ |
+
+备注：
+
+1. 所有转化到具有固长或变长的类型时会根据类型的定义来裁剪或填充数据。
+2. 使用 `TO_TIMESTAMP` 方法和 `TO_TIMESTAMP_LTZ` 方法的场景，不要使用 `CAST` 或 `TRY_CAST`。
+3. 支持转换，当且仅当用其内部数据结构也支持转化时。转换可能会失败，当且仅当用其内部数据结构也可能会转换失败。
+4. 支持转换，当且仅当用使用 `RAW` 的类和类的序列化器一样。
+5. 支持转换，当且仅当用使用 `INTERVAL` 做“月”到“年”的转换。
+6. 支持转换，当且仅当用使用 `INTERVAL` 做“天”到“时间”的转换。
+
+请注意：无论是 `CAST` 还是 `TRY_CAST`，当输入为 `NULL` ，输出也为 `NULL`。
+
+<a name="legacy-casting"></a>
+
+### 旧版本 CAST 方法
+
+用户可以通过将参数 `table.exec.legacy-cast-behaviour` 设置为 `enabled` 来启用 1.15 版本之前的 CAST
行为。
+在 Flink 1.15 版本此参数默认为 disabled。
+
+如果设置为 enabled，请注意以下问题：
+
+* 转换为 `CHAR`/`VARCHAR`/`BINARY`/`VARBINARY` 数据类型时，不再自动修剪（trim）或填充（pad）。
+* 使用 `CAST` 时不再会因为转化失败而停止作业，只会返回 `NULL`，但不会像 `TRY_CAST` 那样推断正确的类型。
+* `CHAR`/`VARCHAR`/`STRING` 的转换结果会有一些细微的差别。
+
+{{< hint warning >}}
+我们 **不建议** 配置此参数，而是 **强烈建议** 在新项目中保持这个参数为默认禁用，以使用最新版本的 CAST 方法。
+在下一个版本，这个参数会被移除。
+{{< /hint >}}
+
Data Type Extraction
--------------------
