DatabaseDimensionCombination

class lsst.daf.butler.DatabaseDimensionCombination(name: str, storage: dict, *, required: lsst.daf.butler.core.named.NamedValueAbstractSet[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], alwaysJoin: bool)

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

A DimensionCombination 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 : NamedValueAbstractSet [ Dimension ]

Dimensions whose keys define the compound primary key for this combinations’s (logical) table, as well as references to their own tables.

implied : NamedValueAbstractSet [ Dimension ]

Dimensions whose keys are included in this combinations’s (logical) table as foreign keys.

metadata : NamedValueAbstractSet [ ddl.FieldSpec ]

Field specifications for all non-key fields in this combination’s table.

alwaysJoin : bool, optional

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.

Notes

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

This class has a lot in common with DatabaseDimension, but they are expected to diverge in future changes, and the only way to make them share method implementations would be via multiple inheritance. Given the trivial nature of all of those implementations, this does not seem worth the drawbacks (particularly the constraints it imposes on constructor signatures).

Attributes Summary

RecordClass The DimensionRecord subclass used to hold records for this element (type).
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).
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.
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.

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

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.

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.