httk.serve.optimade.backend

Public backend adapters, stores, and filter translation helpers.

Submodules

• httk.serve.optimade.backend.adapter
• httk.serve.optimade.backend.execution
• httk.serve.optimade.backend.handlers
• httk.serve.optimade.backend.memory_store
• httk.serve.optimade.backend.partial
• httk.serve.optimade.backend.protocols
• httk.serve.optimade.backend.providers
• httk.serve.optimade.backend.stores
• httk.serve.optimade.backend.translation

Classes

BackendAdapter	Bind a store to the OPTIMADE entry endpoints it serves.
EntrySource	Describe one queryable source behind an OPTIMADE entry endpoint.
StoreResults	Results of a query over one or more searchers.
InMemoryStore	Provide a store over dictionary rows.
PartialDimension	Describe one list axis of a PartialValue.
PartialValue	Describe a property value provided lazily, one slice at a time.
QueryFunction	The callback seam through which the request engine runs queries on a backend.
QueryResults	The results of a query against a backend, as consumed by the entry endpoints.
StoredBackendAdapter	Serve one data federation per OPTIMADE entry type.

Functions

execute_query(adapter, entries, response_fields, ...)	Execute a translated query across the adapter's sources.
adapter_from_providers(providers, **options)	Build a BackendAdapter serving the given entry providers.
providers_from_registry()	Return the registered entry-provider factories keyed by their registered name.
adapter_from_store(store, **options)	Build a lazy OPTIMADE adapter from every described family in one store.
adapter_from_stores(sources, **options)	Build a lazy store-backed adapter from durable entry sources.
translate_filter(filter_ast, entries, adapter[, sort])	Build one searcher per entry source, with the filter applied to each.
translate_filter_node(node, search_variable, entry, ...)	Translate one filter node against an OPTIMADE entry-info property mapping.

Package Contents

class httk.serve.optimade.backend.BackendAdapter

Bind a store to the OPTIMADE entry endpoints it serves.

sources maps entry endpoint names (e.g. 'structures') to the sources queried for that endpoint; an endpoint with several sources (e.g. several calculation result types) is queried across all of them.

schema is required: it declares the served entry types and properties. field_handlers maps each entry type to its filter-handler table. When omitted (left empty) it is derived from schema via simple_property_handlers(), using an identity property-key map (each property is filtered against a backend field of the same name); a backend whose field names differ, or that wants finer control, supplies its own tables instead.

Parameters:

• store – Store implementing the neutral query protocol.

• sources – Queryable sources keyed by entry endpoint.

• schema – Required schema describing served entries and properties.

• field_handlers – Optional filter handlers keyed by entry endpoint.

store: httk.store.query.Store

sources: collections.abc.Mapping[str, collections.abc.Sequence[EntrySource]]

schema: httk.serve.optimade.schema.served.ServedSchema

field_handlers: collections.abc.Mapping[str, httk.store.query.optimade_filters.HandlerTable]

query_function()

Return the callback that executes queries through this adapter.

Returns:

Query callback consumed by the OPTIMADE request engine.

Return type:

httk.serve.optimade.model.results.QueryFunction

class httk.serve.optimade.backend.EntrySource

Describe one queryable source behind an OPTIMADE entry endpoint.

target is what gets passed to searcher.variable(); fields maps OPTIMADE response-field names to extractors applied to matched row objects. relationships, when set, is an extractor mapping a matched row to a dictionary keyed by related entry type, each value a list of {'id': str, 'description': str?, 'role': str?} dictionaries. sort_keys maps response-field names to the backend field names to sort on. property_metadata maps response-field names to extractors returning the per-property metadata dictionary for a matched row (or None when there is no metadata for that row).

Parameters:

• target – Store-specific target passed to searcher.variable.

• fields – Response-field extractors applied to matched rows.

• sort_keys – Response-field to backend-sort-field mappings.

• relationships – Optional extractor for related-resource data.

• property_metadata – Optional per-property metadata extractors.

target: Any

fields: collections.abc.Mapping[str, FieldExtractor]

sort_keys: collections.abc.Mapping[str, str]

relationships: FieldExtractor | None = None

property_metadata: collections.abc.Mapping[str, FieldExtractor]

class httk.serve.optimade.backend.StoreResults(pairs, response_fields, unknown_response_fields, limit, offset, total_count, recognized_prefixes)

Results of a query over one or more searchers.

Implements the QueryResults protocol. Iteration yields one ResultRow per entry, whose values map response-field names to values extracted from the matched row objects.

Parameters:

• pairs (list[tuple[httk.serve.optimade.backend.adapter.EntrySource, httk.store.query.Searcher]]) – Sources and already-configured searchers to iterate.

• response_fields (list[str]) – Recognized fields to extract.

• unknown_response_fields (list[str]) – Unknown fields to return as null.

• limit (int | None) – Maximum number of results to yield.

• offset (int) – Number of results to skip.

• total_count (int) – Total matches before pagination.

• recognized_prefixes (tuple[str, Ellipsis]) – Prefixes for dynamic row attributes.

pairs

recognized_prefixes

cur: collections.abc.Iterator[tuple[httk.serve.optimade.backend.adapter.EntrySource, Any]] | None

limit

response_fields

unknown_response_fields

offset

more_data_available = True

count()

Return all current-filter matches, before pagination.

The endpoint metadata needs the filtered total even after execution has applied page limits and offsets to its searchers. Retaining it here also keeps the value stable once this one-shot result iterator is consumed.

httk.serve.optimade.backend.execute_query(adapter, entries, response_fields, unknown_response_fields, response_limit, response_offset, filter_ast=None, *, sort=None, debug=False)

Execute a translated query across the adapter’s sources.

Parameters:

• adapter (httk.serve.optimade.backend.adapter.BackendAdapter) – Backend adapter providing sources and schema.

• entries (list[str]) – Entry endpoints to query.

• response_fields (list[str]) – Recognized fields to return.

• unknown_response_fields (list[str]) – Unknown fields to return as null.

• response_limit (int | None) – Maximum number of returned rows.

• response_offset (int | None) – Number of matching rows to skip.

• filter_ast (httk.core.optimade.FilterAst | None) – Parsed filter, when one was requested.

• sort (collections.abc.Sequence[tuple[str, bool]] | None) – Fields and directions to sort by.

• debug (bool) – Enable backend diagnostics.

Returns:

Lazy results for the requested page.

Raises:

httk.serve.optimade.model.errors.TranslatorError – If sorting across multiple sources is requested.

Return type:

StoreResults

class httk.serve.optimade.backend.InMemoryStore(tables)

Provide a store over dictionary rows.

Parameters:

tables (dict[str, list[Row]]) – Row lists keyed by table name.

tables

searcher(*, as_of=None)

Create a searcher over this store’s tables.

Parameters:

as_of (object) – Optional historic timestamp cutoff; unsupported here.

Returns:

Fresh in-memory searcher.

Raises:

ValueError – If a historic cutoff is requested.

Return type:

MemorySearcher

class httk.serve.optimade.backend.PartialDimension

Describe one list axis of a PartialValue.

length is the number of items along the axis (None when unknown or entry-dependent and not declared). sliceable indicates whether the server can honour a slice request for this axis.

Parameters:

• name – Dimension name used in response metadata.

• length – Number of items, or None when unknown.

• sliceable – Whether the server accepts slices on this axis.

name: str

length: int | None = None

sliceable: bool = False

class httk.serve.optimade.backend.PartialValue

Describe a property value provided lazily, one slice at a time.

fetch takes a tuple of Python slices (one per dimension, with the usual exclusive stop) and returns the corresponding nested lists.

Parameters:

• dimensions – Axes describing the value.

• fetch – Slice retrieval operation.

dimensions: tuple[PartialDimension, Ellipsis]

fetch: collections.abc.Callable[[tuple[slice, Ellipsis]], Any]

class httk.serve.optimade.backend.QueryFunction

Bases: Protocol

The callback seam through which the request engine runs queries on a backend.

class httk.serve.optimade.backend.QueryResults

Bases: Protocol

The results of a query against a backend, as consumed by the entry endpoints.

Iteration yields one ResultRow per entry; its values map OPTIMADE response-field names to values, and the id and type keys are always present.

property more_data_available: bool

Report whether another page is available.

count()

Return the total number of matches before pagination.

httk.serve.optimade.backend.adapter_from_providers(providers, **options)

Build a BackendAdapter serving the given entry providers.

Every provider’s entry_types() become served entry types (described by their EntryTypeDefinition), its property_keys() name the served subset and drive both the filter handlers (via simple_property_handlers()) and the response-field extractors, and its records() are loaded into an InMemoryStore. Every served property MUST be described by the entry type’s definition (a custom property must therefore live in an extended() definition); a ValueError names any offender. All served properties beyond id/type are marked default-response. Extra keyword options (e.g. sortable, recognized_prefixes) are forwarded to build_served_schema(); every served property is sortable-capable, since the provider’s property-key map is passed through as the source’s sort_keys.

Declared relationships (relationships()) are fully auto-wired for serving and filtering: for each entry type with declared relationships, a synthetic __rel_<related_type> id-list field is materialized on EVERY row of that entry type (an empty list when the row has no related entries of that type, so inverse set semantics are well-defined), and a '<related_type>.id' entry built with relationship_id_handler() is merged into the entry type’s derived filter-handler table (never overwriting an entry already present, mirroring how BackendAdapter respects explicitly supplied handler tables). <related_type>.id HAS ... filters — and, through the related-property resolver of translate_filter(), depth-1 relationship-property filters such as references.doi CONTAINS "10.1" — therefore work without any hand-wiring.

Parameters:

• providers (collections.abc.Iterable[httk.core.EntryProvider]) – Generic entry providers supplying definitions, keys, records, and relationships.

• **options (Any) – Schema options forwarded to build_served_schema().

Returns:

Fully wired in-memory backend adapter.

Raises:

ValueError – If provider keys or served properties are invalid.

Return type:

httk.serve.optimade.backend.adapter.BackendAdapter

httk.serve.optimade.backend.providers_from_registry()

Return the registered entry-provider factories keyed by their registered name.

Resolves each factory registered via httk.core.register_entry_provider() (through httk.registry.* self-registration) into a callable. Providers need data, so applications instantiate them: providers_from_registry()["atomistic-structures"](data).

Returns:

Registered provider factories keyed by registry name.

Return type:

dict[str, collections.abc.Callable[Ellipsis, httk.core.EntryProvider]]

class httk.serve.optimade.backend.StoredBackendAdapter

Serve one data federation per OPTIMADE entry type.

Parameters:

• federations – Durable federations keyed by entry endpoint.

• schema – Schema describing the federations’ served entries.

federations: collections.abc.Mapping[str, Any]

schema: httk.serve.optimade.schema.served.ServedSchema

snapshot_cutoff_ns(entry_type, now_ns)

Return the resolution-aware snapshot cutoff for one entry type.

query_function()

Return the callback that queries the configured federations.

Returns:

Query callback consumed by the OPTIMADE request engine.

Return type:

httk.serve.optimade.model.results.QueryFunction

httk.serve.optimade.backend.adapter_from_store(store, **options)

Build a lazy OPTIMADE adapter from every described family in one store.

Families declared without an entry-type definition are deliberately ignored. This lets application-specific records, such as DSP publication declarations, coexist with OPTIMADE records in one durable layout.

Parameters:

• store (httk.store.EntryStore) – Entry store whose configured layout is discovered.

• **options (Any) – Schema options forwarded to adapter_from_stores().

Returns:

Lazy adapter over all configured OPTIMADE families.

Raises:

• TypeError – If store does not implement EntryStore.

• ValueError – If the store contains no OPTIMADE-described family.

Return type:

StoredBackendAdapter

httk.serve.optimade.backend.adapter_from_stores(sources, **options)

Build a lazy store-backed adapter from durable entry sources.

Sources with the same exact logical family are federated under one entry endpoint. The data layer owns all source/backing traversal and global pagination; this adapter advertises the family’s definition and turns only the returned page into OPTIMADE result rows.

Parameters:

• sources (collections.abc.Sequence[httk.store.db.StoredEntrySource]) – Durable entry sources to federate by entry type.

• **options (Any) – Schema options forwarded to build_served_schema().

Returns:

Lazy adapter over the supplied durable sources.

Raises:

• ValueError – If sources conflict or expose incomplete sort mappings.

• TypeError – If a source is not a stored entry source.

Return type:

StoredBackendAdapter

httk.serve.optimade.backend.translate_filter(filter_ast, entries, adapter, sort=None)

Build one searcher per entry source, with the filter applied to each.

Relationship-property filters (dotted identifiers over served entry types) are resolved through the adapter’s related-property resolver (built by _related_property_resolver), so filtering references.doi behaves exactly like filtering /references directly.

Parameters:

• filter_ast (httk.core.optimade.FilterAst | None) – Parsed filter, or None for an unfiltered query.

• entries (list[str]) – Entry endpoints to search.

• adapter (httk.serve.optimade.backend.adapter.BackendAdapter) – Backend adapter supplying sources and handlers.

• sort (collections.abc.Sequence[tuple[str, bool]] | None) – Response fields and descending flags for sorting.

Returns:

Source/searcher pairs with the filter and sort applied.

Raises:

httk.serve.optimade.model.errors.TranslatorError – If the filter cannot be translated.

Return type:

list[tuple[httk.serve.optimade.backend.adapter.EntrySource, httk.store.query.Searcher]]

httk.serve.optimade.backend.translate_filter_node(node, search_variable, entry, entry_info, handlers, recognized_prefixes, served_entries=())

Translate one filter node against an OPTIMADE entry-info property mapping.

An OPTIMADE-side adaptation of translate_filter_ast(): entry_info maps property names to their property dictionaries (only their 'fulltype' keys are read) rather than straight to fulltypes, served_entries names the relationship targets, and failures surface as TranslatorError instead of the upstream neutral FilterTranslationError.

No related-property resolver is threaded through, so relationship-property filters other than <type>.id HAS ... raise a not-implemented (501) error. Use translate_filter() (which builds the resolver from its adapter) for full relationship-property filtering.

Parameters:

• node (httk.core.optimade.FilterAst) – Filter node to translate.

• search_variable (httk.store.query.SearchVariable) – Backend variable used by the expression.

• entry (str) – Entry endpoint being filtered.

• entry_info (collections.abc.Mapping[str, Any]) – Simplified property metadata for the entry.

• handlers (httk.store.query.optimade_filters.HandlerTable) – Property handlers used for translation.

• recognized_prefixes (tuple[str, Ellipsis]) – Property-definition prefixes accepted by the filter.

• served_entries (tuple[str, Ellipsis]) – Entry types available as relationship targets.

Returns:

Backend search expression.

Raises:

httk.serve.optimade.model.errors.TranslatorError – If the filter cannot be translated.

Return type:

httk.store.query.SearchExpression