duckdb 的 duckdbpyrelation 对象与创建它的连接强绑定，无法直接跨连接注册；本文详解其设计原理、根本限制，并提供三种可行替代方案：arrow 表物化、sql 字符串传递、以及利用实验性 extract_statements 接口实现轻量级语句复用。
duckdb 的 duckdbpyrelation 对象与创建它的连接强绑定，无法直接跨连接注册；本文详解其设计原理、根本限制，并提供三种可行替代方案：arrow 表物化、sql 字符串传递、以及利用实验性 extract_statements 接口实现轻量级语句复用。
在 DuckDB 中，DuckDBPyRelation（即 .sql() 方法返回的对象）并非无状态的“懒数据帧”，而是一个已解析、类型推导完成、逻辑计划部分优化的连接内联对象。它依赖底层连接持有的元数据上下文（如 catalog、type resolver、function registry），因此一旦原连接关闭（conn.close()），Relation 即失效；即使连接仍存活，将其注册到另一连接（conn1.register("test", df)）也会报错 The relation you are attempting to register was not made from this connection —— 这是 DuckDB 明确的设计约束，而非 bug。
✅ 正确实践：三类可落地的替代方案
1. 物化为 Arrow 表（推荐：通用、稳定、零依赖）
最可靠的方式是将 Relation 显式物化为 Arrow Table，脱离连接生命周期：
import duckdb
import pyarrow as pa
# 第一个连接：执行查询并物化为 Arrow
conn = duckdb.connect(":memory:")
df_arrow = conn.sql("SELECT * FROM '/tmp/test.csv'").arrow() # ← 关键：.arrow()
conn.close()
# 第二个连接：注册 Arrow 表（完全独立）
conn1 = duckdb.connect(":memory:")
conn1.register("test", df_arrow) # ✅ 成功
result = conn1.execute("SELECT COUNT(*) FROM test").fetchone()
print(result) # (n,)⚠️ 注意：df_arrow 是内存中完整数据副本，适用于中等规模数据；若需真正“懒加载”，请选方案 2 或 3。
2. 传递 SQL 字符串（轻量、零序列化开销）
若仅需复用查询逻辑（而非中间结果），直接传递 SQL 字符串是最轻量的解耦方式：
# 定义可复用的查询逻辑（纯字符串）
query_sql = "SELECT * FROM '/tmp/test.csv' WHERE price > 100"
# 在任意连接中执行
conn1 = duckdb.connect(":memory:")
result = conn1.execute(query_sql).fetchdf()此方式天然支持跨连接、跨进程，且无内存复制，适合 ETL 流水线中的查询模板管理。
3. 实验性方案：使用 extract_statements（Python ≥ 1.1.0，需启用）
DuckDB v1.1.0+ 引入了实验性 API duckdb.extract_statements()，可将 SQL 字符串解析为可跨连接复用的 ParsedStatement 对象（非 Relation，但可重建 Relation）：
import duckdb
# 解析 SQL 为语句对象（不依赖连接）
parsed = duckdb.extract_statements("SELECT * FROM '/tmp/test.csv'")
# 在目标连接中重建 Relation
conn1 = duckdb.connect(":memory:")
relation = conn1.parse_query(parsed[0]) # ← 返回 DuckDBPyRelation
conn1.register("test", relation) # ✅ 成功（注意：此 relation 属于 conn1）
# 或直接执行
result = conn1.execute(parsed[0]).fetchdf()? 提示：该 API 尚属实验性（文档标注 @experimental），生产环境建议先验证稳定性；它不保存数据，仅复用解析/优化后的逻辑计划，兼顾效率与解耦。
总结与选型建议
| 方案 | 是否跨连接 | 是否懒加载 | 内存开销 | 稳定性 | 适用场景 |
|---|---|---|---|---|---|
| Arrow 物化 | ✅ | ❌ | 高（全量内存） | ★★★★★ | 数据量可控、需保证一致性的分析任务 |
| SQL 字符串 | ✅ | ✅ | 极低 | ★★★★★ | 查询逻辑复用、参数化 SQL、微服务间协作 |
| extract_statements | ✅ | ✅ | 低（仅计划） | ★★★☆☆（实验性） | 高性能流水线、需避免重复解析的 OLAP 场景 |
归根结底，DuckDB 的 Relation 设计强调连接内一致性与性能，而非“连接无关”的抽象。理解这一权衡，选择匹配业务需求的替代路径，才是高效使用 DuckDB 的关键。
