clinical-trials-database

临床试验数据库

前置条件

1. uv：阅读 uv 技能，并按照其中的设置说明操作，确保已安装 uv 且其位于 PATH 中。
2. 用户通知：如果工作区根目录中尚不存在 .licenses/clinical_trials_database_LICENSE.txt，则（1）醒目地通知用户查看 https://clinicaltrials.gov/ 上的条款，然后（2）创建该文件，记录通知文本和时间戳。

概述

通过 REST API v2 访问 ClinicalTrials.gov 的全球临床试验数据。scripts/clinical_trials_api.py 中的 CLI 脚本封装了该 API，并为常见筛选条件（阶段、年龄组、状态、干预措施、申办方等）提供专用标志，因此通常无需构造原始查询。

核心规则

• 使用封装脚本：始终执行提供的辅助脚本来查询数据库，而不是直接访问数据库。这些脚本会自动以适当方式强制执行所需的速率限制。
• 始终使用 --fields — 试验 JSON 记录可能非常大；请限制为所需的数据点。
• 先使用 --count-total — 在获取所有记录之前，先检查结果数量。
• 对大型结果集分页 — 使用 --limit 和 --page-token 逐页获取。
• 信任搜索筛选条件：除非明确要求核实详细的资格标准，否则不要手动重新筛选结果。
• 通知：如果使用了此技能，请确保在输出中提及。

上下文效率警告

试验 JSON 记录可能非常大。始终使用 --fields 参数，将响应限制为所需的数据点。写入文件后，只读取需要的字段，而不要读取整个文件。

提示

使用 references/studies_schema.md 查找 --fields 的确切字段路径。

响应布局概要

API 响应包含一个研究列表（通常位于 studies[] 数组中）。每项研究分为 protocolSection 和可选的 resultsSection。

提示

使用下方的简写别名搭配 --fields 参数请求特定数据，以缩小响应内容。

顶层字段

• totalCount — 匹配查询条件的研究总数（整数）
• studies[] — 研究对象数组
• nextPageToken — 用于分页的游标字符串

常见研究字段（及简写别名）

• 标识信息
  • protocolSection.identificationModule.nctId (NCTId) — 唯一的试验 ID
  • protocolSection.identificationModule.briefTitle (BriefTitle) — 简短标题
• 状态
  • protocolSection.statusModule.overallStatus (OverallStatus) — 招募状态
• 描述
  • protocolSection.descriptionModule.briefSummary (BriefSummary) — 简短描述
• 组别与干预措施
  • protocolSection.armsInterventionsModule.interventions (ArmsInterventionsModule)
• 资格标准
  • protocolSection.eligibilityModule.eligibilityCriteria (EligibilityCriteria) — 纳入/排除标准
  • protocolSection.eligibilityModule.stdAges (StdAge) — 儿童、成人等

如需完整路径（地点、结局、结果）以及常用的 --fields 配置示例，请参阅 references/studies_schema.md。

命令

搜索研究

用途：按疾病、药物、阶段、状态、年龄组或这些筛选条件的任意组合查找试验。

uv run scripts/clinical_trials_api.py search \
  --condition "<disease>" \
  --intervention "<drug_or_treatment>" \
  --status "<status>" \
  --phase "<phase>" \
  --age-group "<age_group>" \
  --study-type "<study_type>" \
  --sponsor "<sponsor_name>" \
  --has-results \
  --sort "<field>:<asc|desc>" \
  --fields "<fields>" \
  --limit <N> \
  --count-total \
  --page-token "<token>" \
  --output /tmp/search_results.json

所有标志都是可选的，并按 AND 逻辑组合。

标志参考：

• --condition — 要搜索的疾病或病症（例如 "cystic fibrosis"）。
• --intervention — 药物、设备或治疗名称（例如 "pembrolizumab"）。
• --status — 招募状态筛选条件。取值：RECRUITING、COMPLETED、 NOT_YET_RECRUITING、ACTIVE_NOT_RECRUITING、ENROLLING_BY_INVITATION、 TERMINATED、SUSPENDED、WITHDRAWN。
• --phase — 试验阶段筛选条件。取值：PHASE1、PHASE2、PHASE3、PHASE4、 EARLY_PHASE1、NA。
• --age-group — 患者年龄组筛选条件。取值：CHILD（0–17）、ADULT （18–64）、OLDER_ADULT（65+）。
• --study-type — 研究类型。取值：INTERVENTIONAL、OBSERVATIONAL、 EXPANDED_ACCESS。
• --sponsor — 主要申办方或机构名称（例如 "National Cancer Institute"）。
• --has-results — 布尔标志（无需提供值）。启用后，仅筛选在 ClinicalTrials.gov 上有可用结果的研究。
• --sort — 排序顺序，格式为 FieldName:asc 或 FieldName:desc。常见字段： LastUpdatePostDate、EnrollmentCount、StudyFirstPostDate、StartDate。
• --fields — 要包含在响应中的 JSON 字段名称，以逗号分隔。使用此选项可缩小响应内容（例如 "NCTId,BriefTitle,OverallStatus,Phase"）。可用字段路径见 references/studies_schema.md。
• --limit — 每次请求返回的研究数量上限（1–1000，默认值 10）。
• --count-total — 布尔标志（无需提供值）。启用后，响应中会包含 totalCount 字段，显示所有页面中匹配研究的总数。
• --page-token — 不透明游标字符串，用于获取下一页结果。请从先前搜索响应的 nextPageToken 字段中获取此值。请勿自行构造此字符串；务必从 API 响应中原样复制。请参阅下文的“分页”部分。
• --advanced — 用于执行超出专用标志范围的结构化查询的原始 Essie 筛选表达式（例如 "AREA[LocationCountry]United States"）。与其他标志按 AND 逻辑组合。语法见 references/clinical_trials_api.md。
• --output — **（必需）**写入 JSON 响应的文件路径。

示例 — 正在积极招募的儿童囊性纤维化 3 期试验：

uv run scripts/clinical_trials_api.py search \
  --condition "cystic fibrosis" \
  --status RECRUITING \
  --phase PHASE3 \
  --age-group CHILD \
  --fields "NCTId,BriefTitle,OverallStatus,Phase" \
  --limit 10 \
  --output /tmp/cf_trials.json

示例 — 食管癌阿替利珠单抗招募试验：

uv run scripts/clinical_trials_api.py search \
  --condition "esophageal cancer" \
  --intervention "Atezolizumab" \
  --status RECRUITING \
  --fields "NCTId,BriefTitle,Phase" \
  --limit 10 \
  --output /tmp/atezolizumab_trials.json

按 NCT ID 获取研究

用途：已知 NCT 标识符时，获取特定试验的完整详情。

uv run scripts/clinical_trials_api.py get-study \
  <nct_id> [--fields "<fields>"] \
  --output /tmp/study.json

如果省略 --fields，则返回一组实用的默认字段： NCTId,BriefTitle,OverallStatus,Phase,BriefSummary, ConditionsModule,ArmsInterventionsModule,EligibilityModule

默认响应的结构：

{
  "protocolSection": {
    "identificationModule": {
      "nctId": "NCT00000000",
      "briefTitle": "Study Title"
    },
    "statusModule": {
      "overallStatus": "RECRUITING"
    },
    "descriptionModule": {
      "briefSummary": "This study is about..."
    },
    "conditionsModule": {
      "conditions": [ "Condition Name" ]
    },
    "armsInterventionsModule": {
      "interventions": [ { "type": "DRUG", "name": "Drug Name" } ]
    },
    "eligibilityModule": {
      "eligibilityCriteria": "Inclusion:\n- ...",
      "stdAges": [ "ADULT" ]
    }
  }
}

获取资格／纳入标准

用途：为患者匹配任务提取纳入／排除规则、年龄范围和性别要求。

uv run scripts/clinical_trials_api.py \
  get-eligibility <nct_id> \
  --output /tmp/eligibility.json

快捷方式，可返回标题和完整的资格模块（纳入／排除标准、年龄范围、性别）。

示例 — NCT04886804 的纳入标准：

uv run scripts/clinical_trials_api.py \
  get-eligibility NCT04886804 \
  --output /tmp/eligibility_NCT04886804.json

统计匹配的研究数量

用途：了解试验概况 — 在获取完整记录前，查看某种病症、阶段或状态对应的试验数量。

uv run scripts/clinical_trials_api.py count \
  --condition "<disease>" \
  [--status "<status>"] [--phase "<phase>"] ... \
  --output /tmp/count.json

仅返回符合搜索条件的临床试验总数，不获取研究记录。接受与 search 相同的筛选标志。

按地点／地理位置搜索

用途：将试验范围缩小到特定国家、州或城市。

使用 --advanced 和 AREA[LocationCountry] 或 AREA[LocationCity] 按地理位置筛选结果：

uv run scripts/clinical_trials_api.py search \
  --condition "cystic fibrosis" \
  --status RECRUITING \
  --advanced "AREA[LocationCity]New York" \
  --fields "NCTId,BriefTitle" \
  --limit 20 \
  --output /tmp/nyc_cf_trials.json

按申办方／组织搜索

用途：了解某个申办方或机构的试验项目组合。

使用 --sponsor 查找由特定机构或公司开展的试验：

uv run scripts/clinical_trials_api.py search \
  --sponsor "National Cancer Institute" \
  --fields "NCTId,BriefTitle,LeadSponsorName" \
  --limit 20 \
  --output /tmp/nci_trials.json

多条件组合搜索

适用于：包含多个筛选条件的复杂查询（例如同时筛选疾病、药物、阶段、地区和申办方等）。

所有标志都会以 AND 组合，因此可在单个查询中叠加疾病、干预措施、状态、阶段、地区和申办方：

uv run scripts/clinical_trials_api.py search \
  --condition "pancreatic cancer" \
  --intervention "immunotherapy" \
  --status RECRUITING \
  --phase PHASE3 \
  --advanced "AREA[LocationCountry]United States" \
  --fields "NCTId,BriefTitle,Phase,LeadSponsorName" \
  --limit 20 \
  --output /tmp/panc_trials.json

原始 API 查询（备用方案）

适用于：专用标志未涵盖的非常见端点或参数组合。

uv run scripts/clinical_trials_api.py raw-query \
  --endpoint <path> \
  --params '<json_dict>' \
  --output /tmp/raw_result.json

分页

当结果超过 --limit 时，响应中会包含 nextPageToken。使用 --page-token 传入该令牌即可获取下一页：

uv run scripts/clinical_trials_api.py search \
  --condition "breast cancer" \
  --status RECRUITING \
  --limit 50 --count-total \
  --output /tmp/breast_cancer_p1.json

uv run scripts/clinical_trials_api.py search \
  --condition "breast cancer" \
  --status RECRUITING \
  --limit 50 --page-token "CAo=" \
  --output /tmp/breast_cancer_p2.json

高级查询

如需使用专用标志之外的复杂筛选，请使用 --advanced 配合 Essie 表达式。

什么是 Essie 表达式？ Essie 是 ClinicalTrials.gov 使用的搜索引擎。Essie 表达式是一种结构化查询，可针对特定字段（例如国家、阶段）进行搜索，而非进行通用关键词搜索。

• AREA[Field]Value：针对特定字段。
  • AREA[LocationCountry]United States
  • AREA[Phase]PHASE3
• 布尔运算符：使用 AND、OR、NOT 组合条件。
• RANGE[min, max]：用于数值或日期字段（例如 RANGE[500, MAX]）。

语法和可用字段请参阅 references/clinical_trials_api.md。

该表达式会与其他标志以 AND 组合：

uv run scripts/clinical_trials_api.py search \
  --condition "diabetes" \
  --advanced "AREA[LocationCountry]United States \
    AND AREA[EnrollmentCount]RANGE[500, MAX]" \
  --fields "NCTId,BriefTitle,EnrollmentCount" \
  --output /tmp/diabetes_us_large.json

参考资料

• API 参数、枚举值和 Essie 语法： references/clinical_trials_api.md
• JSON 字段路径和 --fields 用法示例： references/studies_schema.md