mcpField
S
s3-explore

s3-explore

github.com/duckdb数据与数据库613719 次安装28 周前更新
代码仓库

关于 s3-explore

s3-explore 是一项用 DuckDB 探查远程对象存储数据的技能，适合需要检查云端文件与表格内容的用户。它会根据存储 URL 处理凭据，并区分目录清单、文件预览和 Parquet 元数据查询。

主要功能

  1. 01识别 S3、R2、GCS 和自定义存储
  2. 02列出对象及其大小和修改时间
  3. 03预览文件结构与样本行
  4. 04从 Parquet 元数据读取行数和大小
  5. 05通过 SQL 执行数据分析

适用场景

  1. 01检查远程存储桶中的文件
  2. 02查看远程数据集的结构与样本
  3. 03统计 Parquet 文件的行数
  4. 04筛选云端数据并回答分析问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/duckdb/duckdb-skills --skill s3-explore

安装后在 Claude Code 中输入/s3-explore确认已加载。

详细介绍

你正在帮助用户使用 DuckDB 探索远程对象存储中的数据。

URL：$0 问题：${1:-list and describe what's there}

步骤 1 — 检测提供商并设置凭据

根据 URL 或用户上下文，预先添加相应的密钥配置：

提供商URL 模式密钥设置
AWS S3s3://CREATE SECRET (TYPE S3, PROVIDER credential_chain);
Cloudflare R2r2://、使用 R2 终结点的 s3://CREATE SECRET (TYPE R2, PROVIDER credential_chain);
GCSgs://、gcs://CREATE SECRET (TYPE GCS, PROVIDER credential_chain);
MinIO / 自定义使用自定义终结点的 s3://CREATE SECRET (TYPE S3, KEY_ID '...', SECRET '...', ENDPOINT '...', USE_SSL true);

对于 R2，如果用户提供了账户 ID，终结点为 <account_id>.r2.cloudflarestorage.com。像 r2://bucket/path 这样的 R2 URL 应改写为 s3://bucket/path，并使用 R2 密钥。

对于公开存储桶（例如 Overture Maps、AWS 开放数据），无需密钥 — 跳过此步骤。

始终预先添加：

LOAD httpfs;

步骤 2 — 确定 URL 指向的内容

如果 URL 看起来指向目录或存储桶（没有文件扩展名，或以 / 结尾），请列出其内容及大小：

duckdb -c "
LOAD httpfs;
<SECRET_SETUP>
SELECT filename, (size / 1024 / 1024)::DECIMAL(10,1) AS size_mb, last_modified
FROM read_blob('<URL>/*')
ORDER BY filename
LIMIT 50;
"

注意：只选择 filename、size、last_modified — 切勿选择 content，否则会下载实际文件。

如果 URL 指向特定文件或 glob 模式（包含文件扩展名或 *），请预览它：

duckdb -c "
LOAD httpfs;
<SECRET_SETUP>
DESCRIBE FROM '<URL>';
SELECT count(*) AS row_count FROM '<URL>';
FROM '<URL>' LIMIT 20;
"

对于 Parquet 文件，从元数据中获取行数和大小（不下载数据）：

duckdb -c "
LOAD httpfs;
<SECRET_SETUP>
SELECT file_name,
       sum(row_group_num_rows) AS total_rows,
       (sum(row_group_compressed_bytes) / 1024 / 1024)::DECIMAL(10,1) AS compressed_mb
FROM parquet_metadata('<URL>')
GROUP BY file_name;
"

步骤 3 — 回答问题

使用列表、架构或样本数据回答：

${1:-list and describe what's there}

如果用户提出分析类问题（例如“有多少行符合 X 条件”），请编写并运行相应的 SQL 查询。DuckDB 会将谓词下推到 S3 上的 Parquet 文件中，因此即使面对大型远程数据集，筛选也很高效。

错误处理

  • duckdb: command not found → 委派给 /duckdb-skills:install-duckdb
  • 访问被拒绝 / 403 → 建议用户检查凭据：aws configure、环境变量，或提供明确的密钥 ID / 密钥
  • 未找到存储桶 / 404 → 检查 URL 和区域
  • 列出大量内容时超时 → 建议缩小 glob 模式范围或添加前缀

评论

支持 Markdown