进阶 questdb.com 2026-10-13 06:17:07 · 31 阅读
第7章 QuestDB 核心概念:指定时间戳的深度解析
指定时间戳QuestDB 中的每张表都应该有指定时间戳。这一列定义了数据的时间轴,也是解锁 QuestDB 核心时序能力的关键,包括分区、时序 JOIN 和优化的区间扫描。没有指定时间戳的表只是一个普通的追加式存储——分区没了,时间范围查询不再高效,大部分时序 SQL 特性也无法使用。
核心要点
指定时间戳列定义了表的时间轴
数据按这一列物理排序,从而实现亚毫秒级的时间范围查询
解锁的能力:分区、SAMPLE BY、LATEST ON、ASOF JOIN、TTL、去重、复制
约束:不能为 NULL,建表后不能更改,也不能更新
没有它:无法分区,时间查询必须把所有数据加载进内存
为什么需要指定时间戳
传统数据库按插入顺序或主键存储行数据。当你查询“最近 5 分钟的数据”时,数据库必须扫描整张表来找到匹配的行——哪怕这些数据只占全表的 0.001%。
对时序负载来说,这样的效率是灾难性的。假设有一张 10 亿行、跨度 30 天的表,查询“最近一小时”应该只读约 140 万行,而不是 10 亿行。
QuestDB 用指定时间戳解决了这个问题:
| 问题 | 解决方案 |
|--------------------------------|--------------------------------|
| 数据散落在磁盘各处 | 数据按时间戳物理排序存储 |
| 时间查询必须扫描整表 | 二分查找直接定位到相关行 |
| 无法跳过无关数据 | 分区裁剪直接跳过整个时间范围 |
| 时序操作需要先排序 | 数据已预先排序,运行时零开销 |
指定时间戳不只是元数据——它从根本上改变了 QuestDB 存储和查询数据的方式。
性能影响
QuestDB 的查询引擎会充分利用指定时间戳:
时间戳条件优先执行——先于其他所有过滤条件
分区裁剪——时间范围之外的整个分区直接跳过,减少 I/O
分区内二分查找——无需扫描即可定位精确的行边界
定向列读取——只从磁盘读取其他列中相关的数据帧
结果是:只要带时间戳条件,无论表有多大,大多数查询都能在亚毫秒级完成。在数十亿行的表上查询“最近一小时”,和在几千行的表上查询一样快——只有匹配的行会被读取。
进阶:TICK 区间语法
对于复杂的时间模式,可以使用 TICK 语法,用单个表达式生成多次优化的区间扫描:
-- 一月份工作日的纽交所交易时段(22 个区间,一条查询)
SELECT * FROM trades
WHERE ts IN '[2024-01]T09:30@America/New_York#workday;6h30m';
-- 最近 5 个工作日开盘时段
SELECT * FROM trades
WHERE ts IN '[$today-5bd..$today-1bd]T09:30;1h';
每个生成的区间都采用相同的二分查找优化——复杂调度的查询速度与简单的时间范围查询相当。 工作原理 物理存储顺序 指定时间戳列后,QuestDB 会按照该列的值对所有行进行排序存储。当数据按时间顺序到达时,新数据可以高效追加。如果数据乱序到达,QuestDB 会重新排列数据以维持时间戳顺序。 无指定时间戳: 有指定时间戳:
(按插入顺序存储) (按时间排序存储)
┌─────────────────────────┐ ┌─────────────────────────┐
│ 行 1: 10:05:00 │ │ 行 1: 10:00:00 │
│ 行 2: 10:00:00 │ │ 行 2: 10:01:15 │
│ 行 3: 10:02:30 │ │ 行 3: 10:02:30 │
│ 行 4: 10:01:15 │ │ 行 4: 10:05:00 │
└─────────────────────────┘ └─────────────────────────┘
↓ ↓
查询 10:01-10:03 查询 10:01-10:03
必须扫描所有行 直接跳转到第 2-3 行
这种物理排序为后续所有优化奠定了基础。 分区分配 指定的时间戳决定了每行存储在哪个分区。QuestDB 利用时间戳值将行路由至基于时间的目录(小时、天、周、月或年分区)。 例如,使用按天分区时: 时间戳为 2024-01-15T10:30:00Z 的行进入 2024-01-15 分区 时间戳为 2024-01-16T08:00:00Z 的行进入 2024-01-16 分区 这种物理隔离使 QuestDB 在查询时能够跳过整个分区。 区间扫描优化 当对指定的时间戳列执行带时间过滤条件的查询时,QuestDB 执行区间扫描而非全表扫描: 分区裁剪:完全跳过时间范围之外的分区 二分查找:在相关分区内,使用二分查找确定精确的起止位置 顺序读取:仅读取边界内的行 -- 在对按天分区的 1 年表中执行此查询:
SELECT * FROM trades
WHERE timestamp > '2024-01-15' AND timestamp < '2024-01-16';
-- 跳过 364 个分区,在 1 个分区内进行二分查找
只读取匹配的行,而非整张表
使用 EXPLAIN 验证区间扫描: EXPLAIN SELECT * FROM trades WHERE timestamp IN '2024-01-15';
| 查询计划 |
|---------------------------------------------------------------|
| 数据框 |
| 行向前扫描 |
| 在 trades 表上进行区间向前扫描 | ← 发生了区间扫描!
| 区间: [("2024-01-15T00:00:00.000000Z", |
| "2024-01-15T23:59:59.999999Z")] |
如果你看到的是异步过滤(Async Filter)或全表扫描(Table scan)而非区间向前扫描, 说明该查询未使用指定的时间戳优化。 它带来的优势 指定时间戳(designated timestamp)可解锁以下功能: 查询功能: 功能 | 为何需要指定时间戳 | SAMPLE BY | 在排序数据上按时间桶聚合 | LATEST ON | 利用排序顺序查找最新行 | ASOF JOIN | 按最近时间戳匹配行 | WINDOW JOIN | 基于时间窗的表间连接 | 区间扫描 | 对排序数据进行二分查找以执行时间范围查询 存储与生命周期: 功能 | 为何需要指定时间戳 | 分区 | 将行路由至基于时间的分区 | TTL(时间生存期) | 根据数据年龄删除分区(需依赖分区) | 去重 | 利用排序顺序查找重叠时间戳,实现高效更新插入(upsert) | 物化视图 | 基于 SAMPLE BY 的视图会继承此要求 | 复制 | 需要 WAL(预写日志),而 WAL 又需要分区 未指定时间戳时的情况 未指定时间戳的表将失去上述所有能力。它们仅适用于数据操作期间的临时表。 能力 | 未指定时间戳时的表现 | 时间范围查询 | 必须将整个投影加载到内存中 | 分区 | 不可用——仅有一个分区 | 分层存储 | 不可用 | 复制 | 不可用 | ILP 摄取 | 无法使用 HTTP ILP 协议 备注 | 例外:静态查找表(如国家代码、货币映射)没有时间维度,不需要指定时间戳。 如何设置 在创建表时设置(推荐) 使用 TIMESTAMP(columnName) 子句: CREATE TABLE trades (
ts TIMESTAMP,
symbol SYMBOL,
price DOUBLE,
amount DOUBLE
) TIMESTAMP(ts) PARTITION BY DAY;
指定的 timestamp 列必须先在列定义中声明,之后才能在 TIMESTAMP() 子句中引用。 通过 InfluxDB Line Protocol 通过 ILP 自动创建的表会包含一个 timestamp 列作为指定 timestamp,并默认按天分区: trades,symbol=BTC-USD price=50000,amount=1.5 1234567890000000000
└── 自动创建表并指定 timestamp
在查询结果上(动态 timestamp) 对于丢失了指定 timestamp 的查询(参见 Troubleshooting),可以使用 TIMESTAMP() 关键字将其恢复: SELECT * FROM (
SELECT ts, symbol, price FROM trades
UNION ALL
SELECT ts, symbol, price FROM trades_archive
ORDER BY ts
) TIMESTAMP(ts);
warning 只有当数据确实按该列排序时,动态 TIMESTAMP() 才有效。如果数据本身无序,查询结果将是错误的。对于可能无序的数据,在应用 TIMESTAMP() 之前务必先加上 ORDER BY。 属性 Property Value 可用列类型 TIMESTAMP(微秒)或 TIMESTAMP_NS(纳秒) 每张表的列数 恰好一列(或没有) NULL 值 不允许 可变性 表创建后不可更改 可更新性 不能用 UPDATE 修改 Timestamp 精度 QuestDB 支持两种 timestamp 精度: Type Resolution Precision Use case TIMESTAMP 微秒 10⁻⁶ s 大多数应用 TIMESTAMP_NS 纳秒 10⁻⁹ s 高频交易、科学数据 除非确实需要纳秒级精度,否则请使用 TIMESTAMP。两种类型在所有时序功能上表现完全一致。 更多 timestamp 处理的细节,参见 Timestamps and time zones。 限制 表创建后不可更改 指定 timestamp 在 CREATE TABLE 时设置,之后无法修改。如果想换用其他列: -- 1. 创建新表,指定正确的 timestamp
CREATE TABLE trades_new (
event_time TIMESTAMP, -- 新的指定 timestamp
ingest_time TIMESTAMP,
symbol SYMBOL,
price DOUBLE
) TIMESTAMP(event_time) PARTITION BY DAY;
-- 2. 复制数据(会按新的指定 timestamp 重新排序)
INSERT INTO trades_new
SELECT event_time, ingest_time, symbol, price
FROM trades
ORDER BY event_time;
-- 3. 替换表
DROP TABLE trades;
RENAME TABLE trades_new TO trades;
对于包含数十亿行的大表,此迁移操作会占用大量时间和磁盘空间。请提前规划: - 为两张表预留充足的临时磁盘空间 - 应用停机或双写窗口期 - 迁移后的数据校验 不可为 NULL 每一行必须具有有效的时间戳值,指定的时间戳列不能包含 NULL。 如果源数据中缺少时间戳: - 插入前过滤掉 NULL 行 - 使用默认值或哨兵值(例如 '1970-01-01T00:00:00Z') - 改用其他列作为指定时间戳 不可更新 不能使用 UPDATE 语句修改指定的时间戳列: -- This will fail:
UPDATE trades SET ts = '2024-01-15T12:00:00Z' WHERE symbol = 'BTC-USD';
-- Error: Designated timestamp column cannot be updated
为什么?更新时间戳需要在分区内重新排序行,甚至可能在分区之间移动行,这会破坏 QuestDB 的追加优化存储模型。 变通方案:将数据复制到临时表,修改后再重新插入: -- 1. Create temp table WITHOUT designated timestamp
-- Copy the partition(s) containing rows you need to modify
CREATE TABLE trades_temp AS (
SELECT * FROM trades
WHERE ts IN '2024-01-15'
);
-- 2. Drop the partition from the source table
ALTER TABLE trades DROP PARTITION LIST '2024-01-15';
-- 3. Update timestamps freely in the temp table (no designated timestamp)
UPDATE trades_temp
SET ts = dateadd('h', 1, ts)
WHERE symbol = 'BTC-USD';
-- 4. Re-insert into main table (data will be sorted automatically)
INSERT INTO trades SELECT * FROM trades_temp;
-- 5. Clean up
DROP TABLE trades_temp;
对于预期会出现重复键的持续校正工作流,建议改用带 UPSERT KEYS 的去重功能。 每张表仅有一个指定时间戳 虽然一张表可以拥有多个 TIMESTAMP 列,但只能指定其中一个作为基准时间戳: CREATE TABLE orders (
exchange_ts TIMESTAMP, -- designated timestamp (when exchange received)
gateway_ts TIMESTAMP, -- when our gateway received
ack_ts TIMESTAMP, -- when exchange acknowledged
symbol SYMBOL,
side SYMBOL,
qty DOUBLE
) TIMESTAMP(exchange_ts) PARTITION BY DAY;
在 WHERE 子句中,请选出你最高频使用的过滤列。 最佳实践 选择合适的列 如果你的数据包含多个时间戳列: | 列类型 | 示例 | 推荐度 | |---|---|---| | 事件时间 | 交易执行时刻 | ✅ 最佳选择 | | 摄入时间 | QuestDB 接收数据的时刻 | ⚠️ 仅在无事件时间时使用 | | 处理时间 | 下游系统处理完成的时刻 | ❌ 很少适用 | 经验法则:请选择符合以下条件的时间戳: * 在查询中最常被用于过滤 * 代表事件实际发生的时间 * 分布最为均匀 常见疑问 重复时间戳:允许时间戳值重复,多行数据可以拥有相同的指定时间戳。若需保证唯一性,请启用 UPSERT KEYS 进行去重。 未来时间戳与 TTL:若使用 TTL 进行自动数据保留,请留意未来时间戳。默认情况下,TTL 以系统实际时间(wall-clock time)为基准,以防因过远的未来时间戳导致数据误删。详情参见 TTL 文档。 时区:所有时间戳内部均存储为 UTC。当你带时区执行查询(如 `SAMPLE BY 1d ALIGN TO CALENDAR TIME ZONE 'Europe/London'`)时,QuestDB 会将指定时区转换为 UTC 进行搜索,随后再将结果转回原时区。源数据理想状态下应为 UTC;若不然,请在摄入时使用 `to_utc()`。 多个时间戳列 将额外时间戳保留为普通列: CREATE TABLE quotes (
exchange_ts TIMESTAMP, -- 交易所发布时间(指定列)
received_ts TIMESTAMP, -- 本地接收时间
symbol SYMBOL,
bid DOUBLE,
ask DOUBLE
) TIMESTAMP(exchange_ts) PARTITION BY DAY;
-- 按交易所时间查询(使用区间扫描):
SELECT * FROM quotes
WHERE exchange_ts > dateadd('h', -1, now());
-- 按接收时间查询(全表扫描,但仍有效):
SELECT * FROM quotes
WHERE received_ts > dateadd('h', -1, now());
乱序数据 QuestDB 会自动接收乱序数据,代价是写放大,其程度取决于分区大小以及数据延迟到达的时间长短。 不同写入方式下的行为、调优方法和常见场景,请参阅 Out-of-order data。 分区大小对齐 分区间隔应与指定时间戳的数据分布相匹配: 数据量 分区间隔 每天 < 10 万行 MONTH 或 YEAR 每天 10 万 - 1000 万行 DAY 每天 1000 万 - 1 亿行 HOUR 每天 > 1 亿行 HOUR 详细指导请参阅 Partitions。 故障排查 某些 SQL 操作的结果集没有指定时间戳,这会导致 SAMPLE BY 等时序功能失效。 会丢失指定时间戳的操作 操作 原因 解决方案 UNION / UNION ALL 合并后的结果不保证有序 先 ORDER BY 再用 TIMESTAMP() 子查询 派生表会丢失表的元数据 对子查询应用 TIMESTAMP() read_parquet() 外部文件没有 QuestDB 元数据 先 ORDER BY 再用 TIMESTAMP() 类型转换 ts::STRING::TIMESTAMP 会丢失时间戳标记 避免往返转换 某些表达式 计算出的时间戳不是指定时间戳 对结果使用 TIMESTAMP() 如何恢复 对有序数据使用 TIMESTAMP() 关键字: -- UNION 会丢失指定时间戳 -- 解决方案:先 ORDER BY,再应用 TIMESTAMP() SELECT * FROM ( SELECT ts, symbol, price FROM trades_2023 UNION ALL SELECT ts, symbol, price FROM trades_2024 ORDER BY ts ) TIMESTAMP(ts) SAMPLE BY 1h; -- Parquet 文件没有指定时间戳 -- 解决方案:先 ORDER BY,再应用 TIMESTAMP() SELECT timestamp, avg(price) FROM ( (SELECT * FROM read_parquet('trades.parquet') ORDER BY timestamp) TIMESTAMP(timestamp) ) SAMPLE BY 1m; -- 子查询会丢失指定时间戳 -- 解决方案:对子查询结果应用 TIMESTAMP() WITH recent AS ( (SELECT * FROM trades WHERE timestamp > dateadd('d', -7, now())) TIMESTAMP(timestamp) ) SELECT * FROM recent SAMPLE BY 1h; 验证指定时间戳 检查表是否有指定时间戳: SELECT table_name, designatedTimestamp FROM tables() WHERE table_name = 'trades'; table_name designatedTimestamp trades ts 查看列详情: SELECT "column", type, designated FROM table_columns('trades'); column type designated ts TIMESTAMP true symbol SYMBOL false price DOUBLE false 检查查询是否使用了区间扫描优化: EXPLAIN SELECT * FROM trades WHERE timestamp IN '2024-01-15'; 检查 Interval 前向扫描——如果看到 Async Filter,说明没有使用 designated timestamp 优化。 确认没有 designated timestamp 的表是否有序: 没有 designated timestamp 的表没有排序保证。由于无法事后添加 designated timestamp,在将数据迁移到有 designated timestamp 的表之前,请先测试 timestamp 列是否已升序排列。参见“检查 timestamp 顺序”食谱。 常见问题 能否为现有表添加 designated timestamp? 不能。designated timestamp 必须在建表时定义。若要添加,需创建带 designated timestamp 的新表并迁移数据。 插入 NULL timestamp 会发生什么? 插入会失败。designated timestamp 列不能包含 NULL 值。 能否拥有两个 designated timestamp? 不能。每张表最多只能有一个 designated timestamp。其他时间值请使用额外的 TIMESTAMP 列。 乱序数据会出问题吗? 不会。QuestDB 会自动将乱序数据合并到正确的排序位置。但过多的乱序数据会增加写放大。 designated timestamp 等同于主键吗? 不等同。designated timestamp: 不强制唯一性(去重需用 deduplication) 决定物理存储顺序 不可更新 可选使用(但强烈推荐设置) 为什么不能 UPDATE designated timestamp? 更新 timestamp 需要重新排序行,并可能使行在分区间移动,这会破坏 QuestDB 的追加优化存储模型。请改用删除后重新插入,或使用 deduplication 进行修正。 另请参阅 CREATE TABLE——建表的完整语法 Partitions——基于时间的数据组织 Interval scan——查询优化细节 TICK intervals——单个表达式内的复杂时间模式 SAMPLE BY——基于时间的聚合 LATEST ON——查找最新记录 Timestamps and time zones——处理时间值
SELECT * FROM trades
WHERE ts IN '[2024-01]T09:30@America/New_York#workday;6h30m';
-- 最近 5 个工作日开盘时段
SELECT * FROM trades
WHERE ts IN '[$today-5bd..$today-1bd]T09:30;1h';
每个生成的区间都采用相同的二分查找优化——复杂调度的查询速度与简单的时间范围查询相当。 工作原理 物理存储顺序 指定时间戳列后,QuestDB 会按照该列的值对所有行进行排序存储。当数据按时间顺序到达时,新数据可以高效追加。如果数据乱序到达,QuestDB 会重新排列数据以维持时间戳顺序。 无指定时间戳: 有指定时间戳:
(按插入顺序存储) (按时间排序存储)
┌─────────────────────────┐ ┌─────────────────────────┐
│ 行 1: 10:05:00 │ │ 行 1: 10:00:00 │
│ 行 2: 10:00:00 │ │ 行 2: 10:01:15 │
│ 行 3: 10:02:30 │ │ 行 3: 10:02:30 │
│ 行 4: 10:01:15 │ │ 行 4: 10:05:00 │
└─────────────────────────┘ └─────────────────────────┘
↓ ↓
查询 10:01-10:03 查询 10:01-10:03
必须扫描所有行 直接跳转到第 2-3 行
这种物理排序为后续所有优化奠定了基础。 分区分配 指定的时间戳决定了每行存储在哪个分区。QuestDB 利用时间戳值将行路由至基于时间的目录(小时、天、周、月或年分区)。 例如,使用按天分区时: 时间戳为 2024-01-15T10:30:00Z 的行进入 2024-01-15 分区 时间戳为 2024-01-16T08:00:00Z 的行进入 2024-01-16 分区 这种物理隔离使 QuestDB 在查询时能够跳过整个分区。 区间扫描优化 当对指定的时间戳列执行带时间过滤条件的查询时,QuestDB 执行区间扫描而非全表扫描: 分区裁剪:完全跳过时间范围之外的分区 二分查找:在相关分区内,使用二分查找确定精确的起止位置 顺序读取:仅读取边界内的行 -- 在对按天分区的 1 年表中执行此查询:
SELECT * FROM trades
WHERE timestamp > '2024-01-15' AND timestamp < '2024-01-16';
-- 跳过 364 个分区,在 1 个分区内进行二分查找
只读取匹配的行,而非整张表
使用 EXPLAIN 验证区间扫描: EXPLAIN SELECT * FROM trades WHERE timestamp IN '2024-01-15';
| 查询计划 |
|---------------------------------------------------------------|
| 数据框 |
| 行向前扫描 |
| 在 trades 表上进行区间向前扫描 | ← 发生了区间扫描!
| 区间: [("2024-01-15T00:00:00.000000Z", |
| "2024-01-15T23:59:59.999999Z")] |
如果你看到的是异步过滤(Async Filter)或全表扫描(Table scan)而非区间向前扫描, 说明该查询未使用指定的时间戳优化。 它带来的优势 指定时间戳(designated timestamp)可解锁以下功能: 查询功能: 功能 | 为何需要指定时间戳 | SAMPLE BY | 在排序数据上按时间桶聚合 | LATEST ON | 利用排序顺序查找最新行 | ASOF JOIN | 按最近时间戳匹配行 | WINDOW JOIN | 基于时间窗的表间连接 | 区间扫描 | 对排序数据进行二分查找以执行时间范围查询 存储与生命周期: 功能 | 为何需要指定时间戳 | 分区 | 将行路由至基于时间的分区 | TTL(时间生存期) | 根据数据年龄删除分区(需依赖分区) | 去重 | 利用排序顺序查找重叠时间戳,实现高效更新插入(upsert) | 物化视图 | 基于 SAMPLE BY 的视图会继承此要求 | 复制 | 需要 WAL(预写日志),而 WAL 又需要分区 未指定时间戳时的情况 未指定时间戳的表将失去上述所有能力。它们仅适用于数据操作期间的临时表。 能力 | 未指定时间戳时的表现 | 时间范围查询 | 必须将整个投影加载到内存中 | 分区 | 不可用——仅有一个分区 | 分层存储 | 不可用 | 复制 | 不可用 | ILP 摄取 | 无法使用 HTTP ILP 协议 备注 | 例外:静态查找表(如国家代码、货币映射)没有时间维度,不需要指定时间戳。 如何设置 在创建表时设置(推荐) 使用 TIMESTAMP(columnName) 子句: CREATE TABLE trades (
ts TIMESTAMP,
symbol SYMBOL,
price DOUBLE,
amount DOUBLE
) TIMESTAMP(ts) PARTITION BY DAY;
指定的 timestamp 列必须先在列定义中声明,之后才能在 TIMESTAMP() 子句中引用。 通过 InfluxDB Line Protocol 通过 ILP 自动创建的表会包含一个 timestamp 列作为指定 timestamp,并默认按天分区: trades,symbol=BTC-USD price=50000,amount=1.5 1234567890000000000
└── 自动创建表并指定 timestamp
在查询结果上(动态 timestamp) 对于丢失了指定 timestamp 的查询(参见 Troubleshooting),可以使用 TIMESTAMP() 关键字将其恢复: SELECT * FROM (
SELECT ts, symbol, price FROM trades
UNION ALL
SELECT ts, symbol, price FROM trades_archive
ORDER BY ts
) TIMESTAMP(ts);
warning 只有当数据确实按该列排序时,动态 TIMESTAMP() 才有效。如果数据本身无序,查询结果将是错误的。对于可能无序的数据,在应用 TIMESTAMP() 之前务必先加上 ORDER BY。 属性 Property Value 可用列类型 TIMESTAMP(微秒)或 TIMESTAMP_NS(纳秒) 每张表的列数 恰好一列(或没有) NULL 值 不允许 可变性 表创建后不可更改 可更新性 不能用 UPDATE 修改 Timestamp 精度 QuestDB 支持两种 timestamp 精度: Type Resolution Precision Use case TIMESTAMP 微秒 10⁻⁶ s 大多数应用 TIMESTAMP_NS 纳秒 10⁻⁹ s 高频交易、科学数据 除非确实需要纳秒级精度,否则请使用 TIMESTAMP。两种类型在所有时序功能上表现完全一致。 更多 timestamp 处理的细节,参见 Timestamps and time zones。 限制 表创建后不可更改 指定 timestamp 在 CREATE TABLE 时设置,之后无法修改。如果想换用其他列: -- 1. 创建新表,指定正确的 timestamp
CREATE TABLE trades_new (
event_time TIMESTAMP, -- 新的指定 timestamp
ingest_time TIMESTAMP,
symbol SYMBOL,
price DOUBLE
) TIMESTAMP(event_time) PARTITION BY DAY;
-- 2. 复制数据(会按新的指定 timestamp 重新排序)
INSERT INTO trades_new
SELECT event_time, ingest_time, symbol, price
FROM trades
ORDER BY event_time;
-- 3. 替换表
DROP TABLE trades;
RENAME TABLE trades_new TO trades;
对于包含数十亿行的大表,此迁移操作会占用大量时间和磁盘空间。请提前规划: - 为两张表预留充足的临时磁盘空间 - 应用停机或双写窗口期 - 迁移后的数据校验 不可为 NULL 每一行必须具有有效的时间戳值,指定的时间戳列不能包含 NULL。 如果源数据中缺少时间戳: - 插入前过滤掉 NULL 行 - 使用默认值或哨兵值(例如 '1970-01-01T00:00:00Z') - 改用其他列作为指定时间戳 不可更新 不能使用 UPDATE 语句修改指定的时间戳列: -- This will fail:
UPDATE trades SET ts = '2024-01-15T12:00:00Z' WHERE symbol = 'BTC-USD';
-- Error: Designated timestamp column cannot be updated
为什么?更新时间戳需要在分区内重新排序行,甚至可能在分区之间移动行,这会破坏 QuestDB 的追加优化存储模型。 变通方案:将数据复制到临时表,修改后再重新插入: -- 1. Create temp table WITHOUT designated timestamp
-- Copy the partition(s) containing rows you need to modify
CREATE TABLE trades_temp AS (
SELECT * FROM trades
WHERE ts IN '2024-01-15'
);
-- 2. Drop the partition from the source table
ALTER TABLE trades DROP PARTITION LIST '2024-01-15';
-- 3. Update timestamps freely in the temp table (no designated timestamp)
UPDATE trades_temp
SET ts = dateadd('h', 1, ts)
WHERE symbol = 'BTC-USD';
-- 4. Re-insert into main table (data will be sorted automatically)
INSERT INTO trades SELECT * FROM trades_temp;
-- 5. Clean up
DROP TABLE trades_temp;
对于预期会出现重复键的持续校正工作流,建议改用带 UPSERT KEYS 的去重功能。 每张表仅有一个指定时间戳 虽然一张表可以拥有多个 TIMESTAMP 列,但只能指定其中一个作为基准时间戳: CREATE TABLE orders (
exchange_ts TIMESTAMP, -- designated timestamp (when exchange received)
gateway_ts TIMESTAMP, -- when our gateway received
ack_ts TIMESTAMP, -- when exchange acknowledged
symbol SYMBOL,
side SYMBOL,
qty DOUBLE
) TIMESTAMP(exchange_ts) PARTITION BY DAY;
在 WHERE 子句中,请选出你最高频使用的过滤列。 最佳实践 选择合适的列 如果你的数据包含多个时间戳列: | 列类型 | 示例 | 推荐度 | |---|---|---| | 事件时间 | 交易执行时刻 | ✅ 最佳选择 | | 摄入时间 | QuestDB 接收数据的时刻 | ⚠️ 仅在无事件时间时使用 | | 处理时间 | 下游系统处理完成的时刻 | ❌ 很少适用 | 经验法则:请选择符合以下条件的时间戳: * 在查询中最常被用于过滤 * 代表事件实际发生的时间 * 分布最为均匀 常见疑问 重复时间戳:允许时间戳值重复,多行数据可以拥有相同的指定时间戳。若需保证唯一性,请启用 UPSERT KEYS 进行去重。 未来时间戳与 TTL:若使用 TTL 进行自动数据保留,请留意未来时间戳。默认情况下,TTL 以系统实际时间(wall-clock time)为基准,以防因过远的未来时间戳导致数据误删。详情参见 TTL 文档。 时区:所有时间戳内部均存储为 UTC。当你带时区执行查询(如 `SAMPLE BY 1d ALIGN TO CALENDAR TIME ZONE 'Europe/London'`)时,QuestDB 会将指定时区转换为 UTC 进行搜索,随后再将结果转回原时区。源数据理想状态下应为 UTC;若不然,请在摄入时使用 `to_utc()`。 多个时间戳列 将额外时间戳保留为普通列: CREATE TABLE quotes (
exchange_ts TIMESTAMP, -- 交易所发布时间(指定列)
received_ts TIMESTAMP, -- 本地接收时间
symbol SYMBOL,
bid DOUBLE,
ask DOUBLE
) TIMESTAMP(exchange_ts) PARTITION BY DAY;
-- 按交易所时间查询(使用区间扫描):
SELECT * FROM quotes
WHERE exchange_ts > dateadd('h', -1, now());
-- 按接收时间查询(全表扫描,但仍有效):
SELECT * FROM quotes
WHERE received_ts > dateadd('h', -1, now());
乱序数据 QuestDB 会自动接收乱序数据,代价是写放大,其程度取决于分区大小以及数据延迟到达的时间长短。 不同写入方式下的行为、调优方法和常见场景,请参阅 Out-of-order data。 分区大小对齐 分区间隔应与指定时间戳的数据分布相匹配: 数据量 分区间隔 每天 < 10 万行 MONTH 或 YEAR 每天 10 万 - 1000 万行 DAY 每天 1000 万 - 1 亿行 HOUR 每天 > 1 亿行 HOUR 详细指导请参阅 Partitions。 故障排查 某些 SQL 操作的结果集没有指定时间戳,这会导致 SAMPLE BY 等时序功能失效。 会丢失指定时间戳的操作 操作 原因 解决方案 UNION / UNION ALL 合并后的结果不保证有序 先 ORDER BY 再用 TIMESTAMP() 子查询 派生表会丢失表的元数据 对子查询应用 TIMESTAMP() read_parquet() 外部文件没有 QuestDB 元数据 先 ORDER BY 再用 TIMESTAMP() 类型转换 ts::STRING::TIMESTAMP 会丢失时间戳标记 避免往返转换 某些表达式 计算出的时间戳不是指定时间戳 对结果使用 TIMESTAMP() 如何恢复 对有序数据使用 TIMESTAMP() 关键字: -- UNION 会丢失指定时间戳 -- 解决方案:先 ORDER BY,再应用 TIMESTAMP() SELECT * FROM ( SELECT ts, symbol, price FROM trades_2023 UNION ALL SELECT ts, symbol, price FROM trades_2024 ORDER BY ts ) TIMESTAMP(ts) SAMPLE BY 1h; -- Parquet 文件没有指定时间戳 -- 解决方案:先 ORDER BY,再应用 TIMESTAMP() SELECT timestamp, avg(price) FROM ( (SELECT * FROM read_parquet('trades.parquet') ORDER BY timestamp) TIMESTAMP(timestamp) ) SAMPLE BY 1m; -- 子查询会丢失指定时间戳 -- 解决方案:对子查询结果应用 TIMESTAMP() WITH recent AS ( (SELECT * FROM trades WHERE timestamp > dateadd('d', -7, now())) TIMESTAMP(timestamp) ) SELECT * FROM recent SAMPLE BY 1h; 验证指定时间戳 检查表是否有指定时间戳: SELECT table_name, designatedTimestamp FROM tables() WHERE table_name = 'trades'; table_name designatedTimestamp trades ts 查看列详情: SELECT "column", type, designated FROM table_columns('trades'); column type designated ts TIMESTAMP true symbol SYMBOL false price DOUBLE false 检查查询是否使用了区间扫描优化: EXPLAIN SELECT * FROM trades WHERE timestamp IN '2024-01-15'; 检查 Interval 前向扫描——如果看到 Async Filter,说明没有使用 designated timestamp 优化。 确认没有 designated timestamp 的表是否有序: 没有 designated timestamp 的表没有排序保证。由于无法事后添加 designated timestamp,在将数据迁移到有 designated timestamp 的表之前,请先测试 timestamp 列是否已升序排列。参见“检查 timestamp 顺序”食谱。 常见问题 能否为现有表添加 designated timestamp? 不能。designated timestamp 必须在建表时定义。若要添加,需创建带 designated timestamp 的新表并迁移数据。 插入 NULL timestamp 会发生什么? 插入会失败。designated timestamp 列不能包含 NULL 值。 能否拥有两个 designated timestamp? 不能。每张表最多只能有一个 designated timestamp。其他时间值请使用额外的 TIMESTAMP 列。 乱序数据会出问题吗? 不会。QuestDB 会自动将乱序数据合并到正确的排序位置。但过多的乱序数据会增加写放大。 designated timestamp 等同于主键吗? 不等同。designated timestamp: 不强制唯一性(去重需用 deduplication) 决定物理存储顺序 不可更新 可选使用(但强烈推荐设置) 为什么不能 UPDATE designated timestamp? 更新 timestamp 需要重新排序行,并可能使行在分区间移动,这会破坏 QuestDB 的追加优化存储模型。请改用删除后重新插入,或使用 deduplication 进行修正。 另请参阅 CREATE TABLE——建表的完整语法 Partitions——基于时间的数据组织 Interval scan——查询优化细节 TICK intervals——单个表达式内的复杂时间模式 SAMPLE BY——基于时间的聚合 LATEST ON——查找最新记录 Timestamps and time zones——处理时间值