TDengine 转化类函数 TO_CHAR 用户手册
TDengine TO_CHAR 函数用户手册
概述
TO_CHAR 函数是 TDengine 中的标量函数，用于将 TIMESTAMP 类型的数据按照指定的格式转换为字符串。该函数支持丰富的时间格式化选项，可以满足各种时间显示需求。
语法
TO_CHAR(ts, format_str_literal)
参数说明
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
ts | TIMESTAMP | 是 | 要转换的时间戳字段或表达式 |
format_str_literal | VARCHAR | 是 | 格式化字符串字面量，定义输出格式 |
返回值类型
VARCHAR - 返回格式化后的字符串
支持的数据类型
- 输入类型：TIMESTAMP
- 输出类型：VARCHAR
适用范围
- 表类型：支持普通表和超级表
- 嵌套查询：支持内层查询和外层查询
- 版本要求：TDengine 3.2.2.0+
格式化选项
年份格式
| 格式 | 说明 | 示例 |
|---|---|---|
YYYY, yyyy | 年，4位数字 | 2023 |
YYY, yyy | 年，最后3位数字 | 023 |
YY, yy | 年，最后2位数字 | 23 |
Y, y | 年，最后1位数字 | 3 |
月份格式
| 格式 | 说明 | 示例 |
|---|---|---|
MONTH | 月，全大写英文 | JANUARY |
Month | 月，首字母大写英文 | January |
month | 月，全小写英文 | january |
MON | 月，缩写，全大写 | JAN |
Mon | 月，缩写，首字母大写 | Jan |
mon | 月，缩写，全小写 | jan |
MM, mm | 月，数字01-12 | 01 |
日期格式
| 格式 | 说明 | 示例 |
|---|---|---|
DD, dd | 月日，01-31 | 15 |
DDD | 年日，001-366 | 285 |
星期格式
| 格式 | 说明 | 示例 |
|---|---|---|
DAY | 星期，全大写英文 | MONDAY |
Day | 星期，首字母大写英文 | Monday |
day | 星期，全小写英文 | monday |
DY | 星期，缩写，全大写 | MON |
Dy | 星期，缩写，首字母大写 | Mon |
dy | 星期，缩写，全小写 | mon |
D, d | 星期，数字1-7，Sunday(1) to Saturday(7) | 2 |
时间格式
| 格式 | 说明 | 示例 |
|---|---|---|
HH24, hh24 | 小时，24小时制，00-23 | 23 |
HH12, hh12, HH, hh | 小时，12小时制，01-12 | 11 |
MI, mi | 分钟，00-59 | 30 |
SS, ss | 秒，00-59 | 45 |
上午下午格式
| 格式 | 说明 | 示例 |
|---|---|---|
AM, am | 无点分隔的上午下午 | am |
PM, pm | 无点分隔的上午下午 | pm |
A.M., a.m. | 有点分隔的上午下午 | a.m. |
P.M., p.m. | 有点分隔的上午下午 | p.m. |
毫秒/微秒/纳秒格式
| 格式 | 说明 | 示例 |
|---|---|---|
MS, ms | 毫秒，000-999 | 123 |
US, us | 微秒，000000-999999 | 123000 |
NS, ns | 纳秒，000000000-999999999 | 123000000 |
时区格式
| 格式 | 说明 | 示例 |
|---|---|---|
TZH, tzh | 时区小时 | +08 |
使用场景
1. 报表生成
生成格式化的时间报表，提高可读性。
-- 生成日期报表
SELECT TO_CHAR(ts, 'YYYY-MM-DD') as 日期,COUNT(*) as 记录数
FROM sensor_data
WHERE ts >= '2024-01-01'
GROUP BY TO_CHAR(ts, 'YYYY-MM-DD')
ORDER BY 日期;
2. 日志格式化
将时间戳格式化为标准的日志时间格式。
-- 格式化系统日志时间
SELECT TO_CHAR(log_time, 'YYYY-MM-DD HH24:MI:SS.MS') as formatted_time,log_level,message
FROM system_logs
WHERE log_time >= NOW() - INTERVAL 1 HOUR;
3. 数据展示
为前端应用提供友好的时间显示格式。
-- 用户友好的时间显示
SELECT device_name,TO_CHAR(last_update, 'Mon DD, YYYY at HH12:MI:SS A.M.') as last_seen,status
FROM device_status;
4. 时间分组分析
按不同时间粒度进行数据分组分析。
-- 按小时分组统计
SELECT TO_CHAR(ts, 'YYYY-MM-DD HH24') as hour,AVG(temperature) as avg_temp,MAX(temperature) as max_temp
FROM weather_data
WHERE ts >= NOW() - INTERVAL 1 DAY
GROUP BY TO_CHAR(ts, 'YYYY-MM-DD HH24')
ORDER BY hour;
5. 国际化时间显示
根据不同地区习惯显示时间格式。
-- 美式日期格式
SELECT TO_CHAR(order_time, 'MM/DD/YYYY HH12:MI:SS PM') as us_format
FROM orders;-- 欧式日期格式
SELECT TO_CHAR(order_time, 'DD/MM/YYYY HH24:MI:SS') as eu_format
FROM orders;
6. 周期性分析
分析数据的周期性模式。
-- 按星期分析销售模式
SELECT TO_CHAR(sale_time, 'Day') as weekday,SUM(amount) as total_sales
FROM sales
WHERE sale_time >= NOW() - INTERVAL 30 DAY
GROUP BY TO_CHAR(sale_time, 'Day'), TO_CHAR(sale_time, 'D')
ORDER BY TO_CHAR(sale_time, 'D');
解决的问题
- 时间格式标准化：将数据库中的时间戳转换为标准化的可读格式
- 国际化支持：支持不同地区的时间显示习惯
- 报表美化：提供丰富的格式选项，美化报表输出
- 数据分组：基于格式化后的时间进行数据分组和聚合
- 用户体验：为应用程序提供用户友好的时间显示
使用说明
1. 文本对齐
Month、Day等英文格式输出是左对齐的，右侧会添加空格- 例如：
OCTOBER(有空格)、SEPTEMBER(无空格，因为September是最长的月份名)
2. 精度处理
ms、us、ns三种格式仅在精度上不同- 例如：时间戳 1697182085123
ms输出：123us输出：123000ns输出：123000000
3. 特殊字符处理
-- 输出文字内容（使用双引号）
SELECT TO_CHAR(ts, 'yyyy-mm-dd "is formatted by yyyy-mm-dd"') FROM table_name;
-- 输出：2023-10-10 is formatted by yyyy-mm-dd-- 输出双引号字符（使用反斜杠转义）
SELECT TO_CHAR(ts, '\"yyyy-mm-dd\"') FROM table_name;
-- 输出："2023-10-10"
4. 大小写等价
数字输出格式的大小写意义相同：
YYYY和yyyy等价MM和mm等价DD和dd等价
5. 时区处理
- 推荐在格式中包含时区信息
- 如果不指定时区，默认使用服务端或客户端配置的时区
- 输入时间戳的精度由查询表的精度确定，未指定表时默认为毫秒精度
实际示例
-- 示例1：基本日期时间格式化
SELECT TO_CHAR(NOW(), 'YYYY-MM-DD HH24:MI:SS') as current_time;
-- 输出：2024-01-15 14:30:25-- 示例2：12小时制带上午下午
SELECT TO_CHAR(NOW(), 'YYYY-MM-DD HH12:MI:SS A.M.') as formatted_time;
-- 输出：2024-01-15 02:30:25 P.M.-- 示例3：完整的英文日期格式
SELECT TO_CHAR(NOW(), 'Day, Month DD, YYYY') as full_date;
-- 输出：Monday , January 15, 2024-- 示例4：带毫秒的时间戳
SELECT TO_CHAR(ts, 'YYYY-MM-DD HH24:MI:SS.MS') as precise_time
FROM events
WHERE ts >= NOW() - INTERVAL 1 MINUTE;-- 示例5：年日格式
SELECT TO_CHAR(ts, 'YYYY-DDD') as year_day
FROM sensor_data
WHERE ts >= '2024-01-01';-- 示例6：自定义分隔符
SELECT TO_CHAR(ts, 'DD/MM/YYYY @ HH24:MI') as custom_format
FROM logs;
最佳实践
- 选择合适的精度：根据实际需求选择毫秒、微秒或纳秒精度
- 考虑时区：在全球化应用中明确指定时区格式
- 性能优化：避免在大数据量查询的 WHERE 条件中使用 TO_CHAR
- 格式一致性：在同一应用中保持时间格式的一致性
- 国际化考虑：根据用户地区选择合适的日期格式
通过灵活使用 TO_CHAR 函数，可以大大提升时间数据的可读性和用户体验。