chembl-database

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ChEMBL Database Query

ChEMBL数据库查询

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://chembl.gitbook.io/chembl-interface-documentation/about, then (2) create the file recording the notification text and timestamp.

uv
：阅读
```
uv
```
技能并遵循其设置说明，确保
```
uv
```
已安装且在PATH路径中。
用户通知：若此技能目录中不存在LICENSE_NOTIFICATION.txt文件，则(1) 显著通知用户查看https://chembl.gitbook.io/chembl-interface-documentation/about上的条款，然后(2) 创建记录通知文本和时间戳的文件。

Core Rules

核心规则

[!IMPORTANT] Use the Utility Scripts: You MUST ALWAYS use the provided utility script
```
scripts/chembl_api.py
```
for all ChEMBL API interactions, including checking status. NEVER use
```
curl
```
or custom Python requests to query the ChEMBL API directly. This ensures rate limit is enfoced and also retries on network errors.
Output to File (Required): The
```
--output
```
flag is required for every subcommand. All JSON results are written to the specified file. After running the command, read the output file with jq or your own code to extract the data. List results are typically wrapped in a JSON array keyed by the endpoint name (e.g.,
```
molecules
```
,
```
activities
```
).
Notification: If this skill is used, ensure this is mentioned in the output.

[!IMPORTANT] 使用实用脚本：所有ChEMBL API交互（包括状态检查）必须使用提供的实用脚本
```
scripts/chembl_api.py
```
。绝不能直接使用
```
curl
```
或自定义Python请求查询ChEMBL API。这能确保速率限制被执行，并在网络错误时自动重试。
输出到文件（必填）：每个子命令都必须使用
```
--output
```
参数。所有JSON结果都会写入指定文件。运行命令后，可使用jq或自定义代码读取输出文件以提取数据。列表结果通常被包裹在以端点名称为键的JSON数组中（例如
```
molecules
```
、
```
activities
```
）。
通知说明：若使用此技能，需在输出中提及这一点。

Utility Script

实用脚本

All ChEMBL API queries use one script with subcommands:

bash

uv run scripts/chembl_api.py <subcommand> --output <file> [options]

所有ChEMBL API查询都通过一个脚本及子命令完成：

bash

uv run scripts/chembl_api.py <subcommand> --output <file> [options]

1. Check API Status

1. 检查API状态

bash

uv run scripts/chembl_api.py status --output /tmp/status.json

bash

uv run scripts/chembl_api.py status --output /tmp/status.json

2. Molecule Queries

2. 分子查询

Fetch by ChEMBL ID:

bash uv run scripts/chembl_api.py molecule --id CHEMBL25 --output /tmp/mol.json

Search by name:

bash uv run scripts/chembl_api.py molecule --search "aspirin" --limit 3 --output /tmp/mol_search.json

Batch fetch:

bash uv run scripts/chembl_api.py molecule --ids "CHEMBL25;CHEMBL1642" --limit 10 --output /tmp/mol_batch.json

Filter by properties:

bash uv run scripts/chembl_api.py molecule --filter molecule_properties__mw_freebase__lte=500 --limit 5 --output /tmp/mol_filter.json

Filter by range:

bash uv run scripts/chembl_api.py molecule --filter molecule_properties__mw_freebase__range=150,200 --limit 5 --output /tmp/mol_range.json

Download SDF structure file:

bash uv run scripts/chembl_api.py molecule --id CHEMBL25 --dl_format sdf --output /tmp/aspirin.sdf

Tip: SDF/MOL files can be passed directly to tools like PyMOL or RDKit for 3D visualization and analysis.

按ChEMBL ID获取：

bash uv run scripts/chembl_api.py molecule --id CHEMBL25 --output /tmp/mol.json

按名称搜索：

bash uv run scripts/chembl_api.py molecule --search "aspirin" --limit 3 --output /tmp/mol_search.json

批量获取：

bash uv run scripts/chembl_api.py molecule --ids "CHEMBL25;CHEMBL1642" --limit 10 --output /tmp/mol_batch.json

按属性过滤：

bash uv run scripts/chembl_api.py molecule --filter molecule_properties__mw_freebase__lte=500 --limit 5 --output /tmp/mol_filter.json

按范围过滤：

bash uv run scripts/chembl_api.py molecule --filter molecule_properties__mw_freebase__range=150,200 --limit 5 --output /tmp/mol_range.json

下载SDF结构文件：

bash uv run scripts/chembl_api.py molecule --id CHEMBL25 --dl_format sdf --output /tmp/aspirin.sdf

提示：SDF/MOL文件可直接传入PyMOL或RDKit等工具进行3D可视化与分析。

3. Target Queries

3. 靶点查询

Search for targets:

bash uv run scripts/chembl_api.py target --search "EGFR" --limit 5 --output /tmp/targets.json

Fetch by ID:

bash uv run scripts/chembl_api.py target --id CHEMBL203 --output /tmp/egfr.json

搜索靶点：

bash uv run scripts/chembl_api.py target --search "EGFR" --limit 5 --output /tmp/targets.json

按ID获取：

bash uv run scripts/chembl_api.py target --id CHEMBL203 --output /tmp/egfr.json

4. Bioactivity Data

4. 生物活性数据

Fetch activity by ID:

bash uv run scripts/chembl_api.py activity --id 31863 --output /tmp/act.json

Search activities:

bash uv run scripts/chembl_api.py activity --search "EGFR" --limit 5 --output /tmp/act_search.json

Filter activities for a target:

bash uv run scripts/chembl_api.py activity --filter target_chembl_id=CHEMBL203 standard_type=IC50 --limit 10 --output /tmp/egfr_ic50.json

Normalize bioactivity units to nM:

bash uv run scripts/chembl_api.py activity --filter target_chembl_id=CHEMBL203 standard_type=IC50 --limit 5 --normalize --output /tmp/egfr_normalized.json

Important: Bioactivity values come in various units (nM, µM, pM). Use
--normalize
to convert all values to nM for consistent comparison. Each record will include
normalized_value_nM
and
normalization_note
.

按ID获取活性数据：

bash uv run scripts/chembl_api.py activity --id 31863 --output /tmp/act.json

搜索活性数据：

bash uv run scripts/chembl_api.py activity --search "EGFR" --limit 5 --output /tmp/act_search.json

按靶点过滤活性数据：

bash uv run scripts/chembl_api.py activity --filter target_chembl_id=CHEMBL203 standard_type=IC50 --limit 10 --output /tmp/egfr_ic50.json

将生物活性单位标准化为nM：

bash uv run scripts/chembl_api.py activity --filter target_chembl_id=CHEMBL203 standard_type=IC50 --limit 5 --normalize --output /tmp/egfr_normalized.json

重要说明：生物活性值有多种单位（nM、µM、pM）。使用
--normalize
参数可将所有值转换为nM，以便统一比较。每条记录都会包含
normalized_value_nM
和
normalization_note
字段。

5. Drug Information

5. 药物信息

Fetch drug details:

bash uv run scripts/chembl_api.py drug --id CHEMBL25 --output /tmp/drug.json

Drug indications:

bash uv run scripts/chembl_api.py drug_indication --filter molecule_chembl_id=CHEMBL25 --limit 10 --output /tmp/indications.json

Filter indications by phase:

bash uv run scripts/chembl_api.py drug_indication --filter molecule_chembl_id=CHEMBL25 max_phase_for_ind=4.0 --limit 10 --output /tmp/approved_indications.json

Drug warnings:

bash uv run scripts/chembl_api.py drug_warning --limit 5 --output /tmp/warnings.json

Mechanisms of action:

bash uv run scripts/chembl_api.py mechanism --filter molecule_chembl_id=CHEMBL25 --limit 5 --output /tmp/mech.json

获取药物详情：

bash uv run scripts/chembl_api.py drug --id CHEMBL25 --output /tmp/drug.json

药物适应症：

bash uv run scripts/chembl_api.py drug_indication --filter molecule_chembl_id=CHEMBL25 --limit 10 --output /tmp/indications.json

按研发阶段过滤适应症：

bash uv run scripts/chembl_api.py drug_indication --filter molecule_chembl_id=CHEMBL25 max_phase_for_ind=4.0 --limit 10 --output /tmp/approved_indications.json

药物警示信息：

bash uv run scripts/chembl_api.py drug_warning --limit 5 --output /tmp/warnings.json

作用机制：

bash uv run scripts/chembl_api.py mechanism --filter molecule_chembl_id=CHEMBL25 --limit 5 --output /tmp/mech.json

6. Structure-Based Searches

6. 基于结构的搜索

Note: Both similarity and substructure searches are performed server-side on ChEMBL's pre-indexed database. They do not require a local RDKit installation.

Similarity search (SMILES + threshold):

bash uv run scripts/chembl_api.py similarity --smiles "CC(=O)Oc1ccccc1C(=O)O" --similarity 85 --limit 5 --output /tmp/similar.json

Substructure search (SMILES):

bash uv run scripts/chembl_api.py substructure --smiles "c1ccccc1" --limit 5 --output /tmp/substruct.json

注意：相似性和子结构搜索均在ChEMBL的预索引数据库服务器端执行，无需本地安装RDKit。

相似性搜索（SMILES + 阈值）：

bash uv run scripts/chembl_api.py similarity --smiles "CC(=O)Oc1ccccc1C(=O)O" --similarity 85 --limit 5 --output /tmp/similar.json

子结构搜索（SMILES）：

bash uv run scripts/chembl_api.py substructure --smiles "c1ccccc1" --limit 5 --output /tmp/substruct.json

7. Compound Image

7. 化合物图像

Download a 2D structure image (SVG by default, scalable for publication):

bash

uv run scripts/chembl_api.py image --id CHEMBL25 --output /tmp/chembl25.svg

Options:

```
--dimensions
```
: Image size in pixels (max 500, default 500).
```
--engine
```
: Rendering engine (default: rdkit).
```
--img_format
```
: Output format —
```
svg
```
(default, vector) or
```
png
```
(raster).

下载2D结构图像（默认SVG格式，可缩放用于出版物）：

bash

uv run scripts/chembl_api.py image --id CHEMBL25 --output /tmp/chembl25.svg

可选参数：

```
--dimensions
```
: 图像像素尺寸（最大500，默认500）。
```
--engine
```
: 渲染引擎（默认：rdkit）。
```
--img_format
```
: 输出格式 —
```
svg
```
（默认，矢量图）或
```
png
```
（位图）。

8. Cross-Referencing with Other Databases

8. 与其他数据库交叉引用

ChEMBL integrates with UniProt, Ensembl, PubChem, and other databases. Common cross-referencing patterns:

Find a ChEMBL target from a UniProt accession:

bash uv run scripts/chembl_api.py target --filter target_components__accession=P00533 --limit 5 --output /tmp/uniprot_target.json

Resolve any ChEMBL ID to its entity type:

bash uv run scripts/chembl_api.py chembl_id_lookup --id CHEMBL203 --output /tmp/lookup.json

Look up cross-reference sources:

bash uv run scripts/chembl_api.py xref_source --limit 10 --output /tmp/xrefs.json

Tip: Use the
target_component
endpoint to find UniProt accessions, gene names, and protein sequences for any ChEMBL target.

ChEMBL与UniProt、Ensembl、PubChem等数据库集成。常见交叉引用方式：

通过UniProt编号查找ChEMBL靶点：

bash uv run scripts/chembl_api.py target --filter target_components__accession=P00533 --limit 5 --output /tmp/uniprot_target.json

解析ChEMBL ID对应的实体类型：

bash uv run scripts/chembl_api.py chembl_id_lookup --id CHEMBL203 --output /tmp/lookup.json

查看交叉引用来源：

bash uv run scripts/chembl_api.py xref_source --limit 10 --output /tmp/xrefs.json

提示：使用
target_component
端点可查找任意ChEMBL靶点对应的UniProt编号、基因名称和蛋白质序列。

9. Pagination

9. 分页

All list endpoints support

--limit

and

--offset

for pagination:

bash

undefined

所有列表端点均支持

--limit

和

--offset

参数用于分页：

bash

undefined

First page: 2 results starting at offset 0

第一页：从偏移量0开始返回2条结果

uv run scripts/chembl_api.py molecule --limit 2 --offset 0 --output /tmp/page1.json

Second page: next 2 results starting at offset 2

第二页：从偏移量2开始返回下2条结果

uv run scripts/chembl_api.py molecule --limit 2 --offset 2 --output /tmp/page2.json


The response includes `page_meta` with `total_count`, `limit`, `offset`, `next`,
and `previous` links. Use successive `--offset` values to page through large
result sets.

--------------------------------------------------------------------------------

uv run scripts/chembl_api.py molecule --limit 2 --offset 2 --output /tmp/page2.json


响应结果包含`page_meta`字段，其中有`total_count`、`limit`、`offset`、`next`和`previous`链接。可通过连续设置`--offset`值来遍历大型结果集。

--------------------------------------------------------------------------------

10. Other Endpoints

10. 其他端点

All remaining endpoints follow the same pattern:

bash

uv run scripts/chembl_api.py <subcommand> --output <file> [--id ID | --ids ID1;ID2 | --search QUERY] [--limit N] [--offset N] [--filter KEY=VAL ...]

Key subcommands at a glance:

```
molecule
```
(searchable: true): Molecules/compounds — the primary entry point
```
target
```
(searchable: true): Drug targets (proteins, organisms, etc.)
```
activity
```
(searchable: true): Bioactivity data (IC50, Ki, EC50, etc.)
```
drug
```
(searchable: false): Approved drugs
```
mechanism
```
(searchable: false): Mechanisms of action
```
assay
```
(searchable: true): Assay descriptions
```
similarity
```
(searchable: false): Similarity search (special)
```
substructure
```
(searchable: false): Substructure search (special)
```
image
```
(searchable: false): Compound image download (special)

Full subcommand list:

```
activity_supp
```
(searchable: false): Supplementary activity data
```
assay_class
```
(searchable: false): Assay classifications
```
atc_class
```
(searchable: false): ATC drug classifications
```
binding_site
```
(searchable: false): Binding site information
```
biotherapeutic
```
(searchable: false): Biotherapeutic molecules
```
cell_line
```
(searchable: false): Cell line details
```
chembl_id_lookup
```
(searchable: true): ChEMBL ID resolution
```
chembl_release
```
(searchable: false): Database release info
```
compound_record
```
(searchable: false): Compound records
```
compound_structural_alert
```
(searchable: false): Structural alerts
```
document
```
(searchable: true): Literature documents
```
document_similarity
```
(searchable: false): Document similarity
```
drug_indication
```
(searchable: false): Drug indications
```
drug_warning
```
(searchable: false): Drug safety warnings
```
go_slim
```
(searchable: false): GO slim terms
```
metabolism
```
(searchable: false): Metabolism data
```
molecule_form
```
(searchable: false): Molecule forms (salts/parents)
```
organism
```
(searchable: false): Organisms
```
protein_classification
```
(searchable: true): Protein classifications
```
source
```
(searchable: false): Data sources
```
target_component
```
(searchable: false): Target protein components
```
target_relation
```
(searchable: false): Target relationships
```
tissue
```
(searchable: false): Tissue types
```
xref_source
```
(searchable: false): Cross-reference sources
```
status
```
(searchable: false): API status check (special)

所有剩余端点遵循相同格式：

bash

uv run scripts/chembl_api.py <subcommand> --output <file> [--id ID | --ids ID1;ID2 | --search QUERY] [--limit N] [--offset N] [--filter KEY=VAL ...]

核心子命令概览：

```
molecule
```
（可搜索：是）：分子/化合物 — 主要入口
```
target
```
（可搜索：是）：药物靶点（蛋白质、生物等）
```
activity
```
（可搜索：是）：生物活性数据（IC50、Ki、EC50等）
```
drug
```
（可搜索：否）：已获批药物
```
mechanism
```
（可搜索：否）：作用机制
```
assay
```
（可搜索：是）：试验描述
```
similarity
```
（可搜索：否）：相似性搜索（特殊）
```
substructure
```
（可搜索：否）：子结构搜索（特殊）
```
image
```
（可搜索：否）：化合物图像下载（特殊）

完整子命令列表：

```
activity_supp
```
（可搜索：否）：补充活性数据
```
assay_class
```
（可搜索：否）：试验分类
```
atc_class
```
（可搜索：否）：ATC药物分类
```
binding_site
```
（可搜索：否）：结合位点信息
```
biotherapeutic
```
（可搜索：否）：生物治疗分子
```
cell_line
```
（可搜索：否）：细胞系详情
```
chembl_id_lookup
```
（可搜索：是）：ChEMBL ID解析
```
chembl_release
```
（可搜索：否）：数据库版本信息
```
compound_record
```
（可搜索：否）：化合物记录
```
compound_structural_alert
```
（可搜索：否）：结构警示
```
document
```
（可搜索：是）：文献资料
```
document_similarity
```
（可搜索：否）：文献相似性
```
drug_indication
```
（可搜索：否）：药物适应症
```
drug_warning
```
（可搜索：否）：药物安全警示
```
go_slim
```
（可搜索：否）：GO精简术语
```
metabolism
```
（可搜索：否）：代谢数据
```
molecule_form
```
（可搜索：否）：分子形式（盐/母核）
```
organism
```
（可搜索：否）：生物种类
```
protein_classification
```
（可搜索：是）：蛋白质分类
```
source
```
（可搜索：否）：数据源
```
target_component
```
（可搜索：否）：靶点蛋白质组件
```
target_relation
```
（可搜索：否）：靶点关联关系
```
tissue
```
（可搜索：否）：组织类型
```
xref_source
```
（可搜索：否）：交叉引用来源
```
status
```
（可搜索：否）：API状态检查（特殊）

Common Options

通用参数

```
--output FILE
```
: Required. Output file path for JSON results.
```
--id ID
```
: Fetch a single record by ID.
```
--ids ID1;ID2;...
```
: Batch fetch multiple records.
```
--search QUERY
```
: Free-text search (only for searchable endpoints, marked ✓).
```
--limit N
```
: Max results to return (default: 5).
```
--offset N
```
: Pagination offset.
```
--filter KEY=VAL
```
: Filter parameters (can specify multiple).
```
--normalize
```
: (activity only) Normalize values to nM.
```
--dl_format sdf|mol
```
: (molecule only) Download structure file.

```
--output FILE
```
：必填。JSON结果的输出文件路径。
```
--id ID
```
：按ID获取单条记录。
```
--ids ID1;ID2;...
```
：批量获取多条记录。
```
--search QUERY
```
：自由文本搜索（仅适用于标记为可搜索的端点）。
```
--limit N
```
：返回的最大结果数（默认：5）。
```
--offset N
```
：分页偏移量。
```
--filter KEY=VAL
```
：过滤参数（可指定多个）。
```
--normalize
```
：（仅activity端点）将值标准化为nM。
```
--dl_format sdf|mol
```
：（仅molecule端点）下载结构文件。

Reference

参考资料

API Endpoints Reference: See references/api_endpoints.md for the full list of endpoints and filter operators.

API端点参考：查看references/api_endpoints.md获取完整端点列表和过滤操作符。

Workflow

工作流程

Use
```
status --output /tmp/status.json
```
to verify the API is available.
Search for targets, molecules, or drugs using the relevant subcommand.
Read the output JSON file to extract IDs and data.
Use IDs from search results to fetch detailed records.
Query
```
activity
```
with filters to get bioactivity data for targets/molecules. Use
```
--normalize
```
when comparing values across studies.
Use
```
similarity
```
or
```
substructure
```
for server-side structure-based queries.
Download compound images with
```
image
```
or structure files with
```
molecule --dl_format sdf
```
.

Use

target --filter target_components__accession=<UniProt>

to cross- reference with UniProt.

使用
```
status --output /tmp/status.json
```
验证API是否可用。
使用相关子命令搜索靶点、分子或药物。
读取输出JSON文件以提取ID和数据。
使用搜索结果中的ID获取详细记录。
带过滤参数查询
```
activity
```
端点，获取靶点/分子的生物活性数据。比较不同研究的数据时使用
```
--normalize
```
参数。
使用
```
similarity
```
或
```
substructure
```
端点执行服务器端基于结构的查询。
使用
```
image
```
端点下载化合物图像，或使用
```
molecule --dl_format sdf
```
下载结构文件。

使用

target --filter target_components__accession=<UniProt>

与UniProt进行交叉引用。