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

概述

collection=papers（可省略）查询论文及已接入的文献元数据，可按 DOI、标题、作者、年份、语言、来源等已授权字段筛选；有全文的记录可返回 doc_id。

适用场景

• · 按 DOI、年份、期刊、语言等筛选文献元数据
• · 按相关性、发表时间或引用量等可用能力排序
• · 获取元数据唯一标识；有全文时用 doc_id 继续读取

不适用场景

• · 不用于直接读取全文或下载二进制资源。
• · 不提供最终答案；论文正文证据检索请使用 agentic-search。

能力边界

• · meta-search 返回当前 collection 的实体元数据，不返回正文证据片段。
• · 使用相同 collection 的 meta-catalog 获取可用字段、类型、算子及筛选、排序和投影能力。
• · query 可与 sort 共用；传 sort 时按字段硬排，query 用作命中过滤。深翻页须遵守当前 collection 的 cursor 与排序限制。
• · 各 collection 使用独立字段与授权，返回字段受账号权限约束。

鉴权

统一使用 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
  }'

import requests

url = "https://api.sciverse.space/meta-search"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
payload = {
    "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_size": 50,
}
while True:
    r = requests.post(url, headers=headers, json=payload).json()
    for it in r["results"]:
        print(it.get("title"))
    if not r.get("next_cursor"):
        break
    payload = {**payload, "cursor": r["next_cursor"]}

BASE_URL="${BASE_URL:-https://api.sciverse.space}"
: "${SCIVERSE_API_TOKEN:?Set SCIVERSE_API_TOKEN}"
curl --fail-with-body -sS "${BASE_URL}/meta-search" \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
  "collection": "papers",
  "filters": [
    {
      "field": "doi",
      "operator": "FILTER_OP_EQ",
      "value": "10.1038/s41586-021-03819-2"
    }
  ],
  "fields": [
    "unique_id",
    "title",
    "doi"
  ],
  "page_size": 1
}'

请求体（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 的 meta-catalog 为准。

字段能力

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

响应结构

响应示例

{
  "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=="
}

错误码

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

参数边界

重试建议

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

FAQ

说明

• · papers 返回的是文献元数据；只有具备可用全文的记录才返回 doc_id，元数据标识使用 unique_id。
• · 示例默认使用生产地址；验证预览环境时设置 BASE_URL，并将对应环境的 Token 放入 SCIVERSE_API_TOKEN。字段授权以当前 collection 和账号权限为准。
• · 四类实体使用各自的字段与授权。先查对应 collection 的 meta-catalog，再选择 fields、filters 和 sort；示例不保证当前 token 已获全部字段授权。作者与来源使用 id，不能将其传入 /content。