diff --git a/R/pkg/R/functions.R b/R/pkg/R/functions.R index e92e1fd72bf1..9f286263c216 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 diff --git a/python/pyspark/sql/functions.py b/python/pyspark/sql/functions.py index 399bef02d9cc..57068fbae1dd 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() 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 70354200c82d..eaf878888821 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'); 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 c6d0d86384b7..6bbdfa3ad189 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 */