第2章 QuestDB Schema 设计指南
timestamp TIMESTAMP,
symbol SYMBOL,
side SYMBOL,
price DOUBLE,
quantity DOUBLE
) TIMESTAMP(timestamp) PARTITION BY DAY;
关键要素说明: TIMESTAMP(timestamp) — 指定时间戳列(时序表必需) PARTITION BY DAY — 按天将数据分片,以提升查询效率 SYMBOL — 针对股票代码等类别数据优化的数据类型 指定时间戳 每张时序表都需要一个指定时间戳。该列的作用包括: 决定物理存储顺序(数据按此列排序) 启用分区剪枝(查询时跳过无关的时间范围) 支撑 SAMPLE BY 和 LATEST ON 等时序功能 CREATE TABLE market_data (
ts TIMESTAMP, -- 指定为时间戳列
symbol SYMBOL,
price DOUBLE
) TIMESTAMP(ts) PARTITION BY DAY;
若未指定时间戳,QuestDB 的大部分性能优势将无法发挥。 详情参见「指定时间戳」章节。 分区 分区功能将表数据切分为基于时间的块。请根据数据量选择分区粒度: 数据量 推荐分区 < 100K 行/天 MONTH 或 YEAR 100K - 10M 行/天 DAY 10M - 100M 行/天 HOUR > 100M 行/天 HOUR(考虑拆分为多张表) 分区建议: 单个分区大小宜控制在数百 MB 至数 GB 分区过小会导致过多的文件操作 分区过大则会拖慢查询速度并增加内存占用 -- 高频 Tick 数据
CREATE TABLE trades (...)
TIMESTAMP(ts) PARTITION BY HOUR;
-- 低频日终价格数据
CREATE TABLE eod_prices (...)
TIMESTAMP(ts) PARTITION BY MONTH;
详情参见「分区」章节。 乱序写入 QuestDB 支持以任意时间戳顺序接收数据。晚于已提交数据到达的行会自动合并至正确位置。这一过程会产生写放大,其成本取决于分区大小及数据延迟程度。 如果你的工作负载涉及延迟或重放数据(如交易所更正、Kafka 重放、传感器数据回填),请参阅「乱序数据」章节,了解不同摄取方式的行为及调优建议。 索引 对主要过滤列建立索引,可加速 WHERE 子句查询。QuestDB 针对 SYMBOL 列支持两种索引类型: -- 默认位图索引 —— 开销低,适用于大多数场景
CREATE TABLE trades (
ts TIMESTAMP,
symbol SYMBOL INDEX,
price DOUBLE
) TIMESTAMP(ts) PARTITION BY DAY;
-- 带覆盖列的倒排索引——最适合读多写少、筛选性强的查询
CREATE TABLE trades (
ts TIMESTAMP,
symbol SYMBOL INDEX TYPE POSTING INCLUDE (price),
price DOUBLE,
raw_data VARCHAR -- 不在 INCLUDE 中,从列文件读取
) TIMESTAMP(ts) PARTITION BY DAY;
-- 指定时间戳(ts)会自动包含在覆盖索引中。
何时选择哪种索引: 场景推荐通用、写多读少位图索引(INDEX)读多、按 symbol 筛选倒排索引(INDEX TYPE POSTING)频繁查询少数几列带 INCLUDE 的倒排索引宽表,查询只选部分列带 INCLUDE 的倒排索引——收益最大 覆盖索引(INCLUDE)允许只选取被覆盖列的查询直接从紧凑的伴生文件读取,而非完整的列文件。指定时间戳会自动包含在内,因此基于时间戳的筛选查询也能受益,无需显式列出。使用 EXPLAIN 可以验证你的查询是否使用了 CoveringIndex 执行计划。 详见索引和倒排索引。 数据类型 SYMBOL 与 VARCHAR 何时使用 SYMBOL: * 重复性高的字符串值(股票代码、国家代码、状态标记) * 去重后最多数千万个不同值 * 用于 WHERE 过滤或 GROUP BY 的列 何时使用 VARCHAR: * 唯一或高基数值(数亿个不同值) * 用户生成文本(评论、日志消息) * UUID(尽管 UUID 类型更优) 为何重要: * SYMBOL 使用字典编码(整数查找而非字符串比较) * 过滤更快、分组更快、存储更少 CREATE TABLE trades (
timestamp TIMESTAMP,
symbol SYMBOL, -- 股票代码:AAPL、GOOGL 等
side SYMBOL, -- BUY 或 SELL
price DOUBLE,
quantity DOUBLE
) TIMESTAMP(timestamp) PARTITION BY DAY;
详见 Symbol。 时间戳 QuestDB 将所有时间戳存储为 UTC,精度为微秒。 CREATE TABLE trades (
ts TIMESTAMP, -- 微秒精度(推荐)
exchange_ts TIMESTAMP_NS, -- 纳秒精度(如有需要)
symbol SYMBOL,
price DOUBLE
) TIMESTAMP(ts); 除非确实需要纳秒级精度,否则请使用 TIMESTAMP。关于查询时如何处理时区,请参见 Working with Timestamps and Timezones。
其他类型
类型 | 用途 VARCHAR | 自由文本字符串 DOUBLE / FLOAT | 浮点数 DECIMAL(precision, scale) | 精确小数(金融数据) LONG / INT / SHORT | 整数 BOOLEAN | 布尔标志 UUID | 唯一标识符(比 VARCHAR 更高效) IPv4 | IP 地址 BINARY | 二进制数据 ARRAY | N 维数组(如 DOUBLE[3][4]) 数值类型的存储大小: 类型 | 存储 | 范围 BYTE | 8 位 | -128 到 127 SHORT | 16 位 | -32,768 到 32,767 INT | 32 位 | -21 亿到 21 亿 LONG | 64 位 | ±9.2E18 FLOAT | 32 位 | 单精度 IEEE 754 DOUBLE | 64 位 | 双精度 IEEE 754 DECIMAL | 1-32 字节 | 大小随精度变化 选择能满足需求的最小类型,可以节省存储空间。数组和地理空间数据请参见 Data Types。STRING 与 VARCHAR
QuestDB 有两种字符串类型: 类型 | 编码 | 状态 VARCHAR | UTF-8 | 推荐 STRING | UTF-16 | 旧版,不推荐 新建表时请始终使用 VARCHAR。STRING 类型仅为了向后兼容而保留,效率较低。已有的 STRING 列表仍能正常工作,但建议在方便时迁移到 VARCHAR。去重
QuestDB 默认允许重复数据。如需强制唯一性,可以使用 DEDUP UPSERT KEYS:CREATE TABLE quotes (
timestamp TIMESTAMP,
symbol SYMBOL,
bid DOUBLE,
ask DOUBLE
) TIMESTAMP(timestamp) PARTITION BY DAY
DEDUP UPSERT KEYS(timestamp, symbol);
用 TTL 管理数据保留
QuestDB 不支持删除单行数据。可以使用 TTL 自动删除过期的分区:CREATE TABLE tick_data (
timestamp TIMESTAMP,
symbol SYMBOL,
price DOUBLE,
size LONG
) TIMESTAMP(timestamp) PARTITION BY DAY TTL 90 DAYS;
物化视图
对于频繁执行的聚合查询,可以用物化视图预先计算结果:CREATE MATERIALIZED VIEW ohlc_1h AS
SELECT
timestamp,
symbol,
first(price) as open,
max(price) as high,
min(price) as low,
last(price) as close,
sum(quantity) as volume
FROM trades
SAMPLE BY 1h;
SELECT * FROM trades
WHERE timestamp > dateadd('d', -7, now())
);
视图支持通过 DECLARE OVERRIDABLE 进行参数化: CREATE VIEW trades_above AS (
DECLARE OVERRIDABLE @min_price := 100
SELECT * FROM trades WHERE price >= @min_price
);
-- 查询时覆盖参数
DECLARE @min_price := 500 SELECT * FROM trades_above;
详情请参阅“视图”章节。 常见错误 使用 VARCHAR 存储分类数据 -- 错误:对重复值使用 VARCHAR
CREATE TABLE trades (
timestamp TIMESTAMP,
symbol VARCHAR, -- 过滤和分组速度慢
...
);
-- 正确:对分类数据使用 SYMBOL
CREATE TABLE trades (
timestamp TIMESTAMP,
symbol SYMBOL, -- 过滤和分组速度快
...
);
分区大小不当 -- 错误:高频数据使用按年分区
CREATE TABLE trades (...)
PARTITION BY YEAR; -- 分区将非常大
-- 正确:根据数据量调整分区大小
CREATE TABLE trades (...)
PARTITION BY HOUR;
忘记指定时间戳列 -- 错误:未指定时间戳列
CREATE TABLE trades (
ts TIMESTAMP,
price DOUBLE
);
-- 正确:显式指定时间戳列
CREATE TABLE trades (
ts TIMESTAMP,
price DOUBLE
) TIMESTAMP(ts);
模式变更 部分属性在表创建后无法更改: | 属性 | 可否修改 | | :--- | :--- | | 指定时间戳列 | 否 | | 分区策略 | 否 | | 新增列 | 是 | | 删除列 | 是 | | 重命名列 | 是 | | 更改列类型 | 受限 | 要修改不可变属性,需创建新表并迁移数据: -- 1. 使用期望的模式创建新表
CREATE TABLE trades_new (...) PARTITION BY HOUR;
-- 2. 复制数据
INSERT INTO trades_new SELECT * FROM trades;
-- 3. 替换表
DROP TABLE trades;
RENAME TABLE trades_new TO trades;
多租户 QuestDB 每个实例仅支持单个数据库。对于多租户应用,请利用表名前缀进行隔离: -- 客户端专属表
CREATE TABLE acme_trades (...);
CREATE TABLE globex_trades (...);
-- 环境和区域表
CREATE TABLE prod_us_trades (...);
CREATE TABLE prod_eu_trades (...);
CREATE TABLE staging_trades (...);
-- Asset class tables
CREATE TABLE equities_trades (...);
CREATE TABLE fx_trades (...);
CREATE TABLE crypto_trades (...);
命名规范: 使用一致的前缀:{client}_, {env}_{region}_, {asset_class}_ 名称保持小写并以下划线分隔 选择前缀粒度时,需考虑查询模式 借助 QuestDB Enterprise,可以执行按表粒度 的权限控制。 PostgreSQL 兼容性 QuestDB 支持 PostgreSQL 线协议, 因此大多数 PostgreSQL 客户端库都能直接使用。不过,QuestDB 并非 PostgreSQL: 不支持 PRIMARY KEY、FOREIGN KEY 或 NOT NULL 约束 系统目录的兼容性有限 部分 PostgreSQL 函数可能无法使用 从其他数据库迁移 PostgreSQL / TimescaleDB-- PostgreSQL
CREATE TABLE metrics (
timestamp TIMESTAMP PRIMARY KEY,
name VARCHAR(255) NOT NULL,
value DOUBLE PRECISION NOT NULL
);
INSERT INTO metrics VALUES (...)
ON CONFLICT (timestamp) DO UPDATE SET value = EXCLUDED.value;
-- QuestDB equivalent
CREATE TABLE metrics (
timestamp TIMESTAMP,
name SYMBOL,
value DOUBLE
) TIMESTAMP(timestamp) PARTITION BY DAY
DEDUP UPSERT KEYS(timestamp, name);
InfluxDB# InfluxDB line protocol
metrics,name=cpu,region=us value=0.64
-- QuestDB equivalent
CREATE TABLE metrics (
timestamp TIMESTAMP,
name SYMBOL,
region SYMBOL,
value DOUBLE
) TIMESTAMP(timestamp) PARTITION BY DAY;
ClickHouse-- ClickHouse
CREATE TABLE metrics (
timestamp DateTime,
name String,
value Float64
) ENGINE = ReplacingMergeTree
ORDER BY (name, timestamp);
-- QuestDB equivalent
CREATE TABLE metrics (
timestamp TIMESTAMP,
name SYMBOL,
value DOUBLE
) TIMESTAMP(timestamp) PARTITION BY DAY
DEDUP UPSERT KEYS(timestamp, name);
DuckDB-- DuckDB
CREATE TABLE metrics (
timestamp TIMESTAMP,
name VARCHAR,
value DOUBLE
);
-- QuestDB equivalent
CREATE TABLE metrics (
timestamp TIMESTAMP,
name SYMBOL, -- Use SYMBOL for repeated strings
value DOUBLE
) TIMESTAMP(timestamp) PARTITION BY DAY;
Schema 管理
对于 schema 迁移,QuestDB 支持 Flyway。
你也可以使用 ILP 自动建表来处理动态 schema,不过这种方式会采用默认设置。详情请参阅 ILP Overview。
下一步
Quick Start — 创建你的第一张表并运行查询
Capacity Planning — 为生产环境规划部署容量
Connect & Ingest — 向 QuestDB 导入数据
Materialized Views — 预先计算聚合结果,加速仪表盘展示