GovernorDimensionRecordStorage

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

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

Methods Summary

clearCaches()	Clear any in-memory caches held by the storage instance.
digestTables()	Return tables used for schema digest.
fetch_one(data_id, context)	Retrieve a single record from storage.
get_record_cache(context)	Return a local cache of all DimensionRecord objects for this element, fetching it if necessary.
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(target, join, context)	Join this dimension element’s records to a relation.
make_relation(context)	Return a relation that represents this dimension element’s table.
registerInsertionListener(callback, None])	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

The element whose records this instance managers (DimensionElement).

table

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

Methods Documentation

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.

digestTables() → list

Return tables used for schema digest.

Returns:

tables : list [ sqlalchemy.schema.Table ]

Possibly empty list of tables for schema digest calculations.

fetch_one(data_id: DataCoordinate, context: queries.SqlQueryContext) → DimensionRecord | None

Retrieve a single record from storage.

Parameters:

data_id : DataCoordinate

Data ID of the record to fetch. Implied dimensions do not need to be present.

context : queries.SqlQueryContext

Context to be used to execute queries when no cached result is available.

Returns:

record : DimensionRecord or None

Fetched record, or possibly None if there was no match for the given data ID.

get_record_cache(context: queries.SqlQueryContext) → Mapping[DataCoordinate, DimensionRecord]

Return a local cache of all DimensionRecord objects for this element, fetching it if necessary.

Implementations that never cache records should return None.

Parameters:

context : queries.SqlQueryContext

Context to be used to execute queries when no cached result is available.

Returns:

cache : Mapping [ DataCoordinate, DimensionRecord ] or None

Mapping from data ID to dimension record, or None.

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:

db : Database

Interface to the underlying database engine and namespace.

dimension : GovernorDimension

Dimension 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.

Returns:

storage : GovernorDimensionRecordStorage

A new GovernorDimensionRecordStorage subclass instance.

insert(*records, 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 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.

join(target: Relation, join: Join, context: queries.SqlQueryContext) → Relation

Join this dimension element’s records to a relation.

Parameters:

target : Relation

Existing relation to join to. Implementations may require that this relation already include dimension key columns for this dimension element and assume that dataset or spatial join relations that might provide these will be included in the relation tree first.

join : Join

Join operation to use when the implementation is an actual join. When a true join is being simulated by other relation operations, this objects min_columns and max_columns should still be respected.

context : queries.SqlQueryContext

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

Returns:

joined : Relation

New relation that includes this relation’s dimension key and record columns, as well as all columns in target, with rows constrained to those for which this element’s dimension key values exist in the registry and rows already exist in target.

make_relation(context: queries.SqlQueryContext) → Relation

Return a relation that represents this dimension element’s table.

This is used to provide an implementation for DimensionRecordStorage.join, and is also callable in its own right.

Parameters:

context : queries.SqlQueryContext

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

Returns:

relation : Relation

New relation that includes this relation’s dimension key and record columns, with rows constrained to those for which the dimension key values exist in the registry.

registerInsertionListener(callback: collections.abc.Callable[lsst.daf.butler.core.dimensions._records.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.

sync(record: lsst.daf.butler.core.dimensions._records.DimensionRecord, update: bool = False) → bool | dict[str, typing.Any][bool, dict]

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

Parameters:

record : DimensionRecord.

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_updated : bool 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.