GovernorDimension¶

class lsst.daf.butler.GovernorDimension(name: str, storage: dict, *, 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

Governor dimension.

A special Dimension with no dependencies and a small number of rows, used to group the dimensions that depend on it.

Parameters:

name : str: Name of the dimension.
storage : dict: Fully qualified name of the GovernorDimensionRecordStorage subclass that will back this element in the registry (in a “cls” key) along with any other construction keyword arguments (in other 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

Most dimensions have exactly one governor dimension as a required dependency, and queries that involve those dimensions are always expected to explicitly identify the governor dimension value(s), rather than retrieve all matches from the database. Because governor values are thus almost always known at query-generation time, they can be used there to simplify queries, provide sensible defaults, or check in advance for common mistakes that might otherwise yield confusing (albeit formally correct) results instead of straightforward error messages.

Governor dimensions may not be associated with any kind of topological extent.

Governor dimension rows are often affiliated with a Python class or instance (e.g. lsst.obs.base.Instrument) that is capable of generating the rows of at least some dependent dimensions or providing other related functionality. In the future, we hope to attach these instances to governor dimension records (instantiating them from information in the database row when it is fetched), and use those objects to add additional functionality to governor dimensions, but a number of (code) dependency relationships would need to be reordered first.

Attributes Summary

`MAX_KEY_LENGTH`
`RecordClass`	Return the record subclass for this element.
`alternateKeys`	Return alternate keys.
`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.
`name`	Return unique string identifier for this endpoint (`str`).
`primaryKey`	Return primary key field for this dimension (`FieldSpec`).
`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.
`uniqueKeys`	Return the unique fields.
`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)	Make storage record.
`to_json`(minimal)	Convert this class to JSON form.
`to_simple`(minimal)	Convert this class to a simple python type.

Attributes Documentation

MAX_KEY_LENGTH = 128¶

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.

alternateKeys¶

Return alternate keys.

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¶

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¶

Return the implied dimensions.

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¶: Return unique string identifier for this endpoint (str).

primaryKey¶

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

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¶: Return this endpoint’s SPATIAL family.

temporal¶: Return this endpoint’s TEMPORAL family.

topology¶

Return the relationship families to which this endpoint belongs.

It is keyed by the category for that family.

uniqueKeys¶

Return the unique fields.

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

classmethod from_json(json_str: str, universe: Optional[DimensionUniverse] = None, registry: Optional[Registry] = 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_str : `str` Representation of the dimensions in JSON format as created by `to_json()`. universe : `DimensionUniverse`, optional The special graph of all known dimensions. Passed directly to `from_simple()`. registry : `lsst.daf.butler.Registry`, optional Registry to use to convert simple name of a DatasetType to a full `DatasetType`. Passed directly to `from_simple()`.
Returns:	constructed : Any Newly-constructed object.

classmethod from_simple(simple: str, universe: Optional[DimensionUniverse] = None, registry: Optional[Registry] = None) → DimensionElement¶

Construct a new object from the simplified form.

Usually the data is returned from the to_simple method.

Parameters:	simple : `str` The value returned by `to_simple()`. universe : `DimensionUniverse` The special graph of all known dimensions. registry : `lsst.daf.butler.Registry`, optional Registry from which a universe can be extracted. Can be `None` if universe is provided explicitly.
Returns:	dataId : `DimensionElement` 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: Optional[StaticTablesContext] = None) → GovernorDimensionRecordStorage¶

Make storage record.

Constructs 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.
Returns:	storage : `GovernorDimensionRecordStorage` 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:	minimal : `bool`, optional Use minimal serialization. Requires Registry to convert back to a full type.
Returns:	json : `str` 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:	minimal : `bool`, optional Use minimal serialization. Has no effect on for this class.
Returns:	simple : `str` The object converted to a single string.

Navigation

GovernorDimension¶