DimensionRecordStorageManager

class lsst.daf.butler.registry.interfaces.DimensionRecordStorageManager(*, universe: DimensionUniverse, registry_schema_version: VersionTuple | None = None)

Bases: VersionedExtension

An interface for managing the dimension records in a Registry.

DimensionRecordStorageManager primarily serves as a container and factory for DimensionRecordStorage instances, which each provide access to the records for a different DimensionElement.

Parameters:

universeDimensionUniverse

Universe of all dimensions and dimension elements known to the Registry.

Notes

In a multi-layer Registry, many dimension elements will only have records in one layer (often the base layer). The union of the records across all layers forms the logical table for the full Registry.

Methods Summary

checkCompatibility(registry_schema_version, ...)	Check that schema version defined in registry is compatible with current implementation.
checkNewSchemaVersion(schema_version)	Verify that requested schema version can be created by an extension.
clearCaches()	Clear any in-memory caches held by nested DimensionRecordStorage instances.
clsNewSchemaVersion(schema_version)	Class method which returns schema version to use for newly created registry database.
currentVersions()	Return schema version(s) supported by this extension class.
extensionName()	Return full name of the extension.
get(element)	Return an object that provides access to the records associated with the given element, if one exists in this layer.
initialize(db, context, *, universe[, ...])	Construct an instance of the manager.
load_dimension_group(key)	Retrieve a DimensionGroup that was previously saved in the database.
make_spatial_join_relation(element1, ...[, ...])	Create a relation that represents the spatial join between two dimension elements.
newSchemaVersion()	Return schema version for newly created registry.
register(element)	Ensure that this layer can hold records for the given element, creating new tables as necessary.
save_dimension_group(graph)	Save a DimensionGroup definition to the database, allowing it to be retrieved later via the returned key.

Methods Documentation

classmethod checkCompatibility(registry_schema_version: VersionTuple, update: bool) → None

Check that schema version defined in registry is compatible with current implementation.

Parameters:

registry_schema_versionVersionTuple

Schema version that exists in registry or defined in a configuration for a registry to be created.

updatebool

If True then read-write access is expected.

Raises:

IncompatibleVersionError

Raised if schema version is not supported by implementation.

Notes

Default implementation uses VersionTuple.checkCompatibility on the versions returned from currentVersions method. Subclasses that support different compatibility model will overwrite this method.

classmethod checkNewSchemaVersion(schema_version: VersionTuple) → None

Verify that requested schema version can be created by an extension.

Parameters:

schema_versionVersionTuple

Schema version that this extension is asked to create.

Notes

This method may be used only occasionally when a specific schema version is given in a regisitry config file. This can be used with an extension that supports multiple schem versions to make it create new schema with a non-default version number. Default implementation compares requested version with one of the version returned from currentVersions.

abstract clearCaches() → None

Clear any in-memory caches held by nested DimensionRecordStorage instances.

This is called by Registry when transactions are rolled back, to avoid in-memory caches from ever containing records that are not present in persistent storage.

classmethod clsNewSchemaVersion(schema_version: VersionTuple | None) → VersionTuple | None

Class method which returns schema version to use for newly created registry database.

Parameters:

schema_versionVersionTuple or None

Configured schema version or None if default schema version should be created. If not None then it is guaranteed to be compatible with currentVersions.

Returns:

versionVersionTuple or None

Schema version created by this extension. None is returned if an extension does not require its version to be saved or checked.

Notes

Default implementation of this method can work in simple cases. If the extension only supports single schema version than that version is returned. If the extension supports multiple schema versions and schema_version is not None then schema_version is returned. If the extension supports multiple schema versions, but schema_version is None it calls _newDefaultSchemaVersion method which needs to be reimplemented in a subsclass.

abstract classmethod currentVersions() → list[lsst.daf.butler.registry.interfaces._versioning.VersionTuple]

Return schema version(s) supported by this extension class.

Returns:

versionlist [VersionTuple]

Schema versions for this extension. Empty list is returned if an extension does not require its version to be saved or checked.

classmethod extensionName() → str

Return full name of the extension.

This name should match the name defined in registry configuration. It is also stored in registry attributes. Default implementation returns full class name.

Returns:

namestr

Full extension name.

abstract get(element: DimensionElement | str) → DimensionRecordStorage | None

Return an object that provides access to the records associated with the given element, if one exists in this layer.

Parameters:

elementDimensionElement

Element for which records should be returned.

Returns:

recordsDimensionRecordStorage or None

The object representing the records for the given element in this layer, or None if there are no records for that element in this layer.

Notes

Dimension elements registered by another client of the same layer since the last call to initialize or refresh may not be found.

abstract classmethod initialize(db: Database, context: StaticTablesContext, *, universe: DimensionUniverse, registry_schema_version: VersionTuple | None = None) → DimensionRecordStorageManager

Construct an instance of the manager.

Parameters:

dbDatabase

Interface to the underlying database engine and namespace.

contextStaticTablesContext

Context object obtained from Database.declareStaticTables; used to declare any tables that should always be present in a layer implemented with this manager.

universeDimensionUniverse

Universe graph containing dimensions known to this Registry.

registry_schema_versionVersionTuple or None

Schema version of this extension as defined in registry.

Returns:

managerDimensionRecordStorageManager

An instance of a concrete DimensionRecordStorageManager subclass.

abstract load_dimension_group(key: int) → DimensionGroup

Retrieve a DimensionGroup that was previously saved in the database.

Parameters:

keyint

Integer used as the unique key for this DimensionGroup in the database.

Returns:

dimensionsDimensionGroup

Retrieved dimensions.

Raises:

KeyError

Raised if the given key cannot be found in the database.

abstract make_spatial_join_relation(element1: str, element2: str, context: queries.SqlQueryContext, governor_constraints: Mapping[str, Set[str]], existing_relationships: Set[frozenset[str]] = frozenset({})) → tuple[Relation, bool]

Create a relation that represents the spatial join between two dimension elements.

Parameters:

element1str

Name of one of the elements participating in the join.

element2str

Name of the other element participating in the join.

contextqueries.SqlQueryContext

Object that manages relation engines and database-side state (e.g. temporary tables) for the query.

governor_constraintsMapping [ str, collections.abc.Set ], optional

Constraints imposed by other aspects of the query on governor dimensions.

existing_relationshipsSet [ frozenset [ str ] ], optional

Relationships between dimensions that are already present in the relation the result will be joined to. Spatial join relations that duplicate these relationships will not be included in the result, which may cause an identity relation to be returned if a spatial relationship has already been established.

Returns:

relationlsst.daf.relation.Relation

New relation that represents a spatial join between the two given elements. Guaranteed to have key columns for all required dimensions of both elements.

needs_refinementbool

Whether the returned relation represents a conservative join that needs refinement via native-iteration predicate.

newSchemaVersion() → VersionTuple | None

Return schema version for newly created registry.

Returns:

versionVersionTuple or None

Schema version created by this extension. None is returned if an extension does not require its version to be saved or checked.

Notes

Extension classes that support multiple schema versions need to override _newDefaultSchemaVersion method.

abstract register(element: DimensionElement) → DimensionRecordStorage

Ensure that this layer can hold records for the given element, creating new tables as necessary.

Parameters:

elementDimensionElement

Element for which a table should created (as necessary) and an associated DimensionRecordStorage returned.

Returns:

recordsDimensionRecordStorage

The object representing the records for the given element in this layer.

Raises:

TransactionInterruption

Raised if this operation is invoked within a Database.transaction context.

abstract save_dimension_group(graph: DimensionGroup) → int

Save a DimensionGroup definition to the database, allowing it to be retrieved later via the returned key.

Parameters:

dimensionsDimensionGroup

Set of dimensions to save.

Returns:

keyint

Integer used as the unique key for this DimensionGroup in the database.

Raises:

TransactionInterruption

Raised if this operation is invoked within a Database.transaction context.