POST/meta-search

meta-search 按字段过滤与排序检索元数据

按年份、期刊、DOI、语言等结构化条件筛选论文书目信息。

概述

meta-search 返回标题、摘要、作者、发表年份等元数据，适合做论文列表、筛选和导出，不返回段落正文。你可以不传 query 仅以 filters / sort 精准检索；也可以传入 query 做全文模糊检索（可与 sort 共用：传 sort 时按字段硬排，query 退化为命中过滤；不传 sort 时可用 freshness_boost 偏向新文献，或 impact_boost 偏向高被引）。

适用场景

· 按学科 / 年份 / 期刊 / 语言等字段筛选文献列表
· 结合 meta-catalog 动态生成 UI 过滤器
· 需要跨页检索的场景，使用 cursor 翻页

不适用场景

· 开放式语义证据召回优先使用 agentic-search。
· 读取全文正文请使用 content。
· 下载 Figure、Table 或附件请使用 resource。

鉴权

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

Authorization: Bearer YOUR_API_TOKEN

请求示例

curl -X POST https://api.sciverse.space/meta-search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "graphene battery cycle stability",
    "filters": [
      {"field": "publication_published_year", "operator": "FILTER_OP_GTE", "value": 2022}
    ],
    "fields": ["title", "doi", "publication_published_year", "publication_venue_name_unified"],
    "page": 1,
    "page_size": 10
  }'

请求体（JSON）

FilterItem：{ field, operator?, value }，operator 默认 EQ，可选值 FILTER_OP_EQ/NE/GT/GTE/LT/LTE/IN/NIN/CONTAINS/MATCH/MATCH_PHRASE。SortItem：{ field, order }，order 默认 SORT_ORDER_DESC。

字段	类型	必填	说明
collection	string	可选	检索的实体集合。papers（默认，论文）/ authors（作者）/ sources（来源期刊）。各 collection 字段不同，用 meta-catalog?collection=<name> 获取对应字段表；authors 用 orcid、sources 用 issn 与论文检索结果关联。默认 papers范围 papers / authors / sources
query	string	可选	全文模糊检索词。可与 sort 共用——传 sort 时按字段硬排，query 退化为命中过滤、不再按相关性排序。
filters	array<FilterItem>	可选	字段过滤条件列表。
sort	array<SortItem>	可选	排序字段集合。可排序字段：publication_published_year / publication_published_date / reference_count / citation_count / influential_citation_count / fwci。可与 query 共用（传 sort 时按字段硬排，query 退化为命中过滤）；传 sort 时 freshness_boost/impact_boost 被忽略（硬排优先）。
fields	array<string>	可选	字段投影。doc_id 始终返回。
page	integer	可选	页码。默认 1范围 ≥ 1
page_size	integer	可选	每页条数。默认 25范围 1–200
cursor	string	可选	游标翻页令牌；与 page>1 互斥。
freshness_boost	enum	可选	模糊搜索新鲜度加权。MILD：近 10 年加权，适合日常查文献；STRONG：近 3 年加权，适合跟踪研究方向 / 追最新进展。仅 query 非空且未传 sort 时生效（传 sort 时硬排优先、本参数被忽略）；可与 impact_boost 叠加。实现走 rescore 两阶段（BM25 取候选→对候选套 gauss decay 重排）；boost 生效时为浅翻页，不支持 cursor 深翻页。默认 NONE范围 NONE / MILD / STRONG
impact_boost	enum	可选	模糊搜索影响力加权，让高被引文献在保留相关性的前提下上浮。MILD：轻度上浮，相关性仍主导；STRONG：明显偏向高被引。仅 query 非空且未传 sort 时生效；可与 freshness_boost 叠加（都设非 NONE 即「相关+偏新+高被引」）。实现走 rescore 两阶段，引用因子 = 1 + weight × saturation(citation_count)（乘法、有界、零被引中性）；boost 生效时为浅翻页，不支持 cursor 深翻页。默认 NONE范围 NONE / MILD / STRONG

字段能力

字段可见性受当前 Token 字段权限影响；点分子字段仅用于 filters / sort，不能放入 fields[] 返回投影。运行期仍建议以 meta-catalog 返回为准。

字段	类型	筛选	检索	排序	默认	投影	说明
doc_id	string	✓	–	–	✓	✓	全文 artifact 内容哈希（sha256）。仅在文档存在全文时返回；没有全文的元数据记录无 doc_id 字段。要引用元数据记录本身请用 unique_id；要拉全文走 /content 接口必须用 doc_id。
unique_id	string	✓	–	–	✓	✓	元数据记录的全局唯一 ID。任何记录都有，与是否有全文无关；适合做引用、去重、跨服务关联（默认返回）。
metadata_type	string	✓	–	–	✓	✓	元数据来源类型。论文来源取值 paper，图书来源取值 ebook。
title	string	✓	✓	–	✓	✓	资源标题 / 题名
abstract	string	✓	✓	–	✓	✓	摘要、简介或内容概述
language	string	✓	–	–	✓	✓	资源语言
doi	string	✓	–	–	✓	✓	数字对象唯一标识符，主要用于论文等学术资源定位
isbns	array<string>	✓	–	–	✓	✓	图书ISBN列表，可能包含多个ISBN
isbn13	string	✓	–	–	✓	✓	13位ISBN，图书资源的标准编号
type	string	✓	–	–	✓	✓	资源类型或文献类型
author	array<object>	✓	–	–	✓	✓	作者列表（对象数组，子字段 name/orcid）。按作者名过滤：精确走 author.name.keyword，MATCH 模糊走 author.name；过滤时传 field 为 author
contributors	array<string>	✓	–	–	–	✓	贡献者列表，如编者、译者等
locations	array<object>	–	–	–	✓	✓	资源可访问位置、来源链接或馆藏/开放获取位置列表
access_is_oa	string	✓	–	–	✓	✓	是否开放获取
access_oa_status	string	✓	–	–	✓	✓	开放获取状态
access_oa_url	string	✓	–	–	✓	✓	开放获取URL
access_license	string	✓	–	–	✓	✓	开放获取或使用许可协议
publication_published_date	date	✓	–	✓	–	✓	出版/发表日期（ISO yyyy-MM-dd）。支持区间过滤、按日 sort、按日 freshness_boost。约 19.6% 文档为 YYYY-01-01 占位（只到年），按日精度时聚簇到年初
publication_published_year	integer	✓	–	✓	✓	✓	出版/发表年份
publication_published_place	array<string>	✓	–	–	–	✓	出版地
publication_published_country	array<string>	✓	–	–	–	✓	出版国家/地区
publication_venue_name_unified	string	✓	✓	–	✓	✓	规范化后的发表载体名称（消除缩写/大小写/标点噪声）。比 publication_venue_name_unified 更适合精确匹配 / 分组聚合；可作为 venue_name 的替代。
publication_venue_type	string	✓	–	–	✓	✓	发表载体类型
publication_venue_issn	array<string>	✓	–	–	✓	✓	发表载体ISSN列表
publication_publisher	array<string>	✓	–	–	✓	✓	出版方/出版社
publication_venue_biblio_volume	string	✓	–	–	–	✓	期刊/会议卷号
publication_venue_biblio_issue	string	✓	–	–	–	✓	期刊/会议期号
publication_venue_biblio_pages	string	✓	–	–	–	✓	期刊/会议页码范围
publication_pages	integer	✓	–	–	–	✓	图书页数或资源总页数
keywords	array<string>	✓	✓	–	✓	✓	关键词列表
primary_topic	object	–	–	–	–	✓	主要主题信息
topics	array<object>	–	–	–	–	✓	主题列表
subjects	array<string>	✓	–	–	–	✓	图书主题词列表
genre	array<string>	✓	–	–	–	✓	图书载体/类型列表
reference_count	integer	✓	–	✓	✓	✓	引用文献数：本文引用了多少篇文献
citation_count	integer	✓	–	✓	✓	✓	被引次数：该文章被其他文章引用的次数，是衡量文章影响力的重要指标
influential_citation_count	integer	✓	–	✓	✓	✓	高影响力被引次数
fwci	float	✓	–	✓	✓	✓	一篇文献的'领域加权引用影响力'Field-Weighted Citation Impact
references	array<string>	–	–	–	✓	✓	本论文引用的文献列表
related_works	array<string>	–	–	–	✓	✓	本文相关工作列表
citation_normalized_percentile	object	–	–	–	✓	✓	一篇文献的'被引百分位'，表示该文献的引用次数在其文献类型、出版年份和学科子领域构成的可比集合中所处的百分位位置
cited_by_percentile_year	object	–	–	–	✓	✓	按'出版年份'细分的被引百分位信息。min: 0，max: 100，表示该文献在同年份的所有文献中，位于 99~100 百分位段，即最顶尖 1%
citations	array<object>	–	–	–	–	✓	引用本篇论文的文献列表（按需投影，整体下发不按子字段过滤）
primary_topic.id	string	✓	–	–	–	–	主要主题 OpenAlex topic id（如 https://openalex.org/T11615）。
primary_topic.display_name	string	✓	–	–	–	–	主要主题显示名精确匹配。
primary_topic.score	float	✓	–	✓	–	–	主要主题置信度，范围 0-1。
primary_topic.domain.id	string	✓	–	–	–	–	主要主题所属领域 OpenAlex domain id（如 https://openalex.org/domains/3）。
primary_topic.domain.display_name	string	✓	–	–	–	–	主要主题所属领域显示名精确匹配。
topics.id	string	✓	–	–	–	–	topic id（nested；OpenAlex URL 格式）。
topics.display_name	string	✓	–	–	–	–	topic 显示名精确匹配（nested）。
topics.score	float	✓	–	✓	–	–	topic 置信度（nested）。
citation_normalized_percentile.value	float	✓	–	✓	–	–	被引百分位，范围 0-1；0.99 表示前 1%。
citation_normalized_percentile.is_in_top_10_percent	boolean	✓	–	–	–	–	是否在前 10% 被引。
citation_normalized_percentile.is_in_top_1_percent	boolean	✓	–	–	–	–	是否在前 1% 被引。
cited_by_percentile_year.min	float	✓	–	✓	–	–	同年份被引百分位下界，范围 0-100。
cited_by_percentile_year.max	float	✓	–	✓	–	–	同年份被引百分位上界，范围 0-100。

响应结构

字段	类型	说明
results	array<object>	命中记录列表；字段受 fields 参数与 Token 权限影响。
results[].abstract	string	摘要、简介或内容概述
results[].access_is_oa	string	是否开放获取
results[].access_license	string	开放获取或使用许可协议
results[].access_oa_status	string	开放获取状态
results[].access_oa_url	string	开放获取URL
results[].author	array<object>	作者列表（对象数组，子字段 name/orcid）
results[].citation_count	integer	被引次数：该文章被其他文章引用的次数，是衡量文章影响力的重要指标
results[].citation_normalized_percentile	object	一篇文献的'被引百分位'，表示该文献的引用次数在其文献类型、出版年份和学科子领域构成的可比集合中所处的百分位位置
results[].cited_by_percentile_year	object	按'出版年份'细分的被引百分位信息。min: 0，max: 100，表示该文献在同年份的所有文献中，位于 99~100 百分位段，即最顶尖 1%
results[].contributors	array<string>	贡献者列表，如编者、译者等
results[].doc_id	string	全文 artifact 内容哈希（sha256）。仅在文档存在全文时返回；没有全文的元数据记录无 doc_id 字段。要引用元数据记录本身请用 unique_id；要拉全文走 /content 接口必须用 doc_id。
results[].doi	string	数字对象唯一标识符，主要用于论文等学术资源定位
results[].fwci	float	一篇文献的'领域加权引用影响力'Field-Weighted Citation Impact
results[].genre	array<string>	图书载体/类型列表
results[].influential_citation_count	integer	高影响力被引次数
results[].isbn13	string	13位ISBN，图书资源的标准编号
results[].isbns	array<string>	图书ISBN列表，可能包含多个ISBN
results[].keywords	array<string>	关键词列表
results[].language	string	资源语言
results[].locations	array<object>	资源可访问位置、来源链接或馆藏/开放获取位置列表
results[].metadata_type	string	元数据来源类型。论文来源取值 paper，图书来源取值 ebook。
results[].primary_topic	object	主要主题信息
results[].publication_pages	integer	图书页数或资源总页数
results[].publication_published_country	array<string>	出版国家/地区
results[].publication_published_date	date	出版/发表日期（ISO yyyy-MM-dd）。支持区间过滤、按日 sort、按日 freshness_boost。约 19.6% 文档为 YYYY-01-01 占位（只到年），按日精度时聚簇到年初
results[].publication_published_place	array<string>	出版地
results[].publication_published_year	integer	出版/发表年份
results[].publication_publisher	array<string>	出版方/出版社
results[].publication_venue_biblio_issue	string	期刊/会议期号
results[].publication_venue_biblio_pages	string	期刊/会议页码范围
results[].publication_venue_biblio_volume	string	期刊/会议卷号
results[].publication_venue_issn	array<string>	发表载体ISSN列表
results[].publication_venue_name_unified	string	规范化后的发表载体名称（消除缩写/大小写/标点噪声）。比 publication_venue_name_unified 更适合精确匹配 / 分组聚合；可作为 venue_name 的替代。
results[].publication_venue_type	string	发表载体类型
results[].reference_count	integer	引用文献数：本文引用了多少篇文献
results[].references	array<string>	本论文引用的文献列表
results[].related_works	array<string>	本文相关工作列表
results[].subjects	array<string>	图书主题词列表
results[].title	string	资源标题 / 题名
results[].topics	array<object>	主题列表
results[].type	string	资源类型或文献类型
results[].unique_id	string	元数据记录的全局唯一 ID。任何记录都有，与是否有全文无关；适合做引用、去重、跨服务关联（默认返回）。
total_count	integer	命中总数。
page	integer	当前页。
page_size	integer	每页条数。
total_pages	integer	总页数。
search_time_ms	float	检索耗时（毫秒）。
next_cursor	string	下一段 cursor（深翻页用）。

响应示例

{
  "results": [
    {
      "doc_id": "d_2a91...",
      "title": "Cycle stability of graphene composite cathodes",
      "doi": "10.1234/xyz",
      "language": "en",
      "publication_published_year": 2024,
      "publication_venue_name_unified": "Adv. Energy Mater.",
      "citation_count": 42,
      "fwci": 1.84
    }
  ],
  "total_count": 318,
  "page": 1,
  "page_size": 25,
  "total_pages": 13,
  "search_time_ms": 56.4,
  "next_cursor": "eyJvZmZzZXQiOjI1fQ=="
}

错误码

错误码	信息	说明
400	INVALID_REQUEST / INVALID_ARGUMENT	参数错误，含非可排序字段作 sort、cursor/page 互斥。
401	UNAUTHORIZED / UNAUTHENTICATED	鉴权失败。
403	PERMISSION_DENIED	字段无访问权限，调整 fields 或使用其他 Token。
429	RATE_LIMITED	触发账号配额限制。
500/502/503/504	UPSTREAM_UNAVAILABLE	服务异常。

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

重试建议

· 建议重试：502 / 503 / 504
· 不应重试：400 / 401 / 403；429 请等待限流窗口恢复或每日额度重置

能力边界

· meta-search 面向结构化元数据检索，不返回 evidence chunk 正文。
· filters、fields、sort 字段名必须来自 meta-catalog，不应硬编码或自行拼接。
· query 与 sort 不应同时用于相关性排序场景；深翻页超过 page * page_size 10000 时应使用 cursor。
· 返回字段会按账号字段权限裁剪。

FAQ

meta-search 适合什么场景？

适合按年份、期刊、DOI、语言、开放获取状态等字段筛选论文，并返回论文级元数据列表。

meta-search 能返回全文片段吗？

不返回。需要证据片段用 agentic-search，需要原文上下文用 content。

如何确认字段是否可筛选或排序？

先调用 meta-catalog，读取字段的 filterable、sortable、projectable 和可用 operators。

如何处理深翻页？

浅翻页使用 page 和 page_size；超过公开限制后改用 next_cursor/cursor，避免 page * page_size 过深。

还没有 API Key？

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

前往控制台