httk.store.federated_store¶

Frozen query planning and sequential execution for a federated store.

Federated expressions are deliberately represented by a private, backend-neutral AST. Child searcher expressions are used only while validating that each participating source accepts an operation; every execution replays that AST into fresh child searchers.

Exceptions¶

`FederatedStoreError`	Report that a federation-level store operation failed.
`FederatedSourceError`	Report that a named source rejected or failed a federated operation.

Classes¶

`FederatedResultColumn`	Expose one scalar projection lazily from a federated result set.
`FederatedResultSet`	Represent a frozen, lazy, re-iterable federated result plan.
`FederatedTarget`	Bind one logical target to exact concrete targets for named sources.
`FederatedStore`	Fan out read-only queries over an ordered collection of borrowed stores.
`FederatedVariable`	Represent the one root variable supported by a federated query.
`FederatedField`	Represent a backend-neutral path from a federated root variable.
`FederatedExpression`	Represent a federated expression backed by the neutral private AST.
`FederatedSearcher`	Build and validate one portable, single-root federated query.

Module Contents¶

exception httk.store.federated_store.FederatedStoreError¶

Bases: RuntimeError

Report that a federation-level store operation failed.

exception httk.store.federated_store.FederatedSourceError(source, operation)¶

Bases: FederatedStoreError

Report that a named source rejected or failed a federated operation.

Parameters:

source (str) – The source name that failed.
operation (str) – The federation operation being performed.

source¶

operation¶

class httk.store.federated_store.FederatedResultColumn(result, index)¶

Expose one scalar projection lazily from a federated result set.

Parameters:

result (FederatedResultSet) – The result set supplying rows.
index (int) – The zero-based projection index.

name¶

class httk.store.federated_store.FederatedResultSet(store, plan)¶

Represent a frozen, lazy, re-iterable federated result plan.

Results execute source-major in federation source order, preserve duplicate rows, and remain read-only views over the borrowed stores.

Parameters:

store (FederatedStore) – The federation whose sources execute the plan.
plan (object) – The validated frozen federation plan.

property names: tuple[str, Ellipsis]¶

Return the declared projection names.

Returns:: The result projection names in declaration order.
Return type:: tuple[str, Ellipsis]

first()¶

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

Returns:: The first matching row, or None.
Return type:: httk.store.query.ResultRow | None

one()¶

Return the only result row.

Returns:

The sole matching result row.

Raises:

httk.store.query.protocols.NoResultError – If no row matches.
httk.store.query.protocols.MultipleResultsError – If more than one row matches.

Return type:

httk.store.query.ResultRow

scalars(name=None)¶

Iterate over one named projection.

Parameters:

name (str | None) – The projection name, required when more than one output exists.

Returns:

An iterator over the selected projection values.

Raises:

ValueError – If no name is supplied for multiple outputs.
KeyError – If name is not a declared output.

Return type:

collections.abc.Iterator[object]

column(name)¶

Return a lazy scalar column by projection name.

Parameters:

name (str) – The scalar projection name.

Returns:

A lazy column view over the projection.

Raises:

KeyError – If name is not a declared output.
TypeError – If name identifies an object output.

Return type:

FederatedResultColumn

abstractmethod cursor()¶

Reject cursor access because federation cursors are unsupported.

Returns:: Never returns.
Raises:: NotImplementedError – Always, because federated cursors are not implemented.
Return type:: collections.abc.Iterator[httk.store.query.ResultRow]

class httk.store.federated_store.FederatedTarget¶

Bind one logical target to exact concrete targets for named sources.

Parameters:

name – The nonempty logical target name.
targets – Concrete targets keyed by federation source name.
_owner – The federation that owns this target binding.

Raises:

TypeError – If targets is not a mapping or _owner is not a federation.
ValueError – If the name, source set, or source names are invalid.

name: str¶

targets: collections.abc.Mapping[str, object]¶

class httk.store.federated_store.FederatedStore(sources)¶

Fan out read-only queries over an ordered collection of borrowed stores.

The union is source-major, lazy, and non-deduplicating. Queries require the strict common query surface accepted by every participating source, and counts are exact sums of the unpaged source counts. This live borrowed-store view is distinct from the persisted registry in httk.store.backend.sql.stored_federation.

Parameters:

sources (collections.abc.Mapping[str, httk.store.query.Store]) – Child stores keyed by stable federation source name.

Raises:

TypeError – If sources is not a mapping.
ValueError – If fewer than two sources or an invalid source name is supplied.

property source_names: tuple[str, Ellipsis]¶

Return the immutable source names in constructor iteration order.

Returns:: The source names in constructor order.
Return type:: tuple[str, Ellipsis]

target(name, targets)¶

Create an immutable target mapping for an intentional source subset.

Parameters:

name (str) – The logical target name.
targets (collections.abc.Mapping[str, object]) – Concrete targets keyed by federation source name.

Returns:

The validated target binding.

Raises:

TypeError – If targets is not a mapping.
ValueError – If a target name or source name is invalid.

Return type:

FederatedTarget

searcher(*, as_of=None, only_latest=False)¶

Create an unbound federated searcher without touching child stores.

Parameters:

as_of (object) – Optional historic cutoff forwarded to every child store. A child that cannot honor it raises and the federation surfaces that child failure; this is a user-facing store API.
only_latest (bool) – Whether each child restricts root variables to the latest row of each lineage. A child that cannot honor it raises and the federation surfaces that child failure.

Returns:

A new mutable query builder.

Return type:

FederatedSearcher

class httk.store.federated_store.FederatedVariable(searcher, variables, targets)¶

Represent the one root variable supported by a federated query.

Parameters:

searcher (FederatedSearcher) – The owning federated searcher.
variables (collections.abc.Mapping[str, httk.store.query.SearchVariable]) – Child variables keyed by source name.
targets (collections.abc.Mapping[str, object]) – Concrete child targets keyed by source name.

always_true()¶

Build an expression that matches every federated row.

Returns:: A federated expression matching every row.
Return type:: FederatedExpression

always_false()¶

Build an expression that matches no federated row.

Returns:: A federated expression matching no row.
Return type:: FederatedExpression

class httk.store.federated_store.FederatedField(variable, path)¶

Represent a backend-neutral path from a federated root variable.

Parameters:

variable (FederatedVariable) – The federated root variable owning the path.
path (tuple[str, Ellipsis]) – The field path relative to that variable.

contains(text)¶

Match literal values containing text.

Parameters:: text (str) – The literal substring to find.
Returns:: The resulting federated expression.
Return type:: FederatedExpression

startswith(prefix)¶

Match literal values beginning with prefix.

Parameters:: prefix (str) – The literal prefix to find.
Returns:: The resulting federated expression.
Return type:: FederatedExpression

endswith(suffix)¶

Match literal values ending with suffix.

Parameters:: suffix (str) – The literal suffix to find.
Returns:: The resulting federated expression.
Return type:: FederatedExpression

has(value)¶

Match a list field containing value.

Parameters:: value (object) – The list member to match.
Returns:: The resulting federated expression.
Return type:: FederatedExpression

has_any(*values)¶

Match a list field containing any of values.

Parameters:: *values (object) – The list members to match.
Returns:: The resulting federated expression.
Return type:: FederatedExpression

has_only(*values)¶

Match a list field containing no values outside values.

Parameters:: *values (object) – The complete allowed list-member set.
Returns:: The resulting federated expression.
Return type:: FederatedExpression

is_in(*values)¶

Match a scalar field whose value is one of values.

Parameters:: *values (object) – The accepted field values.
Returns:: The resulting federated expression.
Return type:: FederatedExpression

class httk.store.federated_store.FederatedExpression(searcher, ast)¶

Represent a federated expression backed by the neutral private AST.

Parameters:

searcher (FederatedSearcher) – The owning federated searcher.
ast (object) – The validated private expression tree.

class httk.store.federated_store.FederatedSearcher(store, *, as_of=None, only_latest=False)¶

Build and validate one portable, single-root federated query.

Parameters:

store (FederatedStore) – The federation whose child stores provide the query surface.
as_of (object) – Optional historic cutoff forwarded to child stores.
only_latest (bool) – Whether each child restricts root variables to the latest row of each lineage.

offset = 0¶

origin¶

variable(target)¶

Bind one shared or explicit target against child searcher prototypes.

Parameters:

target (object) – A shared child target or a source-specific target binding.

Returns:

The federated root variable.

Raises:

httk.store.query.protocols.UnsupportedQueryError – If a second root or foreign target is supplied.
FederatedSourceError – If a source rejects target binding.

Return type:

FederatedVariable

add(expression)¶

Validate and retain a portable condition for the future frozen plan.

Parameters:

expression (object) – An expression produced by this searcher.

Returns:

None.

Raises:

httk.store.query.protocols.UnsupportedQueryError – If the expression belongs to another searcher.
FederatedSourceError – If a source rejects the expression.

Return type:

None

output(value, name)¶

Declare a record, scalar field, or origin output for a future plan.

Parameters:

value (object) – The root variable, field, or origin sentinel to project.
name (str) – The nonempty output name.

Returns:

None.

Raises:

ValueError – If name is empty or already declared.
httk.store.query.protocols.UnsupportedQueryError – If value is not owned by this searcher.
FederatedSourceError – If a source rejects the output.

Return type:

None

add_sort(field, descending=False)¶

Reject global sorting until a portable sort-semantics contract exists.

Parameters:

field (object) – The requested sort field.
descending (bool) – Whether the requested order is descending.

Raises:

httk.store.query.protocols.UnsupportedQueryError – Always, because global federation sorting has no portable contract.

count()¶

Return the exact unpaged count of the current filtered union.

Returns:

The exact sum of matching rows across participating sources.

Raises:

httk.store.query.protocols.CountUnavailableError – If a source cannot provide an exact count.
FederatedSourceError – If a source fails while counting.

Return type:

int

set_limit(limit)¶

Set the global output limit; a negative value clears it.

Parameters:: limit (int) – The nonnegative limit, or a negative value to clear it.
Returns:: None.
Raises:: TypeError – If limit is not an integer.
Return type:: None

add_offset(offset)¶

Add a global source-union offset.

Parameters:

offset (int) – The nonnegative number of union rows to skip.

Returns:

None.

Raises:

TypeError – If offset is not an integer.
ValueError – If offset is negative.

Return type:

None

results(**outputs)¶

Freeze a projection plan into a lazy, re-iterable result set.

Parameters:

**outputs (object) – Optional output names mapped to root variables or fields.

Returns:

The lazy frozen result set.

Raises:

ValueError – If no outputs are declared or an output name is invalid.
httk.store.query.protocols.UnsupportedQueryError – If an output does not belong to this searcher.
FederatedSourceError – If a source rejects an output.

Return type:

FederatedResultSet

slicer(target)¶

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

Each terminal indexing operation runs against a fresh federated searcher minted with this searcher’s as_of/only_latest scope, so slicer operations never share filter state. Slicer masks never sort, so the federation’s rejection of sorting does not apply.

Parameters:: target (object) – The stored record class to index.
Returns:: A slicer over target.
Return type:: httk.store.query.Slicer