httk.serve.optimade.backend.execution

Query execution: runs translated searchers and adapts results for the endpoints.

Classes

StoreResults

Results of a query over one or more searchers.

Functions

execute_query(adapter, entries, response_fields, ...)

Execute a translated query across the adapter's sources.

Module Contents

class httk.serve.optimade.backend.execution.StoreResults(pairs, response_fields, unknown_response_fields, limit, offset, total_count, recognized_prefixes)

Results of a query over one or more searchers.

Implements the QueryResults protocol. Iteration yields one ResultRow per entry, whose values map response-field names to values extracted from the matched row objects.

Parameters:

• pairs (list[tuple[httk.serve.optimade.backend.adapter.EntrySource, httk.store.query.Searcher]]) – Sources and already-configured searchers to iterate.

• response_fields (list[str]) – Recognized fields to extract.

• unknown_response_fields (list[str]) – Unknown fields to return as null.

• limit (int | None) – Maximum number of results to yield.

• offset (int) – Number of results to skip.

• total_count (int) – Total matches before pagination.

• recognized_prefixes (tuple[str, Ellipsis]) – Prefixes for dynamic row attributes.

pairs

recognized_prefixes

cur: collections.abc.Iterator[tuple[httk.serve.optimade.backend.adapter.EntrySource, Any]] | None

limit

response_fields

unknown_response_fields

offset

more_data_available = True

count()

Return all current-filter matches, before pagination.

The endpoint metadata needs the filtered total even after execution has applied page limits and offsets to its searchers. Retaining it here also keeps the value stable once this one-shot result iterator is consumed.

httk.serve.optimade.backend.execution.execute_query(adapter, entries, response_fields, unknown_response_fields, response_limit, response_offset, filter_ast=None, *, sort=None, debug=False)

Execute a translated query across the adapter’s sources.

Parameters:

• adapter (httk.serve.optimade.backend.adapter.BackendAdapter) – Backend adapter providing sources and schema.

• entries (list[str]) – Entry endpoints to query.

• response_fields (list[str]) – Recognized fields to return.

• unknown_response_fields (list[str]) – Unknown fields to return as null.

• response_limit (int | None) – Maximum number of returned rows.

• response_offset (int | None) – Number of matching rows to skip.

• filter_ast (httk.core.optimade.FilterAst | None) – Parsed filter, when one was requested.

• sort (collections.abc.Sequence[tuple[str, bool]] | None) – Fields and directions to sort by.

• debug (bool) – Enable backend diagnostics.

Returns:

Lazy results for the requested page.

Raises:

httk.serve.optimade.model.errors.TranslatorError – If sorting across multiple sources is requested.

Return type:

StoreResults