httk.serve.optimade.backend.protocols¶

Typed protocols for the store/searcher contract the OPTIMADE backend uses.

The store/searcher protocols are defined in httk.store.query (httk-store is where httk’s data stores live, and this backend programs against their shared query contract); this module re-exports them for the backend’s use, together with the OPTIMADE-specific query-callable types from the result model.

Classes¶

`Searcher`	Build one query and iterate its results.
`SearchExpression`	Require composable backend search expressions.
`SearchField`	Expose a queryable field of a search variable.
`SearchResult`	Represent one match with declared output values and names.
`SearchVariable`	Bind a query variable to a target type whose attributes yield fields.
`Store`	Require a store that can create a query searcher.
`QueryFunction`	The callback seam through which the request engine runs queries on a backend.
`QueryResults`	The results of a query against a backend, as consumed by the entry endpoints.

Module Contents¶

class httk.serve.optimade.backend.protocols.Searcher¶

Bases: Protocol

Build one query and iterate its results.

Iteration yields one SearchResult per match, so item[0][0] is the first declared output of the match (typically the matched row object). The expressions received by add are always ones produced by this same backend’s search variables, so implementations may type them as their own expression class; a backend that needs a second (post-filter) evaluation position decides that from the expression itself, not from the caller.

offset: int¶

variable(target)¶

Bind a query variable to target.

output(variable, name)¶

Declare variable as a named result output.

add(expression)¶

Add a filter expression to the query.

count()¶

Return the exact count of the current query.

set_limit(limit)¶

Set the query limit.

add_offset(offset)¶

Add an offset to the query.

add_sort(field, descending)¶

Add a field sort to the query.

results(**outputs)¶

Return a result set for the requested named outputs.

class httk.serve.optimade.backend.protocols.SearchExpression¶

Bases: Protocol

Require composable backend search expressions.

class httk.serve.optimade.backend.protocols.SearchField¶

Bases: Protocol

Expose a queryable field of a search variable.

In addition to the methods below, fields support the rich comparison operators (==, !=, <, <=, >, >=), returning SearchExpression. The handlers invoke those via getattr(field, '__eq__')(value) since the comparison dunders cannot be typed as expression-returning.

The three string-matching methods take literal text: no wildcard or pattern syntax whatsoever crosses this contract, so % and _ (and any other metacharacter) match themselves. A backend is therefore free to implement them with SQL LIKE over an escaped pattern, with a regular expression, or with a full-text index — the choice is invisible here.

has(value)¶

Match a list field containing value.

has_any(*values)¶

Match a list field containing any of values.

has_only(*values)¶

Match a list field containing no values outside values.

is_in(*values)¶

Match a root scalar field whose value is one of values.

None is an explicit member: it matches a null field value, and its negation excludes nulls rather than inheriting SQL’s three-valued NOT IN (..., NULL) behavior.

Backends define the corresponding semantics for child or set fields; for example, a backend may use the existing has_only-style all-values reading for a child field.

contains(text)¶

Match values containing text as a literal substring.

startswith(prefix)¶

Match values beginning with the literal prefix.

endswith(suffix)¶

Match values ending with the literal suffix.

class httk.serve.optimade.backend.protocols.SearchResult¶

Bases: NamedTuple

Represent one match with declared output values and names.

values holds one entry per Searcher.output() call in declaration order; it is a tuple, so values, names = result and result[0][0] both work.

values: tuple[Any, Ellipsis]¶

names: tuple[str, Ellipsis]¶

class httk.serve.optimade.backend.protocols.SearchVariable¶

Bases: Protocol

Bind a query variable to a target type whose attributes yield fields.

always_true/always_false are reserved names: they are real methods of the variable, never stored fields resolved through __getattr__. They exist so a translation layer can express a constant truth value without inventing a probe field. A field == field probe is NULL-unsound, since it yields NULL (not true) for a NULL field.

always_true()¶

An expression that matches every row.

always_false()¶

An expression that matches no row.

class httk.serve.optimade.backend.protocols.Store¶

Bases: Protocol

Require a store that can create a query searcher.

Implementations predating the as_of keyword may omit it and remain usable for current-state queries, but cannot honor historic queries.

searcher(*, as_of=None)¶

Create an empty searcher, optionally at a historic cutoff.

Parameters:: as_of (object) – Optional canonical historic timestamp cutoff.
Returns:: An empty query searcher.
Return type:: Searcher

class httk.serve.optimade.backend.protocols.QueryFunction¶

Bases: Protocol

The callback seam through which the request engine runs queries on a backend.

class httk.serve.optimade.backend.protocols.QueryResults¶

Bases: Protocol

The results of a query against a backend, as consumed by the entry endpoints.

Iteration yields one ResultRow per entry; its values map OPTIMADE response-field names to values, and the id and type keys are always present.

property more_data_available: bool¶

Report whether another page is available.

count()¶

Return the total number of matches before pagination.