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.