ObservableHQ Framework中DuckDBClient查询结果物化问题解析

在ObservableHQ Framework项目中，开发者发现当使用DuckDBClient执行PIVOT操作时会出现"PendingQuery can only take a single statement"错误。这个问题源于DuckDBClient当前实现方式与DuckDB WASM API的交互特性。

核心问题在于DuckDBClient默认使用statement.send方法执行查询，这种方式会创建流式查询结果。而PIVOT这类复杂操作需要完整物化的结果集才能正确执行。当开发者改用connection.query方法后问题得到解决，因为该方法会直接物化查询结果。

从技术实现角度看，DuckDB WASM API提供了两种查询执行方式：

1. 流式查询(statement.send)：适合大数据集，结果逐步返回
2. 物化查询(connection.query)：立即获取完整结果集，适合需要完整数据才能执行的操作

当前DuckDBClient的实现存在优化空间，特别是对于不需要流式处理的场景。对于大多数前端应用场景，特别是涉及数据透视、聚合等操作时，物化查询可能是更合适的选择。

解决方案建议修改DuckDBClient的实现逻辑，根据查询类型自动选择执行方式：

• 对于简单SELECT查询保持流式处理
• 对于PIVOT、复杂JOIN等操作自动切换为物化查询
• 或者提供显式的执行模式选择参数

这个问题也提醒开发者在使用数据库WASM版本时需要注意执行模式的选择，不同模式对查询类型和性能特性有显著影响。特别是在数据可视化框架中，查询执行方式会直接影响用户体验和功能实现。