rcsb_search_by_structure
Search the Protein Data Bank for structures with a 3D shape similar to a reference PDB entry, with optional filters and grouping.
Instructions
Find structures with a similar 3D shape to a reference PDB structure.
Args:
entry_id: Reference PDB entry, e.g. "4HHB".
assembly_id: Use this biological assembly as the reference (e.g. "1").
Defaults to assembly "1" when neither assembly_id nor asym_id is given.
asym_id: Use this single chain as the reference instead (mutually exclusive
with assembly_id).
return_type: What to return (defaults to "assembly" for an assembly reference or
"polymer_instance" for a chain reference); 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 shape-similarity
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 | ||
| facets | No | ||
| offset | No | ||
| asym_id | No | ||
| sort_by | No | ||
| all_hits | No | ||
| entry_id | Yes | ||
| group_by | No | ||
| attributes | No | ||
| assembly_id | No | ||
| return_type | No | ||
| sort_direction | No | asc | |
| group_by_ranking | No | ||
| logical_operator | No | and |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||