httk.store.backend.sql

The SQL storage layer of httk-store: store frozen dataclasses in relational databases.

This subpackage turns plain frozen dataclasses — declared storable with the stdlib-only marker vocabulary in httk-core (Indexed, Unique, Skip, Shape, StorageInfo, stored_property) — into relational storage. The driver-free, backend-neutral foundation lives one level up, in the httk.store.backend package, and is shared by every backend:

• httk.store.backend.schema — resolve_schema() reads a storable class into a TableSchema, the single source of truth for DDL, inserts, selects, and reconstruction;

• httk.store.backend.codecs — the ValueCodec registry with exact, round-trippable encodings for rationals, surds, and datetimes;

• httk.core.storage — canonical_form and content_id, the content identity used for deduplication.

These modules import cleanly without sqlalchemy. The SQL layer proper builds on them and requires the httk-store[db] extra (sqlalchemy):

• Backend — the engine wrapper naming where data lives (Backend.sqlite(...), Backend.duckdb(...), Backend.postgresql(...), or the Keeper-backed Backend.clickhouse(...));

• SqlStore — save/fetch/dedup/transactions for storable instances, on top of the schema-to-table mapping in httk.store.backend.sql.mapping;

• SqlSearcher (from searcher()) — the query DSL implementing the httk.store.query search protocols, with SqlVariable, SqlColumn and SqlExpression;

• StoreEntryProvider — the bridge that serves stored classes through the neutral EntryProvider contract (e.g. as an OPTIMADE API via httk-serve);

• optimade_filter_searcher() — OPTIMADE-filter querying over storable classes, tying the generic filter translation in httk.store.query.optimade_filters to the SQL layer.

The sqlalchemy-backed names are imported lazily on first attribute access, so import httk.store.backend.sql keeps working without sqlalchemy; touching them without sqlalchemy installed raises ImportError naming the extra.

Submodules

• httk.store.backend.sql.bulk
• httk.store.backend.sql.bulk_deferred
• httk.store.backend.sql.bulk_parallel
• httk.store.backend.sql.engine
• httk.store.backend.sql.entry_provider
• httk.store.backend.sql.fsck
• httk.store.backend.sql.graph
• httk.store.backend.sql.layout
• httk.store.backend.sql.mapping
• httk.store.backend.sql.optimade
• httk.store.backend.sql.paging
• httk.store.backend.sql.provenance_edges
• httk.store.backend.sql.results
• httk.store.backend.sql.rows
• httk.store.backend.sql.searcher
• httk.store.backend.sql.store
• httk.store.backend.sql.stored_federation
• httk.store.backend.sql.stored_properties

Exceptions

MultipleResultsError	Report that a result-set one() operation found multiple results.
NoResultError	Report that a result-set one() operation found no matching result.

Classes

ResultRow

Represent one named result row by position, name, or attribute.

Package Contents

exception httk.store.backend.sql.MultipleResultsError

Bases: LookupError

Report that a result-set one() operation found multiple results.

exception httk.store.backend.sql.NoResultError

Bases: LookupError

Report that a result-set one() operation found no matching result.

class httk.store.backend.sql.ResultRow(values, names, resolver=None, guard=None)

Represent one named result row by position, name, or attribute.

Parameters:

• values (tuple[Any, Ellipsis]) – The row values in declaration order.

• names (tuple[str, Ellipsis]) – The corresponding output names.

• resolver (Any) – An optional lazy value resolver.

• guard (Any) – An optional callback that rejects access to expired values.

property names: tuple[str, Ellipsis]

Return the declared output names.

property values: tuple[Any, Ellipsis]

Return the row values in declaration order.