[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>
This commit is contained in:
parent
93f2b00501
commit
3719d87668
|
@ -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")
|
||||
|
|
|
@ -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);
|
||||
|
||||
-- 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);
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in a new issue