httk.data.db.optimade
=====================

.. py:module:: httk.data.db.optimade

.. autoapi-nested-parse::

   OPTIMADE-filter querying over stored dataclasses: sugar tying the SQL layer to the translator.

   :func:`optimade_filter_searcher` builds a :class:`~httk.data.db.searcher.SqlSearcher`
   over a storable class directly from an OPTIMADE filter string, deriving the
   recognized property names and their types from the class's resolved
   :class:`~httk.data.db.schema.TableSchema` — the same derivation
   :class:`~httk.data.db.entry_provider.StoreEntryProvider` uses to serve the
   class (via the shared :func:`~httk.data.db.entry_provider.served_specs` /
   :func:`~httk.data.db.entry_provider.auto_definition` helpers), so a filter
   that works against the served API works against the store.

   Filter property names are the served names: ``{prefix}{field}`` (default
   ``_httk_<field>``) for every servable stored field. Related storable classes
   declared via ``related_classes`` can be filtered relationally —
   ``references.id HAS "references-3"`` and depth-1 related-property filters like
   ``references._httk_doi CONTAINS "10.1"`` — over the class's reference or
   child-of-storable fields.



Functions
---------

.. autoapisummary::

   httk.data.db.optimade.optimade_filter_searcher


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

.. py:function:: optimade_filter_searcher(store: httk.data.db.store.SqlStore, cls: type, filter_string: str | httk.core.FilterAst, *, prefix: str = '_httk_', definition: httk.core.EntryTypeDefinition | None = None, extra_handlers: collections.abc.Mapping[str, collections.abc.Mapping[str, collections.abc.Callable[Ellipsis, Any]]] | None = None, related_classes: collections.abc.Mapping[str, type] | None = None) -> httk.data.query.Searcher

   Build a searcher over the stored rows of ``cls`` from an OPTIMADE filter.

   ``filter_string`` is an OPTIMADE filter string or an already-parsed
   :py:type:`~httk.core.FilterAst`. The returned searcher outputs the matching
   stored instances (``item[0][0]`` per match).

   **Property names.** Every servable stored field of ``cls`` (per
   :func:`~httk.data.db.entry_provider.served_specs`) is filterable as
   ``{prefix}{field}``, with its schema-derived fulltype driving constant
   conversion and handler dispatch (rational fields compare on their
   documented-approximate float query column). Unknown names carrying
   ``prefix`` raise :class:`~httk.data.optimade_query.FilterTranslationError`
   (``"unrecognized-property"``); other unknown names match nothing, per the
   OPTIMADE specification. Unprefixed property names (beyond ``id``/``type``)
   are recognized only when a ``definition`` describes them — and even then
   they translate only if ``extra_handlers`` supplies their handlers, since
   the store knows no column for them. The OPTIMADE core ``id`` and ``type``
   properties are recognized but **not supported** without ``extra_handlers``
   entries (a store row has no served id: ids are minted at serving time), so
   filtering on them raises ``"not-implemented"``.

   **Relationships.** ``related_classes`` maps relationship-type names to
   storable classes; each must be the target of exactly one reference or
   child-of-storable (``list[Target]``) field of ``cls`` (anything else
   raises :class:`ValueError`). For each such ``(rtype, rcls)``:

   - ``<rtype>.id HAS "<rtype>-<sid>"`` filters over the field's foreign-key
     (or child-element) column against default-minted
     ``"<entry type>-<sid>"`` ids, as
     :class:`~httk.data.db.entry_provider.StoreEntryProvider` mints them;
     ids of any other format match nothing. Custom ``id_of`` minting is out
     of scope here — with a custom minting scheme, supply your own
     ``'<rtype>.id'`` entry via ``extra_handlers``.
   - Depth-1 related-property filters (``<rtype>._httk_doi CONTAINS "10.1"``,
     ``<rtype>.id != "..."``, ``<rtype>._httk_year IS KNOWN``, ...) resolve by
     a two-phase semi-join: a nested ``optimade_filter_searcher`` over
     ``rcls`` (with the same ``prefix``; no further relationship nesting)
     collects the matching related sids, which are then matched as
     ``<rtype>.id HAS ANY ...``. Each dotted filter node resolves
     independently — see :func:`~httk.data.optimade_query.translate_filter_ast`.

   ``extra_handlers`` entries are merged over the derived handler table last
   (so they can also override derived handlers); extra property names that are
   otherwise unknown are recognized with fulltype ``"unknown"`` (filter
   constants pass through unconverted).

   :raises httk.data.optimade_query.FilterTranslationError: When the filter cannot be translated.
   :raises httk.core.ParserSyntaxError: When a filter string does not parse.
   :raises ValueError: When a ``related_classes`` entry does not match exactly one
       reference or child-of-storable field of ``cls``.