From 20edec80f943b0fb76d8bee26f47f8c19ca299be Mon Sep 17 00:00:00 2001 From: Jacek Laskowski Date: Fri, 28 Apr 2017 10:17:53 +0200 Subject: [PATCH 1/5] [MINOR][SQL][DOCS] Improve unix_timestamp's scaladoc (and typo hunting) --- .../expressions/datetimeExpressions.scala | 6 ++--- .../sql/catalyst/util/DateTimeUtils.scala | 2 +- .../org/apache/spark/sql/functions.scala | 25 +++++++++++++------ 3 files changed, 22 insertions(+), 11 deletions(-) diff --git a/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/datetimeExpressions.scala b/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/datetimeExpressions.scala index bb8fd5032d63..a98cd33f2780 100644 --- a/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/datetimeExpressions.scala +++ b/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/datetimeExpressions.scala @@ -488,7 +488,7 @@ case class DateFormatClass(left: Expression, right: Expression, timeZoneId: Opti * Deterministic version of [[UnixTimestamp]], must have at least one parameter. */ @ExpressionDescription( - usage = "_FUNC_(expr[, pattern]) - Returns the UNIX timestamp of the give time.", + usage = "_FUNC_(expr[, pattern]) - Returns the UNIX timestamp of the given time.", extended = """ Examples: > SELECT _FUNC_('2016-04-08', 'yyyy-MM-dd'); @@ -1225,8 +1225,8 @@ case class ParseToTimestamp(left: Expression, format: Expression, child: Express extends RuntimeReplaceable { def this(left: Expression, format: Expression) = { - this(left, format, Cast(UnixTimestamp(left, format), TimestampType)) -} + this(left, format, Cast(UnixTimestamp(left, format), TimestampType)) + } override def flatArguments: Iterator[Any] = Iterator(left, format) override def sql: String = s"$prettyName(${left.sql}, ${format.sql})" diff --git a/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/util/DateTimeUtils.scala b/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/util/DateTimeUtils.scala index eb6aad5b2d2b..6c1592fd8881 100644 --- a/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/util/DateTimeUtils.scala +++ b/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/util/DateTimeUtils.scala @@ -423,7 +423,7 @@ object DateTimeUtils { } /** - * Parses a given UTF8 date string to the corresponding a corresponding [[Int]] value. + * Parses a given UTF8 date string to a corresponding [[Int]] value. * The return type is [[Option]] in order to distinguish between 0 and null. The following * formats are allowed: * diff --git a/sql/core/src/main/scala/org/apache/spark/sql/functions.scala b/sql/core/src/main/scala/org/apache/spark/sql/functions.scala index f07e04368389..e89d93250435 100644 --- a/sql/core/src/main/scala/org/apache/spark/sql/functions.scala +++ b/sql/core/src/main/scala/org/apache/spark/sql/functions.scala @@ -2487,12 +2487,13 @@ object functions { */ def current_timestamp(): Column = withExpr { CurrentTimestamp() } + // scalastyle:off line.size.limit /** * Converts a date/timestamp/string to a value of string in the format specified by the date * format given by the second argument. * * A pattern could be for instance `dd.MM.yyyy` and could return a string like '18.03.1993'. All - * pattern letters of `java.text.SimpleDateFormat` can be used. + * pattern letters of [[https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html java.text.SimpleDateFormat]] can be used. * * @note Use when ever possible specialized functions like [[year]]. These benefit from a * specialized implementation. @@ -2500,6 +2501,7 @@ object functions { * @group datetime_funcs * @since 1.5.0 */ + // scalastyle:on line.size.limit def date_format(dateExpr: Column, format: String): Column = withExpr { DateFormatClass(dateExpr.expr, Literal(format)) } @@ -2647,7 +2649,11 @@ object functions { } /** - * Gets current Unix timestamp in seconds. + * Returns the current Unix timestamp (in seconds). + * + * NOTE: All calls of `unix_timestamp` within the same query return the same value + * (i.e. the current timestamp is calculated at the start of query evaluation). + * * @group datetime_funcs * @since 1.5.0 */ @@ -2657,7 +2663,9 @@ object functions { /** * Converts time string in format yyyy-MM-dd HH:mm:ss to Unix timestamp (in seconds), - * using the default timezone and the default locale, return null if fail. + * using the default timezone and the default locale. + * Returns `null` if fails. + * * @group datetime_funcs * @since 1.5.0 */ @@ -2665,14 +2673,17 @@ object functions { UnixTimestamp(s.expr, Literal("yyyy-MM-dd HH:mm:ss")) } + // scalastyle:off line.size.limit /** - * Convert time string with given pattern - * (see [http://docs.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html]) - * to Unix time stamp (in seconds), return null if fail. + * Converts time string with given pattern to Unix timestamp (in seconds). + * Returns `null` if fails. + * + * @see [[http://docs.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html Customizing Formats]] * @group datetime_funcs * @since 1.5.0 */ - def unix_timestamp(s: Column, p: String): Column = withExpr {UnixTimestamp(s.expr, Literal(p)) } + // scalastyle:on + def unix_timestamp(s: Column, p: String): Column = withExpr { UnixTimestamp(s.expr, Literal(p)) } /** * Convert time string to a Unix timestamp (in seconds). From c3cc96b9c99cc4b3a4efdcf58e5bd63b28daaff9 Mon Sep 17 00:00:00 2001 From: Jacek Laskowski Date: Fri, 28 Apr 2017 11:08:30 +0200 Subject: [PATCH 2/5] Review round 1 --- .../src/main/scala/org/apache/spark/sql/functions.scala | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/sql/core/src/main/scala/org/apache/spark/sql/functions.scala b/sql/core/src/main/scala/org/apache/spark/sql/functions.scala index e89d93250435..974f15f16c80 100644 --- a/sql/core/src/main/scala/org/apache/spark/sql/functions.scala +++ b/sql/core/src/main/scala/org/apache/spark/sql/functions.scala @@ -2487,21 +2487,19 @@ object functions { */ def current_timestamp(): Column = withExpr { CurrentTimestamp() } - // scalastyle:off line.size.limit /** * Converts a date/timestamp/string to a value of string in the format specified by the date * format given by the second argument. * - * A pattern could be for instance `dd.MM.yyyy` and could return a string like '18.03.1993'. All - * pattern letters of [[https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html java.text.SimpleDateFormat]] can be used. + * A pattern `dd.MM.yyyy` would return a string like `18.03.1993`. + * All pattern letters of `java.text.SimpleDateFormat` can be used. * - * @note Use when ever possible specialized functions like [[year]]. These benefit from a + * @note Use specialized functions like [[year]] whenever possible as they benefit from a * specialized implementation. * * @group datetime_funcs * @since 1.5.0 */ - // scalastyle:on line.size.limit def date_format(dateExpr: Column, format: String): Column = withExpr { DateFormatClass(dateExpr.expr, Literal(format)) } From 742fbb41c283c2182aceac7d61f5132885918655 Mon Sep 17 00:00:00 2001 From: Jacek Laskowski Date: Sat, 6 May 2017 21:55:21 +0200 Subject: [PATCH 3/5] Review round 2 --- sql/core/src/main/scala/org/apache/spark/sql/functions.scala | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql/core/src/main/scala/org/apache/spark/sql/functions.scala b/sql/core/src/main/scala/org/apache/spark/sql/functions.scala index 974f15f16c80..0153ab1d1c20 100644 --- a/sql/core/src/main/scala/org/apache/spark/sql/functions.scala +++ b/sql/core/src/main/scala/org/apache/spark/sql/functions.scala @@ -2676,7 +2676,7 @@ object functions { * Converts time string with given pattern to Unix timestamp (in seconds). * Returns `null` if fails. * - * @see [[http://docs.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html Customizing Formats]] + * @see Customizing Formats * @group datetime_funcs * @since 1.5.0 */ From 1079b7d46589752e0c5bfa2ebb9d7cdd6f113561 Mon Sep 17 00:00:00 2001 From: Jacek Laskowski Date: Sun, 7 May 2017 17:59:18 +0200 Subject: [PATCH 4/5] Review round 3 --- sql/core/src/main/scala/org/apache/spark/sql/functions.scala | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/sql/core/src/main/scala/org/apache/spark/sql/functions.scala b/sql/core/src/main/scala/org/apache/spark/sql/functions.scala index 0153ab1d1c20..6c32560bca3f 100644 --- a/sql/core/src/main/scala/org/apache/spark/sql/functions.scala +++ b/sql/core/src/main/scala/org/apache/spark/sql/functions.scala @@ -2671,16 +2671,15 @@ object functions { UnixTimestamp(s.expr, Literal("yyyy-MM-dd HH:mm:ss")) } - // scalastyle:off line.size.limit /** * Converts time string with given pattern to Unix timestamp (in seconds). * Returns `null` if fails. * - * @see Customizing Formats + * @see + * Customizing Formats * @group datetime_funcs * @since 1.5.0 */ - // scalastyle:on def unix_timestamp(s: Column, p: String): Column = withExpr { UnixTimestamp(s.expr, Literal(p)) } /** From c96f137a1c72b19a777415b2d7883770448d1184 Mon Sep 17 00:00:00 2001 From: Jacek Laskowski Date: Sun, 7 May 2017 18:01:46 +0200 Subject: [PATCH 5/5] Review round 3 (missed one comment) --- sql/core/src/main/scala/org/apache/spark/sql/functions.scala | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql/core/src/main/scala/org/apache/spark/sql/functions.scala b/sql/core/src/main/scala/org/apache/spark/sql/functions.scala index 6c32560bca3f..987011edfe1e 100644 --- a/sql/core/src/main/scala/org/apache/spark/sql/functions.scala +++ b/sql/core/src/main/scala/org/apache/spark/sql/functions.scala @@ -2649,7 +2649,7 @@ object functions { /** * Returns the current Unix timestamp (in seconds). * - * NOTE: All calls of `unix_timestamp` within the same query return the same value + * @note All calls of `unix_timestamp` within the same query return the same value * (i.e. the current timestamp is calculated at the start of query evaluation). * * @group datetime_funcs