17.DATE_FORMAT 函数深度解析

Hive DATE_FORMAT 函数深度解析

函数概述
语法定义
参数详解
- [3.1 参数说明](#3.1 参数说明)
- [3.2 返回值类型与格式](#3.2 返回值类型与格式)
格式模式（Pattern）大全
- [4.1 基础模式字符速查表](#4.1 基础模式字符速查表)
- [4.2 进阶模式字符速查表](#4.2 进阶模式字符速查表)
- [4.3 大小写敏感性](#4.3 大小写敏感性)
核心原理：格式化而非提取
- [5.1 与TO_DATE的本质区别](#5.1 与TO_DATE的本质区别)
- [5.2 输入格式的严格限制](#5.2 输入格式的严格限制)
- [5.3 底层实现的版本演进](#5.3 底层实现的版本演进)
使用示例详解
- [6.1 基础格式化示例](#6.1 基础格式化示例)
- [6.2 非标准格式的处理方案](#6.2 非标准格式的处理方案)
- [6.3 日期维度的灵活组合](#6.3 日期维度的灵活组合)
- [6.4 动态分区写入](#6.4 动态分区写入)
性能优化与避坑指南
- [7.1 时区获取的性能瓶颈](#7.1 时区获取的性能瓶颈)
- [7.2 避免在分区字段上使用函数](#7.2 避免在分区字段上使用函数)
- [7.3 大小写错误导致的严重数据异常](#7.3 大小写错误导致的严重数据异常)
- [7.4 格式化器配置](#7.4 格式化器配置)
与其他函数的对比与选择
- [8.1 DATE_FORMAT vs FROM_UNIXTIME](#8.1 DATE_FORMAT vs FROM_UNIXTIME)
- [8.2 DATE_FORMAT vs TO_DATE vs CAST](#8.2 DATE_FORMAT vs TO_DATE vs CAST)
- [8.3 决策速查表](#8.3 决策速查表)
跨引擎行为差异与迁移指南
- [9.1 Hive vs Spark SQL vs MySQL](#9.1 Hive vs Spark SQL vs MySQL)
- [9.2 迁移检查清单](#9.2 迁移检查清单)
总结

1. 函数概述

DATE_FORMAT 是 Hive SQL 中唯一的日期格式化函数，用于将日期、时间戳或符合特定格式的字符串按照指定的格式模板（Pattern）转换成目标格式的字符串。它灵活且强大，是数据仓库工程师在生成报表、构建分区字段和清洗日期数据时不可或缺的工具。

函数名称 ：DATE_FORMAT
函数类型：日期时间函数（Datetime Functions）
主要功能：将输入的日期/时间值，按照指定的格式模式，输出为对应的字符串。
核心特点 ：它不是简单地提取日期部分，而是进行格式转换，可以自由组合年、月、日、时、分、秒等各种元素，并按需插入分隔符（如 -、/、:、T、空格等）。

2. 语法定义

sql 复制代码

-- Hive 语法
DATE_FORMAT(date/timestamp/string ts, string fmt)

参数数量：2个参数。
返回值类型 ：STRING。
参数说明 ：
- ts：待格式化的日期值，可以是 DATE、TIMESTAMP 类型，或者是符合标准日期格式的 STRING 类型。
- fmt：格式模式字符串，用于指定输出的格式。

重要提醒 ：DATE_FORMAT 的格式模式字符串严格区分大小写 ，例如 'yyyy-MM-dd' 中的 MM 代表月份（01-12），mm 则代表分钟（00-59）。错误的大小写是导致数据异常的常见原因。

3. 参数详解

3.1 参数说明

参数	类型	描述
`ts`	`DATE` / `TIMESTAMP` / `STRING`	待格式化的日期值。如果传入 `STRING` 类型，则默认必须符合 `'yyyy-MM-dd'` 或 `'yyyy-MM-dd HH:mm:ss'` 格式。
`fmt`	`STRING`	格式模式字符串，使用 Java 标准模式字符。例如 `'yyyy-MM-dd'`、`'yyyyMMdd'` 等。

3.2 返回值类型与格式

返回类型 ：STRING。
返回格式 ：完全由 fmt 参数决定。例如，输入 DATE_FORMAT('2026-04-21', 'yyyyMMdd') 将返回字符串 '20260421'。

4. 格式模式（Pattern）大全

DATE_FORMAT 遵循 Java 的 SimpleDateFormat（或 DateTimeFormatter，取决于版本）规范，支持丰富的格式模式字符。

4.1 基础模式字符速查表

模式字符	含义	示例输出 (针对 2026-04-21 08:05:03)
`yyyy`	四位年份	`2026`
`yy`	两位年份	`26`
`MM`	两位月份（01-12）	`04`
`M`	月份（1-12）	`4`
`dd`	两位日期（01-31）	`21`
`d`	日期（1-31）	`21`
`HH`	24小时制小时（00-23）	`08`
`hh`	12小时制小时（01-12）	`08`
`mm`	分钟（00-59）	`05`
`ss`	秒（00-59）	`03`
`SSS`	毫秒（000-999）	`000`

注意：HH 代表24小时制，而 hh 代表12小时制。在 SimpleDateFormat 中，如果使用 hh，建议同时使用 a（AM/PM 标记）来明确上下/下午。

4.2 进阶模式字符速查表

模式字符	含义	示例输出
`MMMM`	月份的完整英文名	`April`
`MMM`	月份的缩写英文名	`Apr`
`EEEE`	星期的完整英文名	`Tuesday`
`E`	星期的缩写英文名	`Tue`
`a`	上下午标记（AM/PM）	`AM`
`D`	一年中的第几天（1-366）	`111`
`w`	一年中的第几周	`17`
`W`	一月中的第几周	`4`

4.3 大小写敏感性

DATE_FORMAT 的格式模式字符串严格区分大小写 。错误地使用大写 'YYYY' 或小写 'mm' 会导致完全错误的输出。

sql 复制代码

-- ❌ 错误写法：'YYYY' 代表的是基于周的年份（week year），可能返回上一年或下一年
SELECT DATE_FORMAT('2025-12-31', 'YYYY-MM-dd'); 
-- 结果可能为: '2026-12-31' (因为该周属于2026年)

-- ✅ 正确写法：始终使用小写 'yyyy' 代表日历年
SELECT DATE_FORMAT('2025-12-31', 'yyyy-MM-dd'); 
-- 结果: '2025-12-31'

'MM' 和 'mm' 的混淆也极为常见：'MM' 是月份，'mm' 是分钟，一旦写错，就会将分钟值错误地填入月份部分。

5. 核心原理：格式化而非提取

5.1 与TO_DATE的本质区别

DATE_FORMAT 和 TO_DATE 常被混淆，但它们的核心功能完全不同：

TO_DATE ：是一个提取函数，它从日期时间中剥离出日期部分，返回一个 DATE 类型。
DATE_FORMAT ：是一个格式化 函数，它根据模板将日期转换成任何你想要的字符串形式，返回一个 STRING 类型。

sql 复制代码

-- TO_DATE: 提取日期部分，返回 DATE 类型
SELECT TO_DATE('2026-04-21 15:30:45');        -- 结果: 2026-04-21 (DATE类型)

-- DATE_FORMAT: 格式化输出，返回 STRING 类型
SELECT DATE_FORMAT('2026-04-21', 'yyyy年MM月dd日');  -- 结果: '2026年04月21日' (STRING类型)

5.2 输入格式的严格限制

DATE_FORMAT 的第一个参数 ts 如果是一个 STRING，则它必须能够被隐式转换为日期类型。在 Hive 中，这通常意味着字符串必须符合 'yyyy-MM-dd' 或 'yyyy-MM-dd HH:mm:ss' 的格式。

如果你传入的是 '20260421' 这种格式，DATE_FORMAT 会直接返回 NULL。此时，你需要先用 FROM_UNIXTIME 和 UNIX_TIMESTAMP 函数进行一次"预转换"：

sql 复制代码

-- ❌ 错误：直接传入非标准格式会返回 NULL
SELECT DATE_FORMAT('20260421', 'yyyy-MM-dd');    -- 结果: NULL

-- ✅ 正确：先用 UNUX_TIMESTAMP 解析，再用 FROM_UNIXTIME 格式化
SELECT DATE_FORMAT(
    FROM_UNIXTIME(UNIX_TIMESTAMP('20260421', 'yyyyMMdd')), 
    'yyyy-MM-dd'
);  -- 结果: '2026-04-21'

5.3 底层实现的版本演进

DATE_FORMAT 函数的底层实现经历了重要演变：

传统实现（Hive 3.x及更早） ：底层使用 java.text.SimpleDateFormat。这个实现存在一些已知的 Bug，例如对于 1900 年之前的日期处理可能产生错误结果。
现代实现（Hive 4.0+） ：引入了可配置的格式化器 hive.datetime.formatter。默认使用更现代、更安全的 java.time.format.DateTimeFormatter。这一变更修复了早期版本的不一致性问题。
- DATETIME：使用 java.time.format.DateTimeFormatter（推荐）
- SIMPLE：使用 java.text.SimpleDateFormat（存在已知Bug）

6. 使用示例详解

6.1 基础格式化示例

sql 复制代码

-- 1. 标准日期格式化
SELECT DATE_FORMAT('2026-04-21', 'yyyy-MM-dd');      -- 结果: '2026-04-21'
SELECT DATE_FORMAT('2026-04-21', 'yyyyMMdd');        -- 结果: '20260421'
SELECT DATE_FORMAT('2026-04-21', 'yyyy/MM/dd');      -- 结果: '2026/04/21'

-- 2. 带时间戳的格式化
SELECT DATE_FORMAT('2026-04-21 15:30:45', 'yyyy-MM-dd HH:mm:ss');   
-- 结果: '2026-04-21 15:30:45'

-- 3. 中文格式
SELECT DATE_FORMAT('2026-04-21', 'yyyy年MM月dd日');   
-- 结果: '2026年04月21日'

-- 4. 自定义特殊格式
SELECT DATE_FORMAT(CURRENT_TIMESTAMP, "yyyyMMdd'T'HHmmss");  
-- 结果: '20260421T153045' (T被当作字面量处理)

6.2 非标准格式的处理方案

sql 复制代码

-- 5. 处理 'yyyyMMdd' 格式的原始数据
SELECT DATE_FORMAT(
    FROM_UNIXTIME(UNIX_TIMESTAMP('20260421', 'yyyyMMdd')), 
    'yyyy-MM-dd'
) AS standard_date;

-- 6. 处理带斜杠的日期格式（使用正则替换）
SELECT DATE_FORMAT(
    REGEXP_REPLACE('2026/04/21', '/', '-'), 
    'yyyyMMdd'
) AS formatted_date;
-- 结果: '20260421'

6.3 日期维度的灵活组合

sql 复制代码

-- 7. 提取年份-月份作为统计维度
SELECT 
    DATE_FORMAT(order_date, 'yyyy-MM') AS order_month,
    SUM(amount) AS total_sales
FROM orders
GROUP BY DATE_FORMAT(order_date, 'yyyy-MM');

-- 8. 生成友好的报表日期
SELECT 
    user_id,
    CONCAT(DATE_FORMAT(register_time, 'yyyy年MM月dd日 HH时'), '注册') AS register_info
FROM users;
-- 结果示例: '2026年04月21日 15时注册'

-- 9. 提取星期几（返回完整英文星期名称）
SELECT DATE_FORMAT('2026-04-21', 'EEEE');   
-- 结果: 'Tuesday'

6.4 动态分区写入

sql 复制代码

-- 10. 将日期格式化为 'yyyyMMdd' 作为无分隔符分区键
INSERT OVERWRITE TABLE daily_logs PARTITION(dt)
SELECT 
    *,
    DATE_FORMAT(create_time, 'yyyyMMdd') AS dt
FROM raw_logs;

7. 性能优化与避坑指南

7.1 时区获取的性能瓶颈

DATE_FORMAT 函数在某些 Hive 版本（尤其是较老的版本）中存在性能瓶颈。其内部实现涉及到一个获取系统时区的逻辑，这个操作在每次调用时都可能发生，尤其是在高并发场景下，会显著影响查询性能。

优化建议：

升级 Hive 版本 ：Hive 4.0+ 引入的 DateTimeFormatter 对此进行了优化，建议升级。
物化格式化结果：对于频繁使用的格式化操作，在 ETL 阶段将结果写入新列，避免每次查询都执行格式化。
替代方案 ：如果只是简单地从日期时间戳中提取日期部分，使用 TO_DATE() 函数（返回 DATE 类型）通常比 DATE_FORMAT(..., 'yyyy-MM-dd') 更高效。

7.2 避免在分区字段上使用函数

在 WHERE 子句中对分区字段使用 DATE_FORMAT 会导致分区裁剪失效，查询将被迫进行全表扫描，这是 Hive 最常见的性能杀手。

sql 复制代码

-- ❌ 不推荐：分区裁剪失效，全表扫描
SELECT * FROM logs WHERE DATE_FORMAT(dt, 'yyyy-MM') = '2026-04';

-- ✅ 推荐：直接使用分区字段进行范围比较
SELECT * FROM logs WHERE dt >= '2026-04-01' AND dt < '2026-05-01';

7.3 大小写错误导致的严重数据异常

DATE_FORMAT 格式模式中的大小写错误是最隐蔽的数据陷阱，因为查询不会报错，但结果完全错误。

sql 复制代码

-- ❌ 错误：将分钟（mm）误写为月份（MM）
SELECT DATE_FORMAT('2026-04-21 15:30:45', 'yyyy-MM-dd HH:MM:ss');   
-- 期望: '2026-04-21 15:30:45'，实际: '2026-04-21 15:04:45' (分钟位置错误地变成了月份)

-- ❌ 错误：使用基于周的年份（YYYY）
SELECT DATE_FORMAT('2025-12-31', 'YYYY-MM-dd');   
-- 期望: '2025-12-31'，实际可能: '2026-12-31'

最佳实践 ：始终严格遵循 Java 标准命名规范，并建立代码审查机制。使用 'yyyy-MM-dd HH:mm:ss' 而不是 'YYYY-mm-dd HH:MM:SS'。

7.4 格式化器配置

在 Hive 4.0+ 中，你可以通过 hive.datetime.formatter 配置项来控制日期格式化器的行为。

sql 复制代码

-- 设置为使用新的 DateTimeFormatter（推荐，Hive 4.0+ 默认值）
SET hive.datetime.formatter=DATETIME;

-- 设置为使用旧的 SimpleDateFormat（存在已知Bug，不推荐）
SET hive.datetime.formatter=SIMPLE;

8. 与其他函数的对比与选择

8.1 DATE_FORMAT vs FROM_UNIXTIME

对比维度	`DATE_FORMAT`	`FROM_UNIXTIME`
输入类型	`DATE` / `TIMESTAMP` / `STRING` (标准格式)	`BIGINT` (Unix时间戳)
主要用途	对已有的日期/时间值进行格式化	将数字时间戳转换为可读字符串
返回值	`STRING`	`STRING`
性能	直接格式化，相对高效	需要时间戳转换，稍慢
典型场景	日期维度的自由组合，如 `'yyyy-MM'`	处理以秒数存储的日志时间戳

结论：如果你有一个 DATE 或 TIMESTAMP 列，使用 DATE_FORMAT 进行格式化是更直接、更高效的选择。如果你只有一个数字型时间戳，那么 FROM_UNIXTIME 是你的首选。

8.2 DATE_FORMAT vs TO_DATE vs CAST

函数	功能	输入示例	输出示例
`DATE_FORMAT`	格式化输出	`'2026-04-21'`，`'yyyyMMdd'`	`'20260421'`（STRING）
`TO_DATE`	提取日期部分	`'2026-04-21 15:30:45'`	`2026-04-21`（DATE）
`CAST(... AS DATE)`	类型转换	`'2026-04-21'`	`2026-04-21`（DATE）

使用 TO_DATE ：当你需要从一个时间戳中剥离出日期部分，并将其作为 DATE 类型进行后续计算时。
使用 CAST ：当你需要将一个格式正确的字符串转换为 DATE 类型时。
使用 DATE_FORMAT：当你需要将日期/时间值转换成任意你想要的字符串格式时。

8.3 决策速查表

场景描述	推荐函数	理由
提取时间戳中的日期部分（返回DATE）	`TO_DATE`	语义清晰，性能更好
将日期格式化为 `'yyyyMMdd'` 字符串	`DATE_FORMAT`	专为格式化设计
将 Unix 时间戳转为可读日期	`FROM_UNIXTIME`	直接转换
将非标准格式字符串转为标准日期	`FROM_UNIXTIME` + `UNIX_TIMESTAMP`	组合拳，灵活度高
提取年份或月份用于分组	`DATE_FORMAT(col, 'yyyy')`	灵活，可自由组合
类型安全的日期比较	直接使用 `DATE` 类型列	性能最佳，可索引

9. 跨引擎行为差异与迁移指南

9.1 Hive vs Spark SQL vs MySQL

DATE_FORMAT 在不同 SQL 引擎中的语法和模式字符非常相似，但也存在一些细微差异。

引擎	函数语法	模式字符差异	备注
Hive	`DATE_FORMAT(ts, fmt)`	遵循 Java 规范	输入字符串必须符合标准格式
Spark SQL	`DATE_FORMAT(ts, fmt)`	遵循 Java 规范	与 Hive 高度兼容，同样存在大小写敏感问题
MySQL	`DATE_FORMAT(ts, fmt)`	使用 MySQL 特有模式字符，如 `%Y`, `%m`, `%d`	格式字符串完全不同，是迁移的主要障碍
Presto/Trino	`DATE_FORMAT(ts, fmt)`	遵循 Java 规范	与 Hive 基本兼容

9.2 迁移检查清单

迁移方向	需检查事项	改写建议
MySQL → Hive	模式字符完全不同	`%Y-%m-%d` → `'yyyy-MM-dd'`，`%Y%m%d` → `'yyyyMMdd'`
Hive → Spark SQL	大小写敏感性一致	基本无需改写，但仍需注意 `YYYY` vs `yyyy` 的问题
Presto → Hive	基本兼容	语法一致，可直接迁移
旧版 Hive → Hive 4.0+	底层实现变更	检查 `hive.datetime.formatter` 配置，推荐使用 `DATETIME`

10. 常见问题与避坑指南

问题	原因	解决方案
格式化后结果全部为 `NULL`	输入的日期字符串不符合标准格式	使用 `FROM_UNIXTIME(UNIX_TIMESTAMP(str, 'in_fmt'), 'out_fmt')` 预处理
月份或日期部分结果错误	模式字符大小写混淆（如 `MM` 写成了 `mm`）	严格遵循 Java 规范：`MM`=月份，`mm`=分钟
年份部分跨年异常	使用了基于周的年份 `'YYYY'` 而非日历年 `'yyyy'`	始终使用小写 `'yyyy'` 表示日历年
高并发下性能下降	`DATE_FORMAT` 内部获取时区逻辑导致性能瓶颈	升级到 Hive 4.0+，或在 ETL 中物化结果
分区查询变慢	在分区字段上使用 `DATE_FORMAT`，导致分区裁剪失效	将格式化函数移到过滤条件的常量一侧
升级 Hive 后结果变化	底层格式化器从 `SimpleDateFormat` 变更为 `DateTimeFormatter`	检查 `hive.datetime.formatter` 配置，并充分测试

11. 总结

DATE_FORMAT 是 Hive 唯一的日期格式化函数，它将日期/时间值按照指定的模板转换成字符串。
格式模式严格区分大小写 ，这是导致数据异常的常见根源。始终使用 'yyyy-MM-dd' 而不是 'YYYY-mm-dd'。
输入格式有严格要求 ，如果传入字符串，则必须是 'yyyy-MM-dd' 或 'yyyy-MM-dd HH:mm:ss' 格式。对于非标准格式，需结合 UNIX_TIMESTAMP 和 FROM_UNIXTIME 进行预处理。
性能优化 ：避免在分区字段上使用 DATE_FORMAT，并在 Hive 4.0+ 中利用 hive.datetime.formatter 配置来优化底层实现。
跨引擎迁移 ：MySQL 的模式字符（如 %Y）与 Hive 的 Java 模式完全不同，迁移时需重点检查。
与 TO_DATE 的区别 ：DATE_FORMAT 用于格式化输出，返回 STRING；TO_DATE 用于提取日期部分，返回 DATE。

17.DATE_FORMAT 函数深度解析

Hive DATE_FORMAT 函数深度解析

目录

1. 函数概述

2. 语法定义

3. 参数详解

3.1 参数说明

3.2 返回值类型与格式

4. 格式模式（Pattern）大全

4.1 基础模式字符速查表

4.2 进阶模式字符速查表

4.3 大小写敏感性

5. 核心原理：格式化而非提取

5.1 与TO_DATE的本质区别

5.2 输入格式的严格限制

5.3 底层实现的版本演进

6. 使用示例详解

6.1 基础格式化示例

6.2 非标准格式的处理方案

6.3 日期维度的灵活组合

6.4 动态分区写入

7. 性能优化与避坑指南

7.1 时区获取的性能瓶颈

7.2 避免在分区字段上使用函数

7.3 大小写错误导致的严重数据异常

7.4 格式化器配置

8. 与其他函数的对比与选择

8.1 DATE_FORMAT vs FROM_UNIXTIME

8.2 DATE_FORMAT vs TO_DATE vs CAST

8.3 决策速查表

9. 跨引擎行为差异与迁移指南

9.1 Hive vs Spark SQL vs MySQL

9.2 迁移检查清单

10. 常见问题与避坑指南

11. 总结