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, Ellipsis]¶

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 a $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). The array is deliberately not $unwind-ed — 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 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.

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