### 1.1. Paper relevance search `GET /graph/v1/paper/search`

返回与查询最相关的论文。要精确集合或全量翻页用 1.2 Paper bulk search。

| 参数 | 必填 | 说明 |
|---|---|---|
| `query` | 是 | 纯文本；不支持特殊语法 |
| `fields` | 否 | 逗号分隔的字段投影，见 §3 |
| `offset` / `limit` | 否 | `offset` 默认 0；`limit` 默认 100、上限 100；`offset + limit ≤ 1000` |
| 过滤参数 | 否 | `year` / `publicationDateOrYear` / `venue` / `fieldsOfStudy` / `publicationTypes` / `minCitationCount` / `openAccessPdf`，见下 |

```bash
curl "https://fetchpaper.com/graph/v1/paper/search?query=graph+neural+network&limit=1&fields=title,year,citationCount,authors,externalIds,venue,publicationDate,isOpenAccess,tldr"
```

```json
{"total": 2739010, "offset": 0, "next": 1,
 "data": [{"paperId": "ea5dd6a3d8f210d05e53a7b6fa5e16f1b115f693",
           "title": "Graph Neural Networks: A Review of Methods and Applications",
           "year": 2018, "citationCount": 7603,
           "authors": [{"authorId": "48128428", "name": "Jie Zhou"},
                       {"authorId": "52297757", "name": "Ganqu Cui"}, …],
           "externalIds": {"CorpusId": 56517517, "ArXiv": "1812.08434",
                           "DOI": "10.1016/J.AIOPEN.2021.01.001",
                           "DBLP": "journals/corr/abs-1812-08434",
                           "MAG": "2905224888"},
           "venue": "AI Open", "publicationDate": "2018-12-20", "isOpenAccess": true,
           "tldr": {"text": "A detailed review over existing graph neural network models is provided, …"}}]}
```

- **`total` 是过滤前的 BM25 命中数**（官方也是估算）；过滤只保证 `data` 条目正确。要过滤后的精确总数用 `bulk`。
  `next` 只在**过滤后**确实还有下一条时才给出；翻页窗口封顶 `offset + limit <= 1000`。
- **排序是相关性，不是热度**：默认按词面相关性（标题整串命中、分字段词面强度、引用数、新近度等综合，
  对齐官方开源重排模型）。所以上面第一名是标题原样含整个短语的高引综述。要「领域高引」请在 `bulk` 上加
  `sort=citationCount:desc`。与官方 `search` 的 top-10 平均重合 **35.7%**（库内容覆盖 88.6%），
  **不是官方排序的复刻**。要精确集合或全量翻页一律走 `bulk`。
- `query` 整串都是停用词时（`method`、`the`）这里回 `total: 0`；同一串在 `bulk` 里是全库，两边口径相反（§1.2）。
- **查询宽度有预算**：拦的是「要解多少条倒排链」，不是命中数。去重后查询词 df 之和超过
  **20,000,000** 条直接 400：`Query matches too many papers to rank (21,772,852 postings, max 20,000,000); use fewer or rarer terms`。
  `limit=1` 也一样拦（链要全解完才知道第一名）。量级感：最高频 10 个词合计 1,892 万条，
  `system|model|data|network|analysis|task|graph` 七词 OR 是 1,522 万条，40 个高频主题词堆一起就是 2,177 万条。
  写批量脚本把主题词表拆成几条查询，别堆成一条。

**过滤参数**（`search` / `bulk` / `match` 共用）：

| 参数 | 含义 | 口径 |
|---|---|---|
| `year` | 年份 | `2016`、`2016-2017`、开区间 `2010-` / `-2015`、列表 `2016,2017`（本地宽松展开成区间） |
| `publicationDateOrYear` | 发表日期区间 | `2015-01-01:2019-12-31`、开区间 `1981-08-25:` / `:2015-01`、单年 `2016`、不带冒号的年份区间 `2015-2020`。端点缺月/日按**区间那一端**补：下界补 1 号，上界补当月最后一天（月也没写补 12 月 31 日）；端点越界（`2020-13`）回 400 |
| `venue` | 发表处 | 逗号分隔多个；规范化（小写、去空白）后**精确**匹配，不是子串、不认 ISO4 缩写。**只比对响应里的 `venue` 字段**，`journal.name` 与 `publicationVenue.name` 都不参与（见 §1.5） |
| `fieldsOfStudy` | 学科 | 逗号分隔，忽略大小写的精确匹配 |
| `publicationTypes` | 类型 | 同上，如 `JournalArticle`、`Conference`、`Review` |
| `minCitationCount` | 引用数下界 | 整数 |
| `openAccessPdf` | 只要开放获取 | **裸参数不带值**（官方口径），`&openAccessPdf` 或 `&openAccessPdf=` 都算。数据集没有真 PDF 链接，本地按 `isOpenAccess=true` 近似 |

补 1 号的是**论文自己声明的日期**，不是区间端点：库里写 `2019-06` 的论文按 6 月 1 日参与比较。
端点补齐实测（`query=network`）：`2020-01-01:2020-06` 与 `2020-01-01:2020-06-30` 都是 **94,148**，
而 `2020-01-01:2020-06-01` 只有 85,133；`2020` = **181,510** = 全年。（补齐到月末是本地口径，官方未实测。）

**每个条件在库里能看到多少篇**：

| 条件 | 有值的论文 | 天生够不着的部分 |
|---|---|---|
| `venue` | 10,899,016（54.7%） | 9,018,379 篇没记发表处，任何 `venue=` 都不含它们 |
| `publicationTypes` | 10,367,530（51.9%） | 9,617,355 篇（48.1%）没记类型 |
| `fieldsOfStudy` | 19,885,167（99.8%） | 32,228 篇没记学科（响应里是 `[]`） |
| `year` | 19,901,926（99.9%） | 15,469 篇没记年份，任何年份过滤都不含它们 |
| `publicationDateOrYear` | 14,216,977 有精确日期 | 5,700,418 篇只有年份，按该年 1 月 1 日参与 |
| `openAccessPdf` | 3,190,353（16.0%） | 其余 `isOpenAccess=false` |

**筛不到 ≠ 不存在**：`venue=X` 回 0 有两种可能——这个发表处一篇都没有，或这批论文根本没记 venue。
要区分就 `fields=venue` 抽几条明细看看。

- **空值等于不加条件**（字符串/名单类）：`venue=`、`venue=,,`、`year=`、`fieldsOfStudy=`、
  `publicationTypes=` 都被忽略（实测 `query=attention` 不传过滤 350,751，`venue=` 与 `venue=,,`
  都还是 350,751）。数值类不一样：`minCitationCount=`（空）回 400。
- **名单类是 OR（命中任意一个），不是 AND**，顺序与重复值都不改结果集：
  `query=graph neural network&year=2019-2022` 下 `venue=<NeurIPS 全称>` **320**、
  `venue=<ICLR 全称>` **169**、两者任意顺序 **489** = 320+169（这批没有交集论文），
  `venue=A,B,A` 还是 489，`venue=A,A` 与单写 `venue=A` 同为 320。bulk 游标按此口径折叠书写差异（§1.2）。
- **过滤只收窄候选、不改布尔语义**，OR 侧满足容斥：同一批候选下
  `|(A|B) ∩ F| = |A ∩ F| + |B ∩ F| − |(A+B) ∩ F|`。实测 `graph` / `network` 加 `year=2020`：
  25,543 + 181,510 − 9,813 = **197,240**，与 `query=graph|network` 的 `total` 逐条相等。
- **边界值**：库里最晚年份 **2027**（`query=neural networks&year=2027` 18 条）；
  引用数最大 **354,165**（`minCitationCount=354165` 恰 1 条，354,166 回 0 条）。