DimensionRecordStorageManager

class lsst.daf.butler.registry.interfaces.DimensionRecordStorageManager(*, universe: lsst.daf.butler.core.dimensions._universe.DimensionUniverse)

Bases: lsst.daf.butler.registry.interfaces.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:

universe : DimensionUniverse

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

clearCaches()	Clear any in-memory caches held by nested DimensionRecordStorage instances.
currentVersion()	Return extension version as defined by current implementation.
extensionName()	Return full name of the extension.
get(element, str])	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.
loadDimensionGraph(key)	Retrieve a DimensionGraph that was previously saved in the database.
make_spatial_join_relation(element1, …)	Create a relation that represents the spatial join between two dimension elements.
register(element)	Ensure that this layer can hold records for the given element, creating new tables as necessary.
saveDimensionGraph(graph)	Save a DimensionGraph definition to the database, allowing it to be retrieved later via the returned key.
schemaDigest()	Return digest for schema piece managed by this extension.

Methods Documentation

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 currentVersion() → Optional[lsst.daf.butler.registry.interfaces._versioning.VersionTuple, None]

Return extension version as defined by current implementation.

This method can return None if an extension does not require its version to be saved or checked.

Returns:

version : VersionTuple

Current extension version or None.

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:

name : str

Full extension name.

get(element: lsst.daf.butler.core.dimensions._elements.DimensionElement | str[lsst.daf.butler.core.dimensions._elements.DimensionElement, str]) → lsst.daf.butler.registry.interfaces._dimensions.DimensionRecordStorage | None[lsst.daf.butler.registry.interfaces._dimensions.DimensionRecordStorage, None]

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

Parameters:

element : DimensionElement

Element for which records should be returned.

Returns:

records : DimensionRecordStorage 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.

classmethod initialize(db: Database, context: StaticTablesContext, *, universe: DimensionUniverse) → DimensionRecordStorageManager

Construct an instance of the manager.

Parameters:

db : Database

Interface to the underlying database engine and namespace.

context : StaticTablesContext

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

universe : DimensionUniverse

Universe graph containing dimensions known to this Registry.

Returns:

manager : DimensionRecordStorageManager

An instance of a concrete DimensionRecordStorageManager subclass.

loadDimensionGraph(key: int) → lsst.daf.butler.core.dimensions._graph.DimensionGraph

Retrieve a DimensionGraph that was previously saved in the database.

Parameters:

key : int

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

Returns:

graph : DimensionGraph

Retrieved graph.

Raises:

KeyError

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

make_spatial_join_relation(element1: str, element2: str, context: queries.SqlQueryContext, governor_constraints: Mapping[str, Set[str]]) → tuple[Relation, bool]

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

Parameters:

element1 : str

Name of one of the elements participating in the join.

element2 : str

Name of the other element participating in the join.

context : queries.SqlQueryContext

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

governor_constraints : Mapping [ str, collections.abc.Set ], optional

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

Returns:

relation : ``lsst.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_refinement : bool

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

register(element: lsst.daf.butler.core.dimensions._elements.DimensionElement) → lsst.daf.butler.registry.interfaces._dimensions.DimensionRecordStorage

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

Parameters:

element : DimensionElement

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

Returns:

records : DimensionRecordStorage

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.

saveDimensionGraph(graph: lsst.daf.butler.core.dimensions._graph.DimensionGraph) → int

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

Parameters:

graph : DimensionGraph

Set of dimensions to save.

Returns:

key : int

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

Raises:

TransactionInterruption

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

schemaDigest() → Optional[str, None]

Return digest for schema piece managed by this extension.

Returns:

digest : str or None

String representation of the digest of the schema, None should be returned if schema digest is not to be saved or checked. The length of the returned string cannot exceed the length of the “value” column of butler attributes table, currently 65535 characters.

Notes

There is no exact definition of digest format, any string should work. The only requirement for string contents is that it has to remain stable over time if schema does not change but it should produce different string for any change in the schema. In many cases default implementation in _defaultSchemaDigest can be used as a reasonable choice.