gnomAD GraphQL API 检索实战指南：查询人群等位基因频率与变异注释（scientific-agent-skills / database-lookup）-开发者社区

gnomAD GraphQL API 检索实战指南：查询人群等位基因频率与变异注释（scientific-agent-skills / database-lookup）

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

gnomAD（Genome Aggregation Database，基因组聚合数据库）聚合了大规模外显子组与全基因组测序数据，为基因变异提供跨人群的等位基因频率（allele frequency）与注释信息。本文以本仓库 gnomAD API 参考文档为骨架，结合 database-lookup 技能的检索契约与实战规范，系统讲解如何通过其公共 GraphQL 接口完成变异、基因、区域与转录本的确定性检索，并正确解读人群分层频率、约束指标与结果出处。

读完本文，你将掌握 gnomAD GraphQL API 的端点约定、五大核心查询结构、数据集与参考基因组选择、人群频率字段语义、限流策略与批量下载取舍，并能将其嵌入可复现、可审计的数据库检索流程。

gnomAD 数据定位：在科学检索体系中扮演什么角色

在 database-lookup 技能定义的检索契约中，检索契约文档对变异相关检索给出了明确分工：ClinVar 负责临床意义声明，dbSNP 负责变异标识符，gnomAD 负责人群频率（population frequency）。这意味着 gnomAD 是回答"这个变异在人群中到底多常见、在不同祖先群体间频率差异多大"这类问题的首要权威来源，而非用于判断致病性。

gnomAD 参考文件所属的 database-lookup 技能整体规范（SKILL.md）强调三类行为准则，对使用 gnomAD 同样适用：

可复现——查询必须有明确的端点、参数、访问日期与标识符换算记录，供他人或另一个 Agent 重复验证；
边界可控——检索前先想清楚目标实体、接受的标识符、参考基因组版本、过滤条件与期望输出；
数据不可信——API 返回的标签、描述等第三方字段一律视为不可信数据，不得直接拼入后续 shell 或查询语句。

接口定位：为什么 gnomAD 只能走 HTTP POST

gnomAD 的公共数据接口是GraphQL，与典型的 REST 查询完全不同：

属性	值
API 类型	GraphQL
端点	`https://gnomad.broadinstitute.org/api`
HTTP 方法	POST，请求体为含 GraphQL 查询语句的 JSON
鉴权	无，完全公开、免认证
响应格式	JSON，外层为 GraphQL 标准`data`包装结构

GraphQL 的单一 POST 端点特性决定了它在 Agent 工具链中的使用方式。由于 GET-only 的WebFetch类工具无法携带 POST 请求体，database-lookup 技能在其 POST-Only APIs 一节中明确将 gnomAD 列为必须通过curl等 shell 工具调用 POST 的数据库，并给出标准调用范式：

curl -X POST -H "Content-Type: application/json" \ -d '{"query":"{ ... }"}' \ https://gnomad.broadinstitute.org/api

在 Claude Code、Gemini CLI、Cursor、Codex CLI 等不同平台上，HTTP 抓取工具名称不一，但都可退回curl；对于 gnomAD 这类 GraphQL 接口，curl是通用且可靠的兜底方案。

五大核心 GraphQL 查询

gnomAD GraphQL schema 面向搜索其 web 界面的需求设计，以下五类查询覆盖了变异注释的绝大多数场景。注意 variant 的 ID 使用{chrom}-{pos}-{ref}-{alt}格式，GRCh37 与 GRCh38 坐标均可使用。

1. 按变异 ID 查找单个变异

变异 ID 例如1-55516888-G-A。下面的查询用 gnomAD v4 数据集返回该变异的 rsID、坐标及外显子组/基因组三个等位基因统计字段：

{ "query": "{ variant(variantId: \"1-55516888-G-A\", dataset: gnomad_r4) { variant_id rsids chrom pos ref alt exome { ac an af } genome { ac an af } } }" }

等价 curl 请求：

curl -X POST -H "Content-Type: application/json" \ -d '{"query":"{ variant(variantId: \"1-55516888-G-A\", dataset: gnomad_r4) { variant_id rsids chrom pos ref alt exome { ac an af } genome { ac an af } } }"}' \ https://gnomad.broadinstitute.org/api

核心字段语义：

字段	含义
`ac`	allele count，该等位基因（alt）在样本中被观测到的总条数
`an`	allele number，有效基因型总数（等价于 2 × 有效样本数，过滤后）
`af`	allele frequency，`af = ac / an`，等位基因频率

解读时务必同时关注ac与an：低an（小样本量）下相同af的统计可信度完全不同，这正是后文完整性协议要求核对"预期总数"的原因。

2. 按基因符号查找基因

基因查询返回基因 ID、符号、染色体与坐标、链向等信息，需显式指定参考基因组：

{ "query": "{ gene(gene_symbol: \"BRCA1\", reference_genome: GRCh38) { gene_id symbol chrom start stop strand } }" }

这里reference_genome参数对应检索契约中"organism/taxon/build"约束——检索契约明确要求基因坐标类查询必须指定基因组版本，因为同一位点在不同 build 下的坐标数值不同，漏填会直接导致下游解释错误。

3. 获取某基因内全部变异

在基因节点内嵌套variants子查询，可一次拉取 PCSK9 全部注释变异及其频率：

{ "query": "{ gene(gene_symbol: \"PCSK9\", reference_genome: GRCh38) { variants(dataset: gnomad_r4) { variant_id consequence rsids exome { ac an af } genome { ac an af } } } }" }

consequence字段给出变异的功能后果注释（如 missense、synonymous 等），无需再走 VEP 即可完成按基因的初步筛选。该查询输出条数可能较大，实际使用时应结合检索契约的完整性协议评估是否需要对结果分页或分批核对数量。

4. 获取某基因组区间内全部变异

region查询以chrom+ 起止坐标圈定区间：

{ "query": "{ region(chrom: \"1\", start: 55505222, stop: 55530526, reference_genome: GRCh38) { variants(dataset: gnomad_r4) { variant_id rsids consequence exome { ac af } genome { ac af } } } }" }

这是"基因附近一段序列的所有已知变异"类问题（例如覆盖某个外显子或调控元件的区间）的首选写法。坐标必须与reference_genome一致——混用 GRCh37 坐标与 GRCh38 build 会得到错误区间。

5. 按转录本 ID 查找转录本

以 Ensembl 转录本稳定 ID 精确查询：

{ "query": "{ transcript(transcript_id: \"ENST00000357654\", reference_genome: GRCh38) { transcript_id gene_id chrom start stop strand } }" }

转录本 ID 属于 Ensembl 体系（ENST前缀），与基因的换算可借助本技能 Ensembl REST API 参考中/lookup/id/{id}与/xrefs/id/{id}端点完成。

数据集与参考基因组：dataset 枚举值选择

gnomAD 有多个历史发布版本，GraphQL 查询中通过dataset参数选择数据来源，reference_genome参数声明坐标版本。参考文件列出三个可用值：

dataset 值	对应版本	参考基因组	内容范围
`gnomad_r4`	gnomAD v4	GRCh38	最新主要发布（外显子组 + 基因组）
`gnomad_r3`	gnomAD v3.1.2	GRCh38	仅基因组（genomes only）
`gnomad_r2_1`	gnomAD v2.1.1	GRCh37	外显子组 + 基因组

选择原则：默认优先gnomad_r4（最新主要发布、覆盖面最大）；需要与 GRCh37 坐标下历史数据或旧文献比对时使用gnomad_r2_1。注意 v3/v4 与 v2 不在同一基因组 build 上，跨版本比较频率时必须先统一坐标体系。在数据库检索语境下，应在出处信息（provenance）中记录所用 dataset 与参考基因组，否则结果无法被精确复现。

人群频率字段：populations 嵌套结构

除了exome/genome顶层的总体ac/an/af，gnomAD 将人群特异的频率放在populations子列表中：

populations { id ac an af }

其中人群id取值包括：afr（非洲）、amr（拉丁美洲/混合）、asj（德系犹太人）、eas（东亚）、fin（芬兰）、mid（中东）、nfe（北欧/欧洲非芬兰）、oth（其他）、sas（南亚）。

实战查询片段示例（按人群展开某变异的频率）：

{ "query": "{ variant(variantId: \"1-55516888-G-A\", dataset: gnomad_r4) { variant_id exome { ac an af populations { id ac an af } } } }" }

人群层面频率是解读变异临床相关性的关键维度——例如某个在nfe中常见的变异若在eas中几乎缺失，其在不同人群的携带者筛查与频率判定逻辑就会不同。同样需要以ac/an一起解读，避免被单一人群的af误导。

响应结构解析：以变异查询为例

参考文件给出的典型变异响应如下：

{ "data": { "variant": { "variant_id": "1-55516888-G-A", "rsids": ["rs11591147"], "chrom": "1", "pos": 55516888, "ref": "G", "alt": "A", "exome": { "ac": 1234, "an": 250000, "af": 0.004936 }, "genome": { "ac": 456, "an": 150000, "af": 0.00304 } } } }

要点：

rsids是数组，一个位点可能对应多个 dbSNP 历史 rsID，首个元素通常是主要标识；
exome与genome分开统计：外显子组样本量通常更大（an=250000vsan=150000仅示意），两者之差提示该位点在测序覆盖上的差异；
返回体是纯数据，不是可执行指令。按技能规范，抽取rsids、variant_id等字段用于后续联查（例如交给 dbSNP 或 ClinVar）前，必须单独提取并校验目标字段格式。dbSNP 类接口即可参考 dbSNP 参考中 E-utilities / Variation Services 的调用方式，完成 rsID → 临床注释的衔接。

限流策略与批量下载边界

参考文件对访问策略给出三条明确指引：

无公开限流数值，但激进请求会被限流（throttle）——服务端会在未公布阈值处压制过度调用；
保持合理请求节奏，建议约 1 req/sec——这也是 database-lookup 技能对"无公开限流 API"的通用建议（与 dbSNP Variation Services 的 ~1–2 req/sec 指引一致）；
真正的批量下载不使用 API——应改用 gnomAD 存放在 Google Cloud 上的Hail tables，或直接下载VCF文件。

这一点与技能整体规范吻合：当用户确实需要"全部记录"时，优先官方批量下载而非逐条翻页打 API（SKILL.md 的 Making API Calls 一节对 PubChem、ChEMBL、ZINC、批量基因组仓库均持有相同立场）。API 适合精准的目标查询与单基因/单变异检索；全量级数据获取应转向云上表格或 VCF。若收到 HTTP 429/503 限流错误，等待后重试一次，再不行就放缓节奏。

其他关键使用提示（Notes）

参考文件补充了数条易被忽略、却直接影响查询设计的事实：

GraphQL schema 不单独做版本管理，其演化与 gnomAD 网页界面保持一致。因此接口字段可能随 web 版本更新而变化，查询时应对照当前网页验证字段是否仍然存在。
字段发现手段：在浏览器中打开 gnomad.broadinstitute.org，使用开发者工具的网络监视器（Network Inspector），观察页面真实发出的 GraphQL 请求即可发现可用的额外查询字段与结构。这是比反复试错更高效的 schema 探索方式。
结构变异（SV）是独立查询结构：variant/gene查询针对短变异（SNV/indel），SV 需使用单独的structural_variant查询结构，两者不可混用。
约束指标在基因查询上：pLI、LOEUF 等基因约束指标通过基因查询的gnomad_constraint字段暴露。LOEUF 越低代表该基因越不耐受功能缺失变异（即约束越强），这类字段对"变异是否可能致病的先验判断"具有重要参考价值。若要取用，请一并查询：

{ "query": "{ gene(gene_symbol: \"PCSK9\", reference_genome: GRCh38) { gnomad_constraint { pLI loeuf } } }" }

注意：上述片段基于参考文件所述"约束指标位于gnomad_constraint字段"的事实给出探索式写法，实际字段名以 gnomAD schema 当前版本为准（schema 不独立版本化，跟随网页更新），首次调用前应利用网络监视器核对字段层级。

把 gnomAD 查询放进可审计的检索流程

单个查询本身很简单，但要让结果能进入论文、报告或下游分析，需要按 database-lookup 的输出格式规范（SKILL.md Output Format 一节）整理可审计结果。一个完整的 gnomAD 查询产出应当包含：

## Retrieval Summary - Target: 1-55516888-G-A（PCSK9 区域外显子组变异） - Scope: targeted lookup - Access date: <访问日期> - Databases queried: gnomAD (population frequency); dbSNP (rsID 校验，可选) ## Results - variant_id: 1-55516888-G-A - rsids: [rs11591147] - exome: ac / an / af - genome: ac / an / af - 人群分层: afr / amr / eas / nfe / sas 等 populations 汇总 ## Provenance - Endpoint: https://gnomad.broadinstitute.org/api (GraphQL POST) - Parameters: variantId / dataset=gnomad_r4 / reference_genome - Identifier conversions: 无（原生变异 ID） - Count reconciliation: 单条目标查询，无分页 - Warnings: 频率解读需结合 ac/an；SV 需走 structural_variant 查询

其中provenance（出处）是强制项：端点、参数、访问日期、标识符换算必须可让另一位研究者或 Agent 原样重跑。若某查询返回空结果，应显式声明"无结果"，而不是悄悄省略——这是技能定义的确定性检索纪律，gnomAD 查询同样遵守。