SonnetDB Docs

SQL 参考

当前版本真实支持的数据面与控制面 SQL 语法、限制和示例。

想直接复制完整场景化示例，可先看 SQL Cookbook；本页更偏向能力边界与精确语法说明。

数据面 SQL

`CREATE MEASUREMENT`

定义 measurement schema：

CREATE MEASUREMENT cpu (
    host TAG,
    region TAG STRING,
    usage FIELD FLOAT NULL,
    count FIELD INT,
    ok FIELD BOOL,
    label FIELD STRING NOT NULL
)

规则：

TAG 列默认为字符串，TAG 和 TAG STRING 等价。
FIELD 列支持 FLOAT、INT、BOOL、STRING、VECTOR(N)、GEOPOINT。
schema 中至少要有一个 FIELD 列。
time 不属于 schema 定义的一部分。
NULL / NOT NULL 可作为 DDL 兼容修饰符出现在列类型后；当前仅保留在 SQL AST 中，执行层不把它持久化为 catalog 约束，也不强制 NOT NULL。
DEFAULT <expr> 目前会被 parser 接受，但执行 CREATE MEASUREMENT 时会返回明确的 DEFAULT 暂不支持错误。

稀疏字段语义：

SonnetDB 的 field 是稀疏的：同一个 measurement 的不同时间点可以携带不同 field 集合。
如果某个时间点没有写入某个 field，查询该列时结果为 NULL；这表示“该时间点未记录该字段”，不是 schema 约束失败。
写入时不要用 DEFAULT 或显式 NULL 表达缺值；请省略该 field，或在应用侧写入具体默认值。

`INSERT INTO ... VALUES`

INSERT INTO cpu (time, host, region, usage, count, ok, label)
VALUES
    (1713676800000, 'server-01', 'cn-hz', 0.71, 10, TRUE, 'ok'),
    (1713676860000, 'server-01', 'cn-hz', 0.73, 11, TRUE, 'ok')

规则：

time 是保留伪列，表示 Unix 毫秒时间戳。
time 省略时会使用当前 UTC 毫秒时间。
每一行至少需要提供一个 FIELD 列值。
TAG 列必须是字符串字面量。
FIELD FLOAT 可以接受整数或浮点字面量。
目标 measurement 不存在时，INSERT 会按列值自动创建 schema；已有 measurement 缺失列时也会自动补齐。
SQL INSERT 的未知字符串列会推断为 TAG，未知非字符串列会推断为 FIELD。
已有 INT 字段遇到浮点值时会提升为 FLOAT；已有 FLOAT 字段接收整数时会转换为浮点保存，不会降级为 INT。
NULL 不能作为当前 INSERT 的显式列值；要表达某个 field 在该时间点缺失，请从列列表中省略它。

原始查询 `SELECT`

查询所有列：

SELECT * FROM cpu WHERE host = 'server-01'

显式投影：

SELECT time, host, usage
FROM cpu
WHERE host = 'server-01' AND time >= 1713676800000 AND time < 1713677400000
ORDER BY time ASC

标量函数投影：

SELECT abs(-usage), round(usage / 3, 2), sqrt(count), log(count, 10), coalesce(label, 'n/a')
FROM cpu
WHERE host = 'server-01'

单表别名与限定列名：

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

兼容常见探活查询的字面量投影：

SELECT 1 AS ok FROM cpu LIMIT 1

当前行为：

SELECT * 会展开为 time + 所有 tag 列 + 所有 field 列。
支持字面量投影（如 SELECT 1 ... LIMIT 1），会按匹配到的时间轴返回常量列。
当某个时间点缺少某个 field 时，结果列会返回 NULL。
标量函数当前支持 abs、round、sqrt、log、coalesce。
标量函数当前仅支持出现在 SELECT 投影中，可嵌套，也可接收算术表达式参数。
支持 FROM measurement [AS] alias 单表别名，以及 alias.column / alias."Column" 限定列名；执行前会校验限定符必须匹配当前别名。
当前不支持 JOIN。
coalesce(...) 只会在当前结果行存在时参与求值；它不会额外扩展原始查询的时间轴。
结果按时间升序返回。

分页子句（兼容两种风格）：

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

-- MySQL/PostgreSQL 常见风格
SELECT time, host, usage
FROM cpu
WHERE host = 'server-01'
ORDER BY time DESC
LIMIT 10 OFFSET 20;

说明：

支持 ORDER BY time [ASC|DESC]，排序会在分页前应用；当前要求查询结果中包含 time 列。
支持 OFFSET n（仅跳过，不限制返回行数）。
支持 FETCH FIRST|NEXT n ROW|ROWS ONLY。
支持 LIMIT n [OFFSET m] 兼容语法。
ORDER BY/OFFSET/FETCH/LIMIT 作用在最终结果集（投影/聚合之后）。

聚合查询

支持的聚合函数：

count
sum
min
max
avg
first
last

示例：

SELECT sum(usage), avg(usage), min(usage), max(usage)
FROM cpu
WHERE host = 'server-01'

count(*) 与 SQL 兼容写法 count(1) 也受支持：

SELECT count(*) FROM cpu WHERE host = 'server-01'
SELECT count(1) FROM cpu WHERE host = 'server-01'

`GROUP BY time(...)`

按时间桶聚合：

SELECT avg(usage) AS mean, count(usage)
FROM cpu
WHERE host = 'server-01'
GROUP BY time(1m)

当前限制和真实行为：

仅支持 GROUP BY time(duration)。
仅可用于聚合查询。
不支持 GROUP BY host 这类按列分组。
结果当前只返回聚合列，不会自动带出桶起始时间列。
duration 例子：1000ms、30s、1m。

`DELETE FROM ... WHERE ...`

DELETE FROM cpu
WHERE host = 'server-01' AND time >= 1713676800000 AND time <= 1713677400000

也可以只按 tag 或只按时间范围删除：

DELETE FROM cpu WHERE host = 'server-01'
DELETE FROM cpu WHERE time >= 1713676800000 AND time <= 1713677400000

当前删除语义：

删除底层通过 tombstone 实现，不会原地改写旧 segment。
后续查询会过滤 tombstone 覆盖的点。
compaction 会逐步消化已删除数据。

常见保留策略也可以直接写成相对时间：

DELETE FROM cpu
WHERE time >= now() - 30d

WHERE 子句的当前限制

虽然解析器支持更多表达式形态，但当前执行器的稳定支持范围是：

tag 等值条件，例如 host = 'server-01'
time 的范围比较，例如 time >= 1713676800000 AND time < 1713763200000，或者 time >= now() - 1d AND time < now() + 1d
多个条件使用 AND 连接

当前不建议在生产示例中使用：

OR
tag 不等式
field 条件过滤，例如 usage > 0
混合聚合列与普通列，例如 SELECT host, sum(usage) ...

这些写法中的不少在当前版本会直接报错。

元数据查询

`SHOW MEASUREMENTS` / `SHOW TABLES`

列出当前数据库中所有 measurement，按字典序升序返回单列 name。 SHOW TABLES 是 SHOW MEASUREMENTS 的兼容别名，便于 DBeaver、DataGrip 等通用 SQL 工具直接探测表清单。

SHOW MEASUREMENTS;
SHOW TABLES;        -- 等价

name
cpu
mem

`DESCRIBE [MEASUREMENT] <name>` / `DESC <name>`

描述指定 measurement 的列结构，按 CREATE MEASUREMENT 声明顺序返回三列：

列	类型	说明
`column_name`	string	列名
`column_type`	string	`tag` 或 `field`
`data_type`	string	`float64` / `int64` / `boolean` / `string`

关键字 MEASUREMENT 可省略，DESC 是 DESCRIBE 的兼容别名。

DESCRIBE MEASUREMENT cpu;
DESCRIBE cpu;       -- 等价
DESC cpu;           -- 等价

column_name	column_type	data_type
host	tag	string
usage	field	float64

若指定 measurement 不存在，会抛出 InvalidOperationException。

`EXPLAIN <read-only statement>`

EXPLAIN 返回一组 key / value 结果行，用于估算查询会扫描的 series、segment、block 与行数。

EXPLAIN SELECT usage
FROM cpu
WHERE host = 'server-01' AND time >= now() - 1d;

EXPLAIN SHOW MEASUREMENTS;
EXPLAIN DESCRIBE MEASUREMENT cpu;

当前支持范围：

SELECT ...
SHOW MEASUREMENTS / SHOW TABLES
DESCRIBE [MEASUREMENT] <name> / DESC <name>

当前不支持对 INSERT、DELETE、CREATE、DROP、用户/授权/Token 控制面 SQL 做 EXPLAIN。返回字段包括 database、statement_type、measurement、matched_series_count、estimated_segment_count、estimated_block_count、estimated_scanned_rows、estimated_memtable_rows、estimated_segment_rows、has_time_filter 与 tag_filter_count。

控制面 SQL

控制面 SQL 仅在服务端模式可用。

用户与密码

CREATE USER alice WITH PASSWORD 'pa$$'
CREATE USER admin2 WITH PASSWORD 'secret' SUPERUSER
ALTER USER alice WITH PASSWORD 'new-password'
DROP USER alice

数据库

CREATE DATABASE metrics
DROP DATABASE metrics
SHOW DATABASES

授权

GRANT READ ON DATABASE metrics TO alice
GRANT WRITE ON DATABASE metrics TO alice
GRANT ADMIN ON DATABASE * TO admin2
REVOKE ON DATABASE metrics FROM alice

查询用户、授权与 Token

SHOW USERS
SHOW GRANTS
SHOW GRANTS FOR alice
SHOW TOKENS
SHOW TOKENS FOR alice
ISSUE TOKEN FOR alice
REVOKE TOKEN 'tok_abcdef'

说明：

SHOW TOKENS 只返回 Token 元数据，不返回明文。
ISSUE TOKEN FOR ... 会在结果里一次性返回明文 Token。
REVOKE TOKEN 'tok_xxx' 按 token id 吊销。

HTTP 端点

端点	用途
`POST /v1/db/{db}/sql`	单条 SQL，主要用于数据面；admin 也可通过它执行部分控制面语句
`POST /v1/db/{db}/sql/batch`	批量 SQL 脚本
`POST /v1/sql`	专用控制面 SQL 端点，仅 admin

角色与权限

readonly：仅查询
readwrite：可写入和查询
admin：可管理数据库、执行控制面 SQL、进入完整管理能力

数据面 SQL

CREATE MEASUREMENT

INSERT INTO ... VALUES

原始查询 SELECT