S3 与 httpfs

English · 文档

DuckLocal 可以通过 DuckDB 的 httpfs 扩展读取 S3 及兼容 S3 的存储中的对象。 在标题栏的 S3 按钮中配置。

配置凭据

对话框有四个字段：

字段	默认值	说明
Endpoint	s3.amazonaws.com	会采用 http://；否则使用 HTTPS
Region	us-east-1	按输入原样发送
Access Key ID	—	必填
Secret Access Key	—	必填，掩码显示，带有显示开关

确认后会执行等价于以下内容的语句：

INSTALL httpfs; LOAD httpfs;
CREATE OR REPLACE SECRET ducklocal_s3 (
  TYPE s3, PROVIDER config,
  KEY_ID '…', SECRET '…',
  REGION '…', ENDPOINT '…'
);

凭据仅在当前会话有效。 不会写入磁盘，并且在打开或切换数据库时 会被丢弃——之后需要重新配置。 除了重新配置之外，没有其他方式清除它们。

浏览

配置完成后，侧栏中会出现一个 S3 根节点。它按需加载： 展开根节点会列出存储桶，展开存储桶或前缀会列出其中的对象。 存储桶和前缀会排序，对象会显示易读的大小。 刷新按钮会重新加载某一层级， 出错后它也充当重试入口。

列表每层最多 1,000 条，即使响应表明还有更多可用条目。 没有更深层的分页，没有前缀过滤框，也没有搜索—— 某个存储桶在同一层级下有超过一千个对象时，看起来像是完整的， 但实际并非如此。

查询对象

点击键名带有数据文件扩展名的对象时，会把以下内容填入 当前编辑器：

SELECT *
FROM 's3://bucket/key'
LIMIT 100;

这就是一条普通查询：读取通过 httpfs 进行，因此 DuckDB 的 read_parquet / read_csv_auto 行为及其下推同样适用。 该查询会替换当前 Tab 中原本的内容。

无法识别为数据文件的键名不可点击。

限制

• 浏览是只读的。 浏览器没有上传、下载到文件、删除、复制 或创建存储桶的操作。查询仍会下载远端数据。
• 不支持会话令牌。 永远不会发送 X-Amz-Security-Token 请求头， 因此临时 STS 凭据无法使用——请使用长期密钥， 或使用只接受 key/secret 的端点。
• Endpoint 寻址方式基本是自动的。 当主机名包含 amazonaws.com 时使用虚拟主机寻址，否则使用路径寻址。对自建网关来说， 这通常正是你想要的；如果某个网关需要另一种寻址方式， 则没有覆盖选项。
• 区域填错时会用 DuckDB 返回的区域重试一次。 如果仍然失败，就按原样显示错误。
• 需要网络：INSTALL httpfs 会在首次使用时下载扩展。 浏览会向配置的端点发送 HTTP 或 HTTPS 请求（http:// 使用 HTTP， 否则使用 HTTPS）。这些请求会发送存储桶名、键前缀等元数据， 以及签名请求头中的身份验证信息；浏览不会上传本地数据库文件或查询结果。 对远端对象执行查询时，会通过 httpfs 将数据下载到本机。

故障排查

现象	可能原因
配置后浏览立即失败	区域或端点错误；查看侧栏中显示的消息
自建端点报错	寻址方式不对，或该端点要求会话令牌
httpfs 安装错误	没有网络，或代理阻止了扩展下载
凭据像是被忘记了	打开或切换了数据库，按设计会清除凭据

当 DuckLocal 被以签名应用的形式打包时，加载 httpfs 扩展 需要 com.apple.security.cs.disable-library-validation 授权； 随附的打包脚本已经包含它。