httk.store.query.protocols

Typed protocols for the store/searcher query contract.

These protocols define the backend-agnostic query interface shared by httk data stores: the database layer in httk-store implements them over SQL, and serving modules (such as httk-serve, whose in-memory store also conforms) program against them. They mirror the query interface of the httk v1 database layer (httk.db FilteredCollection searchers), so lightweight fakes can stand in for a real store in tests.

Attributes

ID_FIELD

The backend field name used for the served entry identifier.

Exceptions

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

Classes

PageOrder	Order a continuation page by one named scalar result projection.
ContinuationToken	Carry an opaque URL-safe continuation value.
ResultPage	Represent an immutable continuation-page result.
PageableResultSetLike	Expose optional continuation-page capability on a frozen result set.
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.
SearchVariable	Bind a query variable to a target type whose attributes yield fields.
Searcher	Build one query; consume it through Searcher.results().
BackendSearcher	A searcher plus its private, backend-internal raw query surface.
Store	Require a store that can create a query searcher.

Module Contents

httk.store.query.protocols.ID_FIELD: Final = '__id'

The backend field name used for the served entry identifier.

exception httk.store.query.protocols.UnsupportedQueryError

Bases: ValueError

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

exception httk.store.query.protocols.CountUnavailableError

Bases: RuntimeError

Report that a store cannot provide an exact query count.

exception httk.store.query.protocols.NoResultError

Bases: LookupError

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

exception httk.store.query.protocols.MultipleResultsError

Bases: LookupError

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

exception httk.store.query.protocols.PaginationCursorError

Bases: ValueError

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

class httk.store.query.protocols.PageOrder

Order a continuation page by one named scalar result projection.

name identifies the name supplied to results(), 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.protocols.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.

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

next: ContinuationToken | None

previous: ContinuationToken | None

total: int | None = None

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

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

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

Parameters:

• values (tuple[Any, ...]) – The row values in declaration order.

• names (tuple[str, ...]) – 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, ...]

Return the declared output names.

property values: tuple[Any, ...]

Return the row values in declaration order.

class httk.store.query.protocols.ResultRowLike

Bases: Protocol

Require named access to one result row.

property names: tuple[str, ...]

Return the row’s declared output names.

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

Bases: Protocol

Require composable backend search expressions.

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

Bases: Searcher, Protocol

A searcher plus its private, backend-internal raw query surface.

Result sets, the federated store, stored-property streaming and entry providers build a query and consume its matches through the raw path below; user code consumes a query through Searcher.results() instead.

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