Querying the Database

Query Functions

ChemRecon provides a number of convenience functions for querying the database. They are all imported into the .chemrecon.query module.

Querying entries requires providing both an indentifier and an identifier type. For a list of identifier types, see Identifier Types.

This module contains functions useful for querying the database. These functions are also available in the chemrecon scope.

chemrecon.query.find_entry(id_type: IdentifierType, source_id: str) → Entry | None

Look for an entry with the specified type and id in the connected Database. If not found, returns None.

chemrecon.query.find_compound_entry(id_type: IdentifierTypeCompound, source_id: str) → Compound | None

Look for an entry with the specified type and id in the connected Database. If not found, returns None.

chemrecon.query.find_reaction_entry(id_type: IdentifierTypeReaction, source_id: str) → Reaction | None

Look for an entry with the specified type and id in the connected Database. If not found, returns None.

chemrecon.query.find_enzyme_entry(id_type: IdentifierTypeEnzyme, source_id: str) → Enzyme | None

Look for an entry with the specified type and id in the connected Database. If not found, returns None.

chemrecon.query.find_structure_representation_entry(id_type: IdentifierTypeStructureRepresentation, source_id: str) → MolStructureRepr | None

Look for an entry with the specified type and id in the connected Database. If not found, returns None.

chemrecon.query.find_aam_representation_entry(id_type: IdentifierTypeAAM, source_id: str) → AAMRepr | None

Look for an entry with the specified type and id in the connected Database. If not found, returns None.

chemrecon.query.find_structure_entry(smiles: str) → MolStructure | None

Look for an entry with the specified type and id in the connected Database. If not found, returns None.

chemrecon.query.find_aam_entry(reaction_smiles: str) → AAM | None

Look for an entry with the specified type and id in the connected Database. If not found, returns None.

chemrecon.query.get_relations_from_entry(entry: Entry, relation_type: type[R], get_backward_relations: bool = True) → list[tuple[R, Entry]]

Get relations of a given type with the specified entry as the source.

chemrecon.query.get_all_relations(entry: Entry, get_backward_relations: bool = True, get_transitive_relations: bool = False, get_procedural_relations: bool = False, get_procedural_eg_relations: bool = False) → list[tuple[Relation, Entry]]

Get all relations of a given entry. Note: Procedural relations cannot be explored backwards.

Advanced Queries with Query Handlers

Most common operations of ChemRecon can be performed using the built-in convenience functions described above. These functions query the database using QueryHandler objects. For more advanced functionality, QueryHandlers can be used directly. After connecting, ChemRecon keeps a reference to the active query handler, which can be accessed using get_query_handler().

class chemrecon.QueryHandler(connection: Connection)

Bases: object

Context manager to wrap database queries.

add_procedural_entry(entry: T) → int

Adds a procedural entry, and returns its virtual recon id. If already exists, return the virtual recon id.

get_entry_by_recon_id(table: type[T], recon_id: int) → T

Raises KeyError on failure.

get_entries_by_recon_ids(table: type[T], recon_ids: list[int]) → dict[int, T]

Get the entries associated with the given recon ids. Raises KeyError on failure.

get_entry_by_index(entry_index: T) → T

Given an entry with a valid index, get the corresponding full entry from the database. Raise KeyError in failure.

get_entries_by_indices(entry_indices: list[T]) → list[T]

Given an entry with a valid index, get the corresponding full entry from the database. Raise KeyError in failure.

get_relations_by_recon_ids(entry_type: type[T1], recon_ids: list[int], relation_type: type[Relation] | type[Relation]) → list[list[Relation]] | list[list[Relation]]

Given a list of entries, get all connected relations of a given type.

get_relations_with_entries_by_recon_ids(entry_type: type[T1], recon_ids: list[int], relation_type: type[Relation] | type[Relation]) → list[dict[T2, list[Relation] | list[Relation]]]

Given a list of entries, get connected relations of the given type. Returns a list, containing, for each input recon_id, a dictionary mapping connected vertices to the relation(s) with which they are connected.

get_relations_with_entries_by_recon_ids_symmetric(entry_type: type[T], recon_ids: list[int], relation_type: type[Relation]) → list[dict[T, list[Relation]]]

Specialization for symmetric relations.

get_relations_with_entries_by_recon_ids_of_t1(entry_type: type[T1], recon_ids: list[int], relation_type: type[Relation]) → list[dict[T2, list[Relation]]]

Given a list of entries, get connected relations of the given type. Returns a list, containing, for each input recon_id, a dictionary mapping connected vertices to the relation(s) with which they are connected.

get_relations_with_entries_by_recon_ids_of_t2(entry_type: type[T1], recon_ids: list[int], relation_type: type[Relation]) → list[dict[T2, list[Relation]]]

Given a list of entries, get connected relations of the given type. Returns a list, containing, for each input recon_id, a dictionary mapping connected vertices to the relation(s) with which they are connected.

explore_vertex(entry: T, relation_types: type[Relation[T, Any]]) → list[tuple[Entry, list[Relation]]]

Explores the neighbouring entries to a given entry. Results are returned as a list of tuples, each containing a neighbouring entry and the relations which point to it. Note that the input entry may be given in the output in the case of reflexive relations.

get_number_of_entries(table: type[T]) → int

Return hte number of entries in the table

iterate_table(table: type[T], batch_size: int = 1000, up_to: int = 0) → Generator[T, None, None]

Creates an iterator which queries all entries in a table. Entries are requested from the database in batches, but returned as a continuous iterator.

iterate_relation_with_entries(relationtype: type[Relation], batch_size: int = 1000, up_to: int = 0) → Generator[tuple[Relation, T1, T2], None, None]

Iterates the view over a relation table, getting entries adjacent to each relation.

Any operations which require modifying the database need to be called from a PopulateQueryHandler. Note that this is only possible on self-hosted databases, not the public database.

class chemrecon.PopulateQueryHandler(connection: Connection)

Bases: QueryHandler

Entries and relations are added to a PopulationQueryHandler, which batches operations and sends them to the database. When added, the handler will assign a correct ReconID to the object based on the current state of the corresponding sequence. Should be used as a context.

add_entry(entry: T, returning: bool = True, authoritative: bool = False) → int | None

Add an entry to the DB, returning its reconid immediately. If authoritative, allow overriding fields added previously. If not authoritative, do nothing on conflict.

add_entries(entries: list[T], returning: bool = True, authoritative: bool = False) → list[int] | None

TODO

add_relation(relation: Relation)

When adding a relation, it is expected that the ‘entry_1’ and ‘entry_2’ fields are filled such that the appropriate key can be looked up.

add_relation_by_recon_ids(recon_id_1: int, recon_id_2: int, relation: Relation)

Add a relation, using the recon_id fields of the given relation.

add_relations_by_recon_ids(relations: list[tuple[int, int, Relation]])

Add relations by recon_ids.

add_relation_by_entries(entry_1: T1, entry_2: T2, relation: Relation)

Add a relation, using the entry fields of the given relation.

add_relations_by_entries(relations: list[tuple[T1, T2, Relation]])

Add relations using the entry fields of each given relation.

add_entry_with_relations(entry: T1, relations: list[tuple[Relation, T2]]) → int

An entry and a number of relations to possibly new entries with the first entry as the source. Relations do not need to have their recon_id_1, recon_id_2, or entries filled. Returns id of source entry

add_relations_to_entry_with_reconid(recon_id: int, entry_table: type[Entry], relations: list[tuple[Relation, T2]] | list[tuple[Relation, T2]]) → list[int]

Add a number of relations from the given reconid. Returns a list of assigned Recon IDs in the same order as the input.