httk.serve.optimade.backend.execution
=====================================

.. py:module:: httk.serve.optimade.backend.execution

.. autoapi-nested-parse::

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



Classes
-------

.. autoapisummary::

   httk.serve.optimade.backend.execution.StoreResults


Functions
---------

.. autoapisummary::

   httk.serve.optimade.backend.execution.execute_query


Module Contents
---------------

.. py:class:: StoreResults(pairs, response_fields, unknown_response_fields, limit, offset, total_count, recognized_prefixes)

   Results of a query over one or more searchers.

   Implements the :class:`~httk.serve.optimade.model.results.QueryResults`
   protocol. Iteration yields one
   :class:`~httk.serve.optimade.model.results.ResultRow` per entry, whose values
   map response-field names to values extracted from the matched row objects.

   :param pairs: Sources and already-configured searchers to iterate.
   :param response_fields: Recognized fields to extract.
   :param unknown_response_fields: Unknown fields to return as null.
   :param limit: Maximum number of results to yield.
   :param offset: Number of results to skip.
   :param total_count: Total matches before pagination.
   :param recognized_prefixes: Prefixes for dynamic row attributes.


   .. py:attribute:: pairs


   .. py:attribute:: recognized_prefixes


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


   .. py:attribute:: limit


   .. py:attribute:: response_fields


   .. py:attribute:: unknown_response_fields


   .. py:attribute:: offset


   .. py:attribute:: more_data_available
      :value: True



   .. py:method:: 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.



.. py:function:: 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.

   :param adapter: Backend adapter providing sources and schema.
   :param entries: Entry endpoints to query.
   :param response_fields: Recognized fields to return.
   :param unknown_response_fields: Unknown fields to return as null.
   :param response_limit: Maximum number of returned rows.
   :param response_offset: Number of matching rows to skip.
   :param filter_ast: Parsed filter, when one was requested.
   :param sort: Fields and directions to sort by.
   :param debug: Enable backend diagnostics.
   :return: Lazy results for the requested page.
   :raises httk.serve.optimade.model.errors.TranslatorError: If sorting across multiple sources is requested.