httk.store.backend.sql.stored_properties

SQL plans for property-mapped durable entry backings.

This module translates the backend-neutral httk.core.storage.StoredPropertyProjection callbacks declared by one concrete record backing into SQLAlchemy predicates. A logical entry family supplies its entry type and OPTIMADE definition; every backing configured for that family in the SqlStore supplies only the properties it can actually represent.

The plan is deliberately independent of serving. It exposes concrete-record responses and one SQL searcher per backing, leaving a later protocol adapter to apply public ids, merge backing result streams, and construct envelopes.

Exceptions

StoredPropertySqlConfigurationError

A configured family/backing cannot realize its declared entry definition.

Classes

RelationshipSourceMap

Carry resolved mount prefixes and wire names for one source's relationships.

StoredPropertySqlCandidateStream

One raw, SQL-bounded backing stream for a later federation merge.

StoredPropertySqlPlan

Validated responses and SQL queries for one configured logical entry family.

Functions

stored_property_sql_plan(store, family, *[, served])

Validate and return the SQL property plan for one configured logical family.

Module Contents

exception httk.store.backend.sql.stored_properties.StoredPropertySqlConfigurationError

Bases: ValueError

A configured family/backing cannot realize its declared entry definition.

class httk.store.backend.sql.stored_properties.RelationshipSourceMap

Carry resolved mount prefixes and wire names for one source’s relationships.

Federations derive this mapping from their source inventory.

Parameters:

  • prefixes – Loose-edge forward target prefixes keyed by internal family type.

  • reverse_prefixes – Prefixes of reverse source mounts keyed by their concrete backing class.

  • wire_types – Served relationship target names keyed by internal family type.

  • backing_prefixes – Typed target prefixes keyed by their concrete backing class.

prefixes: collections.abc.Mapping[str, str]
reverse_prefixes: collections.abc.Mapping[type, tuple[str, Ellipsis]]
wire_types: collections.abc.Mapping[str, str]
backing_prefixes: collections.abc.Mapping[type, str]
class httk.store.backend.sql.stored_properties.StoredPropertySqlCandidateStream

One raw, SQL-bounded backing stream for a later federation merge.

searcher outputs only sid, stored id, stored immutable_id, stored alt_kind (NULL for mains), and one raw SQL value per requested sort property. Iterating it therefore never hydrates a record; a federation can select its final page before fetching any object graph.

Parameters:

  • backing – The concrete record class represented by the stream.

  • backing_name – The stable persisted name of the backing.

  • searcher – The SQL searcher yielding the candidate projections.

  • sort_count – The number of requested sort projections in each row.

  • timestamp_output – Whether each row ends with a canonical timestamp value.

backing: type
backing_name: str
searcher: httk.store.backend.sql.searcher.SqlSearcher
sort_count: int
timestamp_output: bool = False
class httk.store.backend.sql.stored_properties.StoredPropertySqlPlan(store, family, layout, entry_type, definition, backings)

Validated responses and SQL queries for one configured logical entry family.

The plan has no federation semantics: filter_searchers() returns one independent searcher per configured concrete backing. That explicit shape preserves backing-local property semantics for a future protocol adapter.

Parameters:

  • store (httk.store.backend.sql.store.SqlStore) – The SQL store containing the configured family.

  • family (type) – The logical entry-family class.

  • layout (Any) – The resolved persisted layout for the family.

  • entry_type (str) – The served entry type name.

  • definition (httk.core.EntryTypeDefinition) – The entry definition used for property validation.

  • backings (tuple[_BackingPlan, Ellipsis]) – The validated concrete backing plans in persisted order.

store
family
layout
entry_type
definition
property backings: tuple[type, Ellipsis]

Return the configured concrete record classes in persisted order.

Returns:

The configured backing classes.

Return type:

tuple[type, Ellipsis]

records()

Yield protocol-boundary rows projected from concrete backing records.

Yield:

A projected protocol-boundary row.

filter_searchers(filter_string, *, sort=(), public_id_prefix='', as_of=None, only_latest=False, revisions=False, alternatives=False, related_property_resolver=None)

Return one concrete-backing SQL searcher for an OPTIMADE filter and sort list.

Parameters:

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

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

  • public_id_prefix (str) – The prefix used when filtering or sorting ids.

  • as_of (object) – Optional historic cutoff in canonical timestamp form.

  • only_latest (bool) – Whether root variables are restricted to the latest row of each lineage.

  • revisions (bool) – Whether ids render immutable revisions instead of mains (mains-only lineage stream).

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

  • related_property_resolver (httk.store.query.optimade_filters.RelatedPropertyResolver | None) – Optional depth-1 related-property resolver; the default matches nothing.

Returns:

One searcher for each configured backing.

Return type:

tuple[httk.store.backend.sql.searcher.SqlSearcher, Ellipsis]

candidate_searchers(filter_string=None, *, sort=(), public_id_prefix='', as_of=None, only_latest=False, revisions=False, alternatives=False, related_property_resolver=None, relationship_source_map=None)

Return ID-only concrete streams for a bounded federated page.

None emits the query context’s portable true predicate. It never adds an ORDER BY unless a sort was explicitly requested. The supplied public-id prefix participates in both the intrinsic id filter handlers and id sort expression. Every row also carries the raw alt_kind (NULL for mains) so a federation can render composite alternative ids without a second read.

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.

  • public_id_prefix (str) – The prefix used when filtering or sorting ids.

  • as_of (object) – Optional historic cutoff in canonical timestamp form.

  • only_latest (bool) – Whether root variables are restricted to the latest row of each lineage.

  • revisions (bool) – Whether ids render immutable revisions instead of mains (mains-only lineage stream).

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

  • related_property_resolver (httk.store.query.optimade_filters.RelatedPropertyResolver | None) – Optional depth-1 related-property resolver; the default matches nothing.

  • relationship_source_map (RelationshipSourceMap | None) – Resolved relationship mount prefixes and wire names, when federated.

Returns:

One candidate stream for each configured backing.

Return type:

tuple[StoredPropertySqlCandidateStream, Ellipsis]

response_row(backing, record, *, public_id=None, httk_id=None, revisions=False, kind=None, store_timestamp=None, fields=None)

Render one hydrated backing record at the protocol boundary.

Parameters:

  • backing (type) – The configured concrete class of record.

  • record (object) – The hydrated backing record to project.

  • public_id (str | None) – The public id to use, or the record’s canonical id when omitted.

  • httk_id (str | None) – The plain group entry id rendered for _httk_id when serving revisions or alternatives.

  • revisions (bool) – Whether the row is served from a revision stream (synthesizes _httk_id).

  • kind (str | None) – The alternative kind rendered for _httk_kind when serving alternatives, else None.

  • store_timestamp (int | None) – An already-normalized timestamp from a candidate stream, when available.

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

Returns:

The protocol-boundary response row.

Raises:

StoredPropertySqlConfigurationError – If backing is not configured for the family.

Return type:

collections.abc.Mapping[str, Any]

httk.store.backend.sql.stored_properties.stored_property_sql_plan(store, family, *, served=None)

Validate and return the SQL property plan for one configured logical family.

The family must be present in store.entry_layout; unconfigured family classes and their records cannot accidentally become part of a durable entry source. id, type, immutable_id, _httk_id, and _httk_kind are intrinsic: a concrete backing’s store-minted identifiers and the family’s fixed entry type. Backings must not redeclare any intrinsic property.

The family’s internal definition is used only to establish identity (that the family and its records agree on one durable definition). Everything the plan then serves — the entry type, the property set that response and filter/sort validation runs against, and the projection names backings must match — is taken from served: the OPTIMADE wire form of that definition (see EntryTypeDefinition.served_form()). A prefixed family declares its __httk_stored_properties__ projections under those served names, so it MUST be planned with served= set; without it the bare internal definition rejects the prefixed projection keys as unknown. When served is omitted the internal definition serves itself, which is byte-identical for standard (unprefixed) families.

Parameters:
Returns:

The validated SQL property plan.

Raises:

StoredPropertySqlConfigurationError – If the family or any backing is inconsistent with its definition.

Return type:

StoredPropertySqlPlan