httk.store.db.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¶

`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)

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

Module Contents¶

exception httk.store.db.stored_properties.StoredPropertySqlConfigurationError[source]¶

Bases: ValueError

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

class httk.store.db.stored_properties.StoredPropertySqlCandidateStream[source]¶

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

searcher outputs only sid, canonical content_id, 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.

backing: type[source]¶

backing_name: str[source]¶

searcher: httk.store.db.searcher.SqlSearcher[source]¶

sort_count: int[source]¶

class httk.store.db.stored_properties.StoredPropertySqlPlan(store, family, layout, entry_type, definition, backings)[source]¶

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.db.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[source]¶

family[source]¶

layout[source]¶

entry_type[source]¶

definition[source]¶

property backings: tuple[type, Ellipsis][source]¶

Return the configured concrete record classes in persisted order.

Returns:: The configured backing classes.
Return type:: tuple[type, Ellipsis]

records()[source]¶

Yield protocol-boundary rows projected from concrete backing records.

Yield:: A projected protocol-boundary row.

filter_searchers(filter_string, *, sort=(), public_id_prefix='')[source]¶

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.

Returns:

One searcher for each configured backing.

Return type:

tuple[httk.store.db.searcher.SqlSearcher, Ellipsis]

candidate_searchers(filter_string=None, *, sort=(), public_id_prefix='')[source]¶

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.

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.

Returns:

One candidate stream for each configured backing.

Return type:

tuple[StoredPropertySqlCandidateStream, Ellipsis]

response_row(backing, record, *, public_id=None)[source]¶

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.

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.db.stored_properties.stored_property_sql_plan(store, family)[source]¶

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 and type are intrinsic: a concrete backing’s canonical content_id and the family’s fixed entry type respectively. Backings must not try to redeclare either property.

Parameters:

store (httk.store.db.store.SqlStore) – The SQL store containing the configured family.
family (type) – The logical entry-family class to validate.

Returns:

The validated SQL property plan.

Raises:

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

Return type:

StoredPropertySqlPlan