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-skillsgnomADGenome 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 POSTgnomAD 的公共数据接口是GraphQL与典型的 REST 查询完全不同属性值API 类型GraphQL端点https://gnomad.broadinstitute.org/apiHTTP 方法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核心字段语义字段含义acallele count该等位基因alt在样本中被观测到的总条数anallele number有效基因型总数等价于 2 × 有效样本数过滤后afallele frequencyaf 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_r4gnomAD v4GRCh38最新主要发布外显子组 基因组gnomad_r3gnomAD v3.1.2GRCh38仅基因组genomes onlygnomad_r2_1gnomAD v2.1.1GRCh37外显子组 基因组选择原则默认优先gnomad_r4最新主要发布、覆盖面最大需要与 GRCh37 坐标下历史数据或旧文献比对时使用gnomad_r2_1。注意 v3/v4 与 v2 不在同一基因组 build 上跨版本比较频率时必须先统一坐标体系。在数据库检索语境下应在出处信息provenance中记录所用 dataset 与参考基因组否则结果无法被精确复现。人群频率字段populations 嵌套结构除了exome/genome顶层的总体ac/an/afgnomAD 将人群特异的频率放在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分开统计外显子组样本量通常更大an250000vsan150000仅示意两者之差提示该位点在测序覆盖上的差异返回体是纯数据不是可执行指令。按技能规范抽取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文件。这一点与技能整体规范吻合当用户确实需要全部记录时优先官方批量下载而非逐条翻页打 APISKILL.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/indelSV 需使用单独的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-APCSK9 区域外显子组变异 - 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 / datasetgnomad_r4 / reference_genome - Identifier conversions: 无原生变异 ID - Count reconciliation: 单条目标查询无分页 - Warnings: 频率解读需结合 ac/anSV 需走 structural_variant 查询其中provenance出处是强制项端点、参数、访问日期、标识符换算必须可让另一位研究者或 Agent 原样重跑。若某查询返回空结果应显式声明无结果而不是悄悄省略——这是技能定义的确定性检索纪律gnomAD 查询同样遵守。结语gnomAD 的公共 GraphQL API 以无鉴权、POST-only 的单一端点覆盖了变异、基因、区域、转录本与人群频率的确定性检索需求。实际使用时记住四个关键决策点即可选对查询入口——按变异 ID / 基因符号 / 基因内 / 区间内 / 转录本五种场景选择对应查询声明 build 与 dataset——reference_genome与dataset决定坐标与数据版本跨版本比较先统一坐标系成对解读 ac/an/af——用af表达频率结论用ac/an判断可信度需要时展开populations查看人群分层遵守访问边界——交互式查询保持约 1 req/sec批量需求转向 Google Cloud 上的 Hail tables 或 VCF 下载。将这些步骤纳入 database-lookup 的检索契约、完整性核对与出处记录框架即可让每一个 gnomAD 频率数字都经得起复现与审计。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考