GET/meta-catalog
meta-catalog 查看元数据字段目录
查看 meta-search 支持的字段、筛选排序能力与默认返回列。
概述
meta-catalog 返回 meta-search 可用字段、哪些字段可以筛选或排序、默认返回哪些列，以及过滤算子和枚举样本值。适合在搭筛选器、生成查询表单或让 Agent 自动拼 meta-search 请求前调用。
不适用场景
- · 不用于搜索论文、召回证据片段或读取全文。
- · 不用于判断某篇论文是否存在，请使用 meta-search。
- · 不用于下载资源文件，请使用 resource。
鉴权
统一使用 API Key Bearer Token 鉴权，详见统一鉴权章节。在 HTTP Header 中加入：
Authorization: Bearer YOUR_API_TOKEN
请求示例
curl -G https://api.sciverse.space/meta-catalog \
-H "Authorization: Bearer YOUR_API_TOKEN" \
--data-urlencode "include_sample_values=true"请求参数（URL query）
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| collection | string | 可选 | 字段目录所属实体集合。papers（默认）/ authors / sources，各 collection 字段不同。 默认 papers范围 papers / authors / sources |
| include_sample_values | bool | 可选 | 是否返回枚举字段的样本值；样本值会缓存 24 小时。 默认 false |
响应结构
| 字段 | 类型 | 说明 |
|---|---|---|
| fields | array | 字段列表。 |
| fields[].name | string | 字段名。 |
| fields[].type | string | 类型：String / Integer / Float / List[...]。 |
| fields[].filterable | bool | 是否可作为 filters 字段。 |
| fields[].sortable | bool | 是否可排序。 |
| fields[].searchable | bool | 是否可被全文检索。 |
| fields[].default_returned | bool | 是否为默认返回字段。 |
| fields[].description | string | 字段说明。 |
| fields[].sample_values | array | 枚举样本值，仅在 include_sample_values=true 时返回。 |
| fields[].operators | array | 该字段支持的算子；Integer/Float 通常全集，List 类型多为 IN/NIN/CONTAINS，不可过滤字段为空数组。 |
| default_fields | array | 默认返回的字段集合。 |
| filter_operators | array | 全局支持的过滤算子：EQ / NE / GT / GTE / LT / LTE / IN / NIN / CONTAINS / MATCH / MATCH_PHRASE。MATCH 分词模糊（author、keywords），MATCH_PHRASE 短语模糊（publication_venue_name_unified）。 |
错误码
| 错误码 | 信息 | 说明 |
|---|---|---|
| 401 | UNAUTHORIZED | 鉴权失败。 |
| 429 | RATE_LIMITED | 触发账号配额限制。 |
| 502 | UPSTREAM_UNAVAILABLE | 服务异常。 |
| 503 | METADATA_GRPC_NOT_CONFIGURED / UPSTREAM_ERROR | 元数据服务暂不可用，请稍后重试。 |
通用错误码请参考「错误码」章节。
重试建议
- · 建议重试：502 / 503 / 504
- · 不应重试：401
能力边界
- · meta-catalog 是运行期 schema 自描述接口，返回字段、算子和可投影能力。
- · include_sample_values 可能读取缓存样本，样本值不代表全集。
- · 客户端应把 catalog 作为构造 meta-search 的依据，而不是把字段名长期硬编码。
FAQ
什么时候需要调用 meta-catalog？
当 Agent 或前端要生成 meta-search 筛选器、字段选择器或排序条件时，应先读取 catalog。
sample values 可以当作完整枚举吗？
不可以。它只是样本值或缓存值，只能辅助 UI 和提示，不代表完整取值空间。
meta-catalog 会返回论文结果吗？
不会。它返回 schema 和字段能力；论文结果由 meta-search 返回。
字段权限变化会影响 catalog 吗？
会。不同账号或角色可能看到不同字段能力，调用方需要按返回结果动态构造请求。
还没有 API Key？
登录控制台「密钥」即可创建。同一套 API Key 可用于已开通的 Sciverse、点石与 Skills 能力，提供基础试用额度，具体以账号权限为准。