DatabaseDimension¶

class lsst.daf.butler.DatabaseDimension(name: str, *, required: NamedValueSet[Dimension], implied: NamedValueAbstractSet[Dimension], metadata_columns: NamedValueAbstractSet[IntColumnSpec | StringColumnSpec | FloatColumnSpec | HashColumnSpec | BoolColumnSpec], unique_keys: NamedValueAbstractSet[IntColumnSpec | StringColumnSpec | HashColumnSpec], implied_union_target: str | None, is_cached: bool, doc: str)¶

Bases: Dimension, DatabaseDimensionElement

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

Parameters:

namestr: Name of the dimension.
requiredNamedValueSet [ 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.
impliedNamedValueAbstractSet [ Dimension ]: Other dimensions whose keys are included in this dimension’s (logical) table as foreign keys.
metadata_columnsNamedValueAbstractSet [ MetadataColumnSpec ]: Field specifications for all non-key fields in this dimension’s table.
unique_keysNamedValueAbstractSet [ KeyColumnSpec ]: 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.
implied_union_targetstr or None: If not None, the name of an element whose implied values for this element form the set of allowable values.
is_cachedbool: Whether this element’s records should be persistently cached in the client.
docstr: Extended description of this element.

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`	Return the record subclass for this element.
`alternateKeys`	Return alternate keys.
`alternate_keys`	Additional unique key fields for this dimension element that are not the primary key (`NamedValueAbstractSet` of `KeyColumnSpec`).
`alwaysJoin`	Indicate if the element should always be included.
`defines_relationships`	Whether this element's records define one or more relationships that must be satisfied in rows over dimensions that include it.
`dimensions`	Return all dimensions.
`documentation`	Extended description of this dimension element.
`governor`	Return the governor dimension.
`graph`	Return minimal graph that includes this element (`DimensionGraph`).
`has_own_table`	Whether this element should have its own table in the database.
`implied`	Return the implied dimensions.
`implied_union_target`	If not `None`, another element whose implied values for this element form the set of allowable values.
`is_cached`	Whether this element's records should be aggressively cached, because they are small in number and rarely inserted.
`metadata`	Additional metadata fields included in this element's table.
`metadata_columns`	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.
`primaryKey`	Return primary key field for this dimension (`FieldSpec`).
`primary_key`	The primary key field for this dimension (`KeyColumnSpec`).
`required`	Return the required dimensions.
`schema`	A description of the columns in this element's records and (at least conceptual) table.
`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.
`unique_keys`	Descriptions of unique identifiers for this dimension.
`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.
`to_arrow`(dimensions[, spec])	Return an object that converts the primary key value for this dimension to column in an Arrow table.
`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.

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.

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.

defines_relationships¶: Whether this element’s records define one or more relationships that must be satisfied in rows over dimensions that include it.

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.

documentation¶

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.

has_own_table¶: Whether this element should have its own table in the database.

implied¶

implied_union_target¶

is_cached¶

metadata¶

Additional metadata fields included in this element’s table.

(NamedValueSet of FieldSpec).

metadata_columns¶

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¶

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

primary_key¶

The primary key field for this dimension (KeyColumnSpec).

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¶

schema¶: A description of the columns in this element’s records and (at least conceptual) table.

spatial¶

temporal¶

topology¶

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

unique_keys¶

viewOf¶

Name of another table this element’s records are drawn from.

(str or None).

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

to_arrow(dimensions: DimensionGroup, spec: KeyColumnSpec | None = None) → arrow_utils.ToArrow¶

Return an object that converts the primary key value for this dimension to column in an Arrow table.

Parameters:

dimensionsDimensionGroup: Full set of dimensions over which the rows of the table are unique or close to unique. This is used to determine whether to use Arrow’s dictionary encoding to compress duplicate values.
specKeyColumnSpec, optional: Column specification for this dimension. If not provided, a copy of primary_key the the field name replaced with the dimension name will be used, which is appropriate for when this dimension appears in data ID or the dimension record tables of other dimension elements.

Returns:

converterarrow_utils.ToArrow: Converter for this dimension’s primary key.

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.

Navigation

DatabaseDimension¶