Ibis 的 Table 是声明式、不可变的查询构建器，不直接等价于数据库表；要将计算结果持久化到 DuckDB，需显式调用 insert()、raw_sql() 或结合 mutate() + create_table() 等后端专属方法，而非依赖 .execute() 自动落库。
ibis 的 table 是声明式、不可变的查询构建器，不直接等价于数据库表；要将计算结果持久化到 duckdb，需显式调用 `insert()`、`raw_sql()` 或结合 `mutate()` + `create_table()` 等后端专属方法，而非依赖 `.execute()` 自动落库。
在使用 Ibis 进行数据分析时，一个常见误区是认为调用 .execute() 即可将结果“写回”源表——实际上，.execute() 仅执行查询并返回 Python 对象（如 Pandas DataFrame 或 Arrow Table），不会修改底层数据库。Ibis 的核心设计哲学是「查询即表达式」：Table 对象代表 SQL 逻辑计划，具有不可变性与延迟执行特性。真正的持久化操作必须通过后端提供的显式写入接口完成。以下以 DuckDB 后端为例，系统说明三种关键场景的正确实现方式。
✅ 1. 插入新行：con.insert() 是首选方案
DuckDB 后端提供了原生支持的 insert() 方法，高效、类型安全且自动适配列式写入路径：
import ibis
import pandas as pd
con = ibis.duckdb.connect("mydb.ddb")
person = con.table("person")
# 场景 A：从 Python 字典插入单条/多条记录
con.insert(
"person",
{"id": [101, 102], "name": ["Alice", "Bob"], "age": [30, 25]}
)
# 场景 B：从 Ibis 查询结果插入（先 execute 得到 Arrow Table）
new_records = person.filter(person.age > 40).select("id", "name", "age")
arrow_tbl = new_records.execute() # 返回 pyarrow.Table
con.insert("person", arrow_tbl) # 零拷贝注册 + 批量插入
# 场景 C：从 Pandas DataFrame 插入（推荐转 Arrow 提升性能）
df = pd.DataFrame({"id": [103], "name": ["Charlie"], "age": [35]})
con.insert("person", df.to_arrow()) # 避免 Pandas → Python object → DuckDB 的低效链路⚠️ 注意事项：
- con.insert() 不支持 ibis.Table 对象直接传入，必须先 .execute() 转为 Arrow/Pandas；
- 若目标表不存在，insert() 会报错；如需建表+插入，改用 con.create_table()；
- 对于超大数据集，优先使用 df.to_arrow() + con.register() + INSERT INTO ... SELECT，避免内存瓶颈。
✅ 2. 删除行：必须使用 raw_sql() 执行 DML
Ibis 当前不提供跨后端统一的 delete() API，DuckDB 中需通过 raw_sql() 直接下发 SQL：
# 安全删除：带 WHERE 条件
con.raw_sql("DELETE FROM person WHERE age < 18")
# 批量删除（建议加 LIMIT 防误操作）
con.raw_sql("DELETE FROM person WHERE name IN ('John', 'Jane') LIMIT 1000")
# 清空表（注意：DuckDB 不支持 TRUNCATE，用 DELETE 替代）
con.raw_sql("DELETE FROM person")⚠️ 关键提醒：
- raw_sql() 绕过 Ibis 类型检查与 SQL 编译器，务必自行校验 SQL 语法与权限；
- DuckDB 默认启用自动事务（autocommit=True），每条 raw_sql() 是独立事务；如需批量原子操作，应显式使用 con.begin() + con.commit()；
- 避免在生产环境无 WHERE 的 DELETE FROM table —— 建议始终加上 LIMIT 并在测试库验证。
✅ 3. 修改表结构：mutate() + create_table() 实现安全演进
Ibis 不提供 ALTER TABLE 的抽象 API（因各后端语法差异大），但可通过「重建表」模式安全实现结构变更：
# 示例：为 person 表新增 computed 列 'is_adult'，并保留原数据
person = con.table("person")
# 步骤 1：构建新表结构（使用 mutate 添加列）
extended_person = person.mutate(
is_adult=ibis.case().when(person.age >= 18, True).else_(False).end()
)
# 步骤 2：创建新表（含新 schema），并写入数据
con.create_table(
"person_v2",
extended_person,
temp=False, # 持久化到磁盘
overwrite=True # 覆盖同名表（谨慎！）
)
# 步骤 3：原子切换（可选）——重命名 + 删除旧表
con.raw_sql("ALTER TABLE person_v2 RENAME TO person_new")
con.raw_sql("DROP TABLE person")
con.raw_sql("ALTER TABLE person_new RENAME TO person")? 替代方案说明：
- 若只需重命名列或调整顺序，可用 select() 重排字段后 create_table(..., overwrite=True)；
- 若需添加 NOT NULL 约束或主键，DuckDB 目前不支持 ALTER TABLE ADD CONSTRAINT，必须重建表；
- 强烈建议在变更前备份：con.raw_sql("CREATE TABLE person_backup AS SELECT * FROM person")。
? 总结：Ibis 写入 DuckDB 的黄金法则
| 操作类型 | 推荐方法 | 是否跨后端兼容 | 关键约束 |
|---|---|---|---|
| 插入数据 | con.insert(table_name, data) | ❌ 仅 DuckDB/SQLite 等嵌入式后端支持 | data 必须为 Arrow/Pandas/字典，非 Ibis Table |
| 删除/更新 | con.raw_sql("DELETE/UPDATE...") | ❌ 后端专用 | 需手动处理事务、SQL 注入与语法兼容性 |
| 表结构变更 | mutate() + create_table(overwrite=True) | ✅ 声明式逻辑可复用 | 本质是重建表，需额外空间与原子切换步骤 |
最后强调：Ibis 的价值在于分析逻辑的可移植性与可测试性，而持久化操作应视为「基础设施层任务」，需结合具体后端能力谨慎设计。对于 DuckDB，善用 insert() 和 raw_sql()，配合 Arrow 零拷贝通道，即可在保持 Ibis 声明式优势的同时，高效、安全地完成所有写入需求。
