DatabaseDimensionRecordStorage¶
- class lsst.daf.butler.registry.interfaces.DatabaseDimensionRecordStorage¶
Bases:
DimensionRecordStorage
Intermediate interface for
DimensionRecordStorage
objects that provide storage forDatabaseDimensionElement
instances.Attributes Summary
The element whose records this instance managers (
DimensionElement
).Methods Summary
Clear any in-memory caches held by the storage instance.
connect
(overlaps)Inform this record storage object of the object that will manage the overlaps between this element and another element.
Return tables used for schema digest.
fetch
(dataIds)Retrieve records from storage.
initialize
(db, element, *[, 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.
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¶
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.
- connect(overlaps: DatabaseDimensionOverlapStorage) None ¶
Inform this record storage object of the object that will manage the overlaps between this element and another element.
This will only be called if
self.element.spatial is not None
, and will be called immediately after construction (before any other methods). In the future, implementations will be required to call a method on any connected overlap storage objects any time new records for the element are inserted.- Parameters:
- overlaps
DatabaseDimensionRecordStorage
Object managing overlaps between this element and another database-backed element.
- overlaps
- abstract digestTables() Iterable[Table] ¶
Return tables used for schema digest.
- Returns:
- tables
Iterable
[sqlalchemy.schema.Table
] Possibly empty set of tables for schema digest calculations.
- tables
- abstract fetch(dataIds: DataCoordinateIterable) Iterable[DimensionRecord] ¶
Retrieve records from storage.
- Parameters:
- dataIds
DataCoordinateIterable
Data IDs that identify the records to be retrieved.
- dataIds
- Returns:
- records
Iterable
[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.
- records
- abstract classmethod initialize(db: Database, element: DatabaseDimensionElement, *, context: StaticTablesContext | None = None, config: Mapping[str, Any], governors: NamedKeyMapping[GovernorDimension, GovernorDimensionRecordStorage]) DatabaseDimensionRecordStorage ¶
Construct an instance of this class using a standardized interface.
- Parameters:
- db
Database
Interface to the underlying database engine and namespace.
- element
DatabaseDimensionElement
Dimension element the new instance will manage records for.
- context
StaticTablesContext
, optional If provided, an object to use to create any new tables. If not provided,
db.ensureTableExists
should be used instead.- config
Mapping
Extra configuration options specific to the implementation.
- governors
NamedKeyMapping
Mapping containing all governor dimension storage implementations.
- db
- Returns:
- storage
DatabaseDimensionRecordStorage
A new
DatabaseDimensionRecordStorage
subclass instance.
- storage
- 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_existing
bool
, 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 aRegistry
, we rely onRegistry
to provide transactionality, both by using a SQLALchemy connection shared with theRegistry
and by relying on it to callclearCaches
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:
- builder
QueryBuilder
Builder for the query that should contain this element.
- regions
NamedKeyDict
, 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. IfNone
,self.element
is not being included in the query via a spatial join.- timespan
NamedKeyDict
, optional A mapping from
DimensionElement
to aTimespan
of SQLALchemy columns containing the timespan for that element, which should be updated to include timespan columns for this element if they exist. IfNone
,self.element
is not being included in the query via a temporal join.
- builder
- Returns:
- fromClause
sqlalchemy.sql.FromClause
Table or clause for the element which is joined.
- fromClause
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
andtimespans
cannot be assumed to be notNone
just because an element has a region or timespan.
- 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:
- Returns:
- 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.