[FLLINK-36862][table] Polish Documentation and Error Messages

yiyutian1 · Jan 7, 2025 · 268eb0a · 268eb0a
1 parent 945487a
commit 268eb0a
Show file tree

Hide file tree

Showing 4 changed files with 18 additions and 9 deletions.
diff --git a/flink-python/pyflink/table/expressions.py b/flink-python/pyflink/table/expressions.py
@@ -312,16 +312,25 @@ def to_timestamp_ltz(*args) -> Expression:
 
     Supported functions:
     1. to_timestamp_ltz(Numeric) -> DataTypes.TIMESTAMP_LTZ
+    Converts a numeric value of epoch milliseconds to a TIMESTAMP_LTZ. The default precision is 3.
     2. to_timestamp_ltz(Numeric, Integer) -> DataTypes.TIMESTAMP_LTZ
+    Converts a numeric value of epoch seconds or epoch milliseconds to a TIMESTAMP_LTZ.
+    Valid precisions are 0 or 3.
     3. to_timestamp_ltz(String) -> DataTypes.TIMESTAMP_LTZ
+    Converts a timestamp string using default format 'yyyy-MM-dd HH:mm:ss.SSS' to a TIMESTAMP_LTZ.
     4. to_timestamp_ltz(String, String) -> DataTypes.TIMESTAMP_LTZ
+    Converts a timestamp string using format (default 'yyyy-MM-dd HH:mm:ss.SSS') to a TIMESTAMP_LTZ.
     5. to_timestamp_ltz(String, String, String) -> DataTypes.TIMESTAMP_LTZ
+    Converts a timestamp string string1 using format string2 (default 'yyyy-MM-dd HH:mm:ss.SSS')
+    in time zone string3 (default 'UTC') to a TIMESTAMP_LTZ.
+    Supports any timezone that is available in Java's TimeZone database.
 
     Example:
     ::
 
         >>> table.select(to_timestamp_ltz(100))  # numeric with default precision
         >>> table.select(to_timestamp_ltz(100, 0))  # numeric with second precision
+        >>> table.select(to_timestamp_ltz(100, 3))  # numeric with millisecond precision
         >>> table.select(to_timestamp_ltz("2023-01-01 00:00:00"))  # string with default format
         >>> table.select(to_timestamp_ltz("01/01/2023", "MM/dd/yyyy"))  # string with format
         >>> table.select(to_timestamp_ltz("2023-01-01 00:00:00",

diff --git a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/Expressions.java b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/Expressions.java
@@ -381,7 +381,7 @@ public static ApiExpression toTimestampLtz(String timestampStr, String format) {
     /**
      * Converts a timestamp to {@link DataTypes#TIMESTAMP_LTZ(int)}.
      *
-     * <p>This method takes an object representing a timestamp and converts it to a TIMESTAMP_LTZ
+     * <p>This method takes a string representing a timestamp and converts it to a TIMESTAMP_LTZ
      * using the built-in TO_TIMESTAMP_LTZ function definition.
      *
      * @param timeStamp The timestamp string to be converted.

diff --git a/...in/java/org/apache/flink/table/types/inference/strategies/ToTimestampLtzTypeStrategy.java b/...in/java/org/apache/flink/table/types/inference/strategies/ToTimestampLtzTypeStrategy.java
@@ -57,7 +57,7 @@ public Optional<DataType> inferType(CallContext callContext) {
             if (!isCharacterType(firstTypeRoot) && !firstType.is(LogicalTypeFamily.NUMERIC)) {
                 throw new ValidationException(
                         "Unsupported argument type. "
-                                + "When taking 1 argument, TO_TIMESTAMP_LTZ accepts <CHARACTER> or <NUMERIC>.");
+                                + "When taking 1 argument, TO_TIMESTAMP_LTZ accepts an argument of type <CHARACTER>, <CHAR>, or <NUMERIC>.");
             }
         } else if (argCount == 2) {
             LogicalType secondType = argumentTypes.get(1).getLogicalType();
@@ -72,20 +72,20 @@ public Optional<DataType> inferType(CallContext callContext) {
                 if (!isCharacterType(secondTypeRoot)) {
                     throw new ValidationException(
                             "Unsupported argument type. "
-                                    + "TO_TIMESTAMP_LTZ(<CHARACTER>, <CHARACTER>) requires the second argument to be <CHARACTER>.");
+                                    + "If the first argument is of type <CHARACTER> or <CHAR>, TO_TIMESTAMP_LTZ requires the second argument to be of type <CHARACTER> or <CHAR>.");
                 }
             } else {
                 throw new ValidationException(
                         "Unsupported argument type. "
-                                + "When taking 2 arguments, TO_TIMESTAMP_LTZ requires the first argument to be <NUMERIC> or <CHARACTER>.");
+                                + "When taking 2 arguments, TO_TIMESTAMP_LTZ requires the first argument to be of type <CHARACTER>, <CHAR>, or <NUMERIC>.");
             }
         } else if (argCount == 3) {
             if (!isCharacterType(firstTypeRoot)
                     || !isCharacterType(argumentTypes.get(1).getLogicalType().getTypeRoot())
                     || !isCharacterType(argumentTypes.get(2).getLogicalType().getTypeRoot())) {
                 throw new ValidationException(
                         "Unsupported argument type. "
-                                + "When taking 3 arguments, TO_TIMESTAMP_LTZ requires all three arguments to be of type <CHARACTER>.");
+                                + "When taking 3 arguments, TO_TIMESTAMP_LTZ requires all three arguments to be of type <CHARACTER> or <CHAR>.");
             }
         }
 

diff --git a/...ava/org/apache/flink/table/types/inference/strategies/ToTimestampLtzTypeStrategyTest.java b/...ava/org/apache/flink/table/types/inference/strategies/ToTimestampLtzTypeStrategyTest.java
@@ -44,7 +44,7 @@ protected Stream<TestSpec> testData() {
                                 SpecificTypeStrategies.TO_TIMESTAMP_LTZ)
                         .inputTypes(DataTypes.BOOLEAN())
                         .expectErrorMessage(
-                                "Unsupported argument type. When taking 1 argument, TO_TIMESTAMP_LTZ accepts <CHARACTER> or <NUMERIC>."),
+                                "Unsupported argument type. When taking 1 argument, TO_TIMESTAMP_LTZ accepts an argument of type <CHARACTER>, <CHAR>, or <NUMERIC>."),
                 TestSpec.forStrategy(
                                 "TO_TIMESTAMP_LTZ(<NUMERIC>, <INTEGER>)",
                                 SpecificTypeStrategies.TO_TIMESTAMP_LTZ)
@@ -66,13 +66,13 @@ protected Stream<TestSpec> testData() {
                                 SpecificTypeStrategies.TO_TIMESTAMP_LTZ)
                         .inputTypes(DataTypes.STRING(), DataTypes.FLOAT())
                         .expectErrorMessage(
-                                "Unsupported argument type. TO_TIMESTAMP_LTZ(<CHARACTER>, <CHARACTER>) requires the second argument to be <CHARACTER>."),
+                                "Unsupported argument type. If the first argument is of type <CHARACTER> or <CHAR>, TO_TIMESTAMP_LTZ requires the second argument to be of type <CHARACTER> or <CHAR>."),
                 TestSpec.forStrategy(
                                 "Invalid first argument when taking 2 arguments",
                                 SpecificTypeStrategies.TO_TIMESTAMP_LTZ)
                         .inputTypes(DataTypes.BOOLEAN(), DataTypes.FLOAT())
                         .expectErrorMessage(
-                                "Unsupported argument type. When taking 2 arguments, TO_TIMESTAMP_LTZ requires the first argument to be <NUMERIC> or <CHARACTER>."),
+                                "Unsupported argument type. When taking 2 arguments, TO_TIMESTAMP_LTZ requires the first argument to be of type <CHARACTER>, <CHAR>, or <NUMERIC>."),
                 TestSpec.forStrategy(
                                 "TO_TIMESTAMP_LTZ(<CHARACTER>, <CHARACTER>, <CHARACTER>)",
                                 SpecificTypeStrategies.TO_TIMESTAMP_LTZ)
@@ -82,7 +82,7 @@ protected Stream<TestSpec> testData() {
                                 "Invalid three arguments", SpecificTypeStrategies.TO_TIMESTAMP_LTZ)
                         .inputTypes(DataTypes.STRING(), DataTypes.INT(), DataTypes.STRING())
                         .expectErrorMessage(
-                                "Unsupported argument type. When taking 3 arguments, TO_TIMESTAMP_LTZ requires all three arguments to be of type <CHARACTER>."),
+                                "Unsupported argument type. When taking 3 arguments, TO_TIMESTAMP_LTZ requires all three arguments to be of type <CHARACTER> or <CHAR>."),
                 TestSpec.forStrategy("No arguments", SpecificTypeStrategies.TO_TIMESTAMP_LTZ)
                         .inputTypes()
                         .expectErrorMessage(