Spark SQL functions.scala 源码解析（八）DateTime functions （基于 Spark 3.3.0）

发布时间：2024-01-28 11:00

前言

本文隶属于专栏《1000个问题搞定大数据技术体系》，该专栏为笔者原创，引用请注明来源，不足和错误之处请在评论区帮忙指出，谢谢！

本专栏目录结构和参考文献请见1000个问题搞定大数据技术体系

关联

Spark SQL 内置函数（三）Date and Timestamp Functions（基于 Spark 3.2.0）

正文

add_months

1

  /**
   * @since 1.5.0
   */
  def add_months(startDate: Column, numMonths: Int): Column = add_months(startDate, lit(numMonths))

说明

返回startDate之后numMonths的日期。

参数

startDate – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为日期的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS
numMonths – 添加到startDate的月数，可以为负数以减去月数

日期，如果startDate是无法转换为日期的字符串，则为 null

2

  /**
   * @since 3.0.0
   */
  def add_months(startDate: Column, numMonths: Column): Column = withExpr {
    AddMonths(startDate.expr, numMonths.expr)
  }

说明

返回startDate之后numMonths的日期。

参数

startDate – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为日期的格式，例如yyyy-MM-dd 或yyyy-MM-dd HH:mm:ss.SSSS
numMonths – 要添加到startDate的月数列，可以为负数以减去月数

日期，如果startDate是无法转换为日期的字符串，则为 null

current_date/current_timestamp/localtimestamp

1

  /**

   *
   * @since 1.5.0
   */
  def current_date(): Column = withExpr { CurrentDate() }

说明

将查询评估开始时的当前时间戳作为时间戳列返回。
在同一查询中对 current_timestamp 的所有调用都返回相同的值。

2

  /**
   * @since 1.5.0
   */
  def current_timestamp(): Column = withExpr { CurrentTimestamp() }

说明

将查询评估开始时的当前时间戳作为时间戳列返回。
在同一查询中对 current_timestamp 的所有调用都返回相同的值。

3

  /**
   * @since 3.3.0
   */
  def localtimestamp(): Column = withExpr { LocalTimestamp() }

说明

返回查询评估开始时不带时区的当前时间戳作为不带时区列的时间戳。
同一查询中的所有 localtimestamp 调用都返回相同的值。

date_format

1

  /**
   * @since 1.5.0
   */
  def date_format(dateExpr: Column, format: String): Column = withExpr {
    DateFormatClass(dateExpr.expr, Literal(format))
  }

说明

将日期/时间戳/字符串转换为字符串值，其格式由第二个参数给出的日期格式指定。
有关有效的日期和时间格式模式，请参阅日期时间模式

参数

dateExpr – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为时间戳的格式，例如yyyy-MM-dd yyyy-MM-dd HH:mm:ss.SSSS
format – 模式dd.MM.yyyy将返回一个字符串，如18.03.1993

一个字符串，如果dateExpr是一个无法转换为时间戳的字符串，则为null

抛出

IllegalArgumentException – 如果格式模式无效

注意

尽可能使用像year这样的专门函数，因为它们可以从专门的实现中受益。

date_add/date_sub

1

  /**
   * @since 1.5.0
   */
  def date_add(start: Column, days: Int): Column = date_add(start, lit(days))

说明

返回 start 后 days 天的日期

参数

start – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为日期的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS
days - 添加到start的天数，可以为负数以减去天数

日期，如果start是无法转换为日期的字符串，则为 null

2

  /**
   * @since 3.0.0
   */
  def date_add(start: Column, days: Column): Column = withExpr { DateAdd(start.expr, days.expr) }

说明

返回 start 后 days 天的日期

参数

start – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为日期的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS
days - 添加到start的天数列，可以为负数以减去天数

日期，如果start是无法转换为日期的字符串，则为 null

3

   * @since 1.5.0
   */
  def date_sub(start: Column, days: Int): Column = date_sub(start, lit(days))

说明

返回 start 前 days 天的日期

参数

start – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为日期的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS
days – 要从start 中减去的天数，可以为负数以添加天数

日期，如果start是无法转换为日期的字符串，则为 null

4

  /**
   * @since 3.0.0
   */
  def date_sub(start: Column, days: Column): Column = withExpr { DateSub(start.expr, days.expr) }

说明

返回 start 前 days 天的日期

参数

start – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为日期的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS
days – 要从start 中减去的天数列，可以为负数以添加天数

日期，如果start是无法转换为日期的字符串，则为 null

datediff

  /**
   * @since 1.5.0
   */
  def datediff(end: Column, start: Column): Column = withExpr { DateDiff(end.expr, start.expr) }

说明

返回从start到end的天数。
只考虑输入的日期部分。例如：

// returns 1
dateddiff(\"2018-01-10 00:00:00\", \"2018-01-09 23:59:59\")

参数

end – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为日期的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS
start – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为日期的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS

一个整数，如果end或start是无法转换为日期的字符串，则为 null。如果结束在开始之前则为负

year

  /**
   * @since 1.5.0
   */
  def year(e: Column): Column = withExpr { Year(e.expr) }

说明

从给定的日期/时间戳/字符串中以整数形式提取年份。

整数，如果输入是无法转换为日期的字符串，则为 null

quarter

  /**
   * @since 1.5.0
   */
  def quarter(e: Column): Column = withExpr { Quarter(e.expr) }

说明

从给定的日期/时间戳/字符串中提取作为整数的季度。

整数，如果输入是无法转换为日期的字符串，则为 null

month

  /**
   * @since 1.5.0
   */
  def month(e: Column): Column = withExpr { Month(e.expr) }

说明

从给定的日期/时间戳/字符串中提取月份作为整数。

整数，如果输入是无法转换为日期的字符串，则为 null

dayofweek/dayofmonth/dayofyear

1

  /**
   * @since 2.3.0
   */
  def dayofweek(e: Column): Column = withExpr { DayOfWeek(e.expr) }

说明

从给定的日期/时间戳/字符串中以整数形式提取星期几。范围从周日的 1 到周六的 7

整数，如果输入是无法转换为日期的字符串，则为 null

2

  /**
   * @since 1.5.0
   */
  def dayofmonth(e: Column): Column = withExpr { DayOfMonth(e.expr) }

说明

从给定的日期/时间戳/字符串中提取月份中的某一天作为整数。

整数，如果输入是无法转换为日期的字符串，则为 null

3

  /**
   * @since 1.5.0
   */
  def dayofyear(e: Column): Column = withExpr { DayOfYear(e.expr) }

说明

从给定的日期/时间戳/字符串中提取一年中的某一天作为整数。

整数，如果输入是无法转换为日期的字符串，则为 null

hour

  /**
   * @since 1.5.0
   */
  def hour(e: Column): Column = withExpr { Hour(e.expr) }

说明

从给定的日期/时间戳/字符串中以整数形式提取小时数。

整数，如果输入是无法转换为日期的字符串，则为 null

last_day

  /**
   * @since 1.5.0
   */
  def last_day(e: Column): Column = withExpr { LastDay(e.expr) }

说明

返回给定日期所属月份的最后一天。
例如，输入“2015-07-27”返回“2015-07-31”，因为7月31日是2015年7月的最后一天。

参数

e – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为日期的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS

日期，如果输入是无法转换为日期的字符串，则为 null

minute

  /**
   * @since 1.5.0
   */
  def minute(e: Column): Column = withExpr { Minute(e.expr) }

说明

从给定的日期/时间戳/字符串中提取分钟作为整数。

整数，如果输入是无法转换为日期的字符串，则为 null

make_date

  /**
   * @since 3.3.0
   */
  def make_date(year: Column, month: Column, day: Column): Column = withExpr {
    MakeDate(year.expr, month.expr, day.expr)
  }

基于年、月和日字段创建的日期。

months_between

1

  /**
   * @since 1.5.0
   */
  def months_between(end: Column, start: Column): Column = withExpr {
    new MonthsBetween(end.expr, start.expr)
  }

说明

返回日期start和end之间的月数。
如果两个输入具有相同的月份日期或两者都是各自月份的最后一天，则返回一个整数。否则，按每月 31 天计算差异。
例如

months_between(\"2017-11-14\", \"2017-07-14\")  // returns 4.0
months_between(\"2017-01-01\", \"2017-01-10\")  // returns 0.29032258
months_between(\"2017-06-01\", \"2017-06-16 12:00:00\")  // returns -0.5

参数

end – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为时间戳的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS
start – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为时间戳的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS

如果end或start是无法转换为时间戳的字符串，则为双精度值或 null。
如果end在start之前则为负

2

  /**
   * @since 2.4.0
   */
  def months_between(end: Column, start: Column, roundOff: Boolean): Column = withExpr {
    MonthsBetween(end.expr, start.expr, lit(roundOff).expr)
  }

说明

返回日期end和start之间的月数。
如果roundOff设置为 true，则结果四舍五入为 8 位；否则不会四舍五入。

next_day

1

  /**
   * @since 1.5.0
   */
  def next_day(date: Column, dayOfWeek: String): Column = next_day(date, lit(dayOfWeek))

说明

返回第一个日期，该日期晚于指定的星期几的日期列的值。
例如， next_day(‘2015-07-27’, “Sunday”)返回 2015-08-02，因为那是 2015-07-27 之后的第一个星期日。

参数

date – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为日期的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS
dayOfWeek – 不区分大小写，并接受：“Mon”、“Tue”、“Wed”、“Thu”、“Fri”、“Sat”、“Sun”

日期，如果日期是无法转换为日期的字符串或如果dayOfWeek是无效值，则为null

2

  /**
   * @since 3.2.0
   */
  def next_day(date: Column, dayOfWeek: Column): Column = withExpr {
    NextDay(date.expr, dayOfWeek.expr)
  }

说明

返回第一个日期，该日期晚于指定的星期几的日期列的值。
例如， next_day(‘2015-07-27’, “Sunday”)返回 2015-08-02，因为那是 2015-07-27 之后的第一个星期日。

参数

date – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为日期的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS
dayOfWeek – 不区分大小写，并接受：“Mon”、“Tue”、“Wed”、“Thu”、“Fri”、“Sat”、“Sun”

日期，如果日期是无法转换为日期的字符串或如果dayOfWeek是无效值，则为null

second

  /**
   * @since 1.5.0
   */
  def second(e: Column): Column = withExpr { Second(e.expr) }

说明

从给定的日期/时间戳/字符串中以整数形式提取秒数。

整数，如果输入是无法转换为时间戳的字符串，则为 null

weekofyear

  /**
   * @since 1.5.0
   */
  def weekofyear(e: Column): Column = withExpr { WeekOfYear(e.expr) }

说明

从给定的日期/时间戳/字符串中提取作为整数的周数。
根据 ISO 8601 的定义，一周被视为从星期一开始，第 1 周是超过 3 天的第一周

国际标准化组织的国际标准ISO 8601是日期和时间的表示方法，全称为《数据存储和交换形式·信息交换·日期和时间的表示方法》。最新为第三版ISO8601:2004，第一版为ISO8601:1988，第二版为ISO8601:2000。可以用2位数表示年内第几个日历星期，再加上一位数表示日历星期内第几天，但日历星期前要加上一个大写字母W，如2004年5月3日可写成2004-W19-1或2004W191。但2005-W011是从2005年1月3日开始的，前几天属于上年的第53个日历星期。每个日历星期从星期一开始，星期日为第7天。
第一个日历星期有以下四种等效说法：
1，本年度第一个星期四所在的星期；
2，1月4日所在的星期；
3，本年度第一个至少有4天在同一星期内的星期；
4，星期一在去年12月29日至今年1月4日以内的星期；
推理可得，如果1月1日是星期一、星期二、星期三或者星期四，它所在的星期就是第一个日历星期；如果1月1日是星期五、星期六或者星期日，它所在的星期就是上一年第52或者53个日历星期；12月28日总是在一年最后一个日历星期。

整数，如果输入是无法转换为日期的字符串，则为 null

from_unixtime

1

  /**
   * @since 1.5.0
   */
  def from_unixtime(ut: Column): Column = withExpr {
    FromUnixTime(ut.expr, Literal(TimestampFormatter.defaultPattern))
  }

说明

将 unix epoch (1970-01-01 00:00:00 UTC) 中的秒数转换为表示当前系统时区中该时刻时间戳的字符串，格式为 yyyy-MM-dd HH:mm:ss。

参数

ut – 可转换为 long 类型的数字，例如字符串或整数。 unix 纪元之前的时间戳可能为负

一个字符串，如果输入是一个无法转换为 long 的字符串，则为 null

2

   * @since 1.5.0
   */
  def from_unixtime(ut: Column, f: String): Column = withExpr {
    FromUnixTime(ut.expr, Literal(f))
  }

说明

将 unix epoch (1970-01-01 00:00:00 UTC) 中的秒数转换为一个字符串，以给定格式表示当前系统时区中该时刻的时间戳。
有关有效的日期和时间格式模式，请参阅Datetime Patterns

参数

ut – 可转换为 long 类型的数字，例如字符串或整数。 unix 纪元之前的时间戳可能为负
f – 输入将被格式化为的日期时间模式

一个字符串，如果ut是一个无法转换为 long 的字符串，或者f是一个无效的日期时间模式，则返回 null

unix_timestamp

1

  /**
   * @group datetime_funcs
   * @since 1.5.0
   */
  def unix_timestamp(): Column = withExpr {
    UnixTimestamp(CurrentTimestamp(), Literal(TimestampFormatter.defaultPattern))
  }

说明

以 long 形式返回当前的 Unix 时间戳（以秒为单位）。

注意

同一个查询中的所有unix_timestamp调用都返回相同的值（即当前时间戳是在查询评估开始时计算的）。

2

  /**
   * @since 1.5.0
   */
  def unix_timestamp(s: Column): Column = withExpr {
    UnixTimestamp(s.expr, Literal(TimestampFormatter.defaultPattern))
  }

说明

使用默认时区和默认语言环境将 yyyy-MM-dd HH:mm:ss 格式的时间字符串转换为 Unix 时间戳（以秒为单位）。

参数

s – 日期、时间戳或字符串。如果是字符串，数据必须是yyyy-MM-dd HH:mm:ss格式

如果输入是格式不正确的字符串，则为 long 或 null

3

  /**
   * @since 1.5.0
   */
  def unix_timestamp(s: Column, p: String): Column = withExpr { UnixTimestamp(s.expr, Literal(p)) }

说明

将具有给定模式的时间字符串转换为 Unix 时间戳（以秒为单位）。
有关有效的日期和时间格式模式，请参阅Datetime Patterns

参数

s – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为日期的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS
p – 当s是字符串时，详细说明s格式的日期时间模式

如果s是无法转换为日期的字符串或p是无效格式，则为 long 或 null

to_timestamp

1

  /**
   * @since 2.2.0
   */
  def to_timestamp(s: Column): Column = withExpr {
    new ParseToTimestamp(s.expr)
  }

说明

通过将规则转换为TimestampType来转换为时间戳。

参数

s – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为时间戳的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS

时间戳，如果输入是无法转换为时间戳的字符串，则返回 null

2

  /**
   * @since 2.2.0
   */
  def to_timestamp(s: Column, fmt: String): Column = withExpr {
    new ParseToTimestamp(s.expr, Literal(fmt))
  }

说明

将具有给定模式的时间字符串转换为时间戳。
有关有效的日期和时间格式模式，请参阅Datetime Patterns

参数

s – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为时间戳的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS
fmt – 当s是字符串时，详细说明s格式的日期时间模式

时间戳，如果s是无法转换为时间戳的字符串或fmt是无效格式，则返回 null

to_date

1

  /**
   * @since 1.5.0
   */
  def to_date(e: Column): Column = withExpr { new ParseToDate(e.expr) }

说明

通过转换 DateType 的规则将列转换为 DateType 类型。

2

  /**
   * @since 2.2.0
   */
  def to_date(e: Column, fmt: String): Column = withExpr {
    new ParseToDate(e.expr, Literal(fmt))
  }

说明

将列转换为具有指定格式的DateType
有关有效的日期和时间格式模式，请参阅Datetime Patterns

参数

e – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为日期的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS
fmt – 当e是字符串时，详细说明e格式的日期时间模式

日期，如果e是无法转换为日期的字符串或fmt是无效格式，则为 null

trunc/date_trunc

1

  /**
   * @since 1.5.0
   */
  def trunc(date: Column, format: String): Column = withExpr {
    TruncDate(date.expr, Literal(format))
  }

说明

返回截断为指定格式单位的日期。
例如， trunc(“2018-11-19 12:01:19”, “year”)返回 2018-01-01

参数

date – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为日期的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS
format – : ‘year’, ‘yyyy’, ‘yy’ 按年截断，或 ‘month’, ‘mon’, ‘mm’ 按月截断其他选项有：‘week’, ‘quarter’

日期，如果日期是无法转换为日期的字符串或格式为无效值，则返回 null

2

  /**
   * @since 2.3.0
   */
  def date_trunc(format: String, timestamp: Column): Column = withExpr {
    TruncTimestamp(Literal(format), timestamp.expr)
  }

说明

返回截断为格式指定单位的时间戳。
例如， date_trunc(“year”, “2018-11-19 12:01:19”)返回 2018-01-01 00:00:00

参数

format – : ‘year’, ‘yyyy’, ‘yy’ 按年截断, ‘month’, ‘mon’, ‘mm’ 按月截断, ‘day’, ‘dd’ 按天截断, 其他选项有：‘微秒’，‘毫秒’，‘秒’，‘分钟’，‘小时’，‘周’，‘季度’
timestamp – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为时间戳的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS

时间戳，如果时间戳是无法转换为时间戳的字符串或格式为无效值，则返回 null

from_utc_timestamp/to_utc_timestamp

1

  /**
   * @since 1.5.0
   */
  def from_utc_timestamp(ts: Column, tz: String): Column = withExpr {
    FromUTCTimestamp(ts.expr, Literal(tz))
  }

说明

给定一个时间戳，如“2017-07-14 02:40:00.0”，将其解释为 UTC 时间，并将该时间呈现为给定时区的时间戳。
例如，“GMT+1”将产生“2017-07-14 03:40:00.0”。

参数

ts – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为时间戳的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS
tz – 一个字符串，详细说明输入应调整到的时区 ID。它应该采用基于区域的区域 ID 或区域偏移的格式。地区 ID 的格式必须为“区域/城市”，例如“America/Los_Angeles”。区域偏移量必须采用“(+|-)HH:mm”格式，例如“-08:00”或“+01:00”。还支持“UTC”和“Z”作为“+00:00”的别名。不建议使用其他短名称，因为它们可能会模棱两可。

时间戳，如果ts是无法转换为时间戳的字符串或tz是无效值，则返回 null

2

  /**
   * @since 2.4.0
   */
  def from_utc_timestamp(ts: Column, tz: Column): Column = withExpr {
    FromUTCTimestamp(ts.expr, tz.expr)
  }

说明

给定一个时间戳，如“2017-07-14 02:40:00.0”，将其解释为 UTC 时间，并将该时间呈现为给定时区的时间戳。
例如，“GMT+1”将产生“2017-07-14 03:40:00.0”。

3

  /**
   * @since 1.5.0
   */
  def to_utc_timestamp(ts: Column, tz: String): Column = withExpr {
    ToUTCTimestamp(ts.expr, Literal(tz))
  }

说明

给定一个时间戳，如“2017-07-14 02:40:00.0”，将其解释为给定时区的时间，并将该时间呈现为 UTC 时间戳。
例如，“GMT+1”将产生“2017-07-14 01:40:00.0”。

参数

ts – 日期、时间戳或字符串。如果是字符串，则数据必须采用可以转换为时间戳的格式，例如yyyy-MM-dd或yyyy-MM-dd HH:mm:ss.SSSS
tz – 一个字符串，详细说明输入应调整到的时区 ID。它应该采用基于区域的区域 ID 或区域偏移的格式。地区 ID 的格式必须为“区域/城市”，例如“America/Los_Angeles”。区域偏移量必须采用“(+|-)HH:mm”格式，例如“-08:00”或“+01:00”。还支持“UTC”和“Z”作为“+00:00”的别名。不建议使用其他短名称，因为它们可能会模棱两可。

时间戳，如果ts是无法转换为时间戳的字符串或tz是无效值，则返回 null

4

  /**
   * @since 2.4.0
   */
  def to_utc_timestamp(ts: Column, tz: Column): Column = withExpr {
    ToUTCTimestamp(ts.expr, tz.expr)
  }

说明

给定一个时间戳，如“2017-07-14 02:40:00.0”，将其解释为给定时区的时间，并将该时间呈现为 UTC 时间戳。
例如，“GMT+1”将产生“2017-07-14 01:40:00.0”。

参数

window/session_window

1

  /**
   * @since 2.0.0
   */
  def window(
      timeColumn: Column,
      windowDuration: String,
      slideDuration: String,
      startTime: String): Column = {
    withExpr {
      TimeWindow(timeColumn.expr, windowDuration, slideDuration, startTime)
    }.as(\"window\")
  }

说明

给定指定列的时间戳，将行压缩为一个或多个时间窗口。
窗口开始是包含的，但窗口结束是独占的，例如，12:05将在[12:05,12:10]窗口中，但不在[12:00,12:05]窗口中。
windows可以支持微秒精度。
不支持以月为单位的窗口。

例子

以下是一个平均股价的例子，每10秒种一个一分钟窗口，从当前小时开始后5秒开始计算：

val df = ... // schema => timestamp: TimestampType, stockId: StringType, price: DoubleType
df.groupBy(window($\"timestamp\", \"1 minute\", \"10 seconds\", \"5 seconds\"), $\"stockId\").agg(mean(\"price\"))

窗口将看起来像：

09:00:05-09:01:05 
09:00:15-09:01:15 
09:00:25-09:01:25 
...

对于流式查询，可以使用函数current_timestamp生成处理时间窗口。

参数

timeColumn–用作时间窗口的时间戳的列或表达式。时间列必须是TimestampType。
windowDuration–指定窗口宽度的字符串，例如10 minutes，1 second。查看org.apache.spark.unsafe.types.CalendarInterval 获取有效的持续时间（duration）标识符。请注意，持续时间（duration）是一个固定的时间长度，不会随日历的不同而变化。例如，1天总是意味着86400000毫秒，而不是日历日。
slideDuration–指定窗口滑动间隔的字符串，例如1分钟。每次滑动都会生成一个新窗口。必须小于或等于windowDuration。查看org.apache.spark.unsafe.types.CalendarInterval 获取有效的持续时间（duration）标识符。这一持续时间（duration）同样是绝对的，不会因日历而异。
startTime–相对于1970-01-01 00:00:00 UTC的偏移量，用于开始窗口间隔。例如，为了使每小时滚动窗口在一小时后15分钟开始，例如12:15-13:15，13:15-14:15。。。提供15分钟的启动时间。

CalendarInterval 表示日历间隔的类。日历间隔内部存储在三个组件中：一个整数值，表示此间隔内的“月”数；一个整数值，表示此间隔内的“天”数；一个长整数值，表示此间隔中的“微秒”数。 “月”和“天”不是长度不变的时间单位（不同于小时、秒），因此它们是两个与微秒分开的字段。一个月可能等于28、29、30或31天，一天可能等于23、24或25小时（夏令时）。

2


  /**
   * @since 2.0.0
   */
  def window(timeColumn: Column, windowDuration: String, slideDuration: String): Column = {
    window(timeColumn, windowDuration, slideDuration, \"0 second\")
  }

说明

给定指定列的时间戳，将行压缩为一个或多个时间窗口。
窗口开始是包含的，但窗口结束是独占的，例如，12:05将在[12:05,12:10]窗口中，但不在[12:00,12:05]窗口中。
windows可以支持微秒精度。
不支持以月为单位的窗口。

例子

以下是一个平均股价的例子，每10秒种一个一分钟窗口，从当前小时开始后5秒开始计算：

val df = ... // schema => timestamp: TimestampType, stockId: StringType, price: DoubleType
df.groupBy(window($\"timestamp\", \"1 minute\", \"10 seconds\"), $\"stockId\").agg(mean(\"price\"))

窗口将看起来像：

09:00:00-09:01:00
09:00:10-09:01:10
09:00:20-09:01:20 
...

对于流式查询，可以使用函数current_timestamp生成处理时间窗口。

参数

timeColumn–用作时间窗口的时间戳的列或表达式。时间列必须是TimestampType。
windowDuration–指定窗口宽度的字符串，例如10 minutes，1 second。查看org.apache.spark.unsafe.types.CalendarInterval 获取有效的持续时间（duration）标识符。请注意，持续时间（duration）是一个固定的时间长度，不会随日历的不同而变化。例如，1天总是意味着86400000毫秒，而不是日历日。
slideDuration–指定窗口滑动间隔的字符串，例如1分钟。每次滑动都会生成一个新窗口。必须小于或等于windowDuration。查看org.apache.spark.unsafe.types.CalendarInterval 获取有效的持续时间（duration）标识符。这一持续时间（duration）同样是绝对的，不会因日历而异。

3

  /**
   * @since 2.0.0
   */
  def window(timeColumn: Column, windowDuration: String): Column = {
    window(timeColumn, windowDuration, windowDuration, \"0 second\")
  }

说明

给定指定列的时间戳，将行压缩为一个或多个时间窗口。
窗口开始是包含的，但窗口结束是独占的，例如，12:05将在[12:05,12:10]窗口中，但不在[12:00,12:05]窗口中。
windows可以支持微秒精度。
不支持以月为单位的窗口。

例子

以下是一个平均股价的例子，每10秒种一个一分钟窗口，从当前小时开始后5秒开始计算：

val df = ... // schema => timestamp: TimestampType, stockId: StringType, price: DoubleType
df.groupBy(window($\"timestamp\", \"1 minute\"), $\"stockId\").agg(mean(\"price\"))

窗口将看起来像：

09:00:00-09:01:00
09:01:00-09:02:00
09:02:00-09:03:00 
...

对于流式查询，可以使用函数current_timestamp生成处理时间窗口。

参数

timeColumn–用作时间窗口的时间戳的列或表达式。时间列必须是TimestampType。
windowDuration–指定窗口宽度的字符串，例如10 minutes，1 second。查看org.apache.spark.unsafe.types.CalendarInterval 获取有效的持续时间（duration）标识符。请注意，持续时间（duration）是一个固定的时间长度，不会随日历的不同而变化。例如，1天总是意味着86400000毫秒，而不是日历日。
slideDuration–指定窗口滑动间隔的字符串，例如1分钟。每次滑动都会生成一个新窗口。必须小于或等于windowDuration。查看org.apache.spark.unsafe.types.CalendarInterval 获取有效的持续时间（duration）标识符。这一持续时间（duration）同样是绝对的，不会因日历而异。

4

  /**
   * @since 3.2.0
   */
  def session_window(timeColumn: Column, gapDuration: String): Column = {
    withExpr {
      SessionWindow(timeColumn.expr, gapDuration)
    }.as(\"session_window\")
  }

说明

根据指定列的时间戳生成会话窗口。
会话窗口是一种动态窗口，它意味着窗口的长度根据给定的输入而变化。
会话窗口的长度定义为“会话最新输入的时间戳+间隙持续时间”，因此当新输入绑定到当前会话窗口时，会话窗口的结束时间可以根据新输入进行扩展。
windows可以支持微秒精度。
不支持以月为单位的gapDuration。
对于流式查询，可以使用函数current_timestamp生成处理时间窗口。

参数

timeColumn–用作时间窗口的时间戳的列或表达式。时间列必须是TimestampType。
gapDuration–指定会话超时的字符串，例如10 minutes, 1 second。查看org.apache.spark.unsafe.types.CalendarInterval 获取有效的持续时间（duration）标识符。这一持续时间（duration）同样是绝对的，不会因日历而异。

5

  /**
   * @since 3.2.0
   */
  def session_window(timeColumn: Column, gapDuration: Column): Column = {
    withExpr {
      SessionWindow(timeColumn.expr, gapDuration.expr)
    }.as(\"session_window\")
  }

说明

根据指定列的时间戳生成会话窗口。
会话窗口是一种动态窗口，它意味着窗口的长度根据给定的输入而变化。
对于静态间隔持续时间，会话窗口的长度定义为“会话最新输入的时间戳+间隔持续时间”，因此当新输入绑定到当前会话窗口时，会话窗口的结束时间可以根据新输入进行扩展。
除了静态间隙持续时间值，用户还可以提供一个表达式，根据输入行动态指定间隙持续时间。
使用动态间隙持续时间，会话窗口的关闭不再依赖于最新的输入。
会话窗口的范围是所有事件范围的并集，这些范围由事件开始时间和查询执行期间计算的间隔持续时间决定。
请注意，间隙持续时间为负或为零的行将从聚合中筛选出来。
windows可以支持微秒精度。
不支持以月为单位的gapDuration。
对于流式查询，可以使用函数current_timestamp生成处理时间窗口。

参数

timeColumn–用作时间窗口的时间戳的列或表达式。时间列必须是TimestampType。
gapDuration–指定会话超时的列。它可以是静态值，例如10 minutes, 1 second，也可以是基于输入行动态指定间隙持续时间的表达式/UDF。

timestamp_seconds

  /**
   * Creates timestamp from the number of seconds since UTC epoch.
   * @group datetime_funcs
   * @since 3.1.0
   */
  def timestamp_seconds(e: Column): Column = withExpr {
    SecondsToTimestamp(e.expr)
  }

说明

根据UTC历元后的秒数创建时间戳。