DatabaseDimensionElement

class lsst.daf.butler.DatabaseDimensionElement(name: str, storage: dict, *, implied: NamedValueAbstractSet[Dimension], metadata: NamedValueAbstractSet[FieldSpec])

Bases: DimensionElement

An intermediate base class for DimensionElement database classes.

Theese classes are ones whose instances map directly to a database table or query.

Parameters:

namestr

Name of the dimension.

storagedict

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

impliedNamedValueAbstractSet [ Dimension ]

Other dimensions whose keys are included in this dimension’s (logical) table as foreign keys.

metadataNamedValueAbstractSet [ ddl.FieldSpec ]

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

Attributes Summary

RecordClass	Return the record subclass for this element.
alwaysJoin	Indicate if the element should always be included.
dimensions	Return all dimensions.
governor	Return the governor dimension.
graph	Return minimal graph that includes this element (DimensionGraph).
implied	Return the implied dimensions.
metadata	Additional metadata fields included in this element's table.
minimal_group	Return minimal dimension group that includes this element.
name	Return unique string identifier for this endpoint (str).
populated_by	The dimension that this element's records are always inserted, exported, and imported alongside.
required	Return the required dimensions.
spatial	Return this endpoint's SPATIAL family.
temporal	Return this endpoint's TEMPORAL family.
topology	Return the relationship families to which this endpoint belongs.
viewOf	Name of another table this element's records are drawn from.

Methods Summary

from_json(json_str[, universe, registry])	Return new class from JSON string.
from_simple(simple[, universe, registry])	Construct a new object from the simplified form.
hasTable()	Indicate if this element is associated with a table.
makeStorage(db, *[, context, view_target])	Make the dimension record storage instance for this database.
to_json([minimal])	Convert this class to JSON form.
to_simple([minimal])	Convert this class to a simple python type.

Attributes Documentation

RecordClass

Return the record subclass for this element.

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

Indicate if the element should always be included.

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

Return all 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

Return the governor dimension.

This is the GovernorDimension that is a required dependency of this element, or None if there is no such dimension (GovernorDimension or None).

graph

Return 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

metadata

minimal_group

Return minimal dimension group that includes this element.

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

name

populated_by

The dimension that this element’s records are always inserted, exported, and imported alongside.

Notes

When this is None (as it will be, at least at first, for any data repositories created before this attribute was added), records for this element will often need to be exported manually when datasets associated with some other related dimension are exported, in order for the post-import data repository to function as expected.

required

Return the required dimensions.

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

temporal

topology

viewOf

Methods Documentation

classmethod from_json(json_str: str, universe: DimensionUniverse | None = None, registry: Registry | None = None) → SupportsSimple

Return new class from JSON string.

Converts a JSON string created by to_json and return something of the supplied class.

Parameters:

json_strstr

Representation of the dimensions in JSON format as created by to_json().

universeDimensionUniverse, optional

The special graph of all known dimensions. Passed directly to from_simple().

registrylsst.daf.butler.Registry, optional

Registry to use to convert simple name of a DatasetType to a full DatasetType. Passed directly to from_simple().

Returns:

constructedAny

Newly-constructed object.

classmethod from_simple(simple: str, universe: DimensionUniverse | None = None, registry: Registry | None = None) → DimensionElement

Construct a new object from the simplified form.

Usually the data is returned from the to_simple method.

Parameters:

simplestr

The value returned by to_simple().

universeDimensionUniverse

The special graph of all known dimensions.

registrylsst.daf.butler.Registry, optional

Registry from which a universe can be extracted. Can be None if universe is provided explicitly.

Returns:

dataIdDimensionElement

Newly-constructed object.

hasTable() → bool

Indicate if this element is associated with a table.

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

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

Make the dimension record storage instance for this database.

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

Parameters:

dbDatabase

Interface to the underlying database engine and namespace.

contextStaticTablesContext, optional

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

governorsNamedKeyMapping

Mapping from GovernorDimension to the record storage backend for that dimension, containing all governor dimensions.

view_targetDatabaseDimensionRecordStorage, optional

Storage object for the element this target’s storage is a view of (i.e. when viewOf is not None).

Returns:

storageDatabaseDimensionRecordStorage

Storage object that should back this element in a registry.

to_json(minimal: bool = False) → str

Convert this class to JSON form.

The class type is not recorded in the JSON so the JSON decoder must know which class is represented.

Parameters:

minimalbool, optional

Use minimal serialization. Requires Registry to convert back to a full type.

Returns:

jsonstr

The class in JSON string format.

to_simple(minimal: bool = False) → str

Convert this class to a simple python type.

This is suitable for serialization.

Parameters:

minimalbool, optional

Use minimal serialization. Has no effect on for this class.

Returns:

simplestr

The object converted to a single string.