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; consume it through Searcher.results().
SearchExpression	Require composable backend search expressions.
SearchField	Expose a queryable field of a search variable.
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; consume it through Searcher.results().

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.

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

links.<name> is a reserved relationship namespace: usable as a predicate root (v.links.p == other, field chaining, set operations) and, on its own, as a set-valued output declared through Searcher.results().

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.