rcsb_search_by_attribute

Search by one or more structured attribute conditions combined with a single AND/OR — preferred over rcsb_search_fulltext whenever the request resolves to clear attribute(s) and value(s). NEVER invent, guess, or infer attributes. If you don't know a path or its operators, call rcsb_list_pdb_search_attributes first. All conditions share ONE logical_operator — NESTED boolean groups are not supported.

For a biological concept, resolve it to an ontology id first and filter on the matching annotation (see the resolver guidance in the server instructions). If a resolver returns no usable id, or a concept/annotation filter yields no hits, fall back to rcsb_search_fulltext for the concept. (For ordinary constraints — resolution, organism, dates — an empty result is a valid answer: report it, don't keyword-search instead.)

Example ("human X-ray structures better than 2 A"): attributes=[ {"attribute": "rcsb_entity_source_organism.ncbi_scientific_name", "operator": "exact_match", "value": "Homo sapiens"}, {"attribute": "exptl.method", "operator": "exact_match", "value": "X-RAY DIFFRACTION"}, {"attribute": "rcsb_entry_info.resolution_combined", "operator": "less", "value": 2.0}, ] Single-condition examples: a released-after-date filter -> {"attribute": "rcsb_accession_info.initial_release_date", "operator": "greater", "value": "2024-01-01T00:00:00Z"}; has any ligand (no value) -> {"attribute": "rcsb_nonpolymer_entity.pdbx_description", "operator": "exists"}.

Args: attributes: One or more AttributeFilter conditions, each {attribute, operator, value, negation?, case_sensitive?}. Operators are TYPE-SPECIFIC (strings use exact_match/in or contains_words/contains_phrase; numbers/dates use greater/ greater_or_equal/less/less_or_equal/equals/range; any type supports exists). A numeric value may be a number or a numeric string; a range value is a {from, to, include_lower, include_upper} object (bounds EXCLUSIVE unless the include flags are true). See rcsb_list_pdb_search_attributes for paths/operators. logical_operator: Combine the conditions with "and" (default) or "or". return_type: What to return (default "entry"); see the "Return types and fetching details" note in the server instructions. E.g. return_type="entry" with a ligand attribute finds the structures that contain it. 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. 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. chemical: Set True for chemical-component attributes (paths from rcsb_list_pdb_search_attributes(schema="chemical"), e.g. "chem_comp.formula_weight"). Switches to the text_chem service; usually pair with return_type="mol_definition". facets: Optional aggregation specs to return a breakdown / distribution instead of hits (see the faceting note in the server instructions for the spec). sort_by: Attribute path to order the hits by. A pure attribute filter is a boolean match, so hits otherwise come back in near-arbitrary order — set this for "best resolution first", "newest first", etc. 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}; hits are ids only — batch them into rcsb_get_entries (or the rcsb_get_* tool matching return_type). The per-hit score is near-uniform for a pure attribute filter and carries NO biological meaning — don't rank hits by it. all_hits/facets response variants: see the server instructions.