duckdb 的 duckdbpyrelation 对象与创建它的连接强绑定，无法直接跨连接注册；本文详解其设计原因，并提供基于 sql 解析、arrow 表或临时视图等专业级替代方案。
duckdb 的 duckdbpyrelation 对象与创建它的连接强绑定，无法直接跨连接注册；本文详解其设计原因，并提供基于 sql 解析、arrow 表或临时视图等专业级替代方案。
在 DuckDB 中，DuckDBPyRelation（即 .sql() 方法返回的关系对象）并非“无状态”的逻辑查询计划，而是已执行元数据解析的轻量级执行上下文：列名、类型、表达式绑定、甚至部分优化均已依赖原始连接完成。因此，它本质上是连接（Connection）的派生资源——这解释了为何以下操作会失败：
import duckdb
conn = duckdb.connect(":memory:")
df = conn.sql("SELECT * FROM '/tmp/test.csv'")
conn.close() # ❌ 关闭后 df 不可用
conn1 = duckdb.connect(":memory:")
conn1.register("test", df) # ❌ 报错：Connection has already been closed即使保持 conn 开启，也会触发另一错误：
# conn 未关闭，但：
conn1.register("test", df) # ❌ 报错：The relation you are attempting to register was not made from this connection这是因为 df 的内部引用仍指向 conn 的内存结构（如 catalog、type resolver 等），而 DuckDB 的 Python 绑定明确禁止跨连接共享 Relation 实例。
✅ 正确的跨连接数据传递方案
方案 1：Materialize 到 Arrow（推荐 · 稳定 · 零依赖）
将关系物化为 Apache Arrow Table，彻底脱离连接生命周期：
import duckdb
import pyarrow as pa
# 第一连接：构建并物化
conn = duckdb.connect(":memory:")
arrow_table = conn.sql("SELECT * FROM '/tmp/test.csv'").arrow() # ✅ 返回纯 Arrow 表
conn.close()
# 第二连接：注册 Arrow 表（完全独立）
conn1 = duckdb.connect(":memory:")
conn1.register("test", arrow_table) # ✅ 成功
result = conn1.execute("SELECT COUNT(*) FROM test").fetchone()
print(result) # e.g., (42,)⚠️ 注意：Arrow 物化会拷贝数据到内存（零拷贝仅限于同一进程内 Arrow 生命周期管理良好时），适合中等规模数据；若需极致性能，可配合 arrow_ipc 或磁盘持久化。
方案 2：复用 SQL 字符串 + execute()（轻量 · 延迟执行）
不创建 Relation，直接传递 SQL 文本，在目标连接中重新解析执行：
query_sql = "SELECT * FROM '/tmp/test.csv'" # 纯字符串，无连接依赖
conn1 = duckdb.connect(":memory:")
# 直接执行（非注册）——适用于一次性查询
result = conn1.execute(query_sql).fetch_df()
# 或封装为视图（逻辑复用，不占内存）
conn1.execute(f"CREATE VIEW test AS {query_sql}")
conn1.execute("SELECT * FROM test").show()方案 3：使用临时视图 + ATTACH（多数据库协同场景）
若需长期复用复杂逻辑，可在源连接中创建临时视图，并通过 ATTACH 共享（需同一进程内）：
conn = duckdb.connect(":memory:")
conn.execute("CREATE TEMP VIEW lineitem_view AS SELECT * FROM 'lineitem.parquet'")
# 注意：此视图仅对 conn 可见；若需跨连接，可导出为临时文件表或使用 ATTACH（不推荐用于内存连接间传递）? 当前限制说明：截至 DuckDB v1.0+，Python API 尚未暴露底层 ExtractStatements（C++ 层解析 SQL 为 AST 的能力），因此无法像预期那样生成“连接无关的解析语句对象”。该功能已在社区提案中（duckdb#8243），未来版本可能支持 duckdb.parse_sql("...") 返回可跨连接重建 Relation 的中间表示。
总结与最佳实践建议
- 不要尝试跨连接传递 DuckDBPyRelation：这是设计使然，非 bug；
- 中小规模数据 → 优先用 .arrow()：语义清晰、兼容性强、调试友好；
- 只读/一次性查询 → 直接传 SQL 字符串：零序列化开销，延迟执行更灵活；
- 避免过早物化大表：如需处理 TB 级数据，应优先利用 DuckDB 的原生文件扫描（如 read_csv() / parquet_scan()）在目标连接中直接加载；
- 关注 DuckDB 官方更新：未来 parse_sql() 或 Statement 类型 API 将填补当前抽象缺口。
通过理解 DuckDB 的“连接即执行环境”模型，并选用匹配场景的数据载体（Arrow 表、SQL 字符串、物理文件路径），即可高效实现跨连接的数据协作，无需牺牲性能或可维护性。
