raminqaf commented on code in PR #29864:
URL: https://github.com/apache/flink/pull/29864#discussion_r4601069771


##########
docs/data/functions/cast/cast.yml:
##########
@@ -0,0 +1,109 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License
+
+name: CAST
+summary: Converts a value to another data type, and fails the job if the value 
doesn't convert.
+
+syntax:
+  sql: CAST(value AS type)
+  java: |
+    $("value").cast(DataTypes.INT())
+    $("value").cast(DataTypes.of("INT"))
+  python: col("value").cast(DataTypes.INT())
+
+arguments:
+  - name: value
+    type: Any type
+    required: true
+    description: The value to convert.
+  - name: type
+    type: A data type
+    required: true
+    description: The target type, such as `INT` or `DECIMAL(10, 2)`. The 
[casting table]({{< ref "docs/sql/reference/data-types" >}}#casting) lists the 
types that each type can be cast to.
+
+returns:
+  description: "`value` converted to `type`."
+  nulls: Returns NULL if `value` is NULL.
+  type: "`type`. NOT NULL if `value` is NOT NULL, except for a cast from 
`VARIANT` to another type, which is always nullable."
+
+notes:
+  - A type pair that the casting table doesn't allow fails the statement at 
planning time, such as `BOOLEAN` to `DATE`.
+  - A value that doesn't convert, such as `'abc'` to `INT`, fails the job at 
runtime. To get NULL instead, use `TRY_CAST`.
+  - Casting to `CHAR(n)` cuts the result to `n` characters, whatever the 
source type, and pads a shorter one with spaces. `CAST(12345 AS CHAR(3))` 
returns `123`. Casting to `VARCHAR(n)` only cuts. `BINARY(n)` cuts and pads 
with zero bytes, and `VARBINARY(n)` only cuts.
+  - Casting bytes to a string fails the job if the bytes aren't valid UTF-8. 
To get NULL instead, use `TRY_CAST`, or repair the bytes first with 
`MAKE_VALID_UTF8`. Setting `table.exec.legacy-bytes-to-string-cast` to `true` 
replaces each invalid sequence with U+FFFD in every query of the session.
+  - Casts to an integer type don't check the range. An integer or a `DECIMAL` 
that doesn't fit wraps around, so `CAST(300 AS TINYINT)` returns `44`. A 
fraction is truncated toward zero.
+  - For a `DECIMAL` target, extra digits after the point are rounded half away 
from zero, so `CAST(-1.25 AS DECIMAL(2, 1))` returns `-1.3`. A number that 
still doesn't fit the precision returns NULL.

Review Comment:
   Fixed



##########
docs/data/functions/cast/cast.yml:
##########
@@ -0,0 +1,109 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License
+
+name: CAST
+summary: Converts a value to another data type, and fails the job if the value 
doesn't convert.
+
+syntax:
+  sql: CAST(value AS type)
+  java: |
+    $("value").cast(DataTypes.INT())
+    $("value").cast(DataTypes.of("INT"))
+  python: col("value").cast(DataTypes.INT())
+
+arguments:
+  - name: value
+    type: Any type
+    required: true
+    description: The value to convert.
+  - name: type
+    type: A data type
+    required: true
+    description: The target type, such as `INT` or `DECIMAL(10, 2)`. The 
[casting table]({{< ref "docs/sql/reference/data-types" >}}#casting) lists the 
types that each type can be cast to.
+
+returns:
+  description: "`value` converted to `type`."
+  nulls: Returns NULL if `value` is NULL.
+  type: "`type`. NOT NULL if `value` is NOT NULL, except for a cast from 
`VARIANT` to another type, which is always nullable."
+
+notes:
+  - A type pair that the casting table doesn't allow fails the statement at 
planning time, such as `BOOLEAN` to `DATE`.
+  - A value that doesn't convert, such as `'abc'` to `INT`, fails the job at 
runtime. To get NULL instead, use `TRY_CAST`.
+  - Casting to `CHAR(n)` cuts the result to `n` characters, whatever the 
source type, and pads a shorter one with spaces. `CAST(12345 AS CHAR(3))` 
returns `123`. Casting to `VARCHAR(n)` only cuts. `BINARY(n)` cuts and pads 
with zero bytes, and `VARBINARY(n)` only cuts.
+  - Casting bytes to a string fails the job if the bytes aren't valid UTF-8. 
To get NULL instead, use `TRY_CAST`, or repair the bytes first with 
`MAKE_VALID_UTF8`. Setting `table.exec.legacy-bytes-to-string-cast` to `true` 
replaces each invalid sequence with U+FFFD in every query of the session.
+  - Casts to an integer type don't check the range. An integer or a `DECIMAL` 
that doesn't fit wraps around, so `CAST(300 AS TINYINT)` returns `44`. A 
fraction is truncated toward zero.

Review Comment:
   Fixed



##########
docs/data/functions/cast/try_cast.yml:
##########
@@ -0,0 +1,110 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License
+
+name: TRY_CAST
+summary: Converts a value to another data type, and returns NULL if the value 
doesn't convert.
+
+syntax:
+  sql: TRY_CAST(value AS type)
+  java: |
+    $("value").tryCast(DataTypes.INT())
+    $("value").tryCast(DataTypes.of("INT"))
+  python: col("value").try_cast(DataTypes.INT())
+
+arguments:
+  - name: value
+    type: Any type
+    required: true
+    description: The value to convert.
+  - name: type
+    type: A data type
+    required: true
+    description: The target type, such as `INT` or `DECIMAL(10, 2)`. The 
[casting table]({{< ref "docs/sql/reference/data-types" >}}#casting) lists the 
types that each type can be cast to.
+
+returns:
+  description: "`value` converted to `type`, like `CAST`."
+  nulls: Returns NULL if `value` is NULL, if `CAST` returns NULL for it, or if 
it doesn't convert, where `CAST` fails the job.
+  type: "`type`, always nullable."
+
+notes:
+  - A type pair that the casting table doesn't allow still fails the statement 
at planning time, as with `CAST`.
+  - "`TRY_CAST` catches only the errors of its own conversion. An error in 
`value`, such as a nested `CAST` that fails, still fails the job."
+  - If one element of an array, a map or a row doesn't convert, the whole 
value is NULL.
+  - Casts between numeric types don't fail, so `TRY_CAST` doesn't return NULL 
for them. `TRY_CAST(300 AS TINYINT)` wraps around to `44`, while 
`TRY_CAST('300' AS TINYINT)` returns NULL.

Review Comment:
   Fixed



-- 
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]

Reply via email to