TimespanDatabaseRepresentation

class lsst.daf.butler.TimespanDatabaseRepresentation(*args, **kwds)

Bases: lsst.daf.butler.TopologicalExtentDatabaseRepresentation[lsst.daf.butler.Timespan]

Representation of a time span within a database engine.

Provides an interface that encapsulates how timespans are represented in a database engine.

Most of this class’s interface is comprised of classmethods. Instances can be constructed via the fromSelectable or fromLiteral methods as a way to include timespan overlap operations in query JOIN or WHERE clauses.

Notes

TimespanDatabaseRepresentation implementations are guaranteed to use the same interval definitions and edge-case behavior as the Timespan class. They are also guaranteed to round-trip Timespan instances exactly.

Attributes Summary

NAME	Name to use for this logical column in tables (str).
SPACE	Topological space where regions represented by this class exist.
name	Return base logical name for the topological extent (str).

Methods Summary

contains(other)	Return a SQLAlchemy expression representing containment.
extract(mapping[, name])	Extract a region from a dictionary.
flatten(name)	Return the actual column(s) that comprise this logical column.
fromLiteral(timespan)	Construct a database timespan from a literal Timespan instance.
fromSelectable(selectable[, name])	Construct representation of a column in the table or subquery.
getFieldNames([name])	Return the actual field names used by this representation.
hasExclusionConstraint()	Return True if this representation supports exclusion constraints.
isEmpty()	Return a boolean SQLAlchemy expression for testing empty timespans.
isNull()	Return expression that tests where region is NULL.
makeFieldSpecs(nullable[, name])	Make objects that relfect the fields that must be added to table.
overlaps(other)	Return a SQLAlchemy expression representing timespan overlaps.
update(extent[, name, result])	Add a region to a dictionary.

Attributes Documentation

NAME: ClassVar[str] = 'timespan'

Name to use for this logical column in tables (str).

If the representation actually uses multiple columns, this will just be part of the names of those columns. Queries (and tables that represent materialized queries) may use a different name (via the name parameters to various methods) in order to disambiguate between the regions associated with different tables.

SPACE: ClassVar[lsst.daf.butler.TopologicalSpace] = 2

Topological space where regions represented by this class exist.

name

Return base logical name for the topological extent (str).

If the representation uses only one actual column, this should be the full name of the column. In other cases it is an unspecified subset of the column names.

Methods Documentation

abstract contains(other: Union[_S, sqlalchemy.sql.elements.ColumnElement]) → sqlalchemy.sql.elements.ColumnElement

Return a SQLAlchemy expression representing containment.

Returns a test for whether an in-database timespan contains another timespan or a time point.

Parameters

othertype(self) or sqlalchemy.sql.ColumnElement

The timespan or time to relate to self; either an instance of the same TimespanDatabaseRepresentation subclass as self, or a SQL column expression representing an astropy.time.Time.

Returns

containssqlalchemy.sql.ColumnElement

A boolean SQLAlchemy expression object.

Notes

See Timespan.contains for edge-case behavior.

abstract classmethod extract(mapping: Mapping[str, Any], name: Optional[str] = None) → Optional[_R]

Extract a region from a dictionary.

This region represents a database row in this representation.

Parameters

mappingMapping [ str, Any ]

A dictionary representing a database row containing a Timespan in this representation. Should have key(s) equal to the return value of getFieldNames.

namestr, optional

Name for the logical column; a part of the name for multi-column representations. Defaults to cls.NAME.

Returns

region

Python representation of the region.

abstract flatten(name: Optional[str]) → Iterator[sqlalchemy.sql.elements.ColumnElement]

Return the actual column(s) that comprise this logical column.

Parameters

namestr, optional

If provided, a name for the logical column that should be used to label the columns. If not provided, the columns’ native names will be used.

Returns

columnsIterator [ sqlalchemy.sql.ColumnElement ]

The true column or columns that back this object.

abstract classmethod fromLiteral(timespan: lsst.daf.butler.Timespan) → _S

Construct a database timespan from a literal Timespan instance.

Parameters

timespanTimespan

Literal timespan to convert.

Returns

tsReprTimespanDatabaseRepresentation

A timespan expression object backed by sqlalchemy.sql.literal column expressions.

abstract classmethod fromSelectable(selectable: sqlalchemy.sql.selectable.FromClause, name: Optional[str] = None) → _S

Construct representation of a column in the table or subquery.

Constructs an instance that represents a logical column (which may actually be backed by multiple columns) in the given table or subquery.

Parameters

selectablesqlalchemy.sql.FromClause

SQLAlchemy object representing a table or subquery.

namestr, optional

Name for the logical column; a part of the name for multi-column representations. Defaults to cls.NAME.

Returns

representationTopologicalExtentDatabaseRepresentation

Object representing a logical column.

abstract classmethod getFieldNames(name: Optional[str] = None) → Tuple[str, …]

Return the actual field names used by this representation.

Parameters

namestr, optional

Name for the logical column; a part of the name for multi-column representations. Defaults to cls.NAME.

Returns

namestuple [ str ]

Field name(s). Guaranteed to be the same as the names of the field specifications returned by makeFieldSpecs.

classmethod hasExclusionConstraint() → bool

Return True if this representation supports exclusion constraints.

Returns

supportedbool

If True, defining a constraint via ddl.TableSpec.exclusion that includes the fields of this representation is allowed.

abstract isEmpty() → sqlalchemy.sql.elements.ColumnElement

Return a boolean SQLAlchemy expression for testing empty timespans.

Returns

emptysqlalchemy.sql.ColumnElement

A boolean SQLAlchemy expression object.

abstract isNull() → sqlalchemy.sql.elements.ColumnElement

Return expression that tests where region is NULL.

Returns a SQLAlchemy expression that tests whether this region is logically NULL.

Returns

isnullsqlalchemy.sql.ColumnElement

A boolean SQLAlchemy expression object.

abstract classmethod makeFieldSpecs(nullable: bool, name: Optional[str] = None, **kwargs: Any) → Tuple[lsst.daf.butler.core.ddl.FieldSpec, …]

Make objects that relfect the fields that must be added to table.

Makes one or more ddl.FieldSpec objects that reflect the fields that must be added to a table for this representation.

Parameters

nullablebool

If True, the region is permitted to be logically NULL (mapped to None in Python), though the correspoding value(s) in the database are implementation-defined. Nullable region fields default to NULL, while others default to (-∞, ∞).

namestr, optional

Name for the logical column; a part of the name for multi-column representations. Defaults to cls.NAME.

**kwargs

Keyword arguments are forwarded to the ddl.FieldSpec constructor for all fields; implementations only provide the name, dtype, and default arguments themselves.

Returns

specstuple [ ddl.FieldSpec ]

Field specification objects; length of the tuple is subclass-dependent, but is guaranteed to match the length of the return values of getFieldNames and update.

abstract overlaps(other: _S) → sqlalchemy.sql.elements.ColumnElement

Return a SQLAlchemy expression representing timespan overlaps.

Parameters

othertype(self)

The timespan to overlap self with.

Returns

overlapsqlalchemy.sql.ColumnElement

A boolean SQLAlchemy expression object.

Notes

See Timespan.overlaps for edge-case behavior.

abstract classmethod update(extent: Optional[_R], name: Optional[str] = None, result: Optional[Dict[str, Any]] = None) → Dict[str, Any]

Add a region to a dictionary.

This region represents a database row in this representation.

Parameters

extent

An instance of the region type this class provides a database representation for, or None for NULL.

namestr, optional

Name for the logical column; a part of the name for multi-column representations. Defaults to cls.NAME.

resultdict [ str, Any ], optional

A dictionary representing a database row that fields should be added to, or None to create and return a new one.

Returns

resultdict [ str, Any ]

A dictionary containing this representation of a region. Exactly the dict passed as result if that is not None.