GovernorDimensionRecordStorage

class lsst.daf.butler.registry.interfaces.GovernorDimensionRecordStorage

Bases: DimensionRecordStorage

Intermediate interface for DimensionRecordStorage objects that provide storage for GovernorDimension instances.

Attributes Summary

element	The element whose records this instance managers (DimensionElement).
table	The SQLAlchemy table that backs this dimension (sqlalchemy.schema.Table).
values	All primary key values for this dimension (set [ str ]).

Methods Summary

clearCaches()	Clear any in-memory caches held by the storage instance.
digestTables()	Return tables used for schema digest.
fetch(dataIds)	Retrieve records from storage.
initialize(db, dimension, *[, context])	Construct an instance of this class using a standardized interface.
insert(*records[, replace, skip_existing])	Insert one or more records into storage.
join(builder, *[, regions, timespans])	Add the dimension element's logical table to a query under construction.
refresh()	Ensure all other operations on this manager are aware of any changes made by other clients since it was initialized or last refreshed.
registerInsertionListener(callback)	Add a function or method to be called after new records for this dimension are inserted by insert or sync.
sync(record[, update])	Synchronize a record with the database, inserting it only if it does not exist and comparing values if it does.

Attributes Documentation

element

table

The SQLAlchemy table that backs this dimension (sqlalchemy.schema.Table).

values

All primary key values for this dimension (set [ str ]).

This may rely on an in-memory cache and hence not reflect changes to the set of values made by other Butler / Registry clients. Call refresh to ensure up-to-date results.

Methods Documentation

abstract clearCaches() → None

Clear any in-memory caches held by the storage instance.

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.

abstract digestTables() → Iterable[Table]

Return tables used for schema digest.

Returns:

tablesIterable [ sqlalchemy.schema.Table ]

Possibly empty set of tables for schema digest calculations.

abstract fetch(dataIds: DataCoordinateIterable) → Iterable[DimensionRecord]

Retrieve records from storage.

Parameters:

dataIdsDataCoordinateIterable

Data IDs that identify the records to be retrieved.

Returns:

recordsIterable [ DimensionRecord ]

Record retrieved from storage. Not all data IDs may have corresponding records (if there are no records that match a data ID), and even if they are, the order of inputs is not preserved.

abstract classmethod initialize(db: Database, dimension: GovernorDimension, *, context: StaticTablesContext | None = None, config: Mapping[str, Any]) → GovernorDimensionRecordStorage

Construct an instance of this class using a standardized interface.

Parameters:

dbDatabase

Interface to the underlying database engine and namespace.

dimensionGovernorDimension

Dimension the new instance will manage records for.

contextStaticTablesContext, optional

If provided, an object to use to create any new tables. If not provided, db.ensureTableExists should be used instead.

configMapping

Extra configuration options specific to the implementation.

Returns:

storageGovernorDimensionRecordStorage

A new GovernorDimensionRecordStorage subclass instance.

abstract insert(*records: DimensionRecord, replace: bool = False, skip_existing: bool = False) → None

Insert one or more records into storage.

Parameters:

records

One or more instances of the DimensionRecord subclass for the element this storage is associated with.

replace: `bool`, optional

If True (False is default), replace existing records in the database if there is a conflict.

skip_existingbool, optional

If True (False is default), skip insertion if a record with the same primary key values already exists.

Raises:

TypeError

Raised if the element does not support record insertion.

sqlalchemy.exc.IntegrityError

Raised if one or more records violate database integrity constraints.

Notes

As insert is expected to be called only by a Registry, we rely on Registry to provide transactionality, both by using a SQLALchemy connection shared with the Registry and by relying on it to call clearCaches when rolling back transactions.

abstract join(builder: QueryBuilder, *, regions: NamedKeyDict[DimensionElement, sqlalchemy.sql.ColumnElement] | None = None, timespans: NamedKeyDict[DimensionElement, TimespanDatabaseRepresentation] | None = None) → sqlalchemy.sql.FromClause

Add the dimension element’s logical table to a query under construction.

This is a visitor pattern interface that is expected to be called only by QueryBuilder.joinDimensionElement.

Parameters:

builderQueryBuilder

Builder for the query that should contain this element.

regionsNamedKeyDict, optional

A mapping from DimensionElement to a SQLAlchemy column containing the region for that element, which should be updated to include a region column for this element if one exists. If None, self.element is not being included in the query via a spatial join.

timespanNamedKeyDict, optional

A mapping from DimensionElement to a Timespan of SQLALchemy columns containing the timespan for that element, which should be updated to include timespan columns for this element if they exist. If None, self.element is not being included in the query via a temporal join.

Returns:

fromClausesqlalchemy.sql.FromClause

Table or clause for the element which is joined.

Notes

Elements are only included in queries via spatial and/or temporal joins when necessary to connect them to other elements in the query, so regions and timespans cannot be assumed to be not None just because an element has a region or timespan.

abstract refresh() → None

Ensure all other operations on this manager are aware of any changes made by other clients since it was initialized or last refreshed.

abstract registerInsertionListener(callback: Callable[[DimensionRecord], None]) → None

Add a function or method to be called after new records for this dimension are inserted by insert or sync.

Parameters:

callback

Callable that takes a single DimensionRecord argument. This will be called immediately after any successful insertion, in the same transaction.

abstract sync(record: DimensionRecord, update: bool = False) → bool | Dict[str, Any]

Synchronize a record with the database, inserting it only if it does not exist and comparing values if it does.

Parameters:

recordDimensionRecord.

An instance of the DimensionRecord subclass for the element this storage is associated with.

update: `bool`, optional

If True (False is default), update the existing record in the database if there is a conflict.

Returns:

inserted_or_updatedbool or dict

True if a new row was inserted, False if no changes were needed, or a dict mapping updated column names to their old values if an update was performed (only possible if update=True).

Raises:

DatabaseConflictError

Raised if the record exists in the database (according to primary key lookup) but is inconsistent with the given one.

TypeError

Raised if the element does not support record synchronization.

sqlalchemy.exc.IntegrityError

Raised if one or more records violate database integrity constraints.