httk.store.query¶

Define backend-agnostic query protocols and portable query capabilities.

The httk.store.query.optimade_filters module contains OPTIMADE filter-translation machinery for serving layers and is intentionally not lifted here.

Submodules¶

Attributes¶

ID_FIELD

The backend field name used for the served entry identifier.

Exceptions¶

`CountUnavailableError`	Report that a store cannot provide an exact query count.
`MultipleResultsError`	Report that a result-set `one()` operation found multiple results.
`NoResultError`	Report that a result-set `one()` operation found no matching result.
`PaginationCursorError`	Report that a continuation cursor is malformed, expired, or belongs to another result plan.
`UnsupportedQueryError`	Report that a valid query operation is outside a store's supported profile.

Classes¶

`PortableQueryCapabilities`	Describe the query operations guaranteed by one property definition.
`ContinuationToken`	Carry an opaque URL-safe continuation value.
`PageOrder`	Order a continuation page by one named scalar result projection.
`PageableResultSetLike`	Expose optional continuation-page capability on a frozen result set.
`ResultPage`	Represent an immutable continuation-page result.
`ResultRow`	Represent one named result row by position, name, or attribute.
`ResultRowLike`	Require named access to one result row.
`ResultSetLike`	Require the common operations of a materialized result set.
`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.
`Searcher`	Build one query and iterate its results.
`Store`	Require a store that can create a query searcher.
`Slicer`	A pandas-style indexing view over one record class in a store.
`SlicerColumn`	One field of a `Slicer`, iterable and comparable.
`SlicerMask`	A boolean predicate over a `Slicer`, combinable with `& \| ^ ~`.
`SlicerSelection`	The records of a `Slicer` matching a `SlicerMask`.

Functions¶

`portable_query_capabilities`(definition)	Derive the portable operation subset for `definition`.
`portable_query_fields`(entry_type, *[, include, exclude])	Return the ordered portable query fields described by `entry_type`.

Package Contents¶

class httk.store.query.PortableQueryCapabilities¶

Describe the query operations guaranteed by one property definition.

query-support expresses a cross-provider guarantee, not a particular server’s implementation detail. all optional is deliberately fail-closed here: it gives a portable client no operation it can rely on. A server may offer more, but that is not represented by the definition.

Parameters:

query_support – The normalized declared query-support level.
operations – The portable operation families guaranteed by the definition.

query_support: str | None¶

operations: frozenset[str]¶

supports(operation)¶

Report whether operation is guaranteed by this definition.

Parameters:: operation (str) – The operation family to test.
Returns:: True when the operation is portable.
Return type:: bool

httk.store.query.portable_query_capabilities(definition)¶

Derive the portable operation subset for definition.

The operation names are "equality", "ordering", "stringmatching", and "set". They intentionally describe the query-language operation families rather than storage implementation. IS [NOT] KNOWN is part of the equality family because it is the NULL spelling of equality/inequality in the OPTIMADE filter language.

Parameters:: definition (httk.core.PropertyDefinition) – The OPTIMADE property definition to inspect.
Returns:: The guaranteed portable query capabilities.
Return type:: PortableQueryCapabilities

httk.store.query.portable_query_fields(entry_type, *, include=(), exclude=())¶

Return the ordered portable query fields described by entry_type.

By default, this selects scalar fields and flat lists with at least one operation guaranteed by their definition. include is an explicit binding override for named existing properties; it is appended as a second ordered group after the derived fields, in entry-definition order among the included names, but does not manufacture query capabilities absent from that definition. exclude always wins. Both arguments reject unknown or duplicate names so binding mistakes cannot silently broaden a profile.

Parameters:

entry_type (httk.core.EntryTypeDefinition) – The entry definition whose properties are inspected.
include (collections.abc.Iterable[str]) – Existing property names to append to the derived selection.
exclude (collections.abc.Iterable[str]) – Existing property names to remove from the selection.

Returns:

Derived property names followed by explicitly included names.

Raises:

ValueError – If include or exclude contains an unknown or duplicate property name.

Return type:

tuple[str, Ellipsis]

httk.store.query.ID_FIELD: Final = '__id'¶: The backend field name used for the served entry identifier.

class httk.store.query.ContinuationToken¶

Bases: str

Carry an opaque URL-safe continuation value.

It is a str subclass so normal JSON serializers preserve it as a scalar value. Applications should pass a token returned by a page back unchanged; data backends validate its version, structure, and result-plan fingerprint before using any decoded value as a bound parameter.

Parameters:: value – The opaque continuation value.

exception httk.store.query.CountUnavailableError¶

Bases: RuntimeError

Report that a store cannot provide an exact query count.

exception httk.store.query.MultipleResultsError¶

Bases: LookupError

Report that a result-set one() operation found multiple results.

exception httk.store.query.NoResultError¶

Bases: LookupError

Report that a result-set one() operation found no matching result.

class httk.store.query.PageOrder¶

Order a continuation page by one named scalar result projection.

name identifies the name supplied to results() (or Searcher.output()), never a backend column object. The result-set implementation validates that it is a root scalar projection before it generates SQL.

Parameters:

name – The declared scalar output name used for ordering.
descending – Whether to order this field in descending order.
nulls – Whether null values sort first or last.

name: str¶

descending: bool = False¶

nulls: Literal['first', 'last'] = 'last'¶

class httk.store.query.PageableResultSetLike¶

Bases: Protocol

Expose optional continuation-page capability on a frozen result set.

This deliberately extends neither ResultSetLike nor Searcher: stores that do not support seek pagination remain fully conforming to the required portable contracts.

page(*, size, order_by, cursor=None, include_total=False)¶

Return one ordered continuation page.

exception httk.store.query.PaginationCursorError¶

Bases: ValueError

Report that a continuation cursor is malformed, expired, or belongs to another result plan.

class httk.store.query.ResultPage¶

Represent an immutable continuation-page result.

rows is always a tuple. Returned rows are ordinary persistent result rows, not the expiring proxies produced by SqlResultSet.cursor(). total is populated only when the caller explicitly asks for it.

Parameters:

rows – The persistent rows returned by the page.
next – The token for the next page, if one exists.
previous – The token for the previous page, if one exists.
total – The exact result count when requested, otherwise None.

rows: tuple[ResultRowLike, Ellipsis]¶

next: ContinuationToken | None¶

previous: ContinuationToken | None¶

total: int | None = None¶

class httk.store.query.ResultRow(values, names, resolver=None, guard=None)¶

Represent one named result row by position, name, or attribute.

Parameters:

values (tuple[Any, Ellipsis]) – The row values in declaration order.
names (tuple[str, Ellipsis]) – The corresponding output names.
resolver (Any) – An optional lazy value resolver.
guard (Any) – An optional callback that rejects access to expired values.

property names: tuple[str, Ellipsis]¶

Return the declared output names.

property values: tuple[Any, Ellipsis]¶

Return the row values in declaration order.

class httk.store.query.ResultRowLike¶

Bases: Protocol

Require named access to one result row.

property names: tuple[str, Ellipsis]¶

Return the row’s declared output names.

class httk.store.query.ResultSetLike¶

Bases: Protocol

Require the common operations of a materialized result set.

first()¶

Return the first row, or None when no row matches.

one()¶

Return the only row, or raise when the count is not one.

scalars(name=None)¶

Iterate over one named scalar output.

class httk.store.query.SearchExpression¶

Bases: Protocol

Require composable backend search expressions.

class httk.store.query.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.store.query.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.store.query.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.store.query.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.store.query.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

exception httk.store.query.UnsupportedQueryError¶

Bases: ValueError

Report that a valid query operation is outside a store’s supported profile.

class httk.store.query.Slicer(make_searcher, target)¶

A pandas-style indexing view over one record class in a store.

Index it with a field-name string to iterate that field’s values, or with a boolean SlicerMask to iterate the matching records. Iterating the slicer itself yields every record; len() counts them. Each operation runs against its own fresh searcher, so operations never share filter state.

Parameters:

make_searcher (collections.abc.Callable[[], Any]) – A zero-argument callable returning a fresh searcher.
target (Any) – The stored record class this slicer indexes.

class httk.store.query.SlicerColumn(slicer, path)¶

One field of a Slicer, iterable and comparable.

Iterating yields the field’s decoded scalar values. Comparisons and the isin/isna/notna/between helpers, plus the .str literal matchers, build a SlicerMask for use as a slicer index key.

Parameters:

slicer (Slicer) – The owning slicer.
path (tuple[str, Ellipsis]) – The attribute names from the query variable to this field.

isin(values)¶

Match records whose field value is one of values.

Parameters:: values (collections.abc.Iterable[Any]) – The membership set.
Returns:: A mask matching records in the set.
Return type:: SlicerMask

isna()¶

Match records whose field value is null.

Returns:: A mask matching null field values.
Return type:: SlicerMask

notna()¶

Match records whose field value is not null.

Returns:: A mask matching non-null field values.
Return type:: SlicerMask

between(low, high)¶

Match records whose field value lies in [low, high] inclusive.

Parameters:

low (Any) – The inclusive lower bound.
high (Any) – The inclusive upper bound.

Returns:

A mask matching the closed interval.

Return type:

SlicerMask

property str: _SlicerStr¶

The literal string-matching accessor for this column.

Returns:: The contains/startswith/endswith accessor.
Return type:: _SlicerStr

class httk.store.query.SlicerMask(slicer, ast)¶

A boolean predicate over a Slicer, combinable with & | ^ ~.

A mask is not iterable and has no comparison operators; it is used only as a slicer index key or combined with another mask from the same slicer.

Parameters:

slicer (Slicer) – The owning slicer.
ast (_Node) – The op tree the mask describes.

class httk.store.query.SlicerSelection(slicer, ast)¶

The records of a Slicer matching a SlicerMask.

Iterating yields the reconstructed records; len() counts them. Each runs against its own fresh searcher.

Parameters:

slicer (Slicer) – The owning slicer.
ast (_Node) – The op tree selecting the records.