[FLINK-36941][docs] Update DATE_FORMAT Doc and Python Tests

yiyutian1 · Dec 30, 2024 · 755f3cc · 755f3cc
1 parent 2eda53a
commit 755f3cc
Show file tree

Hide file tree

Showing 4 changed files with 30 additions and 9 deletions.
diff --git a/docs/data/sql_functions.yml b/docs/data/sql_functions.yml
@@ -483,7 +483,10 @@ temporal:
     description: Returns TRUE if two time intervals defined by (timepoint1, temporal1) and (timepoint2, temporal2) overlap. The temporal values could be either a time point or a time interval. E.g., (TIME '2:55:00', INTERVAL '1' HOUR) OVERLAPS (TIME '3:30:00', INTERVAL '2' HOUR) returns TRUE; (TIME '9:00:00', TIME '10:00:00') OVERLAPS (TIME '10:15:00', INTERVAL '3' HOUR) returns FALSE.
   - sql: DATE_FORMAT(timestamp, string)
     table: dateFormat(TIMESTAMP, STRING)
-    description: Converts timestamp to a value of string in the format specified by the date format string. The format string is compatible with Java's SimpleDateFormat.
+    description: Converts timestamp to a string in the format specified by the date format string. The format string is compatible with Java's DateTimeFormatter.
+  - sql: DATE_FORMAT(string, string)
+    table: dateFormat(STRING, STRING)
+    description: Re-format a timestamp string to another string, using a custom format. The format string is compatible with Java's SimpleDateFormat.
   - sql: TIMESTAMPADD(timeintervalunit, interval, timepoint)
   - sql: TIMESTAMPDIFF(timepointunit, timepoint1, timepoint2)
     table: timestampDiff(TIMEPOINTUNIT, TIMEPOINT1, TIMEPOINT2)

diff --git a/docs/data/sql_functions_zh.yml b/docs/data/sql_functions_zh.yml
@@ -601,8 +601,10 @@ temporal:
       `(TIME '9:00:00', TIME '10:00:00') OVERLAPS (TIME '10:15:00', INTERVAL '3' HOUR)` 返回 FALSE。
   - sql: DATE_FORMAT(timestamp, string)
     table: dateFormat(TIMESTAMP, STRING)
-    description: |
-      将时间戳 timestamp 转换为日期格式字符串 string 指定格式的字符串值。格式字符串与 Java 的 SimpleDateFormat 兼容。
+    description: Converts timestamp to a string in the format specified by the date format string. The format string is compatible with Java's DateTimeFormatter.
+  - sql: DATE_FORMAT(string, string)
+    table: dateFormat(STRING, STRING)
+    description: Re-format a timestamp string to another string, using a custom format. The format string is compatible with Java's SimpleDateFormat.
   - sql: TIMESTAMPADD(timeintervalunit, interval, timepoint)
   - sql: TIMESTAMPDIFF(timepointunit, timepoint1, timepoint2)
     table: timestampDiff(TIMEPOINTUNIT, TIMEPOINT1, TIMEPOINT2)

diff --git a/flink-python/pyflink/table/expressions.py b/flink-python/pyflink/table/expressions.py
@@ -350,14 +350,21 @@ def temporal_overlaps(left_time_point,
 def date_format(timestamp, format) -> Expression:
     """
     Formats a timestamp as a string using a specified format.
-    The format must be compatible with MySQL's date formatting syntax as used by the
-    date_parse function.
 
-    For example `date_format(col("time"), "%Y, %d %M")` results in strings formatted as
-    "2017, 05 May".
+    Supported functions:
+    1. date_format(TIMESTAMP, STRING) -> STRING
+       Converts timestamp to a string, using a format string.
+       The format string is compatible with Java's DateTimeFormatter.
+    2. date_format(STRING, STRING) -> STRING
+       Converts timestamp string, using a format string.
+       The format string is compatible with Java's SimpleDateFormat.
+
+    Example:
+    ::
+
+        >>> table.select(date_format(to_timestamp('2020-04-15'), "yyyy/MM/dd"))
+        >>> table.select(date_format("2020-04-15", "MM/dd/yyyy"))
 
-    :param timestamp: The timestamp to format as string.
-    :param format: The format of the string.
     :return: The formatted timestamp as string.
     """
     return _binary_op("dateFormat", timestamp, format)

diff --git a/flink-python/pyflink/table/tests/test_expression.py b/flink-python/pyflink/table/tests/test_expression.py
@@ -275,6 +275,15 @@ def test_expressions(self):
                              lit(2).hours)))
         self.assertEqual("dateFormat(time, '%Y, %d %M')",
                          str(date_format(col("time"), "%Y, %d %M")))
+        self.assertEqual("dateFormat(toTimestamp('1970-01-01 08:01:40'), 'yyyy-MM-dd HH:mm:ss')",
+                         str(date_format(to_timestamp('1970-01-01 08:01:40'),
+                         "yyyy-MM-dd HH:mm:ss")))
+        self.assertEqual("DATE_FORMAT(TO_TIMESTAMP('1970-01-01 08:01:40.123456+02:00'), "
+                         "'yyyy-MM-dd HH:mm:ss.SSSSSS z')",
+                         str(date_format(to_timestamp('1970-01-01 08:01:40.123456+02:00'),
+                         'yyyy-MM-dd HH:mm:ss.SSSSSS z')))
+        self.assertEqual("dateFormat('1970-01-01 08:01:40', 'yyyy-MM-dd HH:mm:ss')",
+                         str(date_format("1970-01-01 08:01:40", "yyyy-MM-dd HH:mm:ss")))
         self.assertEqual("timestampDiff(DAY, cast('2016-06-15', DATE), cast('2016-06-18', DATE))",
                          str(timestamp_diff(
                              TimePointUnit.DAY,