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 forDimensionRecordStorage
instances, which each provide access to the records for a differentDimensionElement
.- Parameters:
- universe
DimensionUniverse
Universe of all dimensions and dimension elements known to the
Registry
.
- universe
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 fullRegistry
.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.
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.
Return schema version(s) supported by this extension class.
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.
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.
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.
saveDimensionGraph
(graph)Save a
DimensionGraph
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_version
VersionTuple
Schema version that exists in registry or defined in a configuration for a registry to be created.
- update
bool
If True then read-write access is expected.
- registry_schema_version
- Raises:
- IncompatibleVersionError
Raised if schema version is not supported by implementation.
Notes
Default implementation uses
VersionTuple.checkCompatibility
on the versions returned fromcurrentVersions
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_version
VersionTuple
Schema version that this extension is asked to create.
- schema_version
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_version
VersionTuple
orNone
Configured schema version or
None
if default schema version should be created. If notNone
then it is guaranteed to be compatible withcurrentVersions
.
- schema_version
- Returns:
- version
VersionTuple
orNone
Schema version created by this extension.
None
is returned if an extension does not require its version to be saved or checked.
- version
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 notNone
thenschema_version
is returned. If the extension supports multiple schema versions, butschema_version
isNone
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:
- version
list
[VersionTuple
] Schema versions for this extension. Empty list is returned if an extension does not require its version to be saved or checked.
- version
- 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.
- 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:
- element
DimensionElement
Element for which records should be returned.
- element
- Returns:
- records
DimensionRecordStorage
orNone
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.
- records
Notes
Dimension elements registered by another client of the same layer since the last call to
initialize
orrefresh
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:
- 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
.- registry_schema_version
VersionTuple
orNone
Schema version of this extension as defined in registry.
- db
- Returns:
- manager
DimensionRecordStorageManager
An instance of a concrete
DimensionRecordStorageManager
subclass.
- manager
- abstract loadDimensionGraph(key: int) 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.
- key
- Returns:
- graph
DimensionGraph
Retrieved graph.
- graph
- 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:
- 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.
- existing_relationships
Set
[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.
- element1
- 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.
- relation
- newSchemaVersion() VersionTuple | None ¶
Return schema version for newly created registry.
- Returns:
- version
VersionTuple
orNone
Schema version created by this extension.
None
is returned if an extension does not require its version to be saved or checked.
- version
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:
- element
DimensionElement
Element for which a table should created (as necessary) and an associated
DimensionRecordStorage
returned.
- element
- Returns:
- records
DimensionRecordStorage
The object representing the records for the given element in this layer.
- records
- Raises:
- TransactionInterruption
Raised if this operation is invoked within a
Database.transaction
context.
- abstract saveDimensionGraph(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.
- graph
- Returns:
- key
int
Integer used as the unique key for this
DimensionGraph
in the database.
- key
- Raises:
- TransactionInterruption
Raised if this operation is invoked within a
Database.transaction
context.