Repository: spark Updated Branches: refs/heads/master 2b6ff0cef -> e17901d6d
[SPARK-22049][DOCS] Confusing behavior of from_utc_timestamp and to_utc_timestamp ## What changes were proposed in this pull request? Clarify behavior of to_utc_timestamp/from_utc_timestamp with an example ## How was this patch tested? Doc only change / existing tests Author: Sean Owen <so...@cloudera.com> Closes #19276 from srowen/SPARK-22049. Project: http://git-wip-us.apache.org/repos/asf/spark/repo Commit: http://git-wip-us.apache.org/repos/asf/spark/commit/e17901d6 Tree: http://git-wip-us.apache.org/repos/asf/spark/tree/e17901d6 Diff: http://git-wip-us.apache.org/repos/asf/spark/diff/e17901d6 Branch: refs/heads/master Commit: e17901d6df42edf2c7a3460995a0e954ad9a159f Parents: 2b6ff0c Author: Sean Owen <so...@cloudera.com> Authored: Wed Sep 20 20:47:17 2017 +0900 Committer: hyukjinkwon <gurwls...@gmail.com> Committed: Wed Sep 20 20:47:17 2017 +0900 ---------------------------------------------------------------------- R/pkg/R/functions.R | 10 ++++++---- python/pyspark/sql/functions.py | 10 ++++++---- .../catalyst/expressions/datetimeExpressions.scala | 14 ++++++++------ .../main/scala/org/apache/spark/sql/functions.scala | 10 ++++++---- 4 files changed, 26 insertions(+), 18 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/spark/blob/e17901d6/R/pkg/R/functions.R ---------------------------------------------------------------------- diff --git a/R/pkg/R/functions.R b/R/pkg/R/functions.R index e92e1fd..9f28626 100644 --- a/R/pkg/R/functions.R +++ b/R/pkg/R/functions.R @@ -2226,8 +2226,9 @@ setMethod("from_json", signature(x = "Column", schema = "characterOrstructType") }) #' @details -#' \code{from_utc_timestamp}: Given a timestamp, which corresponds to a certain time of day in UTC, -#' returns another timestamp that corresponds to the same time of day in the given timezone. +#' \code{from_utc_timestamp}: Given a timestamp like '2017-07-14 02:40:00.0', interprets it as a +#' time in UTC, and renders that time as a timestamp in the given time zone. For example, 'GMT+1' +#' would yield '2017-07-14 03:40:00.0'. #' #' @rdname column_datetime_diff_functions #' @@ -2286,8 +2287,9 @@ setMethod("next_day", signature(y = "Column", x = "character"), }) #' @details -#' \code{to_utc_timestamp}: Given a timestamp, which corresponds to a certain time of day -#' in the given timezone, returns another timestamp that corresponds to the same time of day in UTC. +#' \code{to_utc_timestamp}: Given a timestamp like '2017-07-14 02:40:00.0', interprets it as a +#' time in the given time zone, and renders that time as a timestamp in UTC. For example, 'GMT+1' +#' would yield '2017-07-14 01:40:00.0'. #' #' @rdname column_datetime_diff_functions #' @aliases to_utc_timestamp to_utc_timestamp,Column,character-method http://git-wip-us.apache.org/repos/asf/spark/blob/e17901d6/python/pyspark/sql/functions.py ---------------------------------------------------------------------- diff --git a/python/pyspark/sql/functions.py b/python/pyspark/sql/functions.py index 399bef0..57068fb 100644 --- a/python/pyspark/sql/functions.py +++ b/python/pyspark/sql/functions.py @@ -1150,8 +1150,9 @@ def unix_timestamp(timestamp=None, format='yyyy-MM-dd HH:mm:ss'): @since(1.5) def from_utc_timestamp(timestamp, tz): """ - Given a timestamp, which corresponds to a certain time of day in UTC, returns another timestamp - that corresponds to the same time of day in the given timezone. + Given a timestamp like '2017-07-14 02:40:00.0', interprets it as a time in UTC, and renders + that time as a timestamp in the given time zone. For example, 'GMT+1' would yield + '2017-07-14 03:40:00.0'. >>> df = spark.createDataFrame([('1997-02-28 10:30:00',)], ['t']) >>> df.select(from_utc_timestamp(df.t, "PST").alias('local_time')).collect() @@ -1164,8 +1165,9 @@ def from_utc_timestamp(timestamp, tz): @since(1.5) def to_utc_timestamp(timestamp, tz): """ - Given a timestamp, which corresponds to a certain time of day in the given timezone, returns - another timestamp that corresponds to the same time of day in UTC. + Given a timestamp like '2017-07-14 02:40:00.0', interprets it as a time in the given time + zone, and renders that time as a timestamp in UTC. For example, 'GMT+1' would yield + '2017-07-14 01:40:00.0'. >>> df = spark.createDataFrame([('1997-02-28 10:30:00',)], ['ts']) >>> df.select(to_utc_timestamp(df.ts, "PST").alias('utc_time')).collect() http://git-wip-us.apache.org/repos/asf/spark/blob/e17901d6/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/datetimeExpressions.scala ---------------------------------------------------------------------- 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 7035420..eaf8788 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 @@ -978,12 +978,13 @@ case class TimeAdd(start: Expression, interval: Expression, timeZoneId: Option[S } /** - * Given a timestamp, which corresponds to a certain time of day in UTC, returns another timestamp - * that corresponds to the same time of day in the given timezone. + * Given a timestamp like '2017-07-14 02:40:00.0', interprets it as a time in UTC, and renders + * that time as a timestamp in the given time zone. For example, 'GMT+1' would yield + * '2017-07-14 03:40:00.0'. */ // scalastyle:off line.size.limit @ExpressionDescription( - usage = "_FUNC_(timestamp, timezone) - Given a timestamp, which corresponds to a certain time of day in UTC, returns another timestamp that corresponds to the same time of day in the given timezone.", + usage = "_FUNC_(timestamp, timezone) - Given a timestamp like '2017-07-14 02:40:00.0', interprets it as a time in UTC, and renders that time as a timestamp in the given time zone. For example, 'GMT+1' would yield '2017-07-14 03:40:00.0'.", examples = """ Examples: > SELECT from_utc_timestamp('2016-08-31', 'Asia/Seoul'); @@ -1153,12 +1154,13 @@ case class MonthsBetween(date1: Expression, date2: Expression, timeZoneId: Optio } /** - * Given a timestamp, which corresponds to a certain time of day in the given timezone, returns - * another timestamp that corresponds to the same time of day in UTC. + * Given a timestamp like '2017-07-14 02:40:00.0', interprets it as a time in the given time zone, + * and renders that time as a timestamp in UTC. For example, 'GMT+1' would yield + * '2017-07-14 01:40:00.0'. */ // scalastyle:off line.size.limit @ExpressionDescription( - usage = "_FUNC_(timestamp, timezone) - Given a timestamp, which corresponds to a certain time of day in the given timezone, returns another timestamp that corresponds to the same time of day in UTC.", + usage = "_FUNC_(timestamp, timezone) - Given a timestamp like '2017-07-14 02:40:00.0', interprets it as a time in the given time zone, and renders that time as a timestamp in UTC. For example, 'GMT+1' would yield '2017-07-14 01:40:00.0'.", examples = """ Examples: > SELECT _FUNC_('2016-08-31', 'Asia/Seoul'); http://git-wip-us.apache.org/repos/asf/spark/blob/e17901d6/sql/core/src/main/scala/org/apache/spark/sql/functions.scala ---------------------------------------------------------------------- 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 c6d0d86..6bbdfa3 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 @@ -2791,8 +2791,9 @@ object functions { } /** - * Given a timestamp, which corresponds to a certain time of day in UTC, returns another timestamp - * that corresponds to the same time of day in the given timezone. + * Given a timestamp like '2017-07-14 02:40:00.0', interprets it as a time in UTC, and renders + * that time as a timestamp in the given time zone. For example, 'GMT+1' would yield + * '2017-07-14 03:40:00.0'. * @group datetime_funcs * @since 1.5.0 */ @@ -2801,8 +2802,9 @@ object functions { } /** - * Given a timestamp, which corresponds to a certain time of day in the given timezone, returns - * another timestamp that corresponds to the same time of day in UTC. + * Given a timestamp like '2017-07-14 02:40:00.0', interprets it as a time in the given time + * zone, and renders that time as a timestamp in UTC. For example, 'GMT+1' would yield + * '2017-07-14 01:40:00.0'. * @group datetime_funcs * @since 1.5.0 */ --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@spark.apache.org For additional commands, e-mail: commits-h...@spark.apache.org
