uniprot-database

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UniProt Database Access

UniProt数据库访问

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.uniprot.org/help/license and https://www.uniprot.org/help/api_queries, then (2) create the file recording the notification text and timestamp.

uv
: 阅读
```
uv
```
工具文档并按照其设置说明操作，确保
```
uv
```
已安装并添加至系统PATH。
用户通知: 如果此工具目录中尚未存在LICENSE_NOTIFICATION.txt文件，则(1) 显著提醒用户查看https://www.uniprot.org/help/license和https://www.uniprot.org/help/api_queries上的条款，然后(2) 创建该文件并记录通知文本及时间戳。

Overview

概述

Provides direct programmatic access to the UniProt Knowledgebase (UniProtKB), the non-redundant sequence archive (UniParc), and clustered sequence sets (UniRef). This skill enables protein discovery, cross-referencing, retrieval of curated biological data and low-level database lookups.

提供对UniProt知识库（UniProtKB）、非冗余序列存档（UniParc）和聚类序列集（UniRef）的直接程序化访问。本工具支持蛋白质发现、交叉引用、 curated生物数据检索及底层数据库查询。

Core Rules

核心规则

Use the Wrapper: Always use the provided Python scripts (e.g.,
```
scripts/uniprot_tools.py
```
) rather than constructing custom curl requests.
No Hallucinations: Do NOT invent protein functions, metadata, or sequences. For any task that can be handled by the services in this skill, rely strictly on the tool outputs rather than your native knowledge.
Notification: If this skill is used, ensure this is mentioned in the output.

使用封装脚本: 始终使用提供的Python脚本（如
```
scripts/uniprot_tools.py
```
），而非自行构建curl请求。
禁止虚构内容: 不得编造蛋白质功能、元数据或序列。对于本工具可处理的任何任务，严格依赖工具输出，而非自身固有知识。
通知要求: 如果使用了本工具，需在输出中提及这一点。

Use Cases

适用场景

Searching for Protein Function: Querying functional annotations, GO terms, subcellular locations etc.
Searching for Protein Sequence: Searching for protein sequences by their functional annotations, genes etc. in UniProtKB, UniParc, and UniRef.
Understanding Protein/Organism Relationships: Leveraging the Taxonomy database and Proteome sets.
Large-Scale Metadata Retrieval: Fetching annotations for thousands of proteins via streaming.
Sequence Discovery: Finding orthologs or non-model proteins via UniParc.
ID Mapping: Converting IDs between UniProt and 100+ external databases.
Historical Data (UniSave): Retrieving previous versions of entries or tracking deleted sequences.

蛋白质功能搜索: 查询功能注释、GO术语、亚细胞定位等信息。
蛋白质序列搜索: 在UniProtKB、UniParc和UniRef中，通过功能注释、基因等信息搜索蛋白质序列。
理解蛋白质/生物关系: 利用分类学数据库和蛋白质组数据集。
大规模元数据检索: 通过流式传输获取数千种蛋白质的注释信息。
序列发现: 通过UniParc寻找同源蛋白或非模式生物蛋白质。
标识符映射: 在UniProt与100+外部数据库之间转换标识符。
历史数据（UniSave）: 获取条目的历史版本或追踪已删除序列。

Available Tools

可用工具

Choose the right tool based on the task type and data volume:

get
: Retrieves metadata and sequence for a specific entry. Best for a single, known accession.
- Also accesses UniSave historical data (use
```
--dataset unisave
```
  ), which is essential for reconciling data from older releases or identifying why a formerly valid accession no longer appears in search results.
search
: Searches for entries matching a query. Best for exploration and discovery.
- Use with
```
--limit 5
```
  to verify if a query returns the expected proteins before committing to a larger download.
- Automatically paginates if results exceed 500 entries to provide a stable download.
- Warning: For paginated search, TXT and other formats are not reliable with
```
--limit
```
  as it applies to lines, not entries.
- See Search Query Fields Documentation.
stream
: Streams all matching entries. Best for bulk retrieval of large datasets (up to 10,000,000 entries).
- Does NOT support
```
--limit
```
  ; always returns the full result set.
- Use
```
search
```
  with
```
--limit
```
  if you need a subset.
count
: Counts entries matching a query. Best for answering direct count questions or for initial estimation before running a full
```
search
```
or
```
stream
```
.
sparql
: Executes graph queries for complex discovery. Best for counting, exact sequence matches, and multi-database queries.
- See SPARQL Examples.
map
: Converts IDs between UniProt and 100+ databases. Best for ID mapping tasks.
- See ID Mapping Documentation.
- search
  vs.
  map
  : Try
```
search
```
  first before resorting to
```
map
```
  if not explicitly requested by the user. E.g., an external ID might be searchable in UniParc but fail to map to UniProtKB.

根据任务类型和数据量选择合适的工具：

get
: 检索特定条目的元数据和序列。最适用于单个已知登录号。
- 也可访问UniSave历史数据（使用
```
--dataset unisave
```
  ），这对于协调旧版本数据或识别曾经有效的登录号不再出现在搜索结果中的原因至关重要。
search
: 搜索匹配查询条件的条目。最适用于探索与发现。
- 使用
```
--limit 5
```
  在进行大规模下载前验证查询是否返回预期蛋白质。
- 如果结果超过500条，会自动分页以提供稳定的下载。
- 注意: 对于分页搜索，TXT及其他格式在使用
```
--limit
```
  时不可靠，因为该参数针对行数而非条目数。
- 参见搜索查询字段文档。
stream
: 流式传输所有匹配条目。最适用于批量检索大型数据集（最多10,000,000条条目）。
- 不支持
```
--limit
```
  ；始终返回完整结果集。
- 如果需要子集数据，请使用带
```
--limit
```
  的
```
search
```
  。
count
: 统计匹配查询条件的条目数量。最适用于直接回答计数问题或在运行完整的
```
search
```
或
```
stream
```
前进行初步估算。
sparql
: 执行图查询以进行复杂发现。最适用于计数、精确序列匹配和多数据库查询。
- 参见SPARQL示例。
map
: 在UniProt与100+数据库之间转换标识符。最适用于标识符映射任务。
- 参见标识符映射文档。
- search
  vs.
  map
  : 如果用户未明确要求，优先尝试
```
search
```
  而非
```
map
```
  。例如，某个外部ID可能在UniParc中可搜索，但无法映射到UniProtKB。

Workflows

工作流程

Typical Protein Research Workflow

典型蛋白质研究工作流程

Copy this checklist and track progress:

Step 1: Identify target protein(s) and organism(s).
Step 2: Search UniProtKB for reviewed entries (
```
reviewed:true
```
).
Step 3: If no reviewed entries, search unreviewed or use UniParc for sequence discovery.
Step 4: Map external IDs (e.g., Ensembl, PDB) to UniProt Accessions if necessary.
Step 5: Retrieve functional metadata or sequence in desired format (JSON, FASTA).

复制此清单并跟踪进度：

步骤1：确定目标蛋白质和生物。
步骤2：在UniProtKB中搜索已评审条目（
```
reviewed:true
```
）。
步骤3：如果没有已评审条目，搜索未评审条目或使用UniParc进行序列发现。
步骤4：如有必要，将外部ID（如Ensembl、PDB）映射到UniProt登录号。
步骤5：以所需格式（JSON、FASTA）检索功能元数据或序列。

Handling Search Misses (e.g. Gene Search in Non-Model Organisms)

处理搜索无结果情况（如非模式生物中的基因搜索）

If a direct query (e.g.,

gene:SYMBOL

) fails:

Pivot to Protein Name: Search for the common protein name (e.g.,
```
protein_name:Alpha-crystallin A
```
).
Use UniParc: Search the UniParc dataset, which integrates sequences from across all of life, even if they aren't fully annotated in UniProtKB.
Check Orthologs/Canonical: Resolve the Human/Mouse ortholog first to find the correct naming/mnemonic.

如果直接查询（如

gene:SYMBOL

）失败：

转向蛋白质名称: 搜索常见蛋白质名称（如
```
protein_name:Alpha-crystallin A
```
）。
使用UniParc: 搜索UniParc数据集，该数据集整合了所有生命形式的序列，即使这些序列在UniProtKB中未被完整注释。
检查同源蛋白/标准序列: 先确定人类/小鼠同源蛋白，以找到正确的命名/助记符。

Bulk Retrieval Priorities

批量检索优先级

[!IMPORTANT] Always prefer stream
or sparql
for bulk data.
search
is suitable for exploration; if results exceed 500 entries, it automatically paginates to provide a stable download.

Priority 0:
count
: ALWAYS check the result count before running a
```
search
```
or
```
stream
```
.
Priority 1:
stream
: The primary method for bulk data retrieval (up to 10M entries). Does NOT support
```
--limit
```
; always returns all results.
Priority 2:
sparql
: Best for complex filtering and exact matching during retrieval.

[!IMPORTANT] 对于批量数据，始终优先使用**
stream
或
sparql
**。
search
适用于探索；如果结果超过500条，它会自动分页以提供稳定的下载。

优先级0:
count
: 在运行
```
search
```
或
```
stream
```
前，务必检查结果数量。
优先级1:
stream
: 批量数据检索的主要方法（最多1000万条条目）。不支持
```
--limit
```
；始终返回所有结果。
优先级2:
sparql
: 最适用于检索过程中的复杂过滤和精确匹配。

Sequence-Based Search (Exact Match)

基于序列的搜索（精确匹配）

[!IMPORTANT] Use SPARQL when searching for a protein by its full amino acid sequence. The REST API
/search
endpoint does not support direct sequence-string lookups. For any non-exact match use specialized sequence similarity search skills. Use UniParc if you cannot find query in UniProt.

SPARQL Query Pattern (UniProt):

text

PREFIX up: <http://purl.uniprot.org/core/>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
SELECT ?protein ?name WHERE {
  ?protein a up:Protein ;
           up:sequence/rdf:value "SEQUENCE_HERE" .
  OPTIONAL {
    ?protein up:recommendedName/up:fullName ?name .
  }
}

SPARQL Query Pattern (UniParc):

text

PREFIX up: <http://purl.uniprot.org/core/>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>

SELECT ?uniparc ?val WHERE {
  GRAPH <http://sparql.uniprot.org/uniparc> {
    ?uniparc a up:Sequence ;
             rdf:value ?val .
    FILTER (?val = "SEQUENCE_HERE")
  }
}

[!IMPORTANT] 当通过完整氨基酸序列搜索蛋白质时，请使用SPARQL。REST API的
/search
端点不支持直接的序列字符串查找。对于非精确匹配，请使用专门的序列相似性搜索工具。如果在UniProt中找不到查询结果，请使用UniParc。

SPARQL查询模式（UniProt）：

text

PREFIX up: <http://purl.uniprot.org/core/>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
SELECT ?protein ?name WHERE {
  ?protein a up:Protein ;
           up:sequence/rdf:value "SEQUENCE_HERE" .
  OPTIONAL {
    ?protein up:recommendedName/up:fullName ?name .
  }
}

SPARQL查询模式（UniParc）：

text

PREFIX up: <http://purl.uniprot.org/core/>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>

SELECT ?uniparc ?val WHERE {
  GRAPH <http://sparql.uniprot.org/uniparc> {
    ?uniparc a up:Sequence ;
             rdf:value ?val .
    FILTER (?val = "SEQUENCE_HERE")
  }
}

Counting Entries Efficiently

高效统计条目数量

[!IMPORTANT] Use count
or SPARQL
for counting entries (e.g., "How many proteins in Human?").

Counting Pattern (Proteins per Organism):

text

PREFIX up: <http://purl.uniprot.org/core/>
PREFIX taxon: <http://purl.uniprot.org/taxonomy/>
SELECT (COUNT(?protein) AS ?count) WHERE {
  ?protein a up:Protein ;
           up:reviewed true ;
           up:organism taxon:9606 .
}

[!IMPORTANT] 使用**
count
或
SPARQL
**统计条目数量（如“人类有多少种蛋白质？”）。

统计模式（每个生物的蛋白质数量）：

text

PREFIX up: <http://purl.uniprot.org/core/>
PREFIX taxon: <http://purl.uniprot.org/taxonomy/>
SELECT (COUNT(?protein) AS ?count) WHERE {
  ?protein a up:Protein ;
           up:reviewed true ;
           up:organism taxon:9606 .
}

REST Search Syntax

REST搜索语法

No Commas in Lists: Commas are treated as literals. Use capitalized
```
OR
```
to separate items.
- Grouped:
```
accession:(P12345 OR P67890)
```
- Repeated:
```
accession:P12345 OR accession:P67890
```
Space = AND: E.g.,
```
gene:p53 human
```
searches for both.

列表中不要使用逗号: 逗号会被视为文字。使用大写的
```
OR
```
分隔条目。
- 分组写法:
```
accession:(P12345 OR P67890)
```
- 重复写法:
```
accession:P12345 OR accession:P67890
```
空格 = AND: 例如，
```
gene:p53 human
```
会同时搜索这两个条件。

Example Commands

示例命令

Below are example commands for each mode of

uniprot_tools.py

Count total number of entries for a given query.

bash

uv run scripts/uniprot_tools.py count "taxonomy_id:9606"

Search for entries.

bash

uv run scripts/uniprot_tools.py search "gene:p53 AND reviewed:true" --limit 5

Retrieve a single entry by accession.

bash

uv run scripts/uniprot_tools.py get P04637

Retrieve Historical/Deleted Entry (UniSave).

bash

uv run scripts/uniprot_tools.py get P04637 --dataset unisave

Stream large result sets for bulk retrieval (returns ALL matched entries, no

--limit

support).

bash

uv run scripts/uniprot_tools.py stream "taxonomy_id:9606 AND reviewed:true" --format tsv --fields accession,gene_names > human_reviewed.tsv

Map IDs from one database to another.

bash

uv run scripts/uniprot_tools.py map "P04637" --from_db UniProtKB_AC-ID --to_db Gene_Name

Execute graph queries with SPARQL.

bash

uv run scripts/uniprot_tools.py sparql 'PREFIX up: <http://purl.uniprot.org/core/> SELECT ?protein WHERE { ?protein a up:Protein ; up:reviewed true . } LIMIT 5'

以下是

uniprot_tools.py

各模式的示例命令。

统计给定查询的总条目数。

bash

uv run scripts/uniprot_tools.py count "taxonomy_id:9606"

搜索条目。

bash

uv run scripts/uniprot_tools.py search "gene:p53 AND reviewed:true" --limit 5

通过登录号检索单个条目。

bash

uv run scripts/uniprot_tools.py get P04637

检索历史/已删除条目（UniSave）。

bash

uv run scripts/uniprot_tools.py get P04637 --dataset unisave

流式传输大型结果集以进行批量检索（返回所有匹配条目，不支持

--limit

）。

bash

uv run scripts/uniprot_tools.py stream "taxonomy_id:9606 AND reviewed:true" --format tsv --fields accession,gene_names > human_reviewed.tsv

在不同数据库之间映射标识符。

bash

uv run scripts/uniprot_tools.py map "P04637" --from_db UniProtKB_AC-ID --to_db Gene_Name

使用SPARQL执行图查询。

bash

uv run scripts/uniprot_tools.py sparql 'PREFIX up: <http://purl.uniprot.org/core/> SELECT ?protein WHERE { ?protein a up:Protein ; up:reviewed true . } LIMIT 5'

Common Mistakes

常见错误

Using
name:
instead of
protein_name:
:
```
name:
```
is not a supported query term, use
```
protein_name:
```
instead.
Ignoring UniParc: Non-model organisms might only exist in UniParc.
Confusing Accession with UPI: UniProtKB Accessions (e.g.,
```
P04637
```
) are linked to functional metadata; UniParc IDs (
```
UPI...
```
) are for sequences only. You can find cross-references from UniParc IDs to UniProtKB Accessions using the ID Mapping tool.
Using UniProtKB-AC as Target in ID Mapping: Use
```
UniProtKB
```
instead.
Giving up on Complex Queries: If a complex search query fails, try to use SPARQL instead of giving up.
Using IDs Without Verifying Meaning: NEVER assume you know the meaning of an ID (e.g. keyword, GO term, Pfam ID etc.). ALWAYS look up the natural language description/meaning of an ID in UniProt before using it for search to ensure it matches your intended search term.
Ignoring Citation Noise in Broad Searches: Broad text searches (
```
search "term"
```
) frequently return false positives (e.g., common maintenance proteins) because UniProt searches full metadata, including publication titles. ALWAYS prefer field-specific filters like
```
cc_function:
```
or
```
protein_name:
```
for functional discovery.
Forgetting to Quote Short Search Terms: Short, unquoted terms (e.g.,
```
lanM
```
) can match substrings in organism names (e.g., Lancefieldella) or other fields. Use quotes and field prefixes (e.g.,
```
gene:lanM
```
) to isolate true hits.
Manipulating Protein Sequences Directly: Always use code and tools for sequence-based operations. Do not attempt to edit, truncate, or modify protein sequences manually.
Over-using Search for Bulk Data: DO NOT use
```
search
```
for retrieving millions of entries if
```
stream
```
or
```
sparql
```
can do the job. Streaming is more efficient for very large datasets. Note that
```
stream
```
has a hard limit of 10,000,000 outputs and does NOT support
```
--limit
```
.
Forgetting to Check Data Volume: ALWAYS perform a
```
count
```
before running a
```
search
```
without
```
--limit
```
or before using
```
stream
```
. Unlimited queries can take a long time and consume significant resources if millions of entries are returned.
Using
--limit
with
stream
: The
```
stream
```
command does NOT support
```
--limit
```
. If you need a limited number of results, use
```
search
```
with
```
--limit
```
instead.
Forgetting the License Notice: Do not neglect to state that the UniProt Database was used and to advise the user to review the licensing terms when presenting results for the first time. Even if the task is concise, this attribution is required in the first response containing UniProt data.

使用
name:
而非
protein_name:
:
```
name:
```
不是支持的查询术语，请使用
```
protein_name:
```
。
忽略UniParc: 非模式生物的蛋白质可能仅存在于UniParc中。
混淆登录号与UPI: UniProtKB登录号（如
```
P04637
```
）关联功能元数据；UniParc ID（
```
UPI...
```
）仅用于序列。您可以使用标识符映射工具从UniParc ID查找对应的UniProtKB登录号。
在标识符映射中使用UniProtKB-AC作为目标: 请使用
```
UniProtKB
```
替代。
放弃复杂查询: 如果复杂搜索查询失败，请尝试使用SPARQL而非放弃。
使用标识符而不验证其含义: 切勿假设您知道某个标识符的含义（如关键词、GO术语、Pfam ID等）。在用于搜索前，务必在UniProt中查找该标识符的自然语言描述/含义，确保其与您预期的搜索词匹配。
忽略广泛搜索中的文献干扰: 广泛文本搜索（
```
search "term"
```
）经常返回假阳性结果（如常见的维持蛋白），因为UniProt会搜索完整元数据，包括文献标题。对于功能发现，始终优先使用特定字段过滤器，如
```
cc_function:
```
或
```
protein_name:
```
。
忘记给短搜索术语加引号: 未加引号的短术语（如
```
lanM
```
）可能匹配生物名称（如Lancefieldella）或其他字段中的子字符串。使用引号和字段前缀（如
```
gene:lanM
```
）来筛选出准确结果。
直接操作蛋白质序列: 序列相关操作始终使用代码和工具。请勿尝试手动编辑、截断或修改蛋白质序列。
过度使用Search进行批量数据检索: 如果
```
stream
```
或
```
sparql
```
可以完成任务，请勿使用
```
search
```
检索数百万条条目。流式传输对于超大型数据集更高效。请注意，
```
stream
```
有10,000,000条输出的硬限制，且不支持
```
--limit
```
。
忘记检查数据量: 在运行不带
```
--limit
```
的
```
search
```
或使用
```
stream
```
前，务必执行
```
count
```
。如果返回数百万条条目，无限制查询可能耗时很长并消耗大量资源。
在
stream
中使用
--limit
:
```
stream
```
命令不支持
```
--limit
```
。如果需要有限数量的结果，请使用带
```
--limit
```
的
```
search
```
。
忘记许可证通知: 在首次展示包含UniProt数据的结果时，务必说明使用了UniProt数据库并建议用户查看许可条款。即使任务简洁，首次响应中也必须包含此归因。

Reference Materials

参考资料

SPARQL Examples
Search Query Fields Documentation
ID Mapping Documentation
UniProt Evidence Docs

Underlying API Endpoints (Used by

scripts/uniprot_tools.py

get

search

stream

count

rest.uniprot.org/{dataset}/

```
map
```
->
```
rest.uniprot.org/idmapping/
```
```
sparql
```
->
```
sparql.uniprot.org/sparql
```

get --dataset unisave

rest.uniprot.org/unisave/

SPARQL示例
搜索查询字段文档
标识符映射文档
UniProt证据文档

底层API端点（由

scripts/uniprot_tools.py

使用）：

get

search

stream

count

rest.uniprot.org/{dataset}/

```
map
```
->
```
rest.uniprot.org/idmapping/
```
```
sparql
```
->
```
sparql.uniprot.org/sparql
```

get --dataset unisave

rest.uniprot.org/unisave/