进阶 questdb.com 2026-10-13 06:17:07 · 32 阅读
第16章 故障排除
FAQ
本文档汇总了运行 QuestDB 时常见的硬件和软件配置问题及其解决方案。如果在其中找不到答案,请前往我们的社区论坛提问。
日志在哪里?如何过滤日志信息?
日志文件存储在根目录下的 `log` 文件夹中。日志支持以下级别,便于过滤:
请查阅日志页面以了解可用的日志级别。
如何删除某一行?
请参阅我们的数据修改指南。
如何将 STRING 列迁移为 VARCHAR?
可以通过 `ALTER COLUMN TYPE` SQL 命令将列类型从 STRING 更改为 VARCHAR。这两种列类型完全兼容,转换过程无损。VARCHAR 列类型最多可将存储大小减少 2 倍。因此,我们强烈建议将所有 STRING 列迁移为 VARCHAR:
```sql
ALTER TABLE my_table ALTER COLUMN str_col TYPE VARCHAR;
```
详情请参见 ALTER TABLE COLUMN TYPE 文档。
如何将 VARCHAR 列转换为 SYMBOL,或反之?
可以将列类型从 VARCHAR 更改为 SYMBOL。当列中包含的重复值数量有限时,我们建议将其转换为 SYMBOL 类型:
```sql
ALTER TABLE my_table ALTER COLUMN var_col TYPE SYMBOL CAPACITY 4096;
```
详情请参见 ALTER TABLE COLUMN TYPE 文档。
设置 SYMBOL 的容量是可选的,但这样做可以优化转换过程和数据插入的性能。Symbol 容量会根据需要自动扩展。欲了解更多信息,请参阅 SYMBOL 文档。
为什么通过 PostgreSQL 协议插入数据时会收到 table busy 错误信息?
在同一张表上并发执行 INSERT 语句时,可能会收到 `table busy [reason=insert]` 或类似的错误。这意味着该表被另一个 SQL 连接或其他客户端协议(如通过 TCP 的 InfluxDB Line Protocol 或通过 HTTP 的 CSV)锁定了,因为正在进行数据导入。
为避免此错误,我们建议使用 WAL 表以允许通过所有接口并发写入。
创建表或插入行时为什么会出现 "could not open read-write" 消息?
日志消息可能如下所示:
```
2022-02-01T13:40:11.336011Z I i.q.c.l.t.LineTcpMeasurementScheduler could not create table [tableName=cpu, ex=could not open read-write...
io.questdb.cairo.CairoException: [24] could not open read-only [file=/root/.questdb/db/cpu/service.k]
```
机器对最大打开文件数的限制可能不够。可以检查机器上的 ulimit 值,详情请参考容量规划页面。
为什么服务器日志里会出现 errno=12 mmap 消息?
日志消息可能类似下面这样:
2022-02-01T13:40:10.636014Z E i.q.c.l.t.LineTcpConnectionContext [8655] could not process line data [table=test_table, msg=could not mmap [size=248, offset=0, fd=1766, memUsed=314809894008, fileLen=8192], errno=12]
机器对进程可用的内存映射区域数量限制可能不足。可以检查并调大机器上的 vm.max_map_count 值,详情请参考容量规划页面。 为什么删除分区时会看到 async command/event queue buffer overflow 消息? 可能是你要执行的 DROP PARTITION 语句需要删除大量分区,超出了服务器内部队列的容量。可以尝试调大 cairo.writer.command.queue.slot.size 的值。该参数默认为 2K(即 2KB),你可能需要设置更大的值,比如 32K。 如何避免字段完全相同的重复行? 我们有一个开放的功能请求,希望支持对字段完全相同的插入行进行可选去重。在该功能实现之前,你需要在数据插入后对其进行处理,并使用 GROUP BY 查询来识别重复项。 可以按时间查询吗? 可以!使用 WHERE 语句定义查询时间范围时,IN 关键字可以修改搜索的范围和间隔,范围可以精确到秒。 例如,下面的查询搜索从 2000 年 1 月 1 日起、共 365 天内每天 9:15 到 16:00(含端点)的记录。原始时间戳 2000-01-01T09:15 被延长 405 分钟来覆盖该范围,然后每天重复一次、共重复 365 次: SELECT timestamp, col1
FROM 'table1'
WHERE timestamp IN '2000-01-01T09:15;405m;1d;365';
时间或时区不正确 如果你使用的是 PostgreSQL 客户端,例如 NodeJS 客户端,可能会遇到时间戳不匹配的情况。PG 库的数据类型文档中写道: node-postgres 会将 JavaScript 的 Date 对象实例转换为 PostgreSQL 服务器期望的输入值。同样,当将 date、timestamp 或 timestamptz 列的值读回 JavaScript 时,node-postgres 会将其解析为 JavaScript Date 对象的实例。 最关键的一点是: node-postgres 将 DATE 和 TIMESTAMP 列转换为 node 进程的本地时间,该时间由 process.env.TZ 设定。 因此,你可能需要在 .env 文件中添加: TZ=UTC 建议作者使用 TIMESTAMPTZ 类型。存储 TIMESTAMPTZ 值时,PostgreSQL 会将其转换为 UTC 时间;读取时,PostgreSQL 会再将其从 UTC 转换回客户端系统设置时区的时间。这种机制确保了无论客户端处于何种时区,时间戳都能被正确解读。 相比之下,TIMESTAMP(无时区时间戳)不存储任何时区信息,仅记录日期和时间。如果不同地区的客户端读取 TIMESTAMP 值,他们可能会误以为该值对应本地时区,从而导致错误结果。 因此,如果应用需要处理跨时区的时间数据,通常首选 TIMESTAMPTZ。它能确保无论用户身在何处,时间戳都能被准确解读。 为什么日志中会出现 “cannot delete file, will retry”? 如果在 Windows 上运行,建议禁用 Windows Defender。Windows Defender 会扫描每一个新建文件。若文件正在被扫描,则无法删除。因此,QuestDB 创建文件后,Windows Defender 开始扫描,当 QuestDB 试图清理时,这些正在被扫描的文件无法被删除。 如何修复 “DatabaseError: unexpected token: CURSOR”?此查询在 PostgreSQL 中是正常的! QuestDB 不支持需要通过 DECLARE CURSOR 显式创建和管理的可滚动游标,也不支持后续的 FETCH 操作。 相反,QuestDB 支持不可滚动的“仅向前”游标。这意味着虽然可以按顺序遍历查询结果,但无法像 PostgreSQL 中的可滚动游标那样反向导航或随机访问结果位置。 更多信息及规避建议,请参阅《查询与 SQL 概览》中的 PostgreSQL 兼容性章节。 我的表因之前的磁盘写满或内核限制错误导致 WAL 数据损坏,该怎么办? 你需要使用 RESUME WAL SQL 语句跳过存在问题的事务。如果有多个事务依赖于损坏的 WAL 数据,可能需要多次执行该操作。
机器对进程可用的内存映射区域数量限制可能不足。可以检查并调大机器上的 vm.max_map_count 值,详情请参考容量规划页面。 为什么删除分区时会看到 async command/event queue buffer overflow 消息? 可能是你要执行的 DROP PARTITION 语句需要删除大量分区,超出了服务器内部队列的容量。可以尝试调大 cairo.writer.command.queue.slot.size 的值。该参数默认为 2K(即 2KB),你可能需要设置更大的值,比如 32K。 如何避免字段完全相同的重复行? 我们有一个开放的功能请求,希望支持对字段完全相同的插入行进行可选去重。在该功能实现之前,你需要在数据插入后对其进行处理,并使用 GROUP BY 查询来识别重复项。 可以按时间查询吗? 可以!使用 WHERE 语句定义查询时间范围时,IN 关键字可以修改搜索的范围和间隔,范围可以精确到秒。 例如,下面的查询搜索从 2000 年 1 月 1 日起、共 365 天内每天 9:15 到 16:00(含端点)的记录。原始时间戳 2000-01-01T09:15 被延长 405 分钟来覆盖该范围,然后每天重复一次、共重复 365 次: SELECT timestamp, col1
FROM 'table1'
WHERE timestamp IN '2000-01-01T09:15;405m;1d;365';
时间或时区不正确 如果你使用的是 PostgreSQL 客户端,例如 NodeJS 客户端,可能会遇到时间戳不匹配的情况。PG 库的数据类型文档中写道: node-postgres 会将 JavaScript 的 Date 对象实例转换为 PostgreSQL 服务器期望的输入值。同样,当将 date、timestamp 或 timestamptz 列的值读回 JavaScript 时,node-postgres 会将其解析为 JavaScript Date 对象的实例。 最关键的一点是: node-postgres 将 DATE 和 TIMESTAMP 列转换为 node 进程的本地时间,该时间由 process.env.TZ 设定。 因此,你可能需要在 .env 文件中添加: TZ=UTC 建议作者使用 TIMESTAMPTZ 类型。存储 TIMESTAMPTZ 值时,PostgreSQL 会将其转换为 UTC 时间;读取时,PostgreSQL 会再将其从 UTC 转换回客户端系统设置时区的时间。这种机制确保了无论客户端处于何种时区,时间戳都能被正确解读。 相比之下,TIMESTAMP(无时区时间戳)不存储任何时区信息,仅记录日期和时间。如果不同地区的客户端读取 TIMESTAMP 值,他们可能会误以为该值对应本地时区,从而导致错误结果。 因此,如果应用需要处理跨时区的时间数据,通常首选 TIMESTAMPTZ。它能确保无论用户身在何处,时间戳都能被准确解读。 为什么日志中会出现 “cannot delete file, will retry”? 如果在 Windows 上运行,建议禁用 Windows Defender。Windows Defender 会扫描每一个新建文件。若文件正在被扫描,则无法删除。因此,QuestDB 创建文件后,Windows Defender 开始扫描,当 QuestDB 试图清理时,这些正在被扫描的文件无法被删除。 如何修复 “DatabaseError: unexpected token: CURSOR”?此查询在 PostgreSQL 中是正常的! QuestDB 不支持需要通过 DECLARE CURSOR 显式创建和管理的可滚动游标,也不支持后续的 FETCH 操作。 相反,QuestDB 支持不可滚动的“仅向前”游标。这意味着虽然可以按顺序遍历查询结果,但无法像 PostgreSQL 中的可滚动游标那样反向导航或随机访问结果位置。 更多信息及规避建议,请参阅《查询与 SQL 概览》中的 PostgreSQL 兼容性章节。 我的表因之前的磁盘写满或内核限制错误导致 WAL 数据损坏,该怎么办? 你需要使用 RESUME WAL SQL 语句跳过存在问题的事务。如果有多个事务依赖于损坏的 WAL 数据,可能需要多次执行该操作。