TDengine 转化函数 TO_CHAR 用户手册

TO_CHAR 函数使用手册

函数概述

功能说明: 将时间戳（TIMESTAMP）按照指定的格式转换为字符串（VARCHAR）。

版本: v3.2.2.0 及以上

返回结果类型: VARCHAR

适用数据类型: TIMESTAMP

嵌套子查询支持: 适用于内层查询和外层查询。

适用于: 表和超级表。

语法

sql 复制代码

TO_CHAR(ts, format_str_literal)

参数说明:

ts: 要转换的时间戳表达式或列名。
format_str_literal: 目标字符串格式模板。

支持的格式化占位符 (完整版)

格式	说明	示例
AM, am, PM, pm	无点分隔的上午下午	`07:00:00am`
A.M., a.m., P.M., p.m.	有点分隔的上午下午	`07:00:00a.m.`
YYYY, yyyy	年，4 个及以上数字	`2023-10-10`
YYY, yyy	年，最后 3 位数字	`023-10-10`
YY, yy	年，最后 2 位数字	`23-10-10`
Y, y	年，最后一位数字	`3-10-10`
MONTH	月，全大写 (右侧补空格)	`2023-JANUARY -01`
Month	月，首字母大写 (右侧补空格)	`2023-January -01`
month	月，全小写 (右侧补空格)	`2023-january -01`
MON	月，缩写，全大写 (三个字符)	`JAN`、`SEP`
Mon	月，缩写，首字母大写	`Jan`、`Sep`
mon	月，缩写，全小写	`jan`、`sep`
MM, mm	月，数字 01-12	`2023-01-01`
DD, dd	月日，01-31	`01`, `31`
DAY	周日，全大写 (右侧补空格)	`MONDAY`
Day	周日，首字符大写 (右侧补空格)	`Monday`
day	周日，全小写 (右侧补空格)	`monday`
DY	周日，缩写，全大写	`MON`
Dy	周日，缩写，首字符大写	`Mon`
dy	周日，缩写，全小写	`mon`
DDD	年日 (一年中的第几天)，001-366	`001`, `365`
D, d	周日，数字，1-7 (Sunday=1 ... Saturday=7)	`1`, `7`
HH24, hh24	小时，00-23	`23:59:59`
hh12, HH12, hh, HH	小时，01-12	`12:59:59PM`
MI, mi	分钟，00-59	`59`
SS, ss	秒，00-59	`59`
MS, ms	毫秒，000-999	`123`
US, us	微秒，000000-999999	`123456`
NS, ns	纳秒，000000000-999999999	`123456789`
TZH, tzh	时区小时	`+08`

详细使用说明

文本对齐 : Month、Day 等全称输出格式是左对齐 的，右侧会自动添加空格以对齐到该字段可能的最大长度。
- 例如：SEPTEMBER 是最长的月份名，所以 JANUARY 输出时后面会补空格变成 JANUARY 。
精度区分 : ms、us、ns 的输出值取决于精度，而不是简单的补零。
- 若 ts 为 1697182085123 (毫秒级时间戳):
  - ms 输出 123
  - us 输出 123000
  - ns 输出 123000000
文字转义 : 如果想要在格式串中包含不被解析的文字，请使用双引号包裹。
- 例如: to_char(ts, 'yyyy-mm-dd "is the date"')
- 如果想输出双引号本身，请使用反斜杠转义: to_char(ts, '\"yyyy-mm-dd\"') -> "2023-10-10"
大小写互换 : 对于输出纯数字的格式（如 YYYY, DD），大小写占位符效果相同。
时区: 推荐在格式中包含时区信息。若不指定，默认使用服务端或客户端配置的时区。
输入精度: 输入时间戳的精度由所查询表的精度确定。若未指定表（如直接转换常量），默认精度为毫秒。

智能电表示例环境搭建

为了方便演示，请先执行以下 SQL 语句搭建测试环境。

1. 创建数据库与超级表

sql 复制代码

-- 创建数据库
CREATE DATABASE IF NOT EXISTS power PRECISION 'ms';
USE power;

-- 创建智能电表超级表
CREATE STABLE meters (
    ts TIMESTAMP,           -- 时间戳
    current FLOAT,          -- 电流 (A)
    voltage FLOAT,          -- 电压 (V)
    phase FLOAT             -- 相位
) TAGS (
    groupid INT,            -- 分组ID
    location VARCHAR(24)    -- 地理位置
);

2. 创建子表并写入数据

sql 复制代码

-- 创建子表
CREATE TABLE d1001 USING meters TAGS (1, 'California');
CREATE TABLE d1002 USING meters TAGS (2, 'New York');

-- 插入跨越多天的数据以演示日期格式化
INSERT INTO d1001 VALUES 
('2024-01-15 08:00:00.123', 10.2, 220.5, 0.31),
('2024-01-15 14:30:00.456', 11.5, 219.8, 0.33),
('2024-01-15 20:00:00.789', 12.1, 221.2, 0.30),
('2024-01-16 09:15:00.000', 10.5, 220.1, 0.32),
('2024-01-16 18:45:00.000', 13.2, 218.4, 0.35);

INSERT INTO d1002 VALUES 
('2024-01-15 08:00:00.000', 9.8, 221.0, 0.30),
('2024-01-15 12:00:00.000', 10.4, 220.5, 0.32),
('2024-01-16 10:00:00.000', 11.0, 220.1, 0.33);

智能电表应用场景示例

场景一: 英文报表格式化 (带星期和月份全称)

用途: 生成符合英语国家阅读习惯的日期格式。

sql 复制代码

-- 输出格式如: Monday, January 15, 2024
SELECT 
  TO_CHAR(ts, 'Day, Month dd, yyyy') AS report_date,
  location,
  current 
FROM meters 
LIMIT 5;

输出示例 (注意 Month 和 Day 后的空格):

复制代码

           report_date            |  location   |  current   |
==============================================================
 Monday   , January    15, 2024   | California  | 10.200000  |

场景二: 高精度时间戳分析 (微秒/纳秒)

用途: 在高频采集场景下，查看微秒或纳秒级的时间戳变化。

sql 复制代码

-- 假设数据库精度为纳秒 (ns)
-- 输出格式: 时:分:秒.纳秒
SELECT 
  TO_CHAR(ts, 'HH24:mi:ss.ns') AS high_prec_time,
  voltage 
FROM meters 
LIMIT 3;

输出示例:

复制代码

     high_prec_time      |  voltage   |
=======================================
 14:30:00.123456789      | 220.500000 |
 14:30:00.123456790      | 220.100000 |

场景三: 带时区信息的日志输出

用途: 跨时区业务中，明确时间对应的时区偏移。

sql 复制代码

-- 输出格式: 2024-01-15 14:30:00 +08
SELECT 
  TO_CHAR(ts, 'yyyy-mm-dd HH24:mi:ss TZH') AS log_time,
  location 
FROM meters;

场景四: 12小时制带上下午标识

用途: 习惯使用 12 小时制的用户展示。

sql 复制代码

-- 输出格式: 2024-01-15 02:30:00 PM
SELECT 
  TO_CHAR(ts, 'yyyy-mm-dd HH12:mi:ss PM') AS time_12h,
  current 
FROM meters;

场景五: 统计一年中的第几天 (DDD)

用途: 分析年度趋势，不关心具体月份。

sql 复制代码

-- 统计第 15 天 (1月15日) 的平均电压
SELECT 
  TO_CHAR(ts, 'DDD') AS day_of_year,
  AVG(voltage) 
FROM meters 
GROUP BY TO_CHAR(ts, 'DDD');

场景六: 包含自定义文字

用途: 直接在 SQL 中生成可读性强的句子。

sql 复制代码

-- 输出:-- 输出: Record at 2024-01-15
SELECT 
  TO_CHAR(ts, '"Record at " yyyy-mm-dd') AS desc_str,
  current 
FROM meters;

关于 TDengine

TDengine 专为物联网IoT平台、工业大数据平台设计。其中，TDengine TSDB 是一款高性能、分布式的时序数据库（Time Series Database），同时它还带有内建的缓存、流式计算、数据订阅等系统功能；TDengine IDMP 是一款AI原生工业数据管理平台，它通过树状层次结构建立数据目录，对数据进行标准化、情景化，并通过 AI 提供实时分析、可视化、事件管理与报警等功能。