httk.store.backend.sql.entry_provider¶

Serve stored dataclasses through the httk-core entry-provider contract.

StoreEntryProvider bridges the SQL storage layer to the neutral EntryProvider contract: it serves the rows of one or more storable classes in a SqlStore as described, JSON-able entry-type records, so a serving module (such as httk-serve) can expose a database as an OPTIMADE API without either side depending on the other.

For each served class the provider either passes through a supplied EntryTypeDefinition (validated to describe every served property) or auto-generates one from the class’s resolved TableSchema: the OPTIMADE core id/type properties plus one from_simple() definition per servable stored field, each named with a registered database-specific prefix (default "_httk_") and merged in via extended() — the same construction route the other httk entry providers use.

The schema-to-OPTIMADE type mapping is:

str/int/bool/float fields — string/integer/ boolean/float;
rational fields (fractions.Fraction, FracScalar, SurdScalar) — float, served as the nearest float (stored values themselves remain exact; only the served value is approximate);
datetime.datetime fields — timestamp, served as ISO-8601 text;
fixed-shape (Shape(r, c)) and variable-rows (Shape(0, c)) FracVector fields — list of list of float (the fixed shape also declares its dimension sizes);
list/tuple fields of scalars or of the codec types above — list of the mapped element type.

Not every stored field can be served as a property: bytes fields (and fields encoded by a custom, non-built-in value codec) have no OPTIMADE value representation and are skipped, while reference fields and child fields of storable elements surface through StoreEntryProvider.relationships() instead — when their target class is itself served, each record declares its related entries as a flat tuple of RelatedEntry values, carrying the role/description metadata of an optional Related field marker (Related(serve=False) suppresses the field as a relationship). Exposed weak links (WeakLink declared exposed_relationship=True) whose target class is served also surface through StoreEntryProvider.relationships(): each source lineage’s live latest link rows become related entries carrying the link’s role/description, resolved to the target lineage’s latest revision id (links declared exposed_relationship=False are served nowhere).

Classes¶

StoreEntryProvider

Serves the stored rows of storable classes as httk-core entry types.

Functions¶

`served_specs`(schema, prefix)	Return the served `(name, field spec, fulltype)` triples.
`auto_definition`(entry_type, schema, prefix)	Auto-generate the `EntryTypeDefinition` of a storable class.

Module Contents¶

httk.store.backend.sql.entry_provider.served_specs(schema, prefix)¶

Return the served (name, field spec, fulltype) triples.

Parameters:

schema (httk.store.backend.schema.TableSchema) – The resolved schema whose fields are inspected.
prefix (str) – The registered prefix used for served property names.

Returns:

One triple for every non-intrinsic schema field with an OPTIMADE value type. The store-managed id and immutable_id fields are intentionally omitted because serving layers expose them intrinsically.

Return type:

list[tuple[str, httk.store.backend.schema.FieldSpec, str]]

httk.store.backend.sql.entry_provider.auto_definition(entry_type, schema, prefix)¶

Auto-generate the EntryTypeDefinition of a storable class.

The definition carries the OPTIMADE core id/type properties plus one from_simple() definition per triple of served_specs(), named in the custom_ sub-namespace of prefix so generated names cannot collide with curated prefixed definitions, merged in via extended() (so prefix must be a registered definition prefix).

Parameters:

entry_type (str) – The entry type name to define.
schema (httk.store.backend.schema.TableSchema) – The resolved schema of the stored class.
prefix (str) – The registered prefix used for generated property names.

Returns:

The generated entry-type definition.

Return type:

httk.core.EntryTypeDefinition

class httk.store.backend.sql.entry_provider.StoreEntryProvider(store, classes, *, definitions=None, prefix='_httk_', id_of=None, only_latest=True)¶

Bases: httk.core.EntryProvider

Serves the stored rows of storable classes as httk-core entry types.

classes maps each served entry-type name to its storable dataclass; the classes’ tables are read through store. definitions optionally supplies the EntryTypeDefinition of an entry type (validated: it must describe every property the provider serves for it); entry types without a supplied definition get one auto-generated from the class’s schema, with every schema-derived property name carrying prefix (which must be registered, see register_definition_prefix()). id_of maps (entry_type, sid, instance) to the served entry id; the default reads the record’s store-minted id field.

See the module docstring for which stored fields are served as properties (and how their types map), which are skipped, and which surface through relationships() instead.

Parameters:

store (httk.store.backend.sql.store.SqlStore) – The SQL store containing the served records.
classes (collections.abc.Mapping[str, type]) – The served entry-type names and their storable classes.
definitions (collections.abc.Mapping[str, httk.core.EntryTypeDefinition] | None) – Optional definitions to use instead of auto-generation.
prefix (str) – The registered prefix for generated property names.
id_of (collections.abc.Callable[[str, int, Any], str] | None) – The function that maps a served record to its public id.
only_latest (bool) – Whether served searchers restrict root variables to the latest row of each lineage.

entry_types()¶

Return the definitions of all served entry types.

This provider is an OPTIMADE serving edge, so each definition is returned in its wire form via EntryTypeDefinition.served_form() (idempotent for the already-prefixed supplied and auto-generated definitions).

Returns:: The served entry-type definitions keyed by entry type.
Return type:: collections.abc.Mapping[str, httk.core.EntryTypeDefinition]

property_keys(entry_type)¶

Return the served property-to-storage-key mapping for an entry type.

Parameters:: entry_type (str) – The served entry type to inspect.
Returns:: The public property names and their storage keys.
Raises:: KeyError – If entry_type is not served.
Return type:: collections.abc.Mapping[str, str]

records(entry_type)¶

Yield JSON-able records for a served entry type.

Parameters:: entry_type (str) – The served entry type whose records are read.
Yield:: A served record.
Raises:: KeyError – If entry_type is not served.

relationships(entry_type)¶

Return relationships grouped by source entry id.

Related entries come from stored reference fields, child fields, exposed weak links targeting served storable classes, and StrongLink provenance edges in both directions: a run’s own edges under their forward wire key (e.g. _httk_has_input), and the derived reverse edges naming the runs that point at each served target under their reverse wire key (e.g. _httk_is_input). The reverse view is store-scoped (only this store’s StrongLink families are scanned) and lineage-level (only a run lineage’s latest main revision contributes).

Parameters:: entry_type (str) – The served entry type whose relationships are read.
Returns:: Related entries keyed by source entry id.
Raises:: KeyError – If entry_type is not served.
Return type:: collections.abc.Mapping[str, tuple[httk.core.RelatedEntry, Ellipsis]]