【KWDB 创作者计划】一文掌握KWDB的时序表管理

前言

本文是在对时序数据库有一定了解，并且KWDB的数据库操作了解后进行学习的文章安排，如果对时序数据库与KWDB的数据库操作还不怎么了解的可以查阅官网的文档进行提前学习，当有了这些基础后，本文就是对时序数据表的一个管理操作。

注：时序表（TIME SERIES TABLE）是用于存储时间序列数据的数据表。

准备KWDB的数据库

这里不能直接create来创建一定要加上TS的参数，这样创建的才是时序数据库：【TIME SERIES】。

sql 复制代码

CREATE TS DATABASE ts_db;

我们已经有了要操作的时序数据库了。

KWDB的时序表创建语法

语法格式需要注意：

sql 复制代码

CREATE TABLE <table_name> (<column_list>) 
[TAGS|ATTRIBUTES] (<tag_list>) 
PRIMARY [TAGS|ATTRIBUTES] (<primary_tag_list>) 
[RETENTIONS <keep_duration>]
[ACTIVETIME <active_duration>]
[PARTITION INTERVAL <interval>]
[DICT ENCODING];

参数说明

参数	说明
`table_name`	待创建的时序表的名称，表名的最大长度为 128 字节。在指定数据库中，时序表名称必须唯一，并且遵循标识符命名规范。
`column_list`	待创建的数据列列表，支持添加两个以上的列定义，最多可指定 4096 列。列定义包括列名、数据类型和默认值。列名的最大长度为 128 字节，支持指定 NOT NULL，默认为空值。支持自定义第一列的列名，但数据类型必须是 TIMESTAMPTZ 或 TIMESTAMP 且非空。默认时区为 UTC。对于非时间类型的数据列，默认值只能是常量。对于时间类型的列（TIMESTAMPTZ 或 TIMESTAMP），默认值可以是常量，也可以是 `now()` 函数。如果默认值类型与列类型不匹配，设置默认值时，系统报错。支持默认值设置为 NULL。时间戳列支持设置时间精度。目前，KWDB 支持毫秒、微秒和纳秒的时间精度。默认情况下，KWDB 采用毫秒时间精度。
`tag_list`	标签列表，支持添加一个或多个标签定义，最多可指定 `128` 个标签。标签定义包含标签名和数据类型，标签名的最大长度为 128 字节，支持指定 NOT NULL，默认为空值。不支持 TIMESTAMP、TIMESTAMPTZ、NVARCHAR 和 GEOMETRY 数据类型。
`primary_tag_list`	主标签列表，支持添加一个或多个主标签名称，最多可指定 `4` 个。主标签必须包含在标签列表内且指定为 NOT NULL，不支持浮点类型和除 VARCHAR 之外的变长数据类型。VARCHAR 类型长度默认 `64` 字节，最大长度为 `128` 字节。
`keep_duration`	可选参数，指定表的生命周期。超过设置的生命周期后，系统自动从数据库中清除目标表中数据。默认值为 `0d`，即不会过期删除。支持配置的时间单位包括：秒（S 或 SECOND）、分钟（M 或 MINUTE）、小时（H 或 HOUR）、天（D 或 DAY）、周（W 或 WEEK）、月（MON 或 MONTH）、年（Y 或 YEAR）。取值必须是整数值，最大值不得超过 `1000` 年。说明 - 当用户单独指定或者修改数据库内某一时序表的生命周期或分区时间范围时，该配置只适用于该时序表。 - 生命周期的配置不适用于当前分区。当生命周期的取值小于分区时间范围的取值时，即使表的生命周期已到期，由于数据存储在当前分区中，用户仍然可以查询数据。 - 当时间分区的所有数据超过生命周期时间点（`now() - retention time`）时，系统尝试删除该分区的数据。如果此时用户正在读写该分区的数据，或者系统正在对该分区进行压缩或统计信息处理等操作，系统无法立即删除该分区的数据。系统会在下一次生命周期调度时再次尝试删除数据（默认情况下，每小时调度一次）。 - 生命周期和分区时间范围设置与系统的存储空间密切相关。生命周期越长，分区时间范围越大，系统所需的存储空间也越大。
`active_duration`	可选参数，指定数据的活跃时间。超过设置的时间后，系统自动压缩表数据。默认值为 `1d`，表示系统对表数据中 1 天前的分区进行压缩。支持配置的时间单位包括：秒（S 或 SECOND）、分钟（M 或 MINUTE）、小时（H 或 HOUR）、天（D 或 DAY）、周（W 或 WEEK）、月（MON 或 MONTH）、年（Y 或 YEAR）。默认时间单位为天（D 或 DAY）。取值必须是整数值，最大值不得超过 `1000` 年。如果设置为 `0`，表示不压缩表数据。
`interval`	可选参数，指定表数据目录分区的时间范围。默认值为 `10d`，即每 10 天进行一次分区。支持配置的时间单位包括：天（D 或 DAY）、周（W 或 WEEK）、月（MON 或 MONTH）、年（Y 或 YEAR）。取值必须是整数值，最大值不得超过 `1000` 年。
`DICT ENCODING`	可选参数，启用字符串的字典编码功能，提升字符串数据的压缩能力。表中存储的字符串数据重复率越高，压缩优化效果越明显。该功能只适用于 CHAR 和 VARCHAR 长度小于等于 `1023` 的字符串，且只能在建表时开启。开启后不支持禁用。

以下是 MySQL 创建数据库和上述创建时序数据库语法的区别对比表格：

对比维度	MySQL 创建数据库语法	创建时序数据库语法
基本语法结构	`CREATE DATABASE <database_name>;` 创建数据库后，使用 `CREATE TABLE` 语句创建表，基本语法为 `CREATE TABLE <table_name> (<column_definition_list>);`	`CREATE TABLE <table_name> (<column_list>) [TAGS	ATTRIBUTES] (<tag_list>) PRIMARY [TAGS	ATTRIBUTES] (<primary_tag_list>) [RETENTIONS <keep_duration>] [ACTIVETIME <active_duration>] [PARTITION INTERVAL ] [DICT ENCODING];`
列定义	主要定义列名、数据类型、约束等，如 `CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255), age INT);`	除了列名和数据类型等基本定义外，还通过 `TAGS` 或 `ATTRIBUTES` 定义标签列，用于对数据进行分类和索引，例如 `CREATE TABLE sensor_data (ts TIMESTAMP, value FLOAT) TAGS (sensor_id VARCHAR(50), location VARCHAR(50));`
主键定义	通常在列定义中直接指定主键，如 `id INT PRIMARY KEY`	通过 `PRIMARY [TAGS	ATTRIBUTES]`明确指定主键，且主键可以是标签列或普通列的组合，例如`PRIMARY TAGS (sensor_id, ts)`
数据保留策略	一般通过存储过程、定时任务等方式实现数据的定期清理或归档	直接在创建表语句中通过 `RETENTIONS <keep_duration>` 明确指定数据保留时长，如 `RETENTIONS 30d` 表示保留 30 天的数据
活跃时间设置	无直接相关语法	可以使用 `ACTIVETIME <active_duration>` 设置数据的活跃时间，用于优化存储和查询性能，如 `ACTIVETIME 7d` 表示最近 7 天的数据为活跃数据
分区设置	可通过 `PARTITION BY` 子句进行分区，如按日期、范围等分区，但语法和功能与时序数据库不同	通过 `PARTITION INTERVAL <interval>` 设置分区间隔，如 `PARTITION INTERVAL 1d` 表示按天进行分区
数据编码	有自己的存储引擎和数据编码方式，但不是在创建表语句中直接这样定义	可以通过 `DICT ENCODING` 开启字典编码等特殊编码方式，用于优化存储和查询

KWDB时序表实操训练

建表DDL语句：

sql 复制代码

CREATE TABLE users (
  k_timestamp TIMESTAMP NOT NULL,
  user_age INT NOT NULL,
  user_height FLOAT,
  user_weight FLOAT
) TAGS (
      user_id INT NOT NULL,
      user_role VARCHAR(30) NOT NULL
) PRIMARY TAGS (user_id);

运行测试：

查看表结构

sql 复制代码

\d users;

可以清晰的看到主键以及其他数据列的信息。

查看建表语句

SHOW CREATE users;

DML测试语句操作

插入一条用户数据：

sql 复制代码

INSERT INTO users (k_timestamp, user_age, user_height, user_weight, user_id, user_role)
VALUES ('2025-04-16T12:00:00Z', 30, 175.5, 70.0, 1, '张三');

由于是时序数据库更新数据操作会报错：

sql 复制代码

-- 将用户ID为1的用户年龄更新为31岁
UPDATE users
SET user_age = 31
WHERE user_id = 1;

我们这里需要变向的来完成更新，需要先删除再添加。

sql 复制代码

delete from users where user_id = 1;
INSERT INTO users (k_timestamp, user_age, user_height, user_weight, user_id, user_role)
VALUES ('2025-04-16T12:00:00Z', 15, 175.5, 70.0, 1, '张三');

修改表操作

ALTER TABLE`语句用于修改以下表信息：

修改表名、设置表的数据生命周期、活跃时间和数据目录分区的时间范围
添加列、修改列名、列的数据类型或宽度、设置列的默认值、删除列的默认值
添加标签、修改标签名、标签的数据类型或宽度、删除标签

注：

删除列时，原表至少保留两列数据列，且不支持删除第一列（时间戳列）。
不支持添加、删除、重命名主标签。
目前，不支持一次添加、删除多个列或标签。

修改语法格式：

sql 复制代码

ALTER TABLE <table_name> 
[ADD [COLUMN] [IF NOT EXISTS] <colunm_name> <data_type> [DEFAULT <expr> | NULL ] 
|ADD [TAG | ATTRIBUTE] <tag_name> <tag_type>
|ALTER [COLUMN] <colunm_name> [SET DATA] TYPE <new_type> [SET DEFAULT <default_expr> | DROP DEFAULT ]
|ALTER [TAG | ATTRIBUTE] <tag_name> [SET DATA] TYPE <new_type>
|DROP [COLUMN] [IF EXISTS] <colunm_name>
|DROP [TAG | ATTRIBUTE] <tag_name>
|RENAME TO <new_table_name> 
|RENAME COLUMN <old_name> TO <new_name>
|RENAME [TAG | ATTRIBUTE] <old_name> TO <new_name>
|SET [RETENTIONS = <keep_duration> | ACTIVETIME = <active_duration> | PARITITION INTERVAL = <interval>]];

参数说明：

ADD COLUMN：添加列，需指定列名和数据类型，也支持指定列的默认值。每张表最多支持 4096 列。

ADD TAG/ATTRITBUTE：添加标签，需指定标签的名称和数据类型，不支持添加主标签。

ALTER COLUMN: 修改列的数据类型或宽度，设置或删除列的默认值。

ALTER TAG/ATTRITBUTE：修改标签的数据类型或宽度，其中 SET DATA 为可选关键字，是否使用不影响修改标签的数据类型和宽度，不支持修改主标签的数据类型和宽度。

DROP COLUMN: 删除列，需指定列名。

RENAME TO: 修改表的名称。

RENAME COLUMN：修改列的名称。

RENAME TAG/ATTRIBUTE：修改标签的名称。

SET RETENTIONS：设置表的生命周期。

SET ACTIVETIME：设置表数据的活跃时间。

SET PARTITION INTERVAL：设置表数据目录分区的时间范围。

实操示例：

sql 复制代码

-- 修改表的名称。

ALTER TABLE users RENAME TO tstable;

-- 修改表的生命周期。

ALTER TABLE users SET RETENTIONS = 20d;

-- 修改表数据的活跃时间。

ALTER TABLE users SET ACTIVETIME = 20d;

-- 修改表数据目录分区的时间范围。

ALTER TABLE users SET PARTITION INTERVAL = 2d;

-- 新增列。

ALTER TABLE users ADD COLUMN c3 INT NULL;

-- 新增列并设置列的默认值。

ALTER TABLE users ADD COLUMN c4 VARCHAR(50) DEFAULT 'aaa';

-- 删除列。

ALTER TABLE users DROP c3;

-- 修改列的名称。

ALTER TABLE users RENAME COLUMN c2 TO c4;

-- 修改列的数据类型。

ALTER TABLE users ALTER COLUMN c3 TYPE INT8;

-- 修改列的默认值。

ALTER TABLE users ALTER COLUMN c4 SET DEFAULT '789';

-- 删除列的默认值。

ALTER TABLE users ALTER COLUMN c4 DROP DEFAULT;

-- 新增标签。

ALTER TABLE users ADD TAG color VARCHAR(30);

-- 删除标签。

ALTER TABLE users DROP TAG color;

-- 修改标签名。

ALTER TABLE users RENAME TAG site TO location;

-- 修改标签的宽度。

ALTER TABLE users ALTER color TYPE VARCHAR(50);

总结

我们已经将时序表的基础操作全部搞定，收获的内容还是比较多的，对于表的创建注意事项还有在实操的注意事项我这里也都所有说明，具体的还需要进行练习操作，希望大家能更好更快的成长。

欢迎来到KWDB社区

KWDB开源库地址：https://gitee.com/kwdb/kwdb

KWDB学习地址：https://www.kaiwudb.com/learning/

KWDB活动地址：https://mp.weixin.qq.com/s/ZKQo7eQj_AtwamONCSl07A

希望本文能为大家带来一些价值，欢迎留言讨论。