事实核验：2026-08-16 · 状态：维护中

记录仅说明核验时间与维护状态，不保证适用于所有环境；使用前请留意正文中的版本、适用条件与风险提示。

warning 适用范围与待维护事项

本文以具备 Python、SQL 和数据库连接基础的读者为对象，主要演示 DuckDB 后端，不保证其他后端具有相同读写、事务或权限行为。正文未提供 orders.parquet 或生成步骤，文件读取练习须先自备并确认其 schema；具体 Ibis、DuckDB 版本组合尚未明确，本轮未执行代码核验。S3 secrets 示例仅适用于已授权且配置好凭据链的环境；建表、覆盖与只读失败测试应在隔离测试库进行，不得直接用于生产验收。

Ibis后端连接与数据读写

abstract 学习目标

正确安装后端 extra、建立连接、读取文件或数据库表、控制写入行为和结果格式，并把凭据、事务、覆盖与数据物化边界纳入工程设计。

Ibis 只提供统一表达层，真正读取和计算的是后端。先理解 表达式与延迟执行，再把连接和 I/O 当作独立工程问题。

1. 安装正确的包与后端

官方入门推荐用 DuckDB 作为本地默认体验：

python -m pip install 'ibis-framework[duckdb]'

PyPI 中 ibis-framework 与名为 ibis 的另一个包不是同一项目，并且两者都使用 import ibis，不能在同一环境共存。依赖锁文件应明确包名、Ibis 版本与后端驱动版本。

2. 三种连接方式

import ibis
from ibis import _

memory_con = ibis.duckdb.connect()
file_con = ibis.duckdb.connect("analytics.duckdb")
url_con = ibis.connect("duckdb://analytics.ddb")

内存连接适合单元测试；文件连接适合可重复本地分析；生产数仓连接则需要对应 extra、驱动和凭据。连接对象承载后端状态，建议由应用入口创建并注入业务函数，不要散落创建。

read_only = ibis.duckdb.connect("analytics.duckdb", read_only=True)

只读模式能缩小误写风险，但不能替代文件权限、凭据最小化和环境隔离。

3. 获取现有表与读取文件

con = ibis.duckdb.connect()
orders = con.read_parquet("orders.parquet", table_name="orders")
print(con.list_tables())
print(orders.schema())

预期表清单包含 orders，schema 显示后端识别的列与类型。不同后端对 read_parquet、read_csv、临时表和外部表的实现不同；应先查具体后端页面，而不是假设所有连接都有相同 I/O 方法。

文件扫描细节可参考 DuckDB直接查询文件。CSV 的自动类型推断适合探索，生产流程应固定 schema 并测试异常行。

4. memtable 与 create_table

ibis.memtable 把小型内存数据表示为 Ibis 表达式，适合固定测试样例。要将数据交给后端持久化或创建临时表，可使用连接方法：

source = ibis.memtable({"id": [1, 2], "value": [10, 20]})

con.create_table(
    "metrics",
    obj=source,
    overwrite=False,
)

预期创建 metrics 表。默认使用 overwrite=False 更安全；覆盖前必须确认目标 catalog、schema、表名和环境。不同后端对临时表、事务和原子替换的支持不一致，不能把本地 DuckDB 的行为直接外推到云数仓。

warning `overwrite=True` 是真实写操作。测试绿并不代表目标环境正确；写入前应输出完全限定表名，并核对行数、schema、分区与权限。

5. 结果输出与物化边界

expr = con.table("metrics").filter(_.value > 10)

pandas_df = expr.to_pandas()
arrow_table = expr.to_pyarrow()

这些方法会执行后端查询并把结果拉回客户端。即使后端能处理 TB 级数据，客户端也未必能容纳全部结果。输出前应过滤、聚合和 limit；大结果优先让后端写入表或文件。

结果进入 Pandas 后可参考 Pandas数据结构 与 Pandas数据操作；若目标是 Polars 流程，结合 Polars表达式与常用操作。

6. 凭据与远程数据

连接字符串、token、私钥不应写进 Markdown、源代码或 notebook 输出。优先使用环境注入、云厂商默认凭据链或密钥管理服务。DuckDB 后端访问 S3 等对象存储时可使用 DuckDB secrets；Ibis 官方 DuckDB 页面明确说明 Ibis 没有原生 secrets API，可通过受控 raw_sql 配置。

con.raw_sql("CREATE SECRET s3 (TYPE S3, PROVIDER CREDENTIAL_CHAIN)")

这会修改连接状态，并可能触发真实云端访问。示例只说明机制；执行前必须获得相应环境授权，且不得在日志输出凭据。

7. 连接健康检查

生产程序启动时可按窄顺序检查：驱动可导入、建立连接、查询常量、列出允许 schema、读取一行目标表。健康检查不应扫描大表或执行写操作。

def check_backend(con):
    probe = con.sql("SELECT 1 AS ok").execute()
    if int(probe.iloc[0]["ok"]) != 1:
        raise RuntimeError("后端健康检查未返回预期值 1")

连接成功不等于业务表存在，也不等于账号拥有写权限。应分别报告网络、认证、catalog、对象存在与业务读取状态。

8. 练习与验收

  1. 分别建立内存和文件 DuckDB 连接，验证关闭重开后的表是否保留。
  2. 用 memtable 创建测试表，第二次创建时保持 overwrite=False 并观察保护行为。
  3. 以只读连接尝试写入，确认测试捕获失败而不是静默通过。
  4. 将结果转为 Pandas 与 Arrow，比较 schema 和 NULL。
  5. 写一个不含凭据的连接工厂，为连接 URL 和环境名写白名单。

9. 延伸阅读

官方来源