GET/meta-catalog

meta-catalog 查看元数据字段目录

查看 meta-search 支持的字段、筛选排序能力与默认返回列。

概述

meta-catalog 返回 meta-search 可用字段、哪些字段可以筛选或排序、默认返回哪些列，以及过滤算子和枚举样本值。适合在搭筛选器、生成查询表单或让 Agent 自动拼 meta-search 请求前调用。

不适用场景

· 不用于搜索论文、召回证据片段或读取全文。
· 不用于判断某篇论文是否存在，请使用 meta-search。
· 不用于下载资源文件，请使用 resource。

能力边界

· meta-catalog 是运行期 schema 自描述接口，返回字段、算子和可投影能力。
· include_sample_values 可能读取缓存样本，样本值不代表全集。
· 客户端应把 catalog 作为构造 meta-search 的依据，而不是把字段名长期硬编码。

鉴权

统一使用 API Key Bearer Token 鉴权，详见统一鉴权章节。在 HTTP Header 中加入：

Authorization: Bearer YOUR_API_TOKEN

请求示例

curl

curl -G https://api.sciverse.space/meta-catalog \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode "include_sample_values=true"

专利字段目录

BASE_URL="${BASE_URL:-https://api.sciverse.space}"
: "${SCIVERSE_API_TOKEN:?Set SCIVERSE_API_TOKEN}"
curl --fail-with-body -sS -G "${BASE_URL}/meta-catalog" \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}" \
  --data-urlencode 'collection=patents'

查看四类实体的字段能力

BASE_URL="${BASE_URL:-https://api.sciverse.space}"
: "${SCIVERSE_API_TOKEN:?Set SCIVERSE_API_TOKEN}"
for COLLECTION in papers authors sources patents; do
  curl --fail-with-body -sS -G "${BASE_URL}/meta-catalog" \
    -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}" \
    --data-urlencode "collection=${COLLECTION}" \
    -o "${COLLECTION}-catalog.json" || exit 1
done

请求参数（URL query）

字段	类型	必填	说明
collection	string	可选	实体集合，默认 papers；专利使用 patents，各集合字段和授权相互独立。默认 papers范围 papers / authors / sources / patents
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	元数据服务暂不可用，请稍后重试。

通用错误码请参考「错误码」章节。

参数边界

限制项	值
样本值默认	默认不拉取，需 include_sample_values=true
doc_id	始终可见

重试建议

· 建议重试：502 / 503 / 504
· 不应重试：401

FAQ

什么时候需要调用 meta-catalog？

当 Agent 或前端要生成 meta-search 筛选器、字段选择器或排序条件时，应先读取 catalog。

sample values 可以当作完整枚举吗？

不可以。它只是样本值或缓存值，只能辅助 UI 和提示，不代表完整取值空间。

meta-catalog 会返回论文结果吗？

不会。它返回 schema 和字段能力；论文结果由 meta-search 返回。

字段权限变化会影响 catalog 吗？

会。不同账号或角色可能看到不同字段能力，调用方需要按返回结果动态构造请求。

说明

· 专利字段需单独授权；论文的字段权限不会自动授予专利访问权。未配置专利字段时返回 403。
· 示例默认使用生产地址；验证预览环境时先设置 BASE_URL，并将该环境的 token 放入 SCIVERSE_API_TOKEN。查询、全文读取、源文件下载分别校验权限；下载专利源文件需要 internal 角色，返回的可能是包含多篇专利的原始 ZIP。

还没有 API Key？

登录控制台「密钥」即可创建。同一套 API Key 可用于已开通的 Sciverse、点石与 Skills 能力，提供基础试用额度，具体以账号权限为准。

前往控制台