rcsb_search_by_chemical
Search PDB chemical components by SMILES/InChI or molecular formula to retrieve matching structures.
Instructions
Search PDB chemical components by structure (SMILES/InChI) or formula.
Args:
value: A SMILES/InChI string (query_type="descriptor") or a molecular
formula like "C8H9NO2" (query_type="formula").
query_type: "descriptor" (default) or "formula".
descriptor_type: "SMILES" or "InChI" (descriptor queries only).
match_type: Graph/fingerprint criterion for descriptor queries, one of:
graph-exact, graph-strict, graph-relaxed (default), graph-relaxed-stereo
(whole-molecule matches, strict->relaxed = stricter->looser); the
sub-struct-graph-* variants of each (substructure search); or
fingerprint-similarity (similar molecules).
match_subset: Formula queries only — match formulas that merely contain the
requested atoms.
return_type: What to return (default "mol_definition" = the chemical component); see the
"Return types and fetching details" note in the server instructions.
limit: Max hits (1-100).
offset: Number of hits to skip, for paging; pass the response's next_offset back with
the same query to fetch the next page.
all_hits: Return the COMPLETE result set in one call (for an explicit "ALL ..." request);
ignores limit, can't be combined with offset, and is refused above 10000 hits.
Ignored when facets is set.
attributes: Optional structured filters AND/OR-combined with this match — a list of
AttributeFilter {attribute, operator, value, negation?, case_sensitive?} (e.g.
restrict to an organism or resolution). See rcsb_search_by_attribute /
rcsb_list_pdb_search_attributes for paths and operators.
logical_operator: Combine this match and the attribute conditions with "and"
(default) or "or".
facets: Optional aggregation specs to return a breakdown / distribution instead of hits
(see the faceting note in the server instructions for the spec).
group_by, group_by_ranking: Collapse redundant polymer_entity hits into clusters, one
representative each (needs return_type="polymer_entity") — see the grouping note in
the server instructions.
sort_by: Attribute path to order the hits by, replacing the default score ordering (each
hit's score is still returned); omit to keep it. Only SORTABLE attributes work: those
listing exact_match (strings) or equals (numbers/dates) in
rcsb_list_pdb_search_attributes; full-text-only attributes (e.g. struct.title) and
return_type="mol_definition" are rejected.
sort_direction: "asc" (default) or "desc"; applies only when sort_by is set.
Returns:
{total_count, returned, offset, has_more, next_offset, hits:[{id, score}],
editor}; with facets, instead returns {total_count, facets, editor}.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| value | Yes | ||
| facets | No | ||
| offset | No | ||
| sort_by | No | ||
| all_hits | No | ||
| group_by | No | ||
| attributes | No | ||
| match_type | No | graph-relaxed | |
| query_type | No | descriptor | |
| return_type | No | mol_definition | |
| match_subset | No | ||
| sort_direction | No | asc | |
| descriptor_type | No | SMILES | |
| group_by_ranking | No | ||
| logical_operator | No | and |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||