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. 时间格式标准化：将数据库中的时间戳转换为标准化的可读格式
2. 国际化支持：支持不同地区的时间显示习惯
3. 报表美化：提供丰富的格式选项，美化报表输出
4. 数据分组：基于格式化后的时间进行数据分组和聚合
5. 用户体验：为应用程序提供用户友好的时间显示

使用说明

1. 文本对齐

• Month、Day 等英文格式输出是左对齐的，右侧会添加空格
• 例如：OCTOBER (有空格)、SEPTEMBER (无空格，因为September是最长的月份名)

2. 精度处理

• ms、us、ns 三种格式仅在精度上不同
• 例如：时间戳 1697182085123
  • ms 输出：123
  • us 输出：123000
  • ns 输出：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;

最佳实践

1. 选择合适的精度：根据实际需求选择毫秒、微秒或纳秒精度
2. 考虑时区：在全球化应用中明确指定时区格式
3. 性能优化：避免在大数据量查询的 WHERE 条件中使用 TO_CHAR
4. 格式一致性：在同一应用中保持时间格式的一致性
5. 国际化考虑：根据用户地区选择合适的日期格式

通过灵活使用 TO_CHAR 函数，可以大大提升时间数据的可读性和用户体验。