DuckDB 拥有最先进的核外（out-of-core）查询引擎，可以在处理超出内存大小的数据时溢出到磁盘。我们不断致力于改进 DuckDB，以提高其可扩展性并尽可能防止内存溢出错误。话虽如此，如果您运行包含多个阻塞算子、特定聚合函数、PIVOT 操作等的查询，或者相对于数据集大小可用内存非常少，您仍可能会遇到内存溢出错误。

“内存溢出”错误的类型

内存溢出错误主要以两种形式出现

OutOfMemoryException

大多数情况下，DuckDB 会因 OutOfMemoryException 而耗尽内存。例如

duckdb.duckdb.OutOfMemoryException: Out of Memory Error: failed to pin block of size 256.0 KiB (476.7 MiB/476.8 MiB used)

OOM Reaper (Linux)

许多 Linux 发行版都有一个 OOM killer 或 OOM reaper 进程，其目标是防止内存过度分配。如果 OOM reaper 终止了您的进程，您通常会在 DuckDB 运行的地方看到以下消息

Killed

要获取更详细的信息，请使用 dmesg 命令（可能需要 sudo）检查诊断消息

sudo dmesg

如果进程是被 OOM killer/reaper 终止的，您会发现类似这样的条目

[Fri Apr 18 02:04:10 2025] Out of memory: Killed process 54400 (duckdb) total-vm:1037911068kB, anon-rss:770031964kB, file-rss:0kB, shmem-rss:0kB, UID:1000 pgtables:1814612kB oom_score_adj:0

内存溢出错误故障排除

要防止内存溢出错误，请尝试减少内存使用。为此，请参阅“如何调整工作负载”页面。简而言之：

• 使用 SET threads = ... 命令减少线程数量。
• 如果您的查询从文件中读取大量数据或写入大量数据，请尝试将 preserve_insertion_order 选项设置为 false：SET preserve_insertion_order = false。
• 反直觉的是，将内存限制降低到默认的 80% 以下有时有助于防止内存溢出错误。这是因为某些 DuckDB 操作会绕过数据库的缓冲区管理器，因此它们预留的内存可能会超过内存限制所允许的范围。如果发生这种情况（例如，DuckDB 被操作系统或 OOM reaper 进程终止），请使用 SET memory_limit = '...' 语句将内存限制设置为总系统内存的 50-60%。
• 将查询拆分为子查询。这使您能够查看中间结果在何处“爆炸”，从而导致查询内存溢出。

另请参阅

有关 DuckDB 内存管理的更多信息，请参阅“DuckDB 中的内存管理”博客文章。