[SPARK-36606][DOCS][TESTS] Enhance the docs and tests of try_add/try_divide

### What changes were proposed in this pull request? The `try_add` function allows the following inputs: - number, number - date, number - date, interval - timestamp, interval - interval, interval And, the `try_divide` function allows the following inputs: - number, number - interval, number However, in the current code, there are only examples and tests about the (number, number) inputs. We should enhance the docs to let users know that the functions can be used for datetime and interval operations too. ### Why are the changes needed? Improve documentation and tests. ### Does this PR introduce _any_ user-facing change? No ### How was this patch tested? New UT Also build docs for preview: ![image](https://user-images.githubusercontent.com/1097932/131212897-8aea14c8-a882-4e12-94e2-f56bde7c0367.png) Closes #33861 from gengliangwang/enhanceTryDoc. Authored-by: Gengliang Wang <gengliang@apache.org> Signed-off-by: Hyukjin Kwon <gurwls223@apache.org> (cherry picked from commit 8a52ad9f82) Signed-off-by: Hyukjin Kwon <gurwls223@apache.org>
2021-08-29 10:30:04 +09:00 · 2021-08-29 10:30:04 +09:00 · 3719d87668
parent 93f2b00501
commit 3719d87668
3 changed files with 222 additions and 6 deletions
--- a/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/TryEval.scala
+++ b/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/TryEval.scala
@ -53,17 +53,28 @@ case class TryEval(child: Expression) extends UnaryExpression with NullIntoleran
    copy(child = newChild)
 }

+// scalastyle:off line.size.limit
@ExpressionDescription(
-  usage = "_FUNC_(expr1, expr2) - Returns `expr1`+`expr2` and the result is null on overflow.",
+  usage = "_FUNC_(expr1, expr2) - Returns the sum of `expr1`and `expr2` and the result is null on overflow. " +
+    "The acceptable input types are the same with the `+` operator.",
  examples = """
    Examples:
      > SELECT _FUNC_(1, 2);
       3
      > SELECT _FUNC_(2147483647, 1);
       NULL
+      > SELECT _FUNC_(date'2021-01-01', 1);
+       2021-01-02
+      > SELECT _FUNC_(date'2021-01-01', interval 1 year);
+       2022-01-01
+      > SELECT _FUNC_(timestamp'2021-01-01 00:00:00', interval 1 day);
+       2021-01-02 00:00:00
+      > SELECT _FUNC_(interval 1 year, interval 2 year);
+       3-0
  """,
  since = "3.2.0",
  group = "math_funcs")
+// scalastyle:on line.size.limit
 case class TryAdd(left: Expression, right: Expression, child: Expression)
    extends RuntimeReplaceable {
  def this(left: Expression, right: Expression) =
@ -81,7 +92,8 @@ case class TryAdd(left: Expression, right: Expression, child: Expression)

 // scalastyle:off line.size.limit
@ExpressionDescription(
-  usage = "_FUNC_(expr1, expr2) - Returns `expr1`/`expr2`. It always performs floating point division. Its result is always null if `expr2` is 0.",
+  usage = "_FUNC_(dividend, divisor) - Returns `dividend`/`divisor`. It always performs floating point division. Its result is always null if `expr2` is 0. " +
+    "`dividend` must be a numeric or an interval. `divisor` must be a numeric.",
  examples = """
    Examples:
      > SELECT _FUNC_(3, 2);
@ -90,6 +102,10 @@ case class TryAdd(left: Expression, right: Expression, child: Expression)
       1.0
      > SELECT _FUNC_(1, 0);
       NULL
+      > SELECT _FUNC_(interval 2 month, 2);
+       0-1
+      > SELECT _FUNC_(interval 2 month, 0);
+       NULL
  """,
  since = "3.2.0",
  group = "math_funcs")
--- a/sql/core/src/test/resources/sql-tests/inputs/try_arithmetic.sql
+++ b/sql/core/src/test/resources/sql-tests/inputs/try_arithmetic.sql
@ -1,11 +1,42 @@
-- TRY_ADD
+-- Numeric + Numeric
 SELECT try_add(1, 1);
 SELECT try_add(2147483647, 1);
 SELECT try_add(-2147483648, -1);
 SELECT try_add(9223372036854775807L, 1);
 SELECT try_add(-9223372036854775808L, -1);

-- TRY_DIVIDE
+-- Date + Integer
+SELECT try_add(date'2021-01-01', 1);
+SELECT try_add(1, date'2021-01-01');
+
+-- Date + Interval
+SELECT try_add(date'2021-01-01', interval 2 year);
+SELECT try_add(date'2021-01-01', interval 2 second);
+SELECT try_add(interval 2 year, date'2021-01-01');
+SELECT try_add(interval 2 second, date'2021-01-01');
+
+-- Timestamp + Interval
+SELECT try_add(timestamp_ltz'2021-01-01 00:00:00', interval 2 year);
+SELECT try_add(timestamp_ntz'2021-01-01 00:00:00', interval 2 second);
+SELECT try_add(interval 2 year, timestamp_ltz'2021-01-01 00:00:00');
+SELECT try_add(interval 2 second, timestamp_ntz'2021-01-01 00:00:00');
+
+-- Interval + Interval
+SELECT try_add(interval 2 year, interval 2 year);
+SELECT try_add(interval 2 second, interval 2 second);
+SELECT try_add(interval 2 year, interval 2 second);
+SELECT try_add(interval 2147483647 month, interval 2 month);
+SELECT try_add(interval 106751991 day, interval 3 day);
+
+-- Numeric / Numeric
 SELECT try_divide(1, 0.5);
 SELECT try_divide(1, 0);
-SELECT try_divide(0, 0);
+SELECT try_divide(0, 0);
+
+-- Interval / Numeric
+SELECT try_divide(interval 2 year, 2);
+SELECT try_divide(interval 2 second, 2);
+SELECT try_divide(interval 2 year, 0);
+SELECT try_divide(interval 2 second, 0);
+SELECT try_divide(interval 2147483647 month, 0.5);
+SELECT try_divide(interval 106751991 day, 0.5);
--- a/sql/core/src/test/resources/sql-tests/results/try_arithmetic.sql.out
+++ b/sql/core/src/test/resources/sql-tests/results/try_arithmetic.sql.out
@ -1,5 +1,5 @@
 -- Automatically generated by SQLQueryTestSuite
-- Number of queries: 8
+-- Number of queries: 29


 -- !query
@ -42,6 +42,127 @@ struct<try_add(-9223372036854775808, -1):bigint>
 NULL


+-- !query
+SELECT try_add(date'2021-01-01', 1)
+-- !query schema
+struct<try_add(DATE '2021-01-01', 1):date>
+-- !query output
+2021-01-02
+
+
+-- !query
+SELECT try_add(1, date'2021-01-01')
+-- !query schema
+struct<try_add(1, DATE '2021-01-01'):date>
+-- !query output
+2021-01-02
+
+
+-- !query
+SELECT try_add(date'2021-01-01', interval 2 year)
+-- !query schema
+struct<try_add(DATE '2021-01-01', INTERVAL '2' YEAR):date>
+-- !query output
+2023-01-01
+
+
+-- !query
+SELECT try_add(date'2021-01-01', interval 2 second)
+-- !query schema
+struct<try_add(DATE '2021-01-01', INTERVAL '02' SECOND):timestamp>
+-- !query output
+2021-01-01 00:00:02
+
+
+-- !query
+SELECT try_add(interval 2 year, date'2021-01-01')
+-- !query schema
+struct<try_add(INTERVAL '2' YEAR, DATE '2021-01-01'):date>
+-- !query output
+2023-01-01
+
+
+-- !query
+SELECT try_add(interval 2 second, date'2021-01-01')
+-- !query schema
+struct<try_add(INTERVAL '02' SECOND, DATE '2021-01-01'):timestamp>
+-- !query output
+2021-01-01 00:00:02
+
+
+-- !query
+SELECT try_add(timestamp_ltz'2021-01-01 00:00:00', interval 2 year)
+-- !query schema
+struct<try_add(TIMESTAMP '2021-01-01 00:00:00', INTERVAL '2' YEAR):timestamp>
+-- !query output
+2023-01-01 00:00:00
+
+
+-- !query
+SELECT try_add(timestamp_ntz'2021-01-01 00:00:00', interval 2 second)
+-- !query schema
+struct<try_add(TIMESTAMP_NTZ '2021-01-01 00:00:00', INTERVAL '02' SECOND):timestamp_ntz>
+-- !query output
+2021-01-01 00:00:02
+
+
+-- !query
+SELECT try_add(interval 2 year, timestamp_ltz'2021-01-01 00:00:00')
+-- !query schema
+struct<try_add(INTERVAL '2' YEAR, TIMESTAMP '2021-01-01 00:00:00'):timestamp>
+-- !query output
+2023-01-01 00:00:00
+
+
+-- !query
+SELECT try_add(interval 2 second, timestamp_ntz'2021-01-01 00:00:00')
+-- !query schema
+struct<try_add(INTERVAL '02' SECOND, TIMESTAMP_NTZ '2021-01-01 00:00:00'):timestamp_ntz>
+-- !query output
+2021-01-01 00:00:02
+
+
+-- !query
+SELECT try_add(interval 2 year, interval 2 year)
+-- !query schema
+struct<try_add(INTERVAL '2' YEAR, INTERVAL '2' YEAR):interval year>
+-- !query output
+4-0
+
+
+-- !query
+SELECT try_add(interval 2 second, interval 2 second)
+-- !query schema
+struct<try_add(INTERVAL '02' SECOND, INTERVAL '02' SECOND):interval second>
+-- !query output
+0 00:00:04.000000000
+
+
+-- !query
+SELECT try_add(interval 2 year, interval 2 second)
+-- !query schema
+struct<>
+-- !query output
+org.apache.spark.sql.AnalysisException
+cannot resolve 'INTERVAL '2' YEAR + INTERVAL '02' SECOND' due to data type mismatch: argument 1 requires (timestamp or timestamp without time zone) type, however, 'INTERVAL '2' YEAR' is of interval year type.; line 1 pos 7
+
+
+-- !query
+SELECT try_add(interval 2147483647 month, interval 2 month)
+-- !query schema
+struct<try_add(INTERVAL '2147483647' MONTH, INTERVAL '2' MONTH):interval month>
+-- !query output
+NULL
+
+
+-- !query
+SELECT try_add(interval 106751991 day, interval 3 day)
+-- !query schema
+struct<try_add(INTERVAL '106751991' DAY, INTERVAL '3' DAY):interval day>
+-- !query output
+NULL
+
+
 -- !query
 SELECT try_divide(1, 0.5)
 -- !query schema
@ -64,3 +185,51 @@ SELECT try_divide(0, 0)
 struct<try_divide(0, 0):double>
 -- !query output
 NULL
+
+
+-- !query
+SELECT try_divide(interval 2 year, 2)
+-- !query schema
+struct<try_divide(INTERVAL '2' YEAR, 2):interval year to month>
+-- !query output
+1-0
+
+
+-- !query
+SELECT try_divide(interval 2 second, 2)
+-- !query schema
+struct<try_divide(INTERVAL '02' SECOND, 2):interval day to second>
+-- !query output
+0 00:00:01.000000000
+
+
+-- !query
+SELECT try_divide(interval 2 year, 0)
+-- !query schema
+struct<try_divide(INTERVAL '2' YEAR, 0):interval year to month>
+-- !query output
+NULL
+
+
+-- !query
+SELECT try_divide(interval 2 second, 0)
+-- !query schema
+struct<try_divide(INTERVAL '02' SECOND, 0):interval day to second>
+-- !query output
+NULL
+
+
+-- !query
+SELECT try_divide(interval 2147483647 month, 0.5)
+-- !query schema
+struct<try_divide(INTERVAL '2147483647' MONTH, 0.5):interval year to month>
+-- !query output
+NULL
+
+
+-- !query
+SELECT try_divide(interval 106751991 day, 0.5)
+-- !query schema
+struct<try_divide(INTERVAL '106751991' DAY, 0.5):interval day to second>
+-- !query output
+NULL