httk.store.backend.mongo.mapping¶

Pure MongoDB physical mapping derived from the schema intermediate form.

Attributes¶

`METADATA_COLLECTION`
`COUNTERS_COLLECTION`

Classes¶

`DocumentFieldSpec`	Describe one field's location and embedded value shape in `f`.
`IndexSpec`	Describe one MongoDB index without performing any I/O.

Functions¶

`entry_dispatch_table_name`(family_name)	Return the deterministic reserved dispatch collection name.
`collection_name_for`(schema)	Return the collection name for a resolved schema.
`document_fields_for`(schema)	Derive the user-field document plan under the `f` subdocument.
`index_specs_for`(schema, *[, store_timestamps])	Derive all record-collection indexes from the schema IR.
`validator_for`(schema, *[, store_timestamps])	Build the writer-owned `$jsonSchema` validator for a record collection.
`dispatch_validator_for`(family)	Build the validator for one entry-family dispatch collection.
`dispatch_index_specs`(family)	Derive the unique `(record, sid)` dispatch index.
`link_validator_for`(link, *[, store_timestamps])	Build the writer-owned `$jsonSchema` validator for a weak-link collection.
`link_index_specs_for`(link)	Derive a weak-link collection's indexes: `(source_lid, target_lid)` and `(target_lid)`.
`counter_next`(database, collection_name, *[, session])	Atomically allocate the next integer sid from the counters collection.

Module Contents¶

httk.store.backend.mongo.mapping.METADATA_COLLECTION: Final = '_httk_store_metadata'¶

httk.store.backend.mongo.mapping.COUNTERS_COLLECTION: Final = '_httk_counters'¶

class httk.store.backend.mongo.mapping.DocumentFieldSpec¶

Describe one field’s location and embedded value shape in f.

Parameters:

field – The logical schema field name.
role – The schema field role.
keys – Parent document keys used by non-child fields.
element_keys – Keys used by one embedded child element.
optional – Whether an absent key represents None.
shape – The schema shape marker, when present.

field: str¶

role: str¶

keys: tuple[str, Ellipsis]¶

element_keys: tuple[str, Ellipsis] = ()¶

optional: bool = False¶

shape: Any = None¶

property key: str¶

Return the single parent key for this field.

Returns:: The parent key.
Raises:: ValueError – If the field has multiple or no parent keys.
Return type:: str

property columns: tuple[str, Ellipsis]¶

Return the generated column names represented by this plan.

Returns:: The physical field column names.
Return type:: tuple[str, Ellipsis]

class httk.store.backend.mongo.mapping.IndexSpec¶

Describe one MongoDB index without performing any I/O.

Parameters:

keys – Ordered dotted field paths and ascending/descending directions.
name – Deterministic index name.
unique – Whether duplicate keys are rejected.
partial_filter_expression – Optional MongoDB partial-index predicate.

keys: tuple[tuple[str, int], Ellipsis]¶

name: str¶

unique: bool = False¶

partial_filter_expression: dict[str, Any] | None = None¶

property key: tuple[tuple[str, int], Ellipsis]¶

Return the ordered MongoDB key pattern.

Returns:: The ordered key pattern.
Return type:: tuple[tuple[str, int], Ellipsis]

property partial_filter: dict[str, Any] | None¶

Return the partial filter expression.

Returns:: The partial filter, or None.
Return type:: dict[str, Any] | None

httk.store.backend.mongo.mapping.entry_dispatch_table_name(family_name)¶

Return the deterministic reserved dispatch collection name.

Parameters:: family_name (str) – Registered entry-family name.
Returns:: The physical dispatch collection name.
Return type:: str

httk.store.backend.mongo.mapping.collection_name_for(schema)¶

Return the collection name for a resolved schema.

Parameters:: schema (httk.store.backend.schema.TableSchema) – Resolved storable schema.
Returns:: The schema’s physical collection name.
Raises:: ValueError – If the name uses the reserved _httk_ prefix.
Return type:: str

httk.store.backend.mongo.mapping.document_fields_for(schema)¶

Derive the user-field document plan under the f subdocument.

Parameters:: schema (httk.store.backend.schema.TableSchema) – Resolved storable schema.
Returns:: One immutable document-field plan per stored schema field.
Return type:: tuple[DocumentFieldSpec, Ellipsis]

httk.store.backend.mongo.mapping.index_specs_for(schema, *, store_timestamps=True)¶

Derive all record-collection indexes from the schema IR.

Parameters:

schema (httk.store.backend.schema.TableSchema) – Resolved storable schema.
store_timestamps (bool) – Whether to index the store-managed timestamp.

Returns:

Deterministically ordered index specifications.

Return type:

list[IndexSpec]

httk.store.backend.mongo.mapping.validator_for(schema, *, store_timestamps=True)¶

Build the writer-owned $jsonSchema validator for a record collection.

Parameters:

schema (httk.store.backend.schema.TableSchema) – Resolved storable schema.
store_timestamps (bool) – Whether parent documents require a timestamp.

Returns:

A MongoDB collection validator command fragment.

Return type:

dict[str, Any]

httk.store.backend.mongo.mapping.dispatch_validator_for(family)¶

Build the validator for one entry-family dispatch collection.

Parameters:: family (httk.store.storage_layout.EntryFamilyLayout) – Normalized entry-family layout.
Returns:: A MongoDB collection validator command fragment.
Return type:: dict[str, Any]

httk.store.backend.mongo.mapping.dispatch_index_specs(family)¶

Derive the unique (record, sid) dispatch index.

Parameters:: family (httk.store.storage_layout.EntryFamilyLayout) – Normalized multi-record entry-family layout.
Returns:: The dispatch collection’s index specification.
Raises:: ValueError – If the family has fewer than two backing records.
Return type:: list[IndexSpec]

httk.store.backend.mongo.mapping.link_validator_for(link, *, store_timestamps=True)¶

Build the writer-owned $jsonSchema validator for a weak-link collection.

A link document is {_id (sid), logical_id, source_lid, target_lid, retracted[, store_timestamp]}; store_timestamp is required exactly when the store keeps timestamps, mirroring the parent-record convention.

Parameters:

link (httk.store.backend.schema.LinkSpec) – The resolved weak-link declaration.
store_timestamps (bool) – Whether link documents require a timestamp.

Returns:

A MongoDB collection validator command fragment.

Return type:

dict[str, Any]

httk.store.backend.mongo.mapping.link_index_specs_for(link)¶

Derive a weak-link collection’s indexes: (source_lid, target_lid) and (target_lid).

Parameters:: link (httk.store.backend.schema.LinkSpec) – The resolved weak-link declaration.
Returns:: The deterministically ordered link index specifications.
Return type:: list[IndexSpec]

httk.store.backend.mongo.mapping.counter_next(database, collection_name, *, session=None)¶

Atomically allocate the next integer sid from the counters collection.

Parameters:

database (Any) – A PyMongo database handle.
collection_name (str) – Counter key, normally a record collection name.
session (Any) – Optional active MongoDB transaction session.

Returns:

The allocated monotonically increasing integer.

Return type:

int