httk.store.db.optimade

Serve OPTIMADE filters over stored dataclasses through the SQL query layer.

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(store, cls, filter_string, *)

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

Module Contents

httk.store.db.optimade.optimade_filter_searcher(store, cls, filter_string, *, prefix='_httk_', definition=None, extra_handlers=None, related_classes=None)

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).

Parameters:

• store (httk.store.db.store.SqlStore) – The SQL store containing the rows to query.

• cls (type) – The storable class whose rows are searched.

• filter_string (str | httk.core.optimade.FilterAst) – The OPTIMADE filter string or parsed filter tree.

• prefix (str) – The registered prefix used for served property names.

• definition (httk.core.EntryTypeDefinition | None) – An optional entry definition supplying additional property types.

• extra_handlers (collections.abc.Mapping[str, collections.abc.Mapping[str, collections.abc.Callable[Ellipsis, Any]]] | None) – Optional handlers for ids, types, or additional properties.

• related_classes (collections.abc.Mapping[str, type] | None) – Related entry types and their storable classes.

Returns:

A searcher yielding the matching stored instances.

Raises:

• FilterTranslationError – When the filter cannot be translated.

• ParserSyntaxError – When a filter string does not parse.

• ValueError – When a related_classes entry does not match exactly one reference or child-of-storable field of cls.

Return type:

httk.store.query.Searcher