datapackage

Frictionless Data Package 指南

此技能适用于任何由 Frictionless Data Package 描述符文件 （datapackage.json）描述的数据集。它刻意保持通用性，适用于任何符合规范的 datapackage，无论其发布者是谁，也无论数据内容是什么。

如需了解 PUDL 专属信息（S3 存储桶路径、表分层约定、数据源背景和使用警告），还请在此技能之上使用 pudl 技能。

什么是 datapackage.json？

datapackage.json 是一个 JSON 文件，用于描述一组表格数据资源。每个资源代表一张表（或一个文件），并包含：

• name：机器可读的标识符
• description：人类可读的描述，通常包含处理说明、主键和使用警告
• path：实际数据文件的文件名或 URL
• schema.fields：列列表，每列都有一个 name 和 description
• schema.primaryKey：唯一标识此资源中一行的一个或多个字段
• schema.foreignKeys：声明此资源的字段与另一个资源的主键之间的关联——在联接或聚合之前请检查这些关联（参见 元数据查询）

该文件可能很大（包含数百个资源、数 MB 的 JSON）。始终有选择地查询它，切勿将整个文件加载到上下文中。

依赖项检查

查询元数据前，请确认 jq 可用：

command -v jq

如果未找到，请告知用户如何安装：

• macOS：brew install jq
• Linux (apt)：sudo apt install jq
• Linux (conda)：conda install jq
• Windows：winget install jqlang.jq

要加载数据并执行 SQL 查询，必须安装 attach-db 和 query 技能（也可选择安装 install-duckdb）。请从 duckdb/duckdb-skills 安装。

工作流概览

1. 定位描述符 — 查找或下载 datapackage.json（见下文）。
2. 有选择地查询元数据 — 使用 jq 提取所需内容。 参见元数据查询。
3. 说明警告 — 呈现资源前，务必检查使用警告。
4. 联接或聚合前检查键 — 如果任务需要合并两个资源， 或汇总一个资源，请先查找每个资源的 schema.primaryKey 和 schema.foreignKeys， 而不是根据同名或看起来相似的列进行联接。参见 元数据查询：联接资源。
5. 验证 （可选） — 如果用户想知道数据是否确实符合描述符，或你正在诊断可疑的软件包，请使用 frictionless validate。参见 Frictionless Validate。
6. 加载数据 （可选） — 仅当用户明确想要查询或探索实际数据时才加载。数据文件可能很大，远程访问也可能缓慢或 昂贵。未经确认用户有此需求，不要在查询元数据后接着加载数据。参见 存储后端。

参考索引

• 元数据查询 — 定位描述符， 使用 jq 有选择地查询，并说明使用警告
• 存储后端 — 从描述符引用的 Parquet、 DuckDB、SQLite 或 CSV 文件加载数据
• Frictionless Validate — 使用 frictionless CLI 验证软件包、检查数据质量、推断架构并诊断不熟悉的描述符；当用户想要验证描述符、检查数据是否符合 其架构，或了解 frictionless 工具可以告知他们哪些软件包信息时，请阅读此文档

社区模式与实践

datapackage 标准具有宽松性：发布者经常会添加非标准字段。 有两种约定值得立即了解：

• 自定义字段 — 发布者添加非标准键很常见，也符合规范。 _ 前缀约定用于标记系统生成或特定平台的键（例如 _cache、_platformVersion）。有些发布者添加自定义键时不使用前缀 （例如包级别的单位注册表，或每个资源的来源元数据）。将 未知字段视为说明性元数据，而不是错误。
• 压缩资源 — 路径以 .gz 或 .zip 结尾的资源可能带有显式的 "compression": "gz" 字段。bytes 和 hash 字段针对的是压缩文件， 而不是解压后的原始文件。

如需了解其他模式（目录、版本控制、外部外键、翻译支持、 字段关系等），请按需获取相关页面：

• v1 模式：https://specs.frictionlessdata.io/patterns/
• v2 实践：https://datapackage.org/recipes/caching-of-resources/（通过 侧边栏或上一页／下一页链接浏览；没有索引页面）

这两个页面涵盖的社区约定大体相同；请参考与所用描述符版本相匹配的页面。

配套技能

此技能将实际的数据查询工作委托给：

• /attach-db — 附加 .duckdb 或 .sqlite 数据库文件，并 设置用于查询的持久会话
• /query — 对已附加的数据库、临时文件（Parquet、CSV、远程 HTTPS/S3）以及 JSON 文件（包括通过 DuckDB 的 read_json 读取的 datapackage.json）运行 SQL 或自然语言查询

必须安装这些技能。请参阅项目根目录中的 skills-lock.json。

主要限制

• 黄金法则：绝不要将完整的 datapackage.json 加载到上下文中。 它可能有数百个资源，占用数兆字节。始终进行有选择的查询。
• 展示资源前，先阅读完整描述。 描述通常包含重要背景信息：处理说明、主键约定、数据来源，或已知局限的注意事项。不要跳过。
• 使用 uv 安装 Python 包 — 优先使用 uv add <package>，而不是 pip install <package>。uv 速度更快，并且会将包安装到虚拟环境中，而非全局安装。仅当 uv 不可用时才退而使用 pip（command -v uv 没有返回任何内容时）。
• 不要使用 Python 查询描述符元数据。 Python 不适合此处的任务 — 它会将完整 JSON 加载到内存中（违反上述黄金法则），引入不必要的依赖，也不便于处理远程描述符。仅处理元数据的任务请使用 jq；需要结合元数据查询与数据查询时，请使用 DuckDB。只有在 已经确定所需的表和列之后，才适合使用 Python 加载数据（通过 pandas 或 polars）。

架构参考与版本检测

Frictionless Data Package 标准有两个常用版本。解析前，请根据顶层描述文件识别版本：

存在的字段	版本	示例值
"$schema"	v2.0	"https://datapackage.org/profiles/2.0/datapackage.json"
"profile"	v1.0	"tabular-data-package" 或 "data-package"
均不存在	不明确（按 v1 基线处理）	—

会影响解析的版本差异：

• 贡献者 — v1 使用 "role": "author"（单数字符串）；v2 使用 "roles": ["author"]（数组）。实际数据中两种格式都可能出现。
• 名称模式 — v1 严格限制为小写 [-a-z0-9._/]；v2 不作限制。
• version 字段 — v2 中存在，v1 中不存在。

随附的架构：

• assets/datapackage-v1.schema.json — v1.0 （JSON Schema draft-04）。用于 FERC XBRL 数据包和许多较早的数据集。
• assets/datapackage-v2.schema.json — v2.0 （JSON Schema draft-07）。当前标准。规范版本始终位于： https://datapackage.org/profiles/2.0/datapackage.json

需要了解描述文件中哪些字段有效，或以编程方式验证描述文件时，请读取相应的架构。