Query Iterators#

Query functions typically return objects that behave like iterators. These objects do not allow for direct access to individual items (like iter[0]), but do allow for looping through them.

The reason for returning an iterator rather than a list is that an iterator will handle batching to the server. Since a query can return many items, they must be retrieved in batches. The iterator does this automatically, but does so incrementally as iteration continues.

>>> query_it = client.query_molecules(molecular_formula='N2')
>>> for mol in query_it:
...    print(mol.id, mol.identifiers.molecular_formula)
371 N2
372 N2

If you need all items as a list, then you can use the list constructor, which will use the iterator to fill in the list. In this case, all the records will be fetched from the server as the list is being created.

>>> query_it = client.query_molecules(molecular_formula='N2')
>>> mols = list(query_it)
>>> print(len(mols))
621

Iterators API#

class MoleculeQueryIterator(client, query_filters)[source]#

Bases: QueryIteratorBase[Molecule]

Iterator for molecule queries

This iterator transparently handles batching and pagination over the results of a molecule query.

Construct an iterator

Parameters:

  • client – QCPortal client object used to contact/retrieve data from the server

  • query_filters (MoleculeQueryFilters) – The actual query information to send to the server

reset()#

Starts retrieval of results from the beginning again

class RecordQueryIterator(client, query_filters, record_type, include=None)[source]#

Bases: QueryIteratorBase[_Record_T]

Iterator for all types of record queries

This iterator transparently handles batching and pagination over the results of a record query, and works with all kinds of records.

Construct an iterator

Parameters:

  • client – QCPortal client object used to contact/retrieve data from the server

  • query_filters (RecordQueryFilters) – The actual query information to send to the server

  • record_type (Type[_Record_T]) – What type of record we are querying for

  • include (Optional[Iterable[str]])

reset()#

Starts retrieval of results from the beginning again