KWDB基础概念与语法：从多模架构到SQL实践的完整指南

在物联网与工业互联网场景中，数据管理的复杂性远超传统企业应用。一个典型的智能制造车间，既需要存储设备传感器产生的海量时序数据，又需要管理设备台账、工单、人员等结构化关系数据。传统做法是部署两套系统：一套时序数据库负责指标采集，一套关系数据库负责业务管理。这种分离架构带来了数据同步延迟、跨库查询困难和运维成本叠加等问题。

KWDB正是为解决这一矛盾而生的分布式多模数据库。它由开放原子开源基金会孵化及运营，基于浪潮KaiwuDB开源，支持在同一实例中同时建立时序库和关系库并融合处理多模数据。具备千万级设备接入、百万级数据秒级写入、亿级数据秒级读取等时序数据高效处理能力，具有稳定安全、高可用、易运维等特点。

本文将从KWDB的核心概念出发，系统讲解其数据类型体系、SQL语法规则、时序数据处理机制和集群部署要点，帮助读者建立对KWDB的完整认知框架。

一、KWDB的核心定位与架构

1.1 多模融合的设计理念

KWDB最核心的设计理念是多模融合。传统数据库要么专注于关系型数据，要么专注于时序数据，而KWDB在同一套引擎中同时支持两种数据模型。

这种融合并非简单的功能叠加。关系库和时序库在KWDB中是完全隔离的，时序表必须建在用CREATE TS DATABASE创建的时序数据库中，关系表必须建在用CREATE DATABASE创建的关系型数据库中。但两者可以通过跨模查询实现关联分析。例如，一张时序表存储传感器读数，一张关系表存储设备信息，用户可以在一条SQL中完成关联查询，将设备维度的属性与传感器维度的指标结合起来。

KWDB采用分布式架构，典型应用场景包括物联网、能源电力、交通车联网等，旨在为各行业提供一站式数据存储、管理与分析的基座。

1.2 系统架构分层

KWDB的系统架构自上而下可分为三层：

接口连接层提供多种通用连接接口，包括JDBC、ODBC、RESTful API等，支持标准SQL协议，与第三方工具无缝集成，降低开发及学习难度。

计算层负责SQL解析、查询规划和执行。SQL语句执行引擎可以分为四个部分：parser解析器进行词法解析和语法解析，将输入的SQL解析成AST抽象语法树；compile编译器进行语义解析和计划构建；optimize优化器对计划进行优化；exec执行器执行计划。这种分层设计使KWDB能够灵活扩展SQL语法，同时保持执行效率。

存储层包含时序存储引擎和关系存储引擎，各自针对不同的数据特征进行优化。时序引擎采用列式存储和专用压缩算法，关系引擎支持完整的ACID事务特性。

1.3 集群部署形态

KWDB支持多种部署形态，适应不同规模的需求。

单机部署适合开发测试和小规模场景。通过Docker可以快速体验KWDB，一条命令即可启动单节点实例。

单副本集群在同一机房的多个节点上运行，整个集群只有一份数据副本，所有数据的存储和更新操作都由该副本负责。写入性能最优，但不具备高可用能力。

多副本集群在同一机房的多个节点上运行，每份数据默认有3份副本，且副本分布在不同节点上。集群启动后，副本和leaseholder均匀分布在所有节点上，确保数据的高可用性和平衡性。如果单个节点因网络断开或磁盘故障导致状态异常，系统会开始迁移该节点的leaseholder，迁移期间数据查询和DML操作可能受影响，DDL操作可能会报错。

1.4 节点状态与高可用机制

KWDB中的集群节点存在三种状态：存活节点是默认节点状态，表示节点正常运行；异常节点指1分钟内无网络连接的节点会被标记为异常节点；不可用节点指节点离线时间达到设定值后，系统会将该节点标记为不可用。

多副本集群通过跨节点复制机制实现故障自动转移和数据强一致性。当单个节点故障时，如果剩余节点数量仍大于副本数，系统自动补足缺失的副本。在3节点3副本的集群中，两个节点故障后仅剩1个节点存活，无法满足多数投票机制，集群将无法继续提供服务。因此生产环境建议部署5节点集群以获得更好的容错能力。

二、KWDB的数据类型体系

2.1 关系型数据类型

KWDB的关系型数据类型与标准SQL高度兼容。

整数类型包括INT2（SMALLINT）占用2字节，取值范围从-32768到+32767；INT4（INT或INTEGER）占用4字节，取值范围从-2147483648到+2147483647；INT8（INT64或BIGINT）占用8字节，取值范围从-9223372036854775808到+9223372036854775807。

浮点类型中，FLOAT用于存储单精度浮点数，在机内占4个字节；DOUBLE用于存储双精度浮点数，在机内占8个字节，比FLOAT数据类型范围更广。IEEE754的特殊值如正无穷大、负无穷大和NaN不能直接使用数字文字输入，而必须使用解释文字或从字符串文字的显式转换进行转换。

文本类型包括CHAR、VARCHAR和TEXT。KWDB 3.2.1版本新增了CITEXT类型，用于存储大小写不敏感的文本，查询时不区分大小写，支持大小写不敏感的模式匹配。

时间类型包括TIME类型用于存储没有时区的时间信息，TIMESTAMP用于存储时间戳。KWDB 3.2.1版本支持运行期通过集群参数动态配置全局时区：客户端连接未携带时区时，TIMESTAMPTZ数据采用集群配置时区；连接显式指定时区时，以连接携带的时区作为会话时区。

2.2 时序型数据类型

时序表的数据列与关系表类似，但增加了标签列的概念。时序表的列分为两类：数据列存储随时间变化的值，如温度、湿度、电压等；标签列存储设备的静态属性，如设备ID、型号、位置等，用于标识数据的来源。

在创建时序表时，第一列的数据类型必须为timestamp或timestamptz，且不可为空值。标签列的定义语法为TAGS (tag1 type1, tag2 type2, ...)，并通过PRIMARY TAGS (tag1, tag2)指定主标签。

2.3 SERIAL类型

KWDB支持SERIAL类型用于自动生成唯一标识符。BIGSERIAL类型在创建表时自动递增，适合作为主键使用。在创建关系表时，可以使用BIGSERIAL PRIMARY KEY定义自增主键。

三、SQL基础语法

3.1 SQL语句的分类

KWDB支持标准SQL语句，涵盖DDL、DML、DQL和DCL四类操作。

DDL数据定义语言用于创建、修改和删除数据库对象，包括CREATE、ALTER、DROP等语句。

DML数据操纵语言用于操作表中的数据，包括INSERT、UPDATE、DELETE等语句。

DQL数据查询语言主要用于SELECT语句，支持简单查询、集合查询、子查询、连接查询等多种形式。

DCL数据控制语言用于权限管理，包括GRANT、REVOKE等语句。

3.2 SQL的基本语法元素

文本也称为常量，是SQL语句中固定不变的值。例如SELECT contact FROM user_info WHERE user_name = 'User 1'中的'User 1'即为文本常量。

关键字是SQL语言中预先定义的特殊单词，用于表示操作类型、对象或条件。关键字不区分大小写。

标识符用于命名数据库对象，如表、字段等。标识符可包含字母、数字、下划线，但不能以数字开头。

表达式由标识符、常量、运算符组合而成，用于表示计算逻辑或条件判断。表达式可以出现在SELECT列表、WHERE条件、ORDER BY子句等位置。

3.3 注释语法

KWDB支持两种注释风格：单行注释使用--开头，多行注释使用/* */包裹。注释可以出现在SQL语句的任何位置，用于说明代码意图。

四、数据库与表的创建

4.1 创建时序数据库

时序数据库必须使用CREATE TS DATABASE语句创建，与关系型数据库的CREATE DATABASE语句区分。

sql 复制代码

CREATE TS DATABASE sensor_data;

创建后使用USE语句切换到时序数据库：

sql 复制代码

USE sensor_data;

4.2 创建关系数据库

关系数据库使用标准的CREATE DATABASE语句：

sql 复制代码

CREATE DATABASE device_management;

关系数据库只能存放普通关系表，时序表必须建在时序数据库中，两者完全隔离。

4.3 创建时序表

时序表的创建语法包含列定义、标签定义和主标签指定：

sql 复制代码

CREATE TABLE sensor_data.readings (
    ts TIMESTAMPTZ NOT NULL,
    temperature FLOAT,
    humidity FLOAT
) TAGS (
    device_id INT NOT NULL,
    location VARCHAR(100)
) PRIMARY TAGS (device_id);

时序表支持配置数据的活跃时间，通过RETENTIONS子句指定：

sql 复制代码

CREATE TABLE power (
    ts TIMESTAMP NOT NULL,
    voltage FLOAT,
    current FLOAT
) TAGS (
    device_id INT NOT NULL
) PRIMARY TAGS (device_id)
RETENTIONS 20D;

RETENTIONS支持的时间单位包括秒（S或SECOND）、分钟（M或MINUTE）、小时（H或HOUR）、天（D或DAY）、周（W或WEEK）、月（MON或MONTH）、年（Y或YEAR），取值必须是整数值，最大值不得超过1000年。

4.4 创建关系表

关系表的创建语法与标准SQL一致：

sql 复制代码

CREATE TABLE users (
    user_id BIGSERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL UNIQUE,
    password VARCHAR(255) NOT NULL,
    email VARCHAR(100),
    phone VARCHAR(20),
    status SMALLINT DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    CONSTRAINT chk_status CHECK (status IN (0, 1))
);

可以为表和列添加注释：

sql 复制代码

COMMENT ON TABLE users IS '用户表';
COMMENT ON COLUMN users.status IS '1:正常,0:禁用';

4.5 创建索引

KWDB支持创建单列索引和复合索引：

sql 复制代码

CREATE INDEX idx_username ON users (username);
CREATE INDEX idx_email ON users (email);

KWDB兼容PostgreSQL语法，支持CONCURRENTLY关键字进行并发创建索引，无需额外操作即可在线创建索引。USING子句支持btree和gin两种索引类型，btree表示标准的二级索引，gin用于JSONB列中无模式数据的倒排索引。

五、数据查询与操作

5.1 简单查询

SELECT语句是读取和处理现有数据的主要SQL语法。基本查询语法：

sql 复制代码

SELECT device_id, temperature, humidity
FROM sensor_data.readings
WHERE temperature > 30.0
ORDER BY ts DESC
LIMIT 100;

KWDB支持WHERE子句中使用LIKE关键字进行模式匹配，支持通配符%和_。

时序数据的查询通常围绕时间范围展开：

sql 复制代码

SELECT * FROM sensor_data.readings
WHERE ts BETWEEN '2025-04-16 10:35:00.779+00:00' 
          AND '2025-04-16 10:36:00.779+00:00';

5.2 聚合查询

KWDB提供丰富的聚合函数用于统计分析。基础聚合函数包括COUNT、AVG、SUM、MIN、MAX和STDDEV。

sql 复制代码

SELECT device_id, AVG(temperature), MIN(temperature), MAX(temperature)
FROM sensor_data.readings
GROUP BY device_id;

时序场景专用的聚合函数包括：

FIRST/LAST关注时间顺序，返回时间窗口内的第一个或最后一个值。TIME_BUCKET用于降采样，将时间戳按固定间隔分组。TWA适应非均匀采样，计算时间加权平均值。

5.3 窗口函数

窗口函数是时序数据处理的核心功能，支持基于时间、行数或状态变化等条件对数据进行动态分组并执行聚合计算。

计数窗COUNT_WINDOW按固定行数分组，适合对数据点数量固定的场景进行统计。

会话窗口SESSION_WINDOW基于数据间隔动态分组，当数据间隔超过设定阈值时开始新的窗口，适合分析设备运行会话。

时间窗口按固定时间间隔分组，是时序数据降采样和趋势分析的基础工具。

5.4 跨模查询

跨模查询是KWDB多模融合能力的核心体现，允许在一条SQL中同时查询时序表和关系表：

sql 复制代码

SELECT r.device_id, d.device_name, AVG(r.temperature) AS avg_temp
FROM sensor_data.readings r
JOIN device_management.devices d ON r.device_id = d.device_id
WHERE r.ts > NOW() - INTERVAL '1 day'
GROUP BY r.device_id, d.device_name;

这种查询能力消除了传统架构中时序库和关系库之间的数据同步需求，简化了数据架构。

5.5 数据更新操作

INSERT用于向表中写入数据：

sql 复制代码

INSERT INTO users (username, password, email, phone, status)
VALUES ('admin', '123123', '123@123.com', '15512345678', 1);

时序表的INSERT通常按列顺序写入：

sql 复制代码

INSERT INTO sensor_data.readings (ts, temperature, humidity, device_id, location)
VALUES ('2025-05-31 10:00:00', 25.5, 60.0, 1, '车间A');

UPDATE用于更新已有数据：

sql 复制代码

UPDATE users SET email = 'new-email@example.com' WHERE user_id = 1;

DELETE用于删除数据。时序表的DELETE支持按时间范围或按主标签删除：

sql 复制代码

DELETE FROM sensor_data.readings
WHERE ts < '2025-01-01 00:00:00';

如果WHERE条件指定时间戳列，只删除数据列数据，保留标签数据；如果指定主标签列，则同时删除数据列数据和标签数据。

5.6 ALTER TABLE操作

KWDB支持使用ALTER TABLE语句修改表结构。添加列的操作是在线的，不会阻塞表中的数据读写：

sql 复制代码

ALTER TABLE users ADD COLUMN address VARCHAR(200);

ALTER TAG语句用于修改时序表标签的数据类型和宽度，同样为在线操作，不会阻塞表中的数据读写。修改数据类型时，如果已有标签的值与新数据类型不匹配，修改操作仍然可以执行成功，不符合新数据类型的标签值在查询时将显示为NULL。

六、SQL执行引擎与语法扩展

6.1 执行引擎的四个阶段

KWDB的SQL语句执行引擎分为四个阶段，每个阶段承担不同的职责。

Parser解析器进行词法解析和语法解析，将输入的SQL解析成AST抽象语法树。词法分析将SQL文本拆分为token序列，语法分析根据语法规则将token序列组织为树形结构。

Compile编译器进行语义解析和计划构建。语义解析阶段会检查表名、列名是否存在，数据类型是否匹配，权限是否充足。计划构建将AST转换为执行计划。

Optimize优化器对执行计划进行优化，包括谓词下推、连接顺序选择、索引选择等。

Exec执行器按照优化后的计划执行查询，返回结果。

6.2 语法扩展机制

KWDB的语法规则定义在pkg/sql/parser/sql.y文件中，使用yacc格式。yacc文件记录了所有的KWDB中的关键字和语法规则，语法规则通过BNF的形式表示。

添加新语法需要修改sql.y文件中的语法规则，然后在tree包中定义对应的AST结构体，实现statement接口中的方法，并在语义解析阶段添加将AST转换为planNode的逻辑。

6.3 与标准SQL的兼容性

KWDB支持ANSI SQL-92基础语法，并对时间窗口函数、嵌套子查询、标签过滤表达式做了增强。这意味着熟悉标准SQL的开发者可以快速上手，同时享受KWDB对时序场景的专门优化。

七、集群部署与运维要点

7.1 部署前的环境准备

KWDB多副本集群部署需要准备多台服务器。每台服务器的硬件配置建议为4核CPU和8GB内存以上，磁盘推荐使用SSD或NVMe设备。

操作系统支持Ubuntu 20.04/22.04/24.04、CentOS 7、openEuler、UOS等。需要安装的依赖包括cmake、go、libprotobuf-dev等。

每个节点需要设置唯一的主机名，并在/etc/hosts中配置所有节点的IP和主机名映射。

时钟同步是保证数据一致性的前提条件。KWDB采用中等强度的时钟同步机制，当节点检测到自身的机器时间与集群中至少50%的节点的机器时间的误差值超过500ms的80%时，该节点会自动停止。因此每个节点都必须运行NTP或systemd-timesyncd等时钟同步软件。

7.2 SSH免密配置

部署脚本需要从部署节点通过SSH连接到其他节点执行安装和配置操作。在部署节点上生成密钥对后，将公钥分发到所有节点：

bash 复制代码

ssh-keygen -f ~/.ssh/id_rsa -N ""
ssh-copy-id -f -i ~/.ssh/id_rsa.pub -o StrictHostKeyChecking=no node1
ssh-copy-id -f -i ~/.ssh/id_rsa.pub -o StrictHostKeyChecking=no node2
ssh-copy-id -f -i ~/.ssh/id_rsa.pub -o StrictHostKeyChecking=no node3

7.3 安装与初始化

从KWDB官方发布页面下载对应系统环境的安装包，解压后执行多副本集群安装命令：

bash 复制代码

chmod +x ./deploy.sh
./deploy.sh install --multi-replica

安装完成后初始化集群：

bash 复制代码

./deploy.sh cluster --init

查看集群状态：

bash 复制代码

./deploy.sh cluster --status

返回信息中的is_available和is_live字段均为true表示节点正常运行。

7.4 安全模式配置

KWDB支持安全模式和非安全模式部署。安全模式使用TLS加密技术验证节点和客户端的身份，并对节点与客户端之间的数据传输进行加密。非安全模式存在严重的安全风险：集群对所有客户端开放，所有用户无需密码即可访问。生产环境强烈建议采用安全模式部署。

7.5 监控与运维

KWDB提供完整的监控方案，基于Prometheus和Grafana构建。关键监控指标包括SQL Queries QPS、Replicas per Node、Service Latency 99th百分位和Capacity使用比例。副本数量图帮助判断数据均衡性，若副本分布不均可能导致热点问题。

结语

KWDB作为面向AIoT场景的分布式多模数据库，通过在同一实例中融合时序库和关系库，解决了传统架构中数据分离、同步延迟和运维复杂等核心痛点。其SQL语法兼容标准SQL的同时，针对时序场景提供了TIME_BUCKET降采样、SESSION_WINDOW会话窗口等专用函数，以及跨模查询能力，使开发者能够用统一的SQL语言完成多模数据的关联分析。

从基础概念到语法实践，KWDB的学习曲线相对平缓。熟悉SQL的开发者可以快速上手，将既有知识迁移到时序数据处理场景。而多副本集群的部署机制、节点状态管理和安全模式配置，则为生产环境的稳定运行提供了保障。对于正在构建物联网、工业互联网或车联网数据平台的团队，KWDB提供了一条从数据采集到分析洞察的一体化路径。