DatabaseDimension¶

class lsst.daf.butler.DatabaseDimension(name: str, storage: dict, *, required: lsst.daf.butler.core.named.NamedValueSet[lsst.daf.butler.core.dimensions._elements.Dimension][lsst.daf.butler.core.dimensions._elements.Dimension], implied: lsst.daf.butler.core.named.NamedValueAbstractSet[lsst.daf.butler.core.dimensions._elements.Dimension][lsst.daf.butler.core.dimensions._elements.Dimension], metadata: lsst.daf.butler.core.named.NamedValueAbstractSet[lsst.daf.butler.core.ddl.FieldSpec][lsst.daf.butler.core.ddl.FieldSpec], uniqueKeys: lsst.daf.butler.core.named.NamedValueAbstractSet[lsst.daf.butler.core.ddl.FieldSpec][lsst.daf.butler.core.ddl.FieldSpec])¶

Bases: lsst.daf.butler.Dimension, lsst.daf.butler.DatabaseDimensionElement

A Dimension implementation that maps directly to a database table or query.

Parameters:

name : str: Name of the dimension.
storage : dict: Fully qualified name of the DatabaseDimensionRecordStorage subclass that will back this element in the registry (in a “cls” key) along with any other construction keyword arguments (in other keys).
required : NamedValueSet [ Dimension ]: Other dimensions whose keys are part of the compound primary key for this dimension’s (logical) table, as well as references to their own tables. The required parameter does not include self (it can’t, of course), but the corresponding attribute does - it is added by the constructor.
implied : NamedValueAbstractSet [ Dimension ]: Other dimensions whose keys are included in this dimension’s (logical) table as foreign keys.
metadata : NamedValueAbstractSet [ ddl.FieldSpec ]: Field specifications for all non-key fields in this dimension’s table.
uniqueKeys : NamedValueAbstractSet [ ddl.FieldSpec ]: Fields that can each be used to uniquely identify this dimension (given values for all required dimensions). The first of these is used as (part of) this dimension’s table’s primary key, while others are used to define unique constraints.

Notes

DatabaseDimension objects may belong to a TopologicalFamily, but it is the responsibility of DatabaseTopologicalFamilyConstructionVisitor to update the topology attribute of their members.

Attributes Summary

`RecordClass`	The `DimensionRecord` subclass used to hold records for this element (`type`).
`alternateKeys`	Additional unique key fields for this dimension that are not the primary key (`NamedValueAbstractSet` of `FieldSpec`).
`alwaysJoin`	If `True`, always include this element in any query or data ID in which its `required` dimensions appear, because it defines a relationship between those dimensions that must always be satisfied.
`dimensions`	The union of `required` and `implied`, with all elements in `required` before any elements in `implied`.
`governor`	The `GovernorDimension` that is a required dependency of this element, or `None` if there is no such dimension (`GovernorDimension` or `None`).
`graph`	Minimal graph that includes this element (`DimensionGraph`).
`implied`	Other dimensions that are uniquely identified directly by a record of this dimension element.
`metadata`	Additional metadata fields included in this element’s table (`NamedValueSet` of `FieldSpec`).
`name`	Unique string identifier for this endpoint (`str`).
`primaryKey`	The primary key field for this dimension (`FieldSpec`).
`required`	Dimensions that are necessary to uniquely identify a record of this dimension element.
`spatial`	This endpoint’s `SPATIAL` family.
`temporal`	This endpoint’s `TEMPORAL` family.
`topology`	The relationship families to which this endpoint belongs, keyed by the category for that family.
`uniqueKeys`	All fields that can individually be used to identify records of this element, given the primary keys of all required dependencies (`NamedValueAbstractSet` of `FieldSpec`).
`viewOf`	Name of another table this element’s records are drawn from (`str` or `None`).

Methods Summary

`hasTable`()	Return `True` if this element is associated with a table (even if that table “belongs” to another element).
`makeStorage`(db, *, context, governors, …)	Construct the `DimensionRecordStorage` instance that should be used to back this element in a registry.

Attributes Documentation

RecordClass¶

The DimensionRecord subclass used to hold records for this element (type).

Because DimensionRecord subclasses are generated dynamically, this type cannot be imported directly and hence can only be obtained from this attribute.

alternateKeys¶

Additional unique key fields for this dimension that are not the primary key (NamedValueAbstractSet of FieldSpec).

If this dimension has required dependencies, the keys of those dimensions are also included in the unique constraints defined for these alternate keys.

alwaysJoin¶: If True, always include this element in any query or data ID in which its required dimensions appear, because it defines a relationship between those dimensions that must always be satisfied.

dimensions¶

The union of required and implied, with all elements in required before any elements in implied.

This differs from self.graph.dimensions both in order and in content:

as in self.implied, implied dimensions are not expanded recursively here;
implied dimensions appear after required dimensions here, instead of being topologically ordered.

As a result, this set is ordered consistently with self.RecordClass.fields.

governor¶: The GovernorDimension that is a required dependency of this element, or None if there is no such dimension (GovernorDimension or None).

graph¶

Minimal graph that includes this element (DimensionGraph).

self.graph.required includes all dimensions whose primary key values are sufficient (often necessary) to uniquely identify self (including self if isinstance(self, Dimension). self.graph.implied includes all dimensions also identified (possibly recursively) by this set.

implied¶

Other dimensions that are uniquely identified directly by a record of this dimension element.

For elements with a database representation, these are exactly the dimensions used to form foreign key constraints whose fields are not (wholly) also part of the primary key.

Unlike self.graph.implied, this set is not expanded recursively.

metadata¶: Additional metadata fields included in this element’s table (NamedValueSet of FieldSpec).

name¶: Unique string identifier for this endpoint (str).

primaryKey¶

The primary key field for this dimension (FieldSpec).

Note that the database primary keys for dimension tables are in general compound; this field is the only field in the database primary key that is not also a foreign key (to a required dependency dimension table).

required¶

Dimensions that are necessary to uniquely identify a record of this dimension element.

For elements with a database representation, these dimension are exactly those used to form the (possibly compound) primary key, and all dimensions here that are not self are also used to form foreign keys.

For Dimension instances, this should be exactly the same as graph.required, but that may not be true for DimensionElement instances in general. When they differ, there are multiple combinations of dimensions that uniquely identify this element, but this one is more direct.

spatial¶: This endpoint’s SPATIAL family.

temporal¶: This endpoint’s TEMPORAL family.

topology¶: The relationship families to which this endpoint belongs, keyed by the category for that family.

uniqueKeys¶: All fields that can individually be used to identify records of this element, given the primary keys of all required dependencies (NamedValueAbstractSet of FieldSpec).

viewOf¶: Name of another table this element’s records are drawn from (str or None).

Methods Documentation

hasTable() → bool¶: Return True if this element is associated with a table (even if that table “belongs” to another element).

makeStorage(db: Database, *, context: Optional[StaticTablesContext] = None, governors: NamedKeyMapping[GovernorDimension, GovernorDimensionRecordStorage]) → DatabaseDimensionRecordStorage¶

Construct the DimensionRecordStorage instance that should be used to back this element in a registry.

Parameters:	db : `Database` Interface to the underlying database engine and namespace. context : `StaticTablesContext`, optional If provided, an object to use to create any new tables. If not provided, `db.ensureTableExists` should be used instead. governors : `NamedKeyMapping` Mapping from `GovernorDimension` to the record storage backend for that dimension, containing all governor dimensions.
Returns:	storage : `DatabaseDimensionRecordStorage` Storage object that should back this element in a registry.

Navigation

DatabaseDimension¶