TDengine 转化函数 TO_CHAR 用户手册

TO_CHAR 函数使用手册

函数概述

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

版本: v3.2.2.0 及以上

返回结果类型: VARCHAR

适用数据类型: TIMESTAMP

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

适用于: 表和超级表。

语法

TO_CHAR(ts, format_str_literal)

参数说明:

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

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

详细使用说明

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

智能电表示例环境搭建

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

1. 创建数据库与超级表

-- 创建数据库
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. 创建子表并写入数据

-- 创建子表
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);

智能电表应用场景示例

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

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

-- 输出格式如: 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  |

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

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

-- 假设数据库精度为纳秒 (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 |

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

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

-- 输出格式: 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 小时制的用户展示。

-- 输出格式: 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)

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

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

场景六: 包含自定义文字

用途: 直接在 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 提供实时分析、可视化、事件管理与报警等功能。