infoverload commented on a change in pull request #18813:
URL: https://github.com/apache/flink/pull/18813#discussion_r810111100
##########
File path: docs/content/docs/dev/table/types.md
##########
@@ -1487,6 +1481,88 @@ Not supported.
{{< /tab >}}
{{< /tabs >}}
+Casting
+-------
+
+Flink SQL can perform casting between a defined pair `from` type and `target`
type. While some
+casting operations can always succeed no matter the input value, others can
fail at runtime, that
+is, for some input values there is no way to create a value for the target
type. For example, it's
+always possible to convert `INT` to `STRING`, but viceversa is not true, as
you can provide an
+input `STRING` which cannot be converted to `INT`, like `'abc'`.
+
+Flink SQL, during planning, rejects queries which cast pairs are invalid with
+a `ValidationException`, e.g. when trying to cast a `TIMESTAMP` to an
`INTERVAL`, but the user needs
+to handle manually cases where a cast pair is valid, but can fail at runtime.
+
+In Flink SQL casting can be performed using one of the two following built-in
functions:
+
+* `CAST`: The regular cast function defined by the SQL standard. It can fail
the job if the cast operation is fallible and the provided input is not valid.
The type inference will preserve the nullability of the input type.
+* `TRY_CAST`: An extension to the regular cast function which returns `NULL`
in case the cast operation fails. Its return type is always nullable.
+
+For example:
+
+```sql
+CAST('42' AS INT) --- returns 42 of type INT NOT NULL
+CAST(NULL AS VARCHAR) --- returns NULL of type VARCHAR
+CAST('non-number' AS INT) --- throws an exception and fails the job
+
+TRY_CAST('42' AS INT) --- returns 42 of type INT
+TRY_CAST(NULL AS VARCHAR) --- returns NULL of type VARCHAR
+TRY_CAST('non-number' AS INT) --- returns NULL of type INT
+COALESCE(TRY_CAST('non-number' AS INT), 0) --- returns 0 of type INT NOT NULL
+```
+
+The matrix below describes the supported cast pairs, where "Y" means
supported, "!" means fallible, "N" means unsupported:
+
+| From\Target |
`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. All the casting to constant length or variable length will also trim and
pad accordingly to the type definition.
+2. `TO_TIMESTAMP` and `TO_TIMESTAMP_LTZ` must be used instead of
`CAST`/`TRY_CAST`.
+3. Supported iff the children type pairs are supported. Fallible iff the
children type pairs are fallible.
+4. Supported iff the `RAW` class and serializer are equals
+5. Supported iff `INTERVAL` is a `MONTH TO YEAR` range
+5. Supported iff `INTERVAL` is a `DAY TO TIME` range
Review comment:
```suggestion
4. Supported iff the `RAW` class and serializer are equals.
5. Supported iff `INTERVAL` is a `MONTH TO YEAR` range.
5. Supported iff `INTERVAL` is a `DAY TO TIME` range.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
