httk.store.backend.sql.stored_federation

Bounded, durable federation of stored entry-family property plans.

Unlike httk.store.federated_store, which is the general portable query protocol, this module joins only configured durable entry families. It can therefore retain a stable backing inventory, push candidate filtering and bounds into SQL, and delay record hydration until a global page is known.

Attributes

RelatedResolverFactory

Exceptions

DuplicateEntryIdError

Several durable origins claim the same public entry id.

Classes

StoredEntrySource

One named configured family in one durable entry store.

StoredEntryOrigin

The durable source of one public entry id.

StoredEntryPage

One immutable globally paginated response.

StoredEntryFederation

Merge one or more configured durable entry-family sources.

Functions

related_property_resolver_factory(plans)

Build a same-store depth-1 related-property resolver factory over sibling plans.

Module Contents

type httk.store.backend.sql.stored_federation.RelatedResolverFactory = Callable[[httk.store.store_common.EntryStore, RelationshipSourceMap | None], RelatedPropertyResolver | None]
httk.store.backend.sql.stored_federation.related_property_resolver_factory(plans)

Build a same-store depth-1 related-property resolver factory over sibling plans.

plans are the family plans available to a serving edge (one per source). The returned factory accepts the store whose row is being filtered and an optional RelationshipSourceMap, yielding a RelatedPropertyResolver that resolves a dotted <related_type>.<prop> filter to the matching related-entry ids by running the stripped sub-filter through the sibling plan for related_type in that same store (same-store scope, mirroring reverse serving). Only the sibling’s own properties are consulted; the sub-search runs only_latest=True over mains, so stale revisions and named alternatives can never satisfy the filter. With a relationship map, each matching candidate receives its concrete backing’s target prefix before ids are combined; that same prefix applies to id predicates in the sibling search. Unrelated backings are excluded, and custom wire types map back to the original plan type. Calling the factory with only the store returns raw stored ids instead. These ids feed the <related_type>.id HAS ... handler used by the semi-join rewrite.

Parameters:

plans (collections.abc.Sequence[httk.store.backend.sql.stored_properties.StoredPropertySqlPlan]) – The family plans (one per source) available to the serving edge.

Returns:

A per-store resolver factory (a miss returns an empty tuple, i.e. matches nothing).

Return type:

RelatedResolverFactory

class httk.store.backend.sql.stored_federation.StoredEntrySource

One named configured family in one durable entry store.

public_id_prefix is concatenated with every backing’s store-minted lineage id. It is intentionally not required to be unique: callers may retain a legacy unprefixed source, in which case collisions are detected when their visible ids are fetched or explicitly audited.

Parameters:

  • store – The durable entry store containing the entry family.

  • entry_family – The logical entry-family class to serve.

  • name – The unique name used to identify this source.

  • public_id_prefix – The prefix prepended to store-minted lineage ids.

  • relationship_sources – Explicit target-family to same-store source-name selections for ambiguous mounts.

store: httk.store.store_common.EntryStore
entry_family: type
name: str
public_id_prefix: str = ''
relationship_sources: collections.abc.Mapping[type, str]
class httk.store.backend.sql.stored_federation.StoredEntryOrigin

The durable source of one public entry id.

Parameters:

  • source – The configured source name.

  • source_index – The source’s position in the federation.

  • backing – The concrete backing name.

  • entry_id – The store-minted lineage id claimed by the backing.

source: str
source_index: int
backing: str
entry_id: str
exception httk.store.backend.sql.stored_federation.DuplicateEntryIdError(public_id, origins)

Bases: RuntimeError

Several durable origins claim the same public entry id.

Call StoredEntryFederation.audit_duplicate_ids() to perform the intentionally explicit complete audit; ordinary pages inspect only the candidates they would otherwise return.

Parameters:
public_id
origins
class httk.store.backend.sql.stored_federation.StoredEntryPage

One immutable globally paginated response.

total_count is the exact filtered count before global offset/limit. The sentinel establishing more_data_available is ID-only and is never present in rows.

Parameters:

  • rows – The rows visible in this page.

  • total_count – The exact filtered count before paging bounds.

  • more_data_available – Whether another row exists after this page.

  • relationships – The per-row exposed weak-link relationships, aligned with rows (an empty mapping for a row carrying none).

rows: tuple[collections.abc.Mapping[str, Any], Ellipsis]
total_count: int
more_data_available: bool
relationships: tuple[collections.abc.Mapping[str, tuple[httk.core.RelatedEntry, Ellipsis]], Ellipsis]
class httk.store.backend.sql.stored_federation.StoredEntryFederation(sources, *, served_type_names=None, related_resolver_factory=None, source_inventory=None)

Merge one or more configured durable entry-family sources.

Sources preserve caller order. Without a sort, rows remain in source, persisted-backing, and native database order and candidate SQL contains no ORDER BY. With a sort, each backing stream orders in SQL and this object performs a bounded heap merge with a deterministic public-id/source /backing tie-breaker.

Pages probe all sibling backings in prefixes shared by multiple sources. Within-source corruption is otherwise audit-only; use audit_duplicate_ids() to detect it.

Parameters:
property sources: tuple[StoredEntrySource, Ellipsis]

Return the immutable declared source order.

Returns:

The declared sources in caller order.

Return type:

tuple[StoredEntrySource, Ellipsis]

snapshot_cutoff_ns(now_ns)

Return the latest instant strictly before every capable source’s current bucket.

Per-source floor conversion then selects each store’s last completed timestamp unit, so future monotonic writes cannot enter the snapshot, even when sources use different timestamp resolutions. Timestamp- disabled sources are ignored; None means no source is capable.

Parameters:

now_ns (int) – Current time in nanoseconds.

Returns:

A nanosecond cutoff, or None when no source stores timestamps.

Return type:

int | None

query(filter_string=None, *, sort=(), offset=0, limit=None, as_of=None, fields=None, revisions=False, alternatives=False)

Return one globally merged page with an exact filtered total.

limit=0 intentionally runs only count plus an ID-only sentinel: it is suitable for metadata initialization and never duplicate-probes or hydrates a candidate.

Parameters:

  • filter_string (str | httk.core.optimade.FilterAst | None) – The OPTIMADE filter, parsed filter tree, or no filter.

  • sort (collections.abc.Sequence[tuple[str, bool]]) – The property sort keys and directions.

  • offset (int) – The number of matching rows to skip globally.

  • limit (int | None) – The maximum number of rows to return, or no maximum.

  • as_of (object) – Optional historic cutoff. Sources without store timestamps deliberately omit this cutoff and serve their current state. Dependencies of a visible row remain visible because references only point at earlier-or-equal rows from the same transaction.

  • fields (collections.abc.Collection[str] | None) – The response property names to render, or None to render every configured property.

  • revisions (bool) – Whether to stream immutable revisions of mains instead of latest mains.

  • alternatives (bool) – Whether to stream latest named alternatives with composite <id>~<kind> ids.

Returns:

The globally merged page.

Raises:

DuplicateEntryIdError – If a visible id has multiple cross-source origins.

Return type:

StoredEntryPage

fetch(public_id, *, as_of=None, fields=None, revisions=False, alternatives=False)

Fetch one public id and detect a collision among its possible origins.

Parameters:

  • public_id (str) – The public id to fetch.

  • as_of (object) – Optional historic cutoff. Sources without store timestamps deliberately omit this cutoff and serve their current state.

  • fields (collections.abc.Collection[str] | None) – The response property names to render, or None to render every configured property.

  • revisions (bool) – Whether public_id addresses an immutable revision instead of a main.

  • alternatives (bool) – Whether public_id is a composite <id>~<kind> alternative id.

Returns:

The fetched (row, relationships) pair, or None when absent.

Raises:

DuplicateEntryIdError – If the id has multiple origins.

Return type:

tuple[collections.abc.Mapping[str, Any], collections.abc.Mapping[str, tuple[httk.core.RelatedEntry, Ellipsis]]] | None

fetch_revision(entry_id, immutable_id, *, as_of=None, fields=None)

Fetch one immutable revision addressed by its lineage and revision ids.

Parameters:

  • entry_id (str) – The public lineage id of the revision.

  • immutable_id (str) – The public immutable revision id.

  • as_of (object) – Optional historic cutoff. Sources without store timestamps deliberately omit this cutoff and serve their current state.

  • fields (collections.abc.Collection[str] | None) – The response property names to render, or None to render every configured property.

Returns:

The fetched (row, relationships) pair, or None when absent.

Raises:

DuplicateEntryIdError – If the id has multiple origins.

Return type:

tuple[collections.abc.Mapping[str, Any], collections.abc.Mapping[str, tuple[httk.core.RelatedEntry, Ellipsis]]] | None

fetch_alternative(entry_id, kind, *, as_of=None, fields=None)

Fetch one named alternative addressed by its group entry id and kind.

The returned alternative is its own latest revision. A malformed kind misses like an absent one, matching fetch_revision().

Parameters:

  • entry_id (str) – The public group lineage id of the alternative.

  • kind (str) – The alternative kind selecting the named alternative.

  • as_of (object) – Optional historic cutoff. Sources without store timestamps deliberately omit this cutoff and serve their current state.

  • fields (collections.abc.Collection[str] | None) – The response property names to render, or None to render every configured property.

Returns:

The fetched (row, relationships) pair, or None when absent.

Raises:

DuplicateEntryIdError – If the id has multiple origins.

Return type:

tuple[collections.abc.Mapping[str, Any], collections.abc.Mapping[str, tuple[httk.core.RelatedEntry, Ellipsis]]] | None

audit_duplicate_ids(*, batch_size=_AUDIT_BATCH_SIZE)

Lazily scan sorted ID-only batches and raise on the first collision.

The audit includes duplicate ids across backings within one source as well as duplicates across sources.

Parameters:

batch_size (int) – The maximum number of candidate ids read per batch.

Returns:

None.

Raises:

DuplicateEntryIdError – If any public id has multiple origins.

Return type:

None