TimespanDatabaseRepresentation

class lsst.daf.butler.TimespanDatabaseRepresentation

Bases: ABC

An interface for representing a timespan in a database.

Notes

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

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	Return base logical name for the timespan column or expression (str).

Methods Summary

contains(other)	Return a SQLAlchemy expression representing containment.
extract(mapping[, name])	Extract a timespan from a dictionary that represents a database row.
flatten([name])	Return the actual column(s) that comprise this logical column.
fromLiteral(timespan)	Construct a database timespan from a literal Timespan instance.
from_columns(columns[, name])	Construct a database timespan from the columns of a 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 whether the timespan is NULL.
lower()	Return a SQLAlchemy expression representing a lower bound of a timespan.
makeFieldSpecs(nullable[, name])	Make objects that reflect the fields that must be added to table.
overlaps(other)	Return a SQLAlchemy expression representing timespan overlaps.
update(timespan[, name, result])	Add a timespan value to a dictionary that represents a database row.
upper()	Return a SQLAlchemy expression representing an upper bound of a timespan.

Attributes Documentation

NAME: ClassVar[str] = 'timespan'

name

Return base logical name for the timespan column or expression (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 common subset of the column names.

Methods Documentation

abstract contains(other: _S | ColumnElement) → 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[Any, Any], name: str | None = None) → Timespan | None

Extract a timespan from a dictionary that represents a database row.

Parameters:

mappingMapping [ Any, 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:

timespanTimespan or None

Python representation of the timespan.

abstract flatten(name: str | None = None) → tuple[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:

columnstuple [ sqlalchemy.sql.ColumnElement ]

The true column or columns that back this object.

abstract classmethod fromLiteral(timespan: Timespan | None) → _S

Construct a database timespan from a literal Timespan instance.

Parameters:

timespanTimespan or None

Literal timespan to convert, or None to make logically NULL timespan.

Returns:

tsReprTimespanDatabaseRepresentation

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

abstract classmethod from_columns(columns: ColumnCollection, name: str | None = None) → _S

Construct a database timespan from the columns of a table or subquery.

Parameters:

columnssqlalchemy.sql.ColumnCollections

SQLAlchemy container for raw columns.

namestr, optional

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

Returns:

tsReprTimespanDatabaseRepresentation

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

abstract classmethod getFieldNames(name: str | None = 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() → ColumnElement

Return a boolean SQLAlchemy expression for testing empty timespans.

Returns:

emptysqlalchemy.sql.ColumnElement

A boolean SQLAlchemy expression object.

abstract isNull() → ColumnElement

Return expression that tests whether the timespan is NULL.

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

Returns:

isnullsqlalchemy.sql.ColumnElement

A boolean SQLAlchemy expression object.

abstract lower() → ColumnElement

Return a SQLAlchemy expression representing a lower bound of a timespan.

Returns:

lowersqlalchemy.sql.ColumnElement

A SQLAlchemy expression for a lower bound.

Notes

If database holds NULL for a timespan then the returned expression should evaluate to 0. Main purpose of this and upper method is to use them in generating SQL, in particular ORDER BY clause, to guarantee a predictable ordering. It may potentially be used for transforming boolean user expressions into SQL, but it will likely require extra attention to ordering issues.

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

Make objects that reflect 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 timespan is permitted to be logically NULL (mapped to None in Python), though the corresponding value(s) in the database are implementation-defined. Nullable timespan 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 | ColumnElement) → ColumnElement

Return a SQLAlchemy expression representing timespan overlaps.

Parameters:

othertype(self)

The timespan or time to overlap self with. If a single time, this is a synonym for contains.

Returns:

overlapsqlalchemy.sql.ColumnElement

A boolean SQLAlchemy expression object.

Notes

See Timespan.overlaps for edge-case behavior.

abstract classmethod update(timespan: Timespan | None, name: str | None = None, result: dict[str, Any] | None = None) → dict[str, Any]

Add a timespan value to a dictionary that represents a database row.

Parameters:

timespan

A timespan literal, 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 timespan. Exactly the dict passed as result if that is not None.

abstract upper() → ColumnElement

Return a SQLAlchemy expression representing an upper bound of a timespan.

Returns:

uppersqlalchemy.sql.ColumnElement

A SQLAlchemy expression for an upper bound.

Notes

If database holds NULL for a timespan then the returned expression should evaluate to 0. Also see notes for lower method.