dbsnp-database

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dbSNP Database Integration

dbSNP 数据库集成

Prerequisites

前置条件

uv
: Read the
```
uv
```
skill and follow its Setup instructions to ensure
```
uv
```
is installed and on PATH.
User Notification: If LICENSE_NOTIFICATION.txt does not already exist in this skill directory then (1) prominently notify the user to check the terms at https://www.ncbi.nlm.nih.gov/snp/, then (2) create the file recording the notification text and timestamp.
.env
file: Make sure the
```
.env
```
file exists in your home directory. Create one if it does not exist.
NCBI_API_KEY
(optional): Raises the NCBI rate limit from 3 to 10 requests/second. The skill works without it, but a key is recommended if the user plans many queries or encounters a 429 error. The user can obtain one for free by registering at https://www.ncbi.nlm.nih.gov/account/settings/. If the variable is missing from
```
.env
```
, do NOT ask the user to paste it into the chat (this would leak the key into the agent's context). Instead, give the user this command — substituting
ENV_FILE
with the resolved literal path to the
.env
file:
bash
```
printf "Enter NCBI API key (typing hidden): " && read -s key && echo && echo "NCBI_API_KEY=$key" >> "ENV_FILE" && echo "Saved."
```
The scripts load credentials automatically via
```
dotenv
```
. NEVER read, print, or inspect the
```
.env
```
file or its variables (e.g. no
```
cat
```
,
```
grep
```
,
```
echo
```
,
```
printenv
```
, or
```
os.environ.get
```
on keys). Credentials must stay out of the agent's context. See the API Key section for more details.

uv
：阅读
```
uv
```
技能文档并按照其设置说明操作，确保
```
uv
```
已安装且在PATH路径中。
用户通知：如果此技能目录中不存在LICENSE_NOTIFICATION.txt文件，则(1) 醒目地通知用户查看https://www.ncbi.nlm.nih.gov/snp/上的条款，然后(2) 创建该文件并记录通知文本和时间戳。
.env
文件：确保你的主目录中存在
```
.env
```
文件。如果不存在则创建一个。
NCBI_API_KEY
（可选）：将NCBI的请求速率限制从每秒3次提升至每秒10次。即使没有该密钥，本技能也能正常工作，但如果用户计划进行大量查询或遇到429错误，建议使用密钥。用户可通过在https://www.ncbi.nlm.nih.gov/account/settings/注册免费获取。如果`.env`文件中缺少该变量，**不要**让用户在聊天中粘贴密钥（这会导致密钥泄露到Agent的上下文环境中）。相反，向用户提供以下命令——**将`ENV_FILE`替换为`.env`文件的实际路径**：
bash
```
printf "Enter NCBI API key (typing hidden): " && read -s key && echo && echo "NCBI_API_KEY=$key" >> "ENV_FILE" && echo "Saved."
```
脚本会通过
```
dotenv
```
自动加载凭据。绝对不要读取、打印或查看
```
.env
```
文件或其中的变量（例如，不要对密钥使用
```
cat
```
、
```
grep
```
、
```
echo
```
、
```
printenv
```
或
```
os.environ.get
```
）。凭据必须远离Agent的上下文环境。更多详情请查看API密钥章节。

Core Rules

核心规则

Use the Wrapper: ALWAYS execute the provided wrapper script
```
scripts/dbsnp_cli.py
```
to query the database rather than constructing custom HTTP or curl requests. The script automatically handles rate limiting, retries, and JSON parsing.
Command Choice: Do NOT use
```
search-region
```
to find the rsID of a specific variant; use
```
resolve-variant
```
instead.
Output Size: Avoid using
```
--full
```
on
```
get-variant
```
unless specifically needed, as raw payloads can exceed 1 MB.
Shell Safety: Always wrap HGVS strings in single quotes to prevent shell expansion errors.
Notification: If this skill is used, ensure this is mentioned in the output.

使用封装脚本：始终执行提供的封装脚本
```
scripts/dbsnp_cli.py
```
来查询数据库，而非构建自定义HTTP或curl请求。该脚本会自动处理速率限制、重试和JSON解析。
命令选择：不要使用
```
search-region
```
来查找特定变异的rsID；请改用
```
resolve-variant
```
。
输出大小：除非特别需要，否则避免在
```
get-variant
```
命令中使用
```
--full
```
参数，因为原始负载可能超过1MB。
Shell安全性：始终将HGVS字符串用单引号包裹，以防止Shell展开错误。
通知说明：如果使用了本技能，请确保在输出中提及这一点。

When to Use

使用场景

Use this skill when you need to:

Map a genomic variant to its canonical rsID (from VCF coordinates or HGVS notation).
Retrieve summary data for an rsID: variant type, gene associations, clinical significance, and population allele frequencies.
Convert an rsID back to genomic coordinates on a specific assembly.
Find all known variants within a chromosomal region.

Do NOT use when you need to:

Obtain clinical pathogenicity classifications with submitter rationales (use clinvar-database).
Get precise population-level allele frequencies stratified by ancestry (use gnomad-database).
Predict the functional effect of a novel mutation (use alphagenome-single-variant-analysis).
View 3D protein structures affected by a variant (use alphafold-database-fetch-and-analyze / pdb-database).

当你需要以下操作时使用本技能：

将基因组变异映射到其标准rsID（从VCF坐标或HGVS符号转换）。
获取rsID的摘要数据：变异类型、基因关联、临床意义和群体等位基因频率。
将rsID转换回特定组装版本的基因组坐标。
查找染色体区域内所有已知的变异。

以下场景请勿使用本技能：

获取带有提交者依据的临床致病性分类（请使用clinvar-database）。
获取按祖先分层的精确群体水平等位基因频率（请使用gnomad-database）。
预测新突变的功能影响（请使用alphagenome-single-variant-analysis）。
查看受变异影响的3D蛋白质结构（请使用alphafold-database-fetch-and-analyze / pdb-database）。

Command Selection Guide

命令选择指南

Pick the right command on the first try. Match the user's input to the correct subcommand below — one command call is almost always sufficient.

User gives you…: Run this command
An rsID (e.g.
```
rs7412
```
,
```
rs268
```
):
```
get-variant
```
Genomic coordinates: chrom pos ref alt (e.g.
```
8 19962213 C T
```
):
```
resolve-variant
```
An HGVS string (e.g.
```
NC_000008.11:g.19962213del
```
):
```
resolve-hgvs
```
An rsID and they want coordinates back:
```
resolve-rsid
```
A chromosomal region (chrom start end):
```
search-region
```

[!CAUTION] Do NOT use
search-region
to find the rsID of a specific variant. If the user provides a chromosome, position, reference allele, and alternate allele (four values), use
resolve-variant
— it is a direct, single-API-call lookup.
search-region
is only for surveying all variants within a positional range and returns hundreds/thousands of results.

首次尝试就选择正确的命令。将用户的输入与以下子命令匹配——几乎一次命令调用就足够了。

用户提供…：执行此命令
一个rsID（例如
```
rs7412
```
、
```
rs268
```
）：
```
get-variant
```
基因组坐标：染色体位置参考等位基因替代等位基因（例如
```
8 19962213 C T
```
）：
```
resolve-variant
```
一个HGVS字符串（例如
```
NC_000008.11:g.19962213del
```
）：
```
resolve-hgvs
```
一个rsID并需要获取坐标：
```
resolve-rsid
```
一个染色体区域（染色体起始位置结束位置）：
```
search-region
```

[!CAUTION] 请勿使用
search-region
查找特定变异的rsID。如果用户提供了染色体、位置、参考等位基因和替代等位基因（四个值），请使用
resolve-variant
——这是直接的单次API调用查询。
search-region
仅用于调查位置范围内的所有变异，会返回数百/数千条结果。

Quick Start

快速开始

bash

undefined

bash

undefined

Look up variant rs7412: type, gene, clinical significance, MAF

查询变异rs7412：类型、基因、临床意义、次要等位基因频率（MAF）

uv run scripts/dbsnp_cli.py get-variant rs7412 --output /tmp/rs7412.json

Find the rsID for a variant at chr8:19962213 C>T

查找chr8:19962213 C>T对应的rsID

uv run scripts/dbsnp_cli.py resolve-variant 8 19962213 C T
--output /tmp/resolve.json


All subcommands write JSON to disk. Always save output in the `/tmp/` directory.
The `--output` flag is required.

uv run scripts/dbsnp_cli.py resolve-variant 8 19962213 C T
--output /tmp/resolve.json


所有子命令都会将JSON写入磁盘。请始终将输出保存到`/tmp/`目录。`--output`参数是必填项。

Commands

命令详情

get-variant

— Fetch Variant Record

get-variant

— 获取变异记录

Retrieve the RefSNP record for one rsID. By default the output is abbreviated to the most useful fields. Both

rs268

and

are accepted.

bash

uv run scripts/dbsnp_cli.py get-variant rs268 --output /tmp/rs268.json
uv run scripts/dbsnp_cli.py get-variant 268 --assembly GCF_000001405.40 \
  --output /tmp/rs268.json

Arguments:

```
rsid
```
(positional, required): The RefSNP identifier.
```
--assembly
```
: RefSeq assembly accession (default:
```
GCF_000001405.40
```
= GRCh38).
```
--full
```
: Return the complete raw JSON payload — see warning below.
```
--output
```
: Output file path (default:
```
/tmp/dbsnp_output.json
```
).

Abbreviated output fields:

```
refsnp_id
```
: Numeric rsID
```
variant_type
```
: e.g.
```
snv
```
,
```
ins
```
,
```
del
```
,
```
delins
```
```
genes
```
: Sorted list of gene symbols (locus names)
```
clinical_significances
```
: List of clinical significance labels
```
minor_allele_frequencies
```
: Study name, allele count, total count
```
placements
```
: Genomic placements for the requested assembly

[!WARNING] About
--full
: The raw RefSNP payload is typically 50–500 KB and can exceed 1 MB for clinically significant variants with many submissions. Only use
--full
when you specifically need data absent from the abbreviated output — for example:
The complete HGVS nomenclature across every transcript and protein isoform.

Full submission history with individual submitter details and timestamps.

Population-level allele frequency breakdowns by sub-population within a study (e.g. per-population gnomAD counts).

The full set of genomic placements across multiple assemblies (GRCh37 and GRCh38 simultaneously).

Merge history showing which older rsIDs were merged into this one.

检索单个rsID的RefSNP记录。默认输出会缩写为最有用的字段。

rs268

和

两种格式均被接受。

bash

uv run scripts/dbsnp_cli.py get-variant rs268 --output /tmp/rs268.json
uv run scripts/dbsnp_cli.py get-variant 268 --assembly GCF_000001405.40 \
  --output /tmp/rs268.json

参数：

```
rsid
```
（位置参数，必填）：RefSNP标识符。
```
--assembly
```
：RefSeq组装版本编号（默认：
```
GCF_000001405.40
```
= GRCh38）。
```
--full
```
：返回完整的原始JSON负载——请查看下方警告。
```
--output
```
：输出文件路径（默认：
```
/tmp/dbsnp_output.json
```
）。

缩写输出字段：

```
refsnp_id
```
：数字形式的rsID
```
variant_type
```
：例如
```
snv
```
、
```
ins
```
、
```
del
```
、
```
delins
```
```
genes
```
：排序后的基因符号列表（基因座名称）
```
clinical_significances
```
：临床意义标签列表
```
minor_allele_frequencies
```
：研究名称、等位基因计数、总计数
```
placements
```
：请求组装版本的基因组定位

[!WARNING] 关于
--full
参数：原始RefSNP负载通常为50–500 KB，对于具有大量提交记录的临床相关变异，可能超过1 MB。仅当你特别需要缩写输出中没有的数据时才使用
--full
——例如：
每个转录本和蛋白质异构体的完整HGVS命名法。

包含单个提交者详细信息和时间戳的完整提交历史。

研究中按亚群体划分的群体水平等位基因频率细分（例如，gnomAD的按群体计数）。

跨多个组装版本（同时包含GRCh37和GRCh38）的完整基因组定位。

显示哪些旧rsID已合并到当前rsID的合并历史。

resolve-variant

— Genomic Coordinates → rsID

resolve-variant

— 基因组坐标 → rsID

Determine the rsID(s) for a variant given its genomic coordinates (chromosome, position, reference allele, alternate allele). This is the command to use when the user provides a variant as space-separated coordinates like

8 19962213 C T

bash

uv run scripts/dbsnp_cli.py resolve-variant 8 19962213 C T \
  --output /tmp/resolve.json

Arguments:

```
chrom
```
(positional): Chromosome number (e.g.
```
8
```
) or RefSeq sequence accession (e.g.
```
NC_000008.11
```
). Chromosomes X and Y must be passed as their numeric equivalents:
23
for X and
24
for Y.
```
pos
```
(positional): 1-based genomic position.
```
ref
```
(positional): Reference allele (e.g.
```
C
```
).
```
alts
```
(positional): Alternate allele(s), comma-separated (e.g.
```
T
```
).
```
--assembly
```
: RefSeq assembly accession (default:
```
GCF_000001405.40
```
).
```
--output
```
: Output file path (default:
```
/tmp/dbsnp_output.json
```
).

Output:

{"rsids": ["12345", "67890"]}

根据基因组坐标（染色体、位置、参考等位基因、替代等位基因）确定变异的rsID。当用户以空格分隔的坐标形式提供变异（如
8 19962213 C T
）时，请使用此命令。

bash

uv run scripts/dbsnp_cli.py resolve-variant 8 19962213 C T \
  --output /tmp/resolve.json

参数：

```
chrom
```
（位置参数）：染色体编号（例如
```
8
```
）或RefSeq序列编号（例如
```
NC_000008.11
```
）。X和Y染色体必须以数字等效形式传递：X为
23
，Y为
24
。
```
pos
```
（位置参数）：基于1的基因组位置。
```
ref
```
（位置参数）：参考等位基因（例如
```
C
```
）。
```
alts
```
（位置参数）：替代等位基因，以逗号分隔（例如
```
T
```
）。
```
--assembly
```
：RefSeq组装版本编号（默认：
```
GCF_000001405.40
```
）。
```
--output
```
：输出文件路径（默认：
```
/tmp/dbsnp_output.json
```
）。

输出：

{"rsids": ["12345", "67890"]}

resolve-rsid

— rsID → Genomic Coordinates

resolve-rsid

— rsID → 基因组坐标

Get the genomic placement (sequence ID and allele details) for a known rsID on a specific assembly.

bash

uv run scripts/dbsnp_cli.py resolve-rsid rs7412 --output /tmp/coords.json

Arguments:

```
rsid
```
(positional): The RefSNP identifier.
```
--assembly
```
: RefSeq assembly accession (default:
```
GCF_000001405.40
```
).
```
--output
```
: Output file path (default:
```
/tmp/dbsnp_output.json
```
).

Output:

{"rsid": "7412", "assembly": "...", "placements": [...]}

获取已知rsID在特定组装版本上的基因组定位（序列ID和等位基因详情）。

bash

uv run scripts/dbsnp_cli.py resolve-rsid rs7412 --output /tmp/coords.json

参数：

```
rsid
```
（位置参数）：RefSNP标识符。
```
--assembly
```
：RefSeq组装版本编号（默认：
```
GCF_000001405.40
```
）。
```
--output
```
：输出文件路径（默认：
```
/tmp/dbsnp_output.json
```
）。

输出：

{"rsid": "7412", "assembly": "...", "placements": [...]}

resolve-hgvs

— HGVS → rsID

resolve-hgvs

— HGVS → rsID

Find the rsID(s) corresponding to an HGVS expression.

bash

uv run scripts/dbsnp_cli.py resolve-hgvs 'NC_000008.11:g.19962213del' \
  --output /tmp/hgvs.json

Arguments:

```
hgvs
```
(positional): The HGVS string.
```
--assembly
```
: RefSeq assembly accession (default:
```
GCF_000001405.40
```
).
```
--output
```
: Output file path (default:
```
/tmp/dbsnp_output.json
```
).

Output:

{"rsids": ["12345"]}

[!TIP] HGVS strings often contain characters that shells interpret (colons, greater-than signs). Always wrap them in single quotes to prevent shell expansion.

查找与HGVS表达式对应的rsID。

bash

uv run scripts/dbsnp_cli.py resolve-hgvs 'NC_000008.11:g.19962213del' \
  --output /tmp/hgvs.json

参数：

```
hgvs
```
（位置参数）：HGVS字符串。
```
--assembly
```
：RefSeq组装版本编号（默认：
```
GCF_000001405.40
```
）。
```
--output
```
：输出文件路径（默认：
```
/tmp/dbsnp_output.json
```
）。

输出：

{"rsids": ["12345"]}

[!TIP] HGVS字符串通常包含Shell会解析的字符（冒号、大于号）。请始终用单引号包裹它们，以防止Shell展开。

search-region

— Regional Variant Search

search-region

— 区域变异搜索

Find all rsIDs within a bounded chromosomal region.

bash

uv run scripts/dbsnp_cli.py search-region 7 117100000 117300000 \
  --output /tmp/region.json

Arguments:

```
chrom
```
(positional): Chromosome (e.g.
```
7
```
). Use
23
for chromosome X and
24
for chromosome Y.
```
start
```
(positional): Start position.
```
end
```
(positional): End position.
```
--retmax
```
: Maximum rsIDs to return (default: 500, ceiling: 5 000).
```
--output
```
: Output file path (default:
```
/tmp/dbsnp_output.json
```
).

Output:

json

{
  "rsids": ["12345", "67890", "..."],
  "returned": 500,
  "total_available": 1423,
  "truncated": true,
  "note": "Only 500 of 1423 variants returned.  Increase --retmax ..."
}

When

total_available

exceeds the returned count, the output includes a

truncated

flag and a

note

. Increase

--retmax

to retrieve more (up to 5 000).

查找染色体边界区域内的所有rsID。

bash

uv run scripts/dbsnp_cli.py search-region 7 117100000 117300000 \
  --output /tmp/region.json

参数：

```
chrom
```
（位置参数）：染色体（例如
```
7
```
）。X染色体用
23
，Y染色体用
24
。
```
start
```
（位置参数）：起始位置。
```
end
```
（位置参数）：结束位置。
```
--retmax
```
：返回的最大rsID数量（默认：500，上限：5000）。
```
--output
```
：输出文件路径（默认：
```
/tmp/dbsnp_output.json
```
）。

输出：

json

{
  "rsids": ["12345", "67890", "..."],
  "returned": 500,
  "total_available": 1423,
  "truncated": true,
  "note": "Only 500 of 1423 variants returned.  Increase --retmax ..."
}

当

total_available

超过返回数量时，输出会包含

truncated

标志和

note

字段。可增加

--retmax

参数来获取更多结果（最多5000条）。

Typical Workflows

典型工作流程

Identify a known variant from coordinates

从坐标识别已知变异

bash

undefined

bash

undefined

Step 1: Map VCF coordinates to rsID

步骤1：将VCF坐标映射到rsID

uv run scripts/dbsnp_cli.py resolve-variant 19 44908684 T C
--output /tmp/step1.json

Step 2: Get the full details for the resolved rsID

步骤2：获取解析后的rsID的完整详情

uv run scripts/dbsnp_cli.py get-variant <rsid_from_step1>
--output /tmp/step2.json

undefined

uv run scripts/dbsnp_cli.py get-variant <rsid_from_step1>
--output /tmp/step2.json

undefined

Survey variants in a gene region

调查基因区域内的变异

bash

undefined

bash

undefined

Step 1: Find all variants in a region spanning the CFTR gene

步骤1：查找CFTR基因所在区域内的所有变异

uv run scripts/dbsnp_cli.py search-region 7 117100000 117300000
--retmax 1000 --output /tmp/region.json

Step 2: Retrieve details on individual rsIDs of interest

步骤2：检索感兴趣的单个rsID的详情

uv run scripts/dbsnp_cli.py get-variant <rsid> --output /tmp/detail.json

undefined

uv run scripts/dbsnp_cli.py get-variant <rsid> --output /tmp/detail.json

undefined

Translate HGVS notation to genomic coordinates

将HGVS符号转换为基因组坐标

bash

undefined

bash

undefined

Step 1: Get the rsID for an HGVS expression

步骤1：获取HGVS表达式对应的rsID

uv run scripts/dbsnp_cli.py resolve-hgvs 'NC_000019.10:g.44908684T>C'
--output /tmp/hgvs.json

Step 2: Resolve that rsID to VCF-style coordinates

步骤2：将该rsID解析为VCF格式的坐标

uv run scripts/dbsnp_cli.py resolve-rsid <rsid> --output /tmp/coords.json

undefined

uv run scripts/dbsnp_cli.py resolve-rsid <rsid> --output /tmp/coords.json

undefined

Assembly Defaults and Automatic Fallback

组装版本默认设置与自动回退

The Variation Services endpoints (used by

get-variant

resolve-variant

resolve-rsid

resolve-hgvs

) expect a RefSeq assembly accession. The RefSeq accession for GRCh38 is

GCF_000001405.40

, and for GRCh37 it is

GCF_000001405.25

The

search-region

subcommand always searches GRCh38 positions.

[!IMPORTANT] Automatic assembly fallback: The
resolve-variant
and
resolve-hgvs
commands automatically try GRCh38 first. If no rsIDs are found, they retry with GRCh37 before reporting failure. When a fallback occurs the output JSON includes a
"note"
field explaining which assembly succeeded. You do NOT need to manually retry with a different assembly — the script handles this transparently.

You only need to override

--assembly

when you specifically want to restrict the lookup to one assembly (e.g. because the user's coordinates are known to be GRCh37).

Variation Services端点（

get-variant

、

resolve-variant

、

resolve-rsid

、

resolve-hgvs

使用的端点）需要RefSeq组装版本编号。GRCh38的RefSeq编号是

GCF_000001405.40

，GRCh37的是

GCF_000001405.25

。

search-region

子命令始终搜索GRCh38位置。

[!IMPORTANT] 自动组装版本回退：
resolve-variant
和
resolve-hgvs
命令会自动先尝试GRCh38。如果未找到rsID，会自动重试GRCh37，然后再报告失败。当发生回退时，输出JSON会包含
"note"
字段，说明哪个组装版本成功。你不需要手动重试不同的组装版本——脚本会透明地处理这一点。

仅当你需要限制查询到某个特定组装版本时（例如，用户的坐标已知是GRCh37格式），才需要覆盖

--assembly

参数。

NCBI API Key and Rate Limiting

NCBI API密钥与速率限制

Without an API key the script is limited to 3 requests per second. With a key this increases to 10 requests per second.

bash

uv run scripts/dbsnp_cli.py get-variant rs268 --output out.json

If a

RateLimitError

is raised, pause execution and follow the prerequisite instructions to help the user add

NCBI_API_KEY

to the

.env

file. See

references/api-notes.md

for details.

没有API密钥时，脚本的请求速率限制为每秒3次。使用密钥后，速率限制提升至每秒10次。

bash

uv run scripts/dbsnp_cli.py get-variant rs268 --output out.json

如果触发

RateLimitError

，请暂停执行，并按照前置条件说明帮助用户将

NCBI_API_KEY

添加到

.env

文件中。详情请查看

references/api-notes.md

。

Troubleshooting HTTP 500 Errors

HTTP 500错误排查

Reference Allele Mismatch

参考等位基因不匹配

If you receive an HTTP 500 error with a message detailing that the asserted reference allele is not equal to the reference sequence:

What it means: The coordinate position is likely valid, but the reference allele (

ref

) you provided does not match the base at that position in the requested assembly.

Action: 1. DO NOT RETRY the exact same query mechanically. 2. Check the assembly: Coordinates are assembly-specific. 3. Switch assembly: If you were querying GRCh37, try GRCh38 (using

--assembly GCF_000001405.40

), or if querying GRCh38, try GRCh37 (using

--assembly GCF_000001405.25

如果你收到HTTP 500错误，且消息显示断言的参考等位基因与参考序列不相等：

含义：坐标位置可能有效，但你提供的参考等位基因（

ref

）与请求组装版本中该位置的碱基不匹配。

解决方法：1. 不要机械地重试完全相同的查询。2. 检查组装版本：坐标是特定于组装版本的。3. 切换组装版本：如果你之前查询的是GRCh37，尝试GRCh38（使用

--assembly GCF_000001405.40

）；如果查询的是GRCh38，尝试GRCh37（使用

--assembly GCF_000001405.25

）。

Common Mistakes

常见错误

Mistake: Forgetting to quote HGVS strings Fix: Wrap in single quotes:
```
'NC_000008.11:g.19962213del'
```
Mistake: Passing a chromosome name to
```
resolve-variant
```
instead of a sequence accession Fix: Use the numeric chromosome ID (e.g.
```
8
```
) or a RefSeq accession like
```
NC_000008.11
```
Mistake: Using
```
--full
```
on
```
get-variant
```
without needing it Fix: The abbreviated output covers most use cases;
```
--full
```
returns 50–500 KB+ of JSON
Mistake: Expecting
```
search-region
```
to return all results by default Fix: The default
```
--retmax
```
is 500; check
```
total_available
```
in the output to see if results were truncated
Mistake: Using GRCh37 coordinates with
```
search-region
```
Fix:
```
search-region
```
always uses GRCh38 positions; lift over coordinates first if starting from GRCh37
Mistake: Manually retrying
```
resolve-variant
```
or
```
resolve-hgvs
```
with a different
```
--assembly
```
when the first call fails Fix: The script automatically tries GRCh38 then GRCh37; a single call is sufficient
Mistake: Passing
```
X
```
or
```
Y
```
as the chromosome value Fix: Use the numeric equivalents:
```
23
```
for chromosome X and
```
24
```
for chromosome Y. The CLI treats chromosomes numerically by default.

错误：忘记给HGVS字符串加引号修复：用单引号包裹：
```
'NC_000008.11:g.19962213del'
```
错误：向
```
resolve-variant
```
传递染色体名称而非序列编号修复：使用数字染色体ID（例如
```
8
```
）或RefSeq编号如
```
NC_000008.11
```
错误：在不需要时对
```
get-variant
```
使用
```
--full
```
参数修复：缩写输出覆盖了大多数使用场景；
```
--full
```
会返回50–500 KB+的JSON数据
错误：期望
```
search-region
```
默认返回所有结果修复：默认
```
--retmax
```
为500；查看输出中的
```
total_available
```
字段以确认结果是否被截断
错误：对
```
search-region
```
使用GRCh37坐标修复：
```
search-region
```
始终使用GRCh38位置；如果从GRCh37开始，请先转换坐标
错误：当首次调用失败时，手动重试
```
resolve-variant
```
或
```
resolve-hgvs
```
并使用不同的
```
--assembly
```
参数修复：脚本会自动先尝试GRCh38再尝试GRCh37；一次调用就足够了
错误：传递
```
X
```
或
```
Y
```
作为染色体值修复：使用数字等效形式：X染色体用
```
23
```
，Y染色体用
```
24
```
。CLI默认按数字处理染色体。

dbsnp-database

Original

Translation

dbSNP Database Integration

dbSNP 数据库集成

Prerequisites

前置条件

Core Rules

核心规则

When to Use

使用场景

Command Selection Guide

命令选择指南

Quick Start

快速开始

Look up variant rs7412: type, gene, clinical significance, MAF

查询变异rs7412：类型、基因、临床意义、次要等位基因频率（MAF）

Find the rsID for a variant at chr8:19962213 C>T

查找chr8:19962213 C>T对应的rsID

Commands

命令详情

1. get-variant — Fetch Variant Record

1. get-variant — 获取变异记录

2. resolve-variant — Genomic Coordinates → rsID

2. resolve-variant — 基因组坐标 → rsID

3. resolve-rsid — rsID → Genomic Coordinates

3. resolve-rsid — rsID → 基因组坐标

4. resolve-hgvs — HGVS → rsID

4. resolve-hgvs — HGVS → rsID

5. search-region — Regional Variant Search

5. search-region — 区域变异搜索

Typical Workflows

典型工作流程

Identify a known variant from coordinates

从坐标识别已知变异

Step 1: Map VCF coordinates to rsID

步骤1：将VCF坐标映射到rsID

Step 2: Get the full details for the resolved rsID

步骤2：获取解析后的rsID的完整详情

Survey variants in a gene region

调查基因区域内的变异

Step 1: Find all variants in a region spanning the CFTR gene

步骤1：查找CFTR基因所在区域内的所有变异

Step 2: Retrieve details on individual rsIDs of interest

步骤2：检索感兴趣的单个rsID的详情

Translate HGVS notation to genomic coordinates

将HGVS符号转换为基因组坐标

Step 1: Get the rsID for an HGVS expression

步骤1：获取HGVS表达式对应的rsID

Step 2: Resolve that rsID to VCF-style coordinates

步骤2：将该rsID解析为VCF格式的坐标

Assembly Defaults and Automatic Fallback

组装版本默认设置与自动回退

NCBI API Key and Rate Limiting

NCBI API密钥与速率限制

Troubleshooting HTTP 500 Errors

HTTP 500错误排查

Reference Allele Mismatch

参考等位基因不匹配

Common Mistakes

常见错误

1.
`get-variant`
— Fetch Variant Record

1.
`get-variant`
— 获取变异记录

2.
`resolve-variant`
— Genomic Coordinates → rsID

2.
`resolve-variant`
— 基因组坐标 → rsID

3.
`resolve-rsid`
— rsID → Genomic Coordinates

3.
`resolve-rsid`
— rsID → 基因组坐标

4.
`resolve-hgvs`
— HGVS → rsID

4.
`resolve-hgvs`
— HGVS → rsID

5.
`search-region`
— Regional Variant Search

5.
`search-region`
— 区域变异搜索