API Documentation

RCSB PDB Search API

class rcsbapi.search.Attr(attribute: str, type: Optional[Union[List[str], str]], description: Optional[Union[List[str], str]] = None)

A search attribute, e.g. “rcsb_entry_container_identifiers.entry_id”

Terminals can be constructed from Attr objects using either a functional syntax, which mirrors the API operators, or with python operators.

Fluent Function

Operator

exact_match

attr == str

contains_words

contains_phrase

greater

attr > date,number

less

attr < date,number

greater_or_equal

attr >= date,number

less_or_equal

attr <= date,number

equals

attr == date,number

range

dict (keys below)*

exists

Previously, __bool__ was overloaded to run the exists function, but __bool__ can’t be overloaded to return non-boolean value. Method overloading bool was deleted.

Rather than their normal bool return values, operators return Terminals.

Pre-instantiated attributes are available from the rcsbapi.search.search_attributes object. These are generally easier to use than constructing Attr objects by hand. A complete list of valid attributes is available in the schema.

  • The range dictionary requires the following keys:

  • “from” -> int

  • “to” -> int

  • “include_lower” -> bool

  • “include_upper” -> bool

__init__(attribute: str, type: Optional[Union[List[str], str]], description: Optional[Union[List[str], str]] = None) → None
contains_phrase(value: Union[str, Value[str]]) → AttributeQuery

Match an exact phrase

contains_words(value: Union[str, Value[str], List[str], Value[List[str]]]) → AttributeQuery

Match any word within the string.

Words are split at whitespace. All results which match any word are returned, with results matching more words sorted first.

equals(value: Union[int, float, date, Value[int], Value[float], Value[date]]) → AttributeQuery

Attribute == value

exact_match(value: Union[str, Value[str]]) → AttributeQuery

Exact match with the value

exists() → AttributeQuery

Attribute is defined for the structure

greater(value: Union[int, float, date, Value[int], Value[float], Value[date]]) → AttributeQuery

Attribute > value

greater_or_equal(value: Union[int, float, date, Value[int], Value[float], Value[date]]) → AttributeQuery

Attribute >= value

in_(value: Union[List[str], List[int], List[float], List[date], Tuple[str, ...], Tuple[int, ...], Tuple[float, ...], Tuple[date, ...], Value[List[str]], Value[List[int]], Value[List[float]], Value[List[date]], Value[Tuple[str, ...]], Value[Tuple[int, ...]], Value[Tuple[float, ...]], Value[Tuple[date, ...]]]) → AttributeQuery

Attribute is contained in the list of values

less(value: Union[int, float, date, Value[int], Value[float], Value[date]]) → AttributeQuery

Attribute < value

less_or_equal(value: Union[int, float, date, Value[int], Value[float], Value[date]]) → AttributeQuery

Attribute <= value

range(value: Dict[str, Any]) → AttributeQuery

Attribute is within the specified half-open range

Parameters

value – lower and upper bounds [a, b)

type: Optional[Union[List[str], str]]

search service type. text for structure attributes, text_chem for chemical attributes

class rcsbapi.search.AttributeQuery(attribute: Optional[str] = None, operator: Optional[str] = None, value: Optional[Union[str, int, float, date, List[str], List[int], List[float], List[date], Tuple[str, ...], Tuple[int, ...], Tuple[float, ...], Tuple[date, ...], Dict[str, Any]]] = None, service: Optional[Union[List[str], str]] = None, negation: Optional[bool] = False)

Special case of a Terminal for Structure and Chemical Attribute Searches

AttributeQueries compares some attribute of a structure to a value.

Examples

>>> AttributeQuery("exptl.method", "exact_match", "X-RAY DIFFRACTION")
>>> AttributeQuery("rcsb_entry_container_identifiers.entry_id", operator="in", value=["4HHB", "2GS2"])

A full list of attributes is available in the schema. Operators are documented here.

The Attr class provides a more pythonic way of constructing AttributeQueries.

__init__(attribute: Optional[str] = None, operator: Optional[str] = None, value: Optional[Union[str, int, float, date, List[str], List[int], List[float], List[date], Tuple[str, ...], Tuple[int, ...], Tuple[float, ...], Tuple[date, ...], Dict[str, Any]]] = None, service: Optional[Union[List[str], str]] = None, negation: Optional[bool] = False)

Search for the string value given possible attribute or operator Also can specify service and negation

Parameters

  • attribute (Optional[str], optional) – specify attribute for search (i.e struct.title, exptl.method, rcsb_id). Defaults to None.

  • operator (Optional[str], optional) – specify operation to be done for search (i.e “contains_phrase”, “exact_match”). Defaults to None.

  • value (Optional[TValue], optional) – value to compare attribute to. Defaults to None.

  • service (Optional[str], optional) – specify what search service (i.e “text”, “text_chem”). Defaults to None.

  • negation (Optional[bool], optional) – logical not. Defaults to False.

class rcsbapi.search.ChemSimilarityQuery(value: Optional[str] = None, query_type: Literal['formula', 'descriptor'] = 'formula', descriptor_type: Optional[Literal['InChI', 'SMILES']] = None, match_subset: Optional[bool] = False, match_type: Optional[Literal['graph-relaxed-stereo', 'graph-relaxed', 'fingerprint-similarity', 'sub-struct-graph-relaxed-stereo', 'sub-struct-graph-relaxed', 'graph-exact']] = None)

Special case of Terminal for chemical similarity search queries

__init__(value: Optional[str] = None, query_type: Literal['formula', 'descriptor'] = 'formula', descriptor_type: Optional[Literal['InChI', 'SMILES']] = None, match_subset: Optional[bool] = False, match_type: Optional[Literal['graph-relaxed-stereo', 'graph-relaxed', 'fingerprint-similarity', 'sub-struct-graph-relaxed-stereo', 'sub-struct-graph-relaxed', 'graph-exact']] = None)
Parameters

  • value (Optional[str], optional) – chemical formula or descriptor (SMILES or InChI). Defaults to None.

  • query_type (ChemSimType, optional) – “formula” or “descriptor”. Defaults to “formula”.

  • descriptor_type (Optional[SubsetDescriptorType], optional) – if “descriptor”, whether it’s “SMILES” or “InCHI”. Defaults to None.

  • match_subset (Optional[bool], optional) – if “formula”, return chemical components/structures that contain the formula as a subset. Defaults to False.

  • match_type (Optional[ChemSimMatchType], optional) – if “descriptor”, type of matches to find and return (see below). Defaults to None.

Guide for “match_type” options: +———————————–+——————————————-+ | match_type | | +===================================+===========================================+ | “graph-relaxed” | Similar Ligands (including Stereoisomers) | | “graph-relaxed-stereo” | Similar Ligands (Stereospecific) | | “fingerprint-similarity” | Similar Ligands (Quick screen) | | “sub-struct-graph-relaxed-stereo” | Substructure (Stereospecific) | | “sub-struct-graph-relaxed” | Substructure (including Stereoisomers) | | “graph-exact” | Exact match | +———————————–+——————————————-+

class rcsbapi.search.Facet(name: str, aggregation_type: Literal['terms', 'histogram', 'date_histogram', 'range', 'date_range', 'cardinality'], attribute: str, interval: Optional[Union[int, str]] = None, ranges: Optional[List[FacetRange]] = None, min_interval_population: Optional[int] = None, max_num_intervals: Optional[int] = None, precision_threshold: Optional[int] = None, nested_facets: Optional[Union[Facet, FilterFacet, List[Union[Facet, FilterFacet]]]] = None)

Facet object for use in a faceted query.

Attributes:

name (str): Specifies the name of the aggregation. aggregation_type (AggregationType): Specifies the type of the aggregation. Can be “terms”, “histogram”, “date_histogram”, “range”, “date_range”, or “cardinality”. attribute (str): Specifies the full attribute name to aggregate on. interval (Optional[Union[int, str]], optional): Size of the intervals into which a given set of values is divided. Required only for use with

“histogram” and “date_histogram” aggregation types (defaults to None if not included).

ranges (Optional[List[FacetRange]], optional): A set of ranges, each representing a bucket. Note that this aggregation includes the ‘from’ value and

excludes the ‘to’ value for each range. Should be a list of FacetRange objects (leave the “include_lower” and “include_upper” fields empty). Required only for use with “range” and “date_range” aggregation types (defaults to None if not included).

min_interval_population (Optional[int], optional): Minimum number of items (>= 0) in the bin required for the bin to be returned. Only for use with

“terms”, “histogram”, and “date_histogram” facets (defaults to 1 for these aggregation types, otherwise defaults to None).

max_num_intervals (Optional[int], optional): Maximum number of intervals (<= 65336) to return for a given facet. Only for use with “terms”

aggregation type (defaults to 65336 for this aggregation type, otherwise defaults to None).

precision_threshold (Optional[int], optional): Allows to trade memory for accuracy, and defines a unique count (<= 40000) below which counts are

expected to be close to accurate. Only for use with “cardinality” aggregation type (defaults to 40000 for this aggregation type, otherwise defaults to None).

nested_facets (Optional[Union[Facet, FilterFacet, List[Union[Facet, FilterFacet]]]], optional): Enables multi-dimensional aggregations.

Should contain a List of Facets or FilterFacets. Can be used with any aggregation type. Defaults to None.

__init__(name: str, aggregation_type: Literal['terms', 'histogram', 'date_histogram', 'range', 'date_range', 'cardinality'], attribute: str, interval: Optional[Union[int, str]] = None, ranges: Optional[List[FacetRange]] = None, min_interval_population: Optional[int] = None, max_num_intervals: Optional[int] = None, precision_threshold: Optional[int] = None, nested_facets: Optional[Union[Facet, FilterFacet, List[Union[Facet, FilterFacet]]]] = None) → None
to_dict() → dict

Get dictionary representing request option, skips values of None

class rcsbapi.search.FacetRange(start: Optional[Union[str, float]] = None, end: Optional[Union[str, float]] = None, include_lower: Optional[bool] = None, include_upper: Optional[bool] = None)

Primarily for use with “range” and “date_range” aggregations with the Facet class. include_upper and include_lower should not be used with Facet queries.

Either start or end are required to construct .. attribute:: start

type

Optional[Union[str, float]]

end
Type

Optional[Union[str, float]]

include_lower

whether to include start value in range

Type

Optional[bool]

include_upper

whether to include end value in range

Type

Optional[bool]

__init__(start: Optional[Union[str, float]] = None, end: Optional[Union[str, float]] = None, include_lower: Optional[bool] = None, include_upper: Optional[bool] = None) → None
class rcsbapi.search.FilterFacet(filter: Union[TerminalFilter, GroupFilter], facets: Union[Facet, FilterFacet, List[Union[Facet, FilterFacet]]])

Filter results that contribute to bucket count

filter

filter to apply to facets

Type

Union[TerminalFilter, GroupFilter]

facets
Type

Union[Facet, “FilterFacet”, List[Union[Facet, “FilterFacet”]]]

__init__(filter: Union[TerminalFilter, GroupFilter], facets: Union[Facet, FilterFacet, List[Union[Facet, FilterFacet]]]) → None
class rcsbapi.search.GroupBy(aggregation_method: str, similarity_cutoff: Optional[int] = None, ranking_criteria_type: Optional[RankingCriteriaType] = None)

return results as groups

aggregation_method

“matching_deposit_group_id”, “sequence_identity”, “matching_uniprot_accession”.

Type

str

similarity_cutoff

only for aggregation method “sequence identity”, identity threshold for grouping. 100, 95, 90,70, 50, or 30. Defaults to None.

Type

int, optional

ranking_criteria_type

control ordering of results. Defaults to None.

Type

Optional[RankingCriteriaType], optional

__init__(aggregation_method: str, similarity_cutoff: Optional[int] = None, ranking_criteria_type: Optional[RankingCriteriaType] = None) → None
to_dict() → Dict

Get dictionary representing request option, skips values of None

class rcsbapi.search.GroupFilter(logical_operator: Literal['and', 'or'], nodes: List[Union[TerminalFilter, GroupFilter]])

Group filter class for use with FilterFacet queries

logical operator

“and”, “or” logical operator

Type

TAndOr

nodes

list of filters to combine

Type

List[Union[“TerminalFilter”, “GroupFilter”]]

__init__(logical_operator: Literal['and', 'or'], nodes: List[Union[TerminalFilter, GroupFilter]]) → None
to_dict()

Get dictionary representing request option, skips values of None

class rcsbapi.search.NestedAttributeQuery(query1: AttributeQuery, query2: AttributeQuery)

Represents a search query restricted to a single nested attribute group.

Ensures that all attributes in the query fall within a valid nested indexing context, and provides consistent behavior for nesting logic. It wraps AttributeQuery objects and restricts operations to those allowed by the nested schema rules.

Parameters

  • query1 (AttributeQuery) – First attribute query containing a nested attribute

  • query2 (AttributeQuery) – Second attribute query containing the corresponding nested attribute that pairs with query1’s attribute

Raises

Error – If queries do not all belong to a valid and consistent nested attribute group.

Returns

A valid instance of a nested group query suitable for use in the RCSB Search API.

Return type

NestedAttributeQuery

__init__(query1: AttributeQuery, query2: AttributeQuery)
class rcsbapi.search.RankingCriteriaType(sort_by: str, filter: Optional[Union[GroupFilter, TerminalFilter]] = None, direction: Optional[Literal['asc', 'desc']] = None)

Request option controlling the order that results are returned

sort_by

“score”, “size”, “count”, or full attribute name

Type

str

filter

filter out results

Type

Optional[Union[GroupFilter, TerminalFilter]], optional

direction

The order in which to sort. Undefined defaults to “desc”.

Type

Optional[Literal[“asc”, “desc”]]

__init__(sort_by: str, filter: Optional[Union[GroupFilter, TerminalFilter]] = None, direction: Optional[Literal['asc', 'desc']] = None) → None
class rcsbapi.search.SeqMotifQuery(value: str, pattern_type: Optional[Literal['simple', 'prosite', 'regex']] = 'simple', sequence_type: Optional[Literal['dna', 'rna', 'protein']] = 'protein')

Special case of a terminal for protein, DNA, or RNA sequence motif queries

__init__(value: str, pattern_type: Optional[Literal['simple', 'prosite', 'regex']] = 'simple', sequence_type: Optional[Literal['dna', 'rna', 'protein']] = 'protein')
Parameters

  • value (str) – motif to search

  • pattern_type (Optional[SeqMode], optional) – motif syntax (“simple”, “prosite”, “regex”). Defaults to “simple”.

  • sequence_type (Optional[SequenceType], optional) – type of biological sequence (“protein”, “dna”, “rna”). Defaults to “protein”.

class rcsbapi.search.SeqSimilarityQuery(value: str, evalue_cutoff: Optional[float] = 0.1, identity_cutoff: Optional[float] = 0, sequence_type: Optional[Literal['dna', 'rna', 'protein']] = 'protein')

Special case of a terminal for protein, DNA, or RNA sequence queries

__init__(value: str, evalue_cutoff: Optional[float] = 0.1, identity_cutoff: Optional[float] = 0, sequence_type: Optional[Literal['dna', 'rna', 'protein']] = 'protein')

The string value is a target sequence that is searched

Parameters

  • value (str) – protein or nucleotide sequence

  • evalue_cutoff (Optional[float], optional) – upper cutoff for E-value (lower is more significant). Defaults to 0.1.

  • identity_cutoff (Optional[float], optional) – lower cutoff for percent sequence match (0-1). Defaults to 0.

  • sequence_type (Optional[SequenceType], optional) – type of biological sequence (“protein”, “dna”, “rna”). Defaults to “protein”.

class rcsbapi.search.Sort(sort_by: str, direction: Optional[str] = None, filter: Optional[Union[GroupFilter, TerminalFilter]] = None)

control sorting of results

sort_by

“score” to sort by relevancy scores or full attribute name

Type

str

filter

filter for results. Defaults to None.

Type

Optional[GroupFilter, TerminalFilter], optional

direction

“asc” (ascending) or “desc” (descending). Defaults to None.

Type

str, optional

__init__(sort_by: str, direction: Optional[str] = None, filter: Optional[Union[GroupFilter, TerminalFilter]] = None) → None
to_dict() → Dict

Get dictionary representing request option, skips values of None

class rcsbapi.search.StructMotifQuery(structure_search_type: Literal['entry_id', 'file_url', 'file_upload'] = 'entry_id', backbone_distance_tolerance: Literal[0, 1, 2, 3] = 1, side_chain_distance_tolerance: Literal[0, 1, 2, 3] = 1, angle_tolerance: Literal[0, 1, 2, 3] = 1, entry_id: Optional[str] = None, url: Optional[str] = None, file_path: Optional[str] = None, file_extension: Optional[str] = None, residue_ids: Optional[list] = None, rmsd_cutoff: int = 2, atom_pairing_scheme: Literal['ALL', 'BACKBONE', 'SIDE_CHAIN', 'PSEUDO_ATOMS'] = 'SIDE_CHAIN', motif_pruning_strategy: Literal['NONE', 'KRUSKAL'] = 'KRUSKAL', allowed_structures: Optional[list] = None, excluded_structures: Optional[list] = None, limit: Optional[int] = None, file_url: Optional[str] = None, file_format: Optional[Literal['cif', 'bcif', 'pdb']] = None)

Special case of a terminal for structure motif queries.

If you provide an entry_id, the other optional parameters can be ignored. If you provide a file_url, you must also provide a file_format. If you provide a file_upload, you must also provide a file_format.

As is standard with Structure Motif Queries, you must include a list of residues.

Positional arguments STRONGLY discouraged.

__init__(structure_search_type: Literal['entry_id', 'file_url', 'file_upload'] = 'entry_id', backbone_distance_tolerance: Literal[0, 1, 2, 3] = 1, side_chain_distance_tolerance: Literal[0, 1, 2, 3] = 1, angle_tolerance: Literal[0, 1, 2, 3] = 1, entry_id: Optional[str] = None, url: Optional[str] = None, file_path: Optional[str] = None, file_extension: Optional[str] = None, residue_ids: Optional[list] = None, rmsd_cutoff: int = 2, atom_pairing_scheme: Literal['ALL', 'BACKBONE', 'SIDE_CHAIN', 'PSEUDO_ATOMS'] = 'SIDE_CHAIN', motif_pruning_strategy: Literal['NONE', 'KRUSKAL'] = 'KRUSKAL', allowed_structures: Optional[list] = None, excluded_structures: Optional[list] = None, limit: Optional[int] = None, file_url: Optional[str] = None, file_format: Optional[Literal['cif', 'bcif', 'pdb']] = None)
Parameters

  • structure_search_type (StructEntryType, optional) – Source of structure to use for structure similarity search. (Options are “entry_id”, “file_url”, “file_upload”). Defaults to “entry_id”.

  • backbone_distance_tolerance (StructMotifTolerance, optional) – tolerance for distance between Cα atoms (in Å). Defaults to 1.

  • side_chain_distance_tolerance (StructMotifTolerance, optional) – tolerance for distance between Cβ atoms (in Å). Defaults to 1.

  • angle_tolerance (StructMotifTolerance, optional) – angle between CαCβ vectors (in multiples of 20 degrees). Defaults to 1.

  • entry_id (Optional[str], optional) – PDB ID or CSM ID (for structure_search_type=”entry_id” only). Defaults to None.

  • url (Optional[str], optional) – DEPRECATED: Use ‘file_url’ instead. Defaults to None.

  • file_url (Optional[str], optional) – URL to structure file (for structure_search_type=”file_url” only). Defaults to None.

  • file_path (Optional[str], optional) – Local path to structure file (for structure_search_type=”file_upload” only). Defaults to None.

  • file_extension (Optional[str], optional) – DEPRECATED: Use ‘file_format’ instead. Defaults to None.

  • file_format (StructSimFormat, optional) – Format of input structure file (for structure_search_type of “file_url” or “file_upload” only). Options are “cif”, “bcif”, or “pdb”. Defaults to None.

  • residue_ids (Optional[list], optional) – list of StructMotifResidue objects . Defaults to None.

  • rmsd_cutoff (int, optional) – upper cutoff for root-mean-square deviation (RMSD) score. Defaults to 2.

  • atom_pairing_scheme (StructMotifAtomPairing, optional) – Which atoms to consider to compute RMSD scores and transformations. Defaults to “SIDE_CHAIN”.

  • motif_pruning_strategy (StructMotifPruning, optional) – specifies how query motifs are pruned (i.e. simplified). Defaults to “KRUSKAL”.

  • allowed_structures (Optional[list], optional) – list of allowed residues specified by strings (ex: [“HIS”, “LYS”]). Defaults to None.

  • excluded_structures (Optional[list], optional) – if the list of structure identifiers is specified, the search will exclude those structures from the search space. Defaults to None.

  • limit (Optional[int], optional) – stop after accepting this many hits. Defaults to None.

class rcsbapi.search.StructMotifResidue(chain_id: Optional[str] = None, struct_oper_id: Optional[str] = None, label_seq_id: Optional[str] = None, exchanges: Optional[list] = None)

This class is for defining residues. For use with the Structure Motif Search.

__init__(chain_id: Optional[str] = None, struct_oper_id: Optional[str] = None, label_seq_id: Optional[str] = None, exchanges: Optional[list] = None)
class rcsbapi.search.StructSimilarityQuery(structure_search_type: Literal['entry_id', 'file_url', 'file_upload'] = 'entry_id', entry_id: Optional[str] = None, assembly_id: Optional[str] = None, chain_id: Optional[str] = None, file_url: Optional[str] = None, file_path: Optional[str] = None, file_format: Optional[Literal['cif', 'bcif', 'pdb']] = None, target_search_space: Optional[Literal['polymer_entity_instance', 'assembly']] = None, number_of_candidates: int = 10000, ptmscore_cutoff: float = 0.8, similarity_type: Optional[Literal['local', 'global']] = 'local', operator: Optional[str] = None, structure_input_type: Optional[str] = None)

Special case of a terminal for structure similarity queries

__init__(structure_search_type: Literal['entry_id', 'file_url', 'file_upload'] = 'entry_id', entry_id: Optional[str] = None, assembly_id: Optional[str] = None, chain_id: Optional[str] = None, file_url: Optional[str] = None, file_path: Optional[str] = None, file_format: Optional[Literal['cif', 'bcif', 'pdb']] = None, target_search_space: Optional[Literal['polymer_entity_instance', 'assembly']] = None, number_of_candidates: int = 10000, ptmscore_cutoff: float = 0.8, similarity_type: Optional[Literal['local', 'global']] = 'local', operator: Optional[str] = None, structure_input_type: Optional[str] = None)
Parameters

  • structure_search_type (StructEntryType, optional) – Source of structure to use for structure similarity search. (Options are “entry_id”, “file_url”, “file_upload”). Defaults to “entry_id”.

  • entry_id (str, optional) – PDB ID or CSM ID (for structure_search_type=”entry_id” only). Defaults to None.

  • assembly_id (str, optional) – The assembly ID of the input structure to use for similarity searching. Defaults to “1” for structure_search_type=”entry_id”; else defaults to None.

  • chain_id (str, optional) – The chain (or “asym”) ID of the input structure to use for similarity searching. Defaults to None.

  • file_url (str, optional) – URL to structure file (for structure_search_type=”file_url” only). Defaults to None.

  • file_path (str, optional) – Local path to structure file (for structure_search_type=”file_upload” only). Defaults to None.

  • file_format (StructSimFormat, optional) – Format of input structure file (for structure_search_type of “file_url” or “file_upload” only). Options are “cif”, “bcif”, or “pdb”. Defaults to None.

  • target_search_space (StructSimSearchSpace, optional) – Target objects against which the query will be compared for shape similarity. Defaults to “assembly” for “assembly_id”-based search. Defaults to “polymer_entity_instance” for “chain_id”-based search.

  • number_of_candidates (int) – Controls the number of the most similar matches to return. The first item is the closest match, with subsequent items decreasing in similarity. Lower values make searches faster but may exclude relevant results, while higher values provide a more exhaustive search at the cost of increased computation time. Must be between [0-15,000]. Default 10,000.

  • ptmscore_cutoff (float) – Minimum predicted TM-score threshold above which hits will be returned. Must be between [0.0-1.0]. Default 0.8.

  • similarity_type (str) – Structural matching mode: LOCAL favors local matches; GLOBAL applies length normalization to favor global similarity. Must be either “local” or “global”. Default “local”.

  • operator (str, optional) – DEPRECATED: No longer used. Use “number_of_candidates” and “ptmscore_cutoff” instead.

  • structure_input_type (str, optional) – DEPRECATED: No longer needed. This is controlled by provision of “assembly_id” or “chain_id”.

class rcsbapi.search.TerminalFilter(attribute: str, operator: Literal['equals', 'greater', 'greater_or_equal', 'less', 'less_or_equal', 'range', 'exact_match', 'in', 'exists'], value: Optional[Union[str, int, float, bool, FacetRange, List[str], List[int], List[float]]] = None, negation: bool = False, case_sensitive: bool = False)

A filter based on a single Terminal node. Can be combined into GroupFilters

Attribute:

attribute (str): specify attribute for search (i.e struct.title, exptl.method, rcsb_id). Defaults to None. operator (Literal[“equals”, “greater”, “greater_or_equal”, “less”, “less_or_equal”, “range”, “exact_match”, “in”, “exists”]):

specify operation to be done for search (i.e “contains_phrase”, “exact_match”). Defaults to None.

value (Optional[Union[str, int, float, bool, FacetRange, List[str], List[int], List[float]]], optional):

The search term(s). Can be a single or multiple words, numbers, dates, date math expressions, or ranges.

negation (bool, optional): logical not. Defaults to False. case_sensitive (bool, optional): whether to do case sensitive matching of value. Defaults to False.

__init__(attribute: str, operator: Literal['equals', 'greater', 'greater_or_equal', 'less', 'less_or_equal', 'range', 'exact_match', 'in', 'exists'], value: Optional[Union[str, int, float, bool, FacetRange, List[str], List[int], List[float]]] = None, negation: bool = False, case_sensitive: bool = False) → None
to_dict()

Get dictionary representing request option, skips values of None

class rcsbapi.search.TextQuery(value: str)

Special case of a Terminal for free-text queries

__init__(value: str)

Search for the string value anywhere in the text

Parameters

value – free-text query

class rcsbapi.search.search_schema.SearchSchemaGroup(attr_type)

A non-leaf node in the RCSB PDB schema. Leaves are Attr values.

get_attribute_details(attribute: str)

Return attribute information given full or partial attribute name

Parameters

attribute (str) – Full attribute name (e.g., “rcsb_id”, “rcsb_entity_source_organism.scientific_name”)

Returns

Return corresponding attribute description if there’s a match

Return type

str

get_attribute_type(attribute: str) → Optional[str]

Return attribute type given full attribute name

Parameters

attribute (str) – Full attribute name (e.g., “rcsb_id”, “rcsb_entity_source_organism.scientific_name”)

Returns

Return search service if there’s a match.

structure search: “text” chemical search: “chem_text” both: [“text”, “chem_text”] (raises error later)

Return type

Union[str, None]

search(pattern: Union[str, Pattern], flags=0)

Find all attributes in the schema matching a regular expression.

Returns

A list of Attr objects whose attribute matches.

class rcsbapi.search.search_query.Session(query: SearchQuery, return_type: Literal['entry', 'assembly', 'polymer_entity', 'non_polymer_entity', 'polymer_instance', 'mol_definition'] = 'entry', rows: int = 10000, return_content_type: List[Literal['experimental', 'computational']] = ['experimental'], results_verbosity: Literal['compact', 'minimal', 'verbose'] = 'compact', return_counts: bool = False, facets: Optional[List[Union[Facet, FilterFacet]]] = None, group_by: Optional[GroupBy] = None, group_by_return_type: Optional[Literal['groups', 'representatives']] = None, sort: Optional[List[Sort]] = None, return_explain_metadata: bool = False, scoring_strategy: Optional[Literal['combined', 'sequence', 'seqmotif', 'strucmotif', 'structure', 'chemical', 'text', 'text_chem', 'full_text']] = None, max_retries: Optional[int] = None, retry_backoff: Optional[int] = None)

A single query session.

Handles paging the query and parsing results

URL to edit this query in the RCSB PDB query editor

URL to view this query on the RCSB PDB website query builder