httk.store.query.optimade_filters¶

Translate OPTIMADE filter syntax trees into backend search expressions.

This module turns the OPTIMADE filter language — parsed by httk.core.optimade.parse_optimade_filter() into a httk.core.optimade.FilterAst nested-tuple syntax tree — into SearchExpression objects over the backend-agnostic store/searcher protocols of httk.store.query. It is pure and store-independent: any Store whose search variables expose the queried fields can execute the translated expressions.

The translation is driven by three inputs:

property_fulltypes — a minimal mapping from recognized property names to their OPTIMADE fulltype strings ("string", "integer", "float", "boolean", "timestamp", "dict", "unknown", or "list of ..."), used to type-check and convert filter constants;
handlers — a HandlerTable mapping property names to the callables that build the actual search expressions (see simple_property_handlers() for the generic property-key-driven builder, and relationship_id_handler() for <type>.id relationship entries);
recognized_prefixes — property-name prefixes the serving side claims: an unknown property carrying such a prefix is an error ("unrecognized-property"), while any other unknown property silently matches nothing, as the OPTIMADE specification prescribes.

Failures raise FilterTranslationError, which carries a neutral category (no HTTP semantics); consumers map categories onto their transport’s error codes.

Relationship filtering (dotted identifiers such as references.doi) is supported for relationship types named in relationship_targets: <type>.id HAS ... translates directly through the handler table, and any other depth-1 dotted filter is resolved by a two-phase semi-join through a supplied RelatedPropertyResolver (see translate_filter_ast()). Each dotted filter node is resolved independently: in references.doi CONTAINS "x" AND references.year >= 2000, some related reference must match the doi condition and some (possibly different) related reference must match the year condition.

Attributes¶

`FilterTranslationCategory`	Why a filter could not be translated (see `FilterTranslationError`).
`HandlerTable`	Per-property translation callables, keyed by property name.
`RelatedPropertyResolver`	Resolve a depth-1 relationship filter to the matching related-entry ids.
`constant_types`	Parsed filter token kinds that represent literal constants.
`invert_op`	Comparison operators after swapping a constant from left to right.

Exceptions¶

FilterTranslationError

Report that a filter cannot be translated into a search expression.

Functions¶

`format_value`(fulltype, val[, allow_null])	Convert a filter constant node to a Python value of the property's `fulltype`.
`true_handler`(search_variable)	Build a constant-true expression over `search_variable`.
`false_handler`(search_variable)	Build a constant-false expression over `search_variable`.
`unknown_unknown_handler`(entry, search_variable, ...)	Translate unknown-value tests for an unrecognized property.
`known_unknown_handler`(entry, search_variable, unknown_type)	Translate known-value tests for a property with known nullability.
`field_unknown_handler`(entry, search_variable, unknown_type)	Test nullability against the mapped backend field.
`unknown_comparison_handler`(entry, ops, values, ...)	Build a false expression for comparison on an unknown property.
`unknown_stringmatching_handler`(entry, values, ...)	Build a false expression for string matching on an unknown property.
`unknown_has_handler`(entry, op, value, search_variable, ...)	Build a false expression for set filtering on an unknown property.
`unknown_length_handler`(entry, op, value, search_variable)	Build a false expression for length filtering on an unknown property.
`string_handler`(entry, op, value, search_variable)	Translate a scalar comparison onto a backend field.
`stringmatching_handler`(entry, value, ...)	Translate `CONTAINS`/`STARTS`/`ENDS` onto the field's literal matchers.
`constant_comparison_handler`(val1, op, val2, ...)	Fold `val1 <op> val2` (both constants) to a constant expression.
`constant_stringmatching_handler`(val1, val2, ...)	Fold `val1 <CONTAINS\|STARTS\|ENDS> val2` (both constants) to a constant expression.
`number_handler`(entry, op, value, search_variable)	Translate a numeric comparison onto a backend field.
`timestamp_handler`(entry, op, value, search_variable)	Normalize an RFC 3339 timestamp and translate its comparison.
`set_handler`(entry, ops, values, has_type, search_variable)	Translate one HAS family node over the list-valued field `entry`.
`constant_set_handler`(val1, ops, val2, has_type, ...)	Fold a HAS-family operation over two constant sets.
`translate_filter_ast`(node, search_variable, ...[, ...])	Translate one filter syntax-tree node into a search expression.
`simple_property_handlers`(entry_type, property_keys, ...)	Build a filter handler table for an entry type from a property-key map.
`relationship_id_handler`(rel_key)	A `'<type>.id'` handler-table entry matching related ids over a list-valued field.
`filter_searcher`(store, target, filter_string, *, ...)	Build a `Searcher` over `store` applying an OPTIMADE filter.

Module Contents¶

type httk.store.query.optimade_filters.FilterTranslationCategory = Literal['unrecognized-property', 'not-implemented', 'type-mismatch', 'internal'][source]¶: Why a filter could not be translated (see FilterTranslationError).

type httk.store.query.optimade_filters.HandlerTable = Mapping[str, Mapping[str, Callable[..., Any]]][source]¶

Per-property translation callables, keyed by property name.

The inner mapping’s keys name the filter-operation families: 'comparison' (=, !=, <, <=, >, >=), 'stringmatching' (CONTAINS/STARTS/ENDS), 'HAS' (the set operations), 'length' (LENGTH), and 'unknown' (IS KNOWN/IS UNKNOWN). A 'HAS' handler is called as handler(property, ops, values, search_variable, has_type) and returns a plain SearchExpression. The caller applies NOT as ~; handlers do not receive negation state or report post-filter placement. Dotted '<type>.id' entries provide relationship-id filtering (see relationship_id_handler()).

type httk.store.query.optimade_filters.RelatedPropertyResolver = Callable[[str, FilterAst], tuple[str, ...]][source]¶

Resolve a depth-1 relationship filter to the matching related-entry ids.

Called as resolver(related_type, sub_ast) where sub_ast is the filter node with the <related_type>. prefix stripped from its identifier (and without any surrounding NOT); returns the ids of the related entries matching the sub-filter, evaluated against the related type’s own properties.

exception httk.store.query.optimade_filters.FilterTranslationError(message, category, detail=None)[source]¶

Bases: Exception

Report that a filter cannot be translated into a search expression.

The exception message describes the failure; category classifies it neutrally (this module knows nothing about transports, so consumers map each category onto their own error codes):

"unrecognized-property" — the filter names an unknown property carrying a recognized prefix (a caller error);
"type-mismatch" — a filter constant does not match the property’s declared type (a caller error);
"not-implemented" — the filter uses a construct this translation (or the supplied handler table) does not support;
"internal" — an inconsistency in the translation itself.

detail optionally carries extra machine-readable context.

Parameters:

message (str) – The human-readable translation failure.
category (FilterTranslationCategory) – The neutral failure category.
detail (str | None) – Optional machine-readable failure context.

category: FilterTranslationCategory[source]¶

detail = None[source]¶

httk.store.query.optimade_filters.constant_types = ('String', 'Number', 'Boolean')[source]¶: Parsed filter token kinds that represent literal constants.

httk.store.query.optimade_filters.invert_op[source]¶: Comparison operators after swapping a constant from left to right.

httk.store.query.optimade_filters.format_value(fulltype, val, allow_null=False)[source]¶

Convert a filter constant node to a Python value of the property’s fulltype.

Parameters:

fulltype (str) – The OPTIMADE fulltype expected by the property.
val (tuple[Any, ...]) – The parsed filter constant node.
allow_null (bool) – Whether a parsed null constant is accepted.

Returns:

The converted Python filter value.

Raises:

FilterTranslationError – With category "type-mismatch" when the constant does not fit the declared type, or "not-implemented" for dictionary-typed properties.

Return type:

Any

httk.store.query.optimade_filters.true_handler(search_variable)[source]¶

Build a constant-true expression over search_variable.

Parameters:: search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.
Returns:: An expression that matches every row.
Return type:: httk.store.query.SearchExpression

httk.store.query.optimade_filters.false_handler(search_variable)[source]¶

Build a constant-false expression over search_variable.

Parameters:: search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.
Returns:: An expression that matches no row.
Return type:: httk.store.query.SearchExpression

httk.store.query.optimade_filters.unknown_unknown_handler(entry, search_variable, unknown_type)[source]¶

Translate unknown-value tests for an unrecognized property.

Parameters:

entry (str) – The property name, retained for handler compatibility.
search_variable (httk.store.query.SearchVariable) – The backend search variable receiving the expression.
unknown_type (str) – The IS_KNOWN or IS_UNKNOWN operator.

Returns:

The corresponding constant expression.

Raises:

FilterTranslationError – If unknown_type is not supported.

Return type: