用于格式化和解析的日期时间模式

在 Spark 中，日期时间的使用有几个常见场景

• CSV/JSON 数据源使用模式字符串来解析和格式化日期时间内容。

• 日期时间函数，用于在 StringType、DateType 和 TimestampType 之间进行转换。例如：unix_timestamp、date_format、to_unix_timestamp、from_unixtime、to_date、to_timestamp、from_utc_timestamp、to_utc_timestamp 等。

Spark 使用下表中的模式字母进行日期和时间戳的解析和格式化

模式字母的数量决定了格式。

• 文本：文本样式由使用的模式字母数量决定。少于 4 个模式字母将使用短文本形式，通常是缩写，例如一周中的星期一可能会输出“Mon”。正好 4 个模式字母将使用完整文本形式，通常是完整描述，例如一周中的星期一可能会输出“Monday”。5 个或更多字母将失败。

• 数字(n)：这里的 n 表示此类型日期时间模式可使用的最大字母数量。
  • 在格式化中，如果字母数量为一，则值将使用最少位数输出，不进行填充；否则，数字数量将用作输出字段的宽度，必要时用零填充。
  • 在解析中，输入字段中期望精确的数字数量。

• 数字/文本：如果模式字母的数量为 3 或更多，请使用上述文本规则。否则使用上述数字规则。

• 小数部分：使用一个或多个（最多 9 个）连续的 'S' 字符，例如 SSSSSS，来解析和格式化秒的小数部分。对于解析，可接受的小数部分长度为 [1, 连续 ‘S’ 的数量]。对于格式化，小数部分长度将用零填充至连续 ‘S’ 的数量。Spark 支持微秒精度的日期时间，最多有 6 位有效数字，但可以解析纳秒，超出部分将被截断。

• 年份：字母数量决定了最小字段宽度，低于此宽度将使用填充。如果字母数量为二，则使用缩减的两位数形式。对于打印，这将输出最右边的两位数。对于解析，这将使用 2000 作为基准值进行解析，从而得到 2000 到 2099（包括）范围内的年份。如果字母数量小于四（但不为二），则只有负年份才输出符号。否则，在没有 ‘G’ 的情况下，如果填充宽度被超出，则输出符号。7 个或更多字母将失败。

• 月份：它遵循数字/文本规则。文本形式取决于字母——‘M’ 表示“标准”形式，‘L’ 表示“独立”形式。这两种形式仅在某些特定语言中有所不同。例如，在俄语中，‘Июль’ 是七月的独立形式，‘Июля’ 是标准形式。以下是所有支持的模式字母的示例：
  • 'M' 或 'L'：一年中的月份数字，从 1 开始。'M' 和 'L' 之间没有区别。1 到 9 月份打印时不会进行填充。

    spark-sql> select date_format(date '1970-01-01', "M");
    1
    spark-sql> select date_format(date '1970-12-01', "L");
    12
    

  • 'MM' 或 'LL'：一年中的月份数字，从 1 开始。1-9 月份会添加零填充。

      spark-sql> select date_format(date '1970-1-01', "LL");
      01
      spark-sql> select date_format(date '1970-09-01', "MM");
      09
    

  • 'MMM'：标准形式的短文本表示。月份模式应该是日期模式的一部分，而不仅仅是独立的月份，除非在像英语这样标准形式和独立形式没有区别的地区。

    spark-sql> select date_format(date '1970-01-01', "d MMM");
    1 Jan
    spark-sql> select to_csv(named_struct('date', date '1970-01-01'), map('dateFormat', 'dd MMM', 'locale', 'RU'));
    01 янв.
    

  • 'LLL'：独立形式的短文本表示。它应该用于仅格式化/解析月份，而不包含任何其他日期字段。

    spark-sql> select date_format(date '1970-01-01', "LLL");
    Jan
    spark-sql> select to_csv(named_struct('date', date '1970-01-01'), map('dateFormat', 'LLL', 'locale', 'RU'));
    янв.
    

  • 'MMMM'：标准形式的完整文本月份表示。它用于将月份作为日期/时间戳的一部分进行解析/格式化。

    spark-sql> select date_format(date '1970-01-01', "d MMMM");
    1 January
    spark-sql> select to_csv(named_struct('date', date '1970-01-01'), map('dateFormat', 'd MMMM', 'locale', 'RU'));
    1 января
    

  • 'LLLL'：独立形式的完整文本月份表示。此模式可用于仅格式化/解析月份。

    spark-sql> select date_format(date '1970-01-01', "LLLL");
    January
    spark-sql> select to_csv(named_struct('date', date '1970-01-01'), map('dateFormat', 'LLLL', 'locale', 'RU'));
    январь
    

• 上午/下午：这输出一天中的上午/下午。模式字母数量必须为 1。

• 时区 ID(V)：这输出显示时区 ID。模式字母数量必须为 2。

• 时区名称(z)：这输出时区 ID 的文本名称。如果字母数量为一、二或三，则输出短名称。如果字母数量为四，则输出完整名称。五个或更多字母将失败。

• 偏移 X 和 x：这根据模式字母的数量格式化偏移。一个字母只输出小时，例如 ‘+01’，除非分钟非零，在这种情况下也输出分钟，例如 ‘+0130’。两个字母输出小时和分钟，不带冒号，例如 ‘+0130’。三个字母输出小时和分钟，带冒号，例如 ‘+01:30’。四个字母输出小时、分钟和可选的秒，不带冒号，例如 ‘+013015’。五个字母输出小时、分钟和可选的秒，带冒号，例如 ‘+01:30:15’。六个或更多字母将失败。模式字母 ‘X’ (大写) 在偏移为零时将输出 ‘Z’，而模式字母 ‘x’ (小写) 将输出 ‘+00’、‘+0000’ 或 ‘+00:00’。

• 偏移 O：这根据模式字母的数量格式化本地化偏移。一个字母输出本地化偏移的短形式，即本地化偏移文本（如 ‘GMT’），小时不带前导零，分钟和秒（如果非零）可选两位数，并带冒号，例如 ‘GMT+8’。四个字母输出完整形式，即本地化偏移文本（如 ‘GMT’），带两位数的小时和分钟字段，秒字段（如果非零）可选，并带冒号，例如 ‘GMT+08:00’。任何其他字母数量将失败。

• 偏移 Z：这根据模式字母的数量格式化偏移。一、二或三个字母输出小时和分钟，不带冒号，例如 ‘+0130’。当偏移为零时，输出将为 ‘+0000’。四个字母输出本地化偏移的完整形式，等同于偏移 O 的四个字母。如果偏移为零，输出将是相应的本地化偏移文本。五个字母输出小时、分钟，如果非零则可选秒，带冒号。如果偏移为零，则输出 ‘Z’。六个或更多字母将失败。

• 可选部分开始和结束：使用 [] 定义一个可选部分，并且可以嵌套。在格式化过程中，所有有效数据即使在可选部分中也会被输出。在解析过程中，整个部分可能在解析字符串中缺失。可选部分由 [ 开始，并使用 ] 结束（或在模式的末尾）。

• 符号 ‘E’、‘F’、‘q’ 和 ‘Q’ 只能用于日期时间格式化，例如 date_format。它们不允许用于日期时间解析，例如 to_timestamp。