httk.store.backend.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.
LinkPredicateNode	A no-$unwind existential/universal predicate over a weak-link target array.
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.
MongoLinks	The links namespace of a query variable: one weak link per attribute.
MongoLinkSet	One weak-link traversal from a query variable to the latest live-linked targets.
MongoLinkField	A scalar or encoded field of a weak-link target, compared existentially.
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.backend.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.backend.mongo.searcher.IsInNode

Test a scalar field for explicit membership.

field: MongoField

values: tuple[Any, ...]

class httk.store.backend.mongo.searcher.LinkPredicateNode

A no-$unwind existential/universal predicate over a weak-link target array.

The link $lookup leaves each source document carrying an array field at path of its live, latest-of-lineage link elements (each with target_lid and an embedded _httk_target doc). predicate is an $elemMatch body matching one such element. For an existential (universal=False: == / has_any / a chained-field comparison) the truth is “some element matches” and the falsity “no element matches” — the latter vacuously true for a zero-link source, so ~ negates set-wise. For a universal (universal=True: has_only) predicate matches an outsider: truth is “no outsider”, falsity “some outsider”.

path: str

predicate: dict[str, Any]

universal: bool

class httk.store.backend.mongo.searcher.StringMatchNode

Match literal text in a scalar string field.

field: MongoField

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

text: str

class httk.store.backend.mongo.searcher.AndNode

Conjoin two AST nodes.

left: Any

right: Any

class httk.store.backend.mongo.searcher.OrNode

Disjoin two AST nodes.

left: Any

right: Any

class httk.store.backend.mongo.searcher.NotNode

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

child: Any

class httk.store.backend.mongo.searcher.AlwaysTrueNode

An AST constant that is true for every document.

class httk.store.backend.mongo.searcher.AlwaysFalseNode

An AST constant that is false for every document.

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

A composable MongoDB expression backed by a neutral AST node.

node

class httk.store.backend.mongo.searcher.MongoField(variable, key_path, spec, codec=None, child_keys=(), presentation_prefix='', operand_converter=None, presentation_converter=None, alternative_composite=False)

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.backend.mongo.searcher.MongoLinks(variable)

The links namespace of a query variable: one weak link per attribute.

Each attribute access resolves the declared LinkSpec and returns a fresh MongoLinkSet — a new link $lookup array every time, never memoized on (variable, name). That freshness lets AND-composed predicates on the same link constrain independent link elements (so (v.links.p.name == 'A') & (v.links.p.name == 'B') is a HAS-ALL over two distinct linked targets), matching the SQL backend and OPTIMADE HAS ALL.

Parameters:

variable (MongoVariable) – The query variable whose weak links this namespace exposes.

class httk.store.backend.mongo.searcher.MongoLinkSet(variable, spec)

One weak-link traversal from a query variable to the latest live-linked targets.

Construction registers nothing: the $lookup that leaves each source document carrying an array field (_httk_link_<n>) of its live, latest-of-lineage link elements, each embedding the latest revision of its target lineage as _httk_target (bounded by as_of when set), is appended lazily by _register() on first use as a predicate operand — so a link set used only as a set-valued results() output (resolved after the query, from the parent document’s own logical_id) never adds a $lookup stage. The array is deliberately not $unwind-ed once registered — that would multiply source documents and break grouped multiplicity and count(); predicates are no-unwind $elemMatch array predicates instead (see LinkPredicateNode).

Identity comparisons (== stored_object, has_any(), has_only()) run over each element’s target_lid; attribute access chains into a scalar or encoded field of the latest target revision.

Parameters:

• variable (MongoVariable) – The query variable the link traverses from.

• spec (httk.store.backend.schema.LinkSpec) – The resolved weak-link declaration.

has(value)

Match a live linked target among value.

Parameters:

value (Any) – The stored target to match.

Returns:

The matching expression.

Return type:

MongoExpression

has_any(*values)

Match at least one live linked target among values.

Parameters:

*values (Any) – The stored targets to match.

Returns:

The matching expression.

Return type:

MongoExpression

has_only(*values)

Require every live linked target to be among values (a no-links source matches).

Parameters:

*values (Any) – The complete set of allowed stored targets.

Returns:

The condition requiring every linked target to match.

Return type:

MongoExpression

class httk.store.backend.mongo.searcher.MongoLinkField(link_set, spec)

A scalar or encoded field of a weak-link target, compared existentially.

Each comparison yields a LinkPredicateNode whose $elemMatch body reaches into the embedded _httk_target doc of a link element: the match is “some live-linked target satisfies the comparison”, and ~ negates set-wise (including a vacuous match on a zero-link source).

Parameters:

• link_set (MongoLinkSet) – The traversal supplying the link array path and target codec context.

• spec (httk.store.backend.schema.FieldSpec) – The resolved scalar or encoded target field.

contains(text)

Match a live-linked target whose field contains text (case-sensitive).

startswith(prefix)

Match a live-linked target whose field starts with prefix.

endswith(suffix)

Match a live-linked target whose field ends with suffix.

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

property links: MongoLinks

Return the weak-link namespace of this variable.

class httk.store.backend.mongo.searcher.MongoSearcher(store, *, as_of=None, only_latest=False, only_main_alt=True)

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

An historic cutoff is injected for every root and lookup variable; visible rows’ dependencies are always visible because references only point at earlier-or-equal rows from the same transaction. When only_latest is set, every declared (root) variable is additionally restricted to the latest document of its logical_id lineage by sid (bounded by as_of when given); reference/lookup variables stay unfiltered so pinned references may still resolve replaced documents.

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, scalar field, or weak-link-set output.

A weak-link-set output (a bare v.links.<name>) yields a tuple of the latest live-linked targets per row, resolved after the query from the source document’s own logical_id; it registers no $lookup, unlike predicate use of the same link set. Chaining into a target field (v.links.<name>.<field>) stays rejected.

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.

slicer(target)

A pandas-style [] indexing view over target records.

Each terminal indexing operation runs against a fresh searcher minted with this searcher’s as_of/only_latest/only_main_alt scope, so slicer operations never share filter state.

Parameters:

target (type) – The stored record class to index.

Returns:

A slicer over target.

Return type:

httk.store.query.Slicer