TDengine 时间函数 WEEK 用户手册

WEEK 函数用户手册

概览

名称：WEEK
语法：WEEK(expr [, mode])
功能：返回输入日期/时间戳所在的"周序号"
返回类型：BIGINT
支持输入类型：
- TIMESTAMP、表示时间戳的 BIGINT
- 符合 ISO8601/RFC3339 的字符串（VARCHAR/NCHAR），如 2024-11-01 12:30:00+08:00

参数说明

expr：要计算周序的时间表达式
mode（可选，0--7）：决定周起始日、返回值范围与"第一周"规则
- 每周第一天（周日或周一）
- 返回值范围（0--53 或 1--53）
- 第一周规则（是否要求该周包含 ≥4 天）

模式定义（简表）

0：周起始=周日，范围=0--53，第一周=第一个包含周日的周
1：周起始=周一，范围=0--53，第一周=第一个包含≥4天的周
2：周起始=周日，范围=1--53，第一周=第一个包含周日的周
3：周起始=周一，范围=1--53，第一周=第一个包含≥4天的周（ISO 周）
4：周起始=周日，范围=0--53，第一周=第一个包含≥4天的周
5：周起始=周一，范围=0--53，第一周=第一个包含周一的周
6：周起始=周日，范围=1--53，第一周=第一个包含≥4天的周
7：周起始=周一，范围=1--53，第一周=第一个包含周一的周

行为与注意事项

expr 为 NULL 或不可解析字符串时返回 NULL
时间戳精度由表精度决定（未指定表时按毫秒）
字符串解析与结果显示受客户端时区影响，建议字符串携带时区（如 +08:00）
WEEK(expr, 3) 等价 ISO 周：周一起始，第一周含 ≥4 天，范围 1--53

智能电表业务示例

假设有超级表 smart_meter：

ts TIMESTAMP（采集时间）
meter_id NCHAR（电表编号）
kwh DOUBLE（累积电量）
kw DOUBLE（有功功率瞬时值）

为每条记录标注周序（ISO 周）

sql 复制代码

SELECT ts, meter_id, kw, WEEK(ts, 3) AS week_no
FROM smart_meter
LIMIT 10;

统计每个电表每周的平均功率

sql 复制代码

SELECT meter_id, WEEK(ts, 3) AS week_no, AVG(kw) AS avg_kw
FROM smart_meter
GROUP BY meter_id, WEEK(ts, 3)
ORDER BY meter_id, week_no;

某电表在特定周的峰值负荷

sql 复制代码

SELECT MAX(kw) AS peak_kw
FROM smart_meter
WHERE meter_id = 'MTR-001'
  AND WEEK(ts, 3) = 45;  -- 第45周（ISO）

统计每周用电量（累积读数差值）

sql 复制代码

SELECT meter_id,
       WEEK(ts, 3) AS week_no,
       (MAX(kwh) - MIN(kwh)) AS weekly_kwh
FROM smart_meter
GROUP BY meter_id, WEEK(ts, 3)
ORDER BY meter_id, week_no;

不同周起始模式对比

sql 复制代码

-- ISO 周（周一起始，1--53）
SELECT meter_id, WEEK(ts, 3) AS iso_week, AVG(kw) AS avg_kw
FROM smart_meter
GROUP BY meter_id, WEEK(ts, 3);

-- 周日起始，0--53
SELECT meter_id, WEEK(ts, 0) AS sunday_week0, AVG(kw) AS avg_kw
FROM smart_meter
GROUP BY meter_id, WEEK(ts, 0);

结合日期范围按周汇总

sql 复制代码

SELECT WEEK(ts, 3) AS week_no, SUM(kw) AS sum_kw
FROM smart_meter
WHERE ts BETWEEN TO_TIMESTAMP('2024-09-01', 'yyyy-mm-dd')
            AND TO_TIMESTAMP('2024-10-31', 'yyyy-mm-dd')
GROUP BY WEEK(ts, 3)
ORDER BY week_no;

常见问题与建议

与企业周报口径一致选择 mode，推荐 ISO 周（mode=3）降低跨年边界歧义
若需"某年某周"精确统计，建议同时分组 YEAR(ts) 或限定日期范围，避免跨年混淆
字符串输入建议使用 TO_TIMESTAMP() 统一解析后再传给 WEEK，确保时区一致
在超级表上分组时，结合 meter_id（或 tbname）进行设备级分析

版本信息

支持版本：自 v3.3.3.0 起
不同客户端时区可能影响字符串解析与显示，跨时区需显式时区标注

关于 TDengine

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