SonnetDB SQL Cookbook：常用查询模式速查

SonnetDB 的时序数据开发常会重复用到建模、写入、过滤、聚合和检索。本文汇总 10 类 SQL 模板供查阅；执行前需要对应的数据库连接、权限、schema 和样例数据。这些片段不是整篇顺序执行的脚本。

1. 建库、建用户与授权

sql 复制代码

CREATE DATABASE demo;
CREATE USER writer WITH PASSWORD '<替换为独立强密码>';
GRANT WRITE ON DATABASE demo TO writer;

控制面建库、用户和授权 SQL 仅用于 Server 模式，需具备相应管理权限。密码占位符必须替换；writer 的 WRITE 授权不能视为读取授权。后续示例连接 demo 数据库，并使用具备相应 DDL、写入或 READ 权限的身份。

2. 创建 Measurement

sql 复制代码

CREATE MEASUREMENT cpu (
    host      TAG,
    region    TAG,
    usage     FIELD FLOAT,
    cores     FIELD INT,
    throttled FIELD BOOL,
    label     FIELD STRING
);

FLOAT 对应 Float64、INT 对应 Int64；TAG 和 FIELD 的作用不同，不应从示例数值推断存储大小或性能。

3. 写入数据

单条和批量写入是可分别采用的模板。时间戳为 Unix 毫秒，按当前应用数据调整。

sql 复制代码

-- 单条写入
INSERT INTO cpu (time, host, region, usage, cores, throttled, label)
VALUES (1713657600000, 'server-01', 'cn-hz', 0.42, 8, FALSE, 'normal');

-- 批量写入
INSERT INTO cpu (time, host, region, usage, cores, throttled, label) VALUES
    (1713657600000, 'server-01', 'cn-hz', 0.42, 8, FALSE, 'normal'),
    (1713657660000, 'server-01', 'cn-hz', 0.55, 8, FALSE, 'normal');

4. 原始数据查询

sql 复制代码

-- 查询特定序列的原始数据
SELECT time, host, usage
FROM cpu
WHERE host = 'server-01'
  AND time >= 1713657600000
  AND time < 1713658200000;

-- 带标量函数
SELECT round(abs(usage - 0.5), 2) AS deviation
FROM cpu
WHERE host = 'server-01';

5. 单表别名

sql 复制代码

SELECT c.time, c.host, c."usage"
FROM cpu AS c
WHERE c.host = 'server-01'
ORDER BY c.time ASC
LIMIT 10;

SonnetDB 支持单个 measurement 的别名限定列名，例如 c.time 或 c."usage"；另有 measurement 与关系维表的受限 JOIN 路径，具体可用条件和列解析合同需单独核对。

6. 分页查询

时间戳可能并列，当前模板不承诺跨请求快照稳定性；深 OFFSET 成本需按实际数据检查。

sql 复制代码

-- 传统风格
SELECT time, host, usage
FROM cpu WHERE host = 'server-01'
ORDER BY time ASC
LIMIT 5 OFFSET 0;

-- SQL 标准风格
SELECT time, host, usage
FROM cpu WHERE host = 'server-01'
ORDER BY time ASC
OFFSET 5 ROWS FETCH NEXT 5 ROWS ONLY;

7. 聚合、统计与分位数

sql 复制代码

SELECT
    count(usage)  AS cnt,
    sum(usage)    AS total,
    min(usage)    AS min_usage,
    max(usage)    AS max_usage,
    avg(usage)    AS avg_usage,
    first(usage)  AS first_usage,
    last(usage)   AS last_usage
FROM cpu
WHERE host = 'server-01';

下面是另一个统计聚合模板；不要把示例结果当作生产精度或性能验收。

sql 复制代码

SELECT
    stddev(usage)       AS std,
    variance(usage)     AS var,
    spread(usage)       AS spread,
    median(usage)       AS median,
    percentile(usage, 95) AS p95,
    histogram(usage, 5) AS hist
FROM cpu
WHERE host = 'server-01';

8. 时间桶聚合

sql 复制代码

SELECT
    avg(usage)   AS avg_usage,
    max(usage)   AS max_usage,
    count(usage) AS cnt
FROM cpu
WHERE host = 'server-01'
GROUP BY time(2m);

9. 窗口分析

sql 复制代码

-- 差分与变化率
SELECT time, difference(usage) AS diff FROM cpu WHERE host = 'server-01';
SELECT time, derivative(usage) AS rate FROM cpu WHERE host = 'server-01';

-- 移动平均与累积求和
SELECT time, moving_average(usage, 3) AS ma3 FROM cpu WHERE host = 'server-01';
SELECT time, cumulative_sum(usage) AS cumsum FROM cpu WHERE host = 'server-01';

10. 向量检索

这些片段要求另有 documents measurement、4 维 VECTOR 字段 embedding 和对应 source 标签，不能复用前面的 cpu schema。模型、字段维度与索引配置均需匹配；WHERE 过滤不代表所有条件自动在 ANN 之前下推。

sql 复制代码

-- KNN 检索（余弦距离默认）
SELECT * FROM knn(documents, embedding, [0.10, 0.20, 0.30, 0.40], 3);

-- 混合检索（带 Tag 和时间过滤）
SELECT * FROM knn(documents, embedding, [0.10, 0.20, 0.30, 0.40], 5, 'cosine')
WHERE source = 'wiki'
  AND time >= 1713657600000;

-- 向量距离函数
SELECT cosine_distance(embedding, [0.10, 0.20, 0.30, 0.40]) AS cos_dist
FROM documents;

这份 Cookbook 为 SonnetDB 常见时序查询提供入口。按当前 SQL 参考和实现审阅了模板，未执行这些 SQL，也未在本轮创建数据库、用户、测试数据或验收模型质量与性能。实际使用时，先在自己的测试数据库按 schema 和权限逐项验证。