httk.store.mongo.searcher

MongoDB query planning for the neutral httk.store.query protocols.

The planner keeps a truth/falsity pair for each predicate. This is important for embedded arrays: the negation of “some element matches” is “no element matches”, not MongoDB’s row-like $ne interpretation.

Classes

ComparisonNode	Compare one stored field with a literal or another field.
IsInNode	Test a scalar field for explicit membership.
StringMatchNode	Match literal text in a scalar string field.
AndNode	Conjoin two AST nodes.
OrNode	Disjoin two AST nodes.
NotNode	Negate an AST node by swapping its truth and falsity filters.
AlwaysTrueNode	An AST constant that is true for every document.
AlwaysFalseNode	An AST constant that is false for every document.
MongoExpression	A composable MongoDB expression backed by a neutral AST node.
MongoField	A scalar field, or the value channel of an embedded child field.
MongoVariable	A query variable, optionally produced by a lookup from another variable.
MongoSearcher	Build and execute a MongoDB query over reference-connected variables.

Module Contents

class httk.store.mongo.searcher.ComparisonNode

Compare one stored field with a literal or another field.

field: MongoField

op: Literal['eq', 'ne', 'lt', 'le', 'gt', 'ge']

literal: Any

class httk.store.mongo.searcher.IsInNode

Test a scalar field for explicit membership.

field: MongoField

values: tuple[Any, Ellipsis]

class httk.store.mongo.searcher.StringMatchNode

Match literal text in a scalar string field.

field: MongoField

mode: Literal['contains', 'startswith', 'endswith']

text: str

class httk.store.mongo.searcher.AndNode

Conjoin two AST nodes.

left: Any

right: Any

class httk.store.mongo.searcher.OrNode

Disjoin two AST nodes.

left: Any

right: Any

class httk.store.mongo.searcher.NotNode

Negate an AST node by swapping its truth and falsity filters.

child: Any

class httk.store.mongo.searcher.AlwaysTrueNode

An AST constant that is true for every document.

class httk.store.mongo.searcher.AlwaysFalseNode

An AST constant that is false for every document.

class httk.store.mongo.searcher.MongoExpression(node)

A composable MongoDB expression backed by a neutral AST node.

node

class httk.store.mongo.searcher.MongoField(variable, key_path, spec, codec=None, child_keys=(), presentation_prefix='')

A scalar field, or the value channel of an embedded child field.

is_in(*values)

Match a scalar member, or universally constrain a child field.

has(value)

Match a child collection containing value.

has_any(*values)

Match a child collection containing any supplied value.

has_only(*values)

Match a child collection containing no value outside those supplied.

contains(text)

Match a literal substring, case-sensitively.

startswith(prefix)

Match a literal, case-sensitive prefix.

endswith(suffix)

Match a literal, case-sensitive suffix.

class httk.store.mongo.searcher.MongoVariable(searcher, cls, schema, alias)

A query variable, optionally produced by a lookup from another variable.

property sid: MongoField

Return the store-managed sid field.

always_true()

Return an expression matching every stored document.

always_false()

Return an expression matching no stored document.

class httk.store.mongo.searcher.MongoSearcher(store)

Build and execute a MongoDB query over reference-connected variables.

offset = 0

set_row_verifier(verifier, identity)

Attach the client-authoritative candidate verifier and its frozen identity.

The identity must be the canonical logical predicate payload, including every verifier constant. It is folded into continuation fingerprints, so cursors never cross between otherwise identical server plans.

Parameters:

• verifier (collections.abc.Callable[[dict[str, Any]], bool]) – Return whether a server candidate is a real match.

• identity (str | bytes) – Canonical text or bytes identifying the verifier logic.

Raises:

TypeError – If either attachment component has the wrong type.

variable(target)

Bind a query variable; each additional one must be join-connected.

output(variable, name)

Declare an object variable or scalar field output.

add(expression)

Add a filter expression, conjoined with earlier filters.

add_sort(field, descending=False, *, nulls='last')

Append a stable scalar sort with an explicit null rank.

set_limit(limit)

Set the iteration limit; negative values clear it.

add_offset(offset)

Add rows to the iteration offset.

count()

Return the exact filtered count, ignoring offset and limit.

results(**outputs)

Return a materialized MongoResultSet for this query.