httk.data.db.optimade

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

optimade_filter_searcher() builds a SqlSearcher over a storable class directly from an OPTIMADE filter string, deriving the recognized property names and their types from the class’s resolved TableSchema — the same derivation StoreEntryProvider uses to serve the class (via the shared served_specs() / 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

optimade_filter_searcher(→ httk.data.query.Searcher)

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

Module Contents

httk.data.db.optimade.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[source]

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

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

Property names. Every servable stored field of cls (per 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 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 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 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 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: