httk.store.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)	Derive all record-collection indexes from the schema IR.
validator_for(schema)	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.
counter_next(database, collection_name, *[, session])	Atomically allocate the next integer sid from the counters collection.

Module Contents

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

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

class httk.store.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.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.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.mongo.mapping.collection_name_for(schema)

Return the collection name for a resolved schema.

Parameters:

schema (httk.store.db.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.mongo.mapping.document_fields_for(schema)

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

Parameters:

schema (httk.store.db.schema.TableSchema) – Resolved storable schema.

Returns:

One immutable document-field plan per stored schema field.

Return type:

tuple[DocumentFieldSpec, Ellipsis]

httk.store.mongo.mapping.index_specs_for(schema)

Derive all record-collection indexes from the schema IR.

Parameters:

schema (httk.store.db.schema.TableSchema) – Resolved storable schema.

Returns:

Deterministically ordered index specifications.

Return type:

list[IndexSpec]

httk.store.mongo.mapping.validator_for(schema)

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

Parameters:

schema (httk.store.db.schema.TableSchema) – Resolved storable schema.

Returns:

A MongoDB collection validator command fragment.

Return type:

dict[str, Any]

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