matriv commented on a change in pull request #18611:
URL: https://github.com/apache/flink/pull/18611#discussion_r807847735
##########
File path: docs/data/sql_functions.yml
##########
@@ -561,7 +561,10 @@ conditional:
conversion:
- sql: CAST(value AS type)
table: ANY.cast(TYPE)
- description: Returns a new value being cast to type type. E.g., CAST('42'
AS INT) returns 42; CAST(NULL AS VARCHAR) returns NULL of type VARCHAR.
+ description: Returns a new value being cast to type type. A CAST error
throws an exception and fails the job. When performing a cast operation that
may fail, like STRING to INT, one should rather use TRY_CAST, in order to
handle errors. If "table.exec.legacy-cast-behaviour" is enabled, CAST behaves
like TRY_CAST. E.g., CAST('42' AS INT) returns 42; CAST(NULL AS STRING) returns
NULL of type STRING; CAST('non-number' AS INT) throws an exception and fails
the job.
+ - sql: TRY_CAST(value AS type)
+ table: ANY.tryCast(TYPE)
+ description: Like CAST, but in case of error, returns NULL rather than
failing the job. E.g., TRY_CAST('42' AS INT) returns 42; TRY_CAST(NULL AS
STRING) returns NULL of type STRING; TRY_CAST('non-number' AS INT) returns NULL
of type INT.
Review comment:
Maybe also here, mention wrapping with `coalesce` for different default
value.
##########
File path: flink-python/pyflink/table/expression.py
##########
@@ -837,12 +837,28 @@ def alias(self, name: str, *extra_names: str) ->
'Expression[T]':
def cast(self, data_type: DataType) -> 'Expression':
"""
- Converts a value to a given data type.
+ Returns a new value being cast to type type.
+ A cast error throws an exception and fails the job.
+ When performing a cast operation that may fail, like STRING to INT,
+ one should rather use try_cast, in order to handle errors.
+ If "table.exec.legacy-cast-behaviour" is enabled, cast behaves like
try_cast.
- e.g. lit("42").cast(DataTypes.INT()) leads to 42.
+ E.g. lit("4").cast(DataTypes.INT()) returns 42;
+ lit(null).cast(DataTypes.STRING()) returns NULL of type STRING;
+ lit("non-number").cast(DataTypes.INT()) throws an exception and fails
the job.
"""
return _binary_op("cast")(self, _to_java_data_type(data_type))
+ def try_cast(self, data_type: DataType) -> 'Expression':
+ """
+ Like cast, but in case of error, returns NULL rather than failing the
job.
+
+ E.g. lit("42").try_cast(DataTypes.INT()) returns 42;
+ lit(null).try_cast(DataTypes.STRING()) returns NULL of type STRING;
+ list("non-number").cast(DataTypes.INT()) returns NULL of type INT.
Review comment:
same here, mentioning `coalesce`.
##########
File path:
flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/BaseExpressions.java
##########
@@ -468,14 +470,33 @@ public OutType collect() {
}
/**
- * Converts a value to a given data type.
+ * Returns a new value being cast to {@code toType}. A cast error throws
an exception and fails
+ * the job. When performing a cast operation that may fail, like {@link
DataTypes#STRING()} to
+ * {@link DataTypes#INT()}, one should rather use {@link
#tryCast(DataType)}, in order to handle
+ * errors. If {@link
ExecutionConfigOptions#TABLE_EXEC_LEGACY_CAST_BEHAVIOUR} is enabled, this
+ * function behaves like {@link #tryCast(DataType)}.
*
- * <p>e.g. "42".cast(DataTypes.INT()) leads to 42.
+ * <p>E.g. {@code "42".cast(DataTypes.INT())} returns {@code 42}; {@code
+ * null.cast(DataTypes.STRING())} returns {@code null} of type {@link
DataTypes#STRING()};
+ * {@code "non-number".cast(DataTypes.INT())} throws an exception and
fails the job.
*/
public OutType cast(DataType toType) {
return toApiSpecificExpression(unresolvedCall(CAST, toExpr(),
typeLiteral(toType)));
}
+ /**
+ * Like {@link #cast(DataType)}, but in case of error, returns {@code
null} rather than failing
+ * the job.
+ *
+ * <p>E.g. {@code "42".tryCast(DataTypes.INT())} returns {@code 42}; {@code
+ * null.tryCast(DataTypes.STRING())} returns {@code null} of type {@link
DataTypes#STRING()};
+ * {@code "non-number".tryCast(DataTypes.INT())} returns {@code null} of
type {@link
+ * DataTypes#INT()}.
Review comment:
How about suggesting the use of `coalesce` to wrap the `tryCast` and
provide a different default value than `null`.
--
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]
