httk.store.backend.sql.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

field_id_has_handlers(field, sids_for)

A '<related_type>.id' HAS handler matching a reference/child field against related sids.

optimade_filter_searcher(store, cls, filter_string, *)

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

Module Contents

httk.store.backend.sql.optimade.field_id_has_handlers(field, sids_for)

A '<related_type>.id' HAS handler matching a reference/child field against related sids.

sids_for(values) returns the sub-select of related-row sids the field’s foreign key must match for those values; the returned handler composes the HAS family over field with the correct set semantics. HAS ALL ANDs one fresh has_any per value (each over an independently joined child row, so a row must carry a child matching every value), HAS ANY is a single has_any over all values, and HAS ONLY uses has_only (a row with no such children matches vacuously).

Parameters:

  • field (str) – The backend reference or child-of-storable field name.

  • sids_for (collections.abc.Callable[[Any], Any]) – A callable mapping filter values to a related-sid sub-select.

Returns:

A handler mapping containing the HAS operation.

Raises:

FilterTranslationError – If an unexpected set operator is supplied.

Return type:

collections.abc.Mapping[str, collections.abc.Callable[Ellipsis, Any]]

httk.store.backend.sql.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 "<stored id>" resolves the supplied stored public id through a correlated subquery over the related table’s physical id column, then compares its sid to the reference (or child-element) column. The same stored-id rule is used by StoreEntryProvider.

  • 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:
Returns:

A searcher yielding the matching stored instances.

Raises:
Return type:

httk.store.query.Searcher