TimespanDatabaseRepresentation¶
- class lsst.daf.butler.TimespanDatabaseRepresentation¶
Bases:
TopologicalExtentDatabaseRepresentation
[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
orfromLiteral
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 theTimespan
class. They are also guaranteed to round-tripTimespan
instances exactly.Attributes Summary
Name to use for this logical column in tables (
str
).Topological space where regions represented by this class exist.
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.
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
.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
(extent[, name, result])Add a region to a dictionary.
upper
()Return a SQLAlchemy expression representing an upper bound of a timespan.
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[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: _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:
- other
type(self)
orsqlalchemy.sql.ColumnElement
The timespan or time to relate to
self
; either an instance of the sameTimespanDatabaseRepresentation
subclass asself
, or a SQL column expression representing anastropy.time.Time
.
- other
- Returns:
- contains
sqlalchemy.sql.ColumnElement
A boolean SQLAlchemy expression object.
- contains
Notes
See
Timespan.contains
for edge-case behavior.
- abstract classmethod extract(mapping: Mapping[str, Any], name: str | None = None) _R | None ¶
Extract a region from a dictionary.
This region represents a database row in this representation.
- Parameters:
- mapping
Mapping
[str
,Any
] A dictionary representing a database row containing a
Timespan
in this representation. Should have key(s) equal to the return value ofgetFieldNames
.- name
str
, optional Name for the logical column; a part of the name for multi-column representations. Defaults to
cls.NAME
.
- mapping
- Returns:
- region
Python representation of the region.
- abstract flatten(name: str | None) Iterator[ColumnElement] ¶
Return the actual column(s) that comprise this logical column.
- Parameters:
- name
str
, 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.
- name
- Returns:
- columns
Iterator
[sqlalchemy.sql.ColumnElement
] The true column or columns that back this object.
- columns
- abstract classmethod fromLiteral(timespan: Timespan) _S ¶
Construct a database timespan from a literal
Timespan
instance.- Parameters:
- timespan
Timespan
Literal timespan to convert.
- timespan
- Returns:
- tsRepr
TimespanDatabaseRepresentation
A timespan expression object backed by
sqlalchemy.sql.literal
column expressions.
- tsRepr
- abstract classmethod fromSelectable(selectable: FromClause, name: str | None = 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:
- selectable
sqlalchemy.sql.FromClause
SQLAlchemy object representing a table or subquery.
- name
str
, optional Name for the logical column; a part of the name for multi-column representations. Defaults to
cls.NAME
.
- selectable
- Returns:
- representation
TopologicalExtentDatabaseRepresentation
Object representing a logical column.
- representation
- abstract classmethod getFieldNames(name: str | None = None) Tuple[str, ...] ¶
Return the actual field names used by this representation.
- Parameters:
- name
str
, optional Name for the logical column; a part of the name for multi-column representations. Defaults to
cls.NAME
.
- name
- Returns:
- names
tuple
[str
] Field name(s). Guaranteed to be the same as the names of the field specifications returned by
makeFieldSpecs
.
- names
- classmethod hasExclusionConstraint() bool ¶
Return
True
if this representation supports exclusion constraints.
- abstract isEmpty() ColumnElement ¶
Return a boolean SQLAlchemy expression for testing empty timespans.
- Returns:
- empty
sqlalchemy.sql.ColumnElement
A boolean SQLAlchemy expression object.
- empty
- abstract isNull() ColumnElement ¶
Return expression that tests where region is
NULL
.Returns a SQLAlchemy expression that tests whether this region is logically
NULL
.- Returns:
- isnull
sqlalchemy.sql.ColumnElement
A boolean SQLAlchemy expression object.
- isnull
- abstract lower() ColumnElement ¶
Return a SQLAlchemy expression representing a lower bound of a timespan.
- Returns:
- lower
sqlalchemy.sql.ColumnElement
A SQLAlchemy expression for a lower bound.
- lower
Notes
If database holds
NULL
for a timespan then the returned expression should evaluate to 0. Main purpose of this andupper
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[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:
- nullable
bool
If
True
, the region is permitted to be logicallyNULL
(mapped toNone
in Python), though the correspoding value(s) in the database are implementation-defined. Nullable region fields default to NULL, while others default to (-∞, ∞).- name
str
, 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 thename
,dtype
, anddefault
arguments themselves.
- nullable
- Returns:
- specs
tuple
[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
andupdate
.
- specs
- abstract overlaps(other: _S) ColumnElement ¶
Return a SQLAlchemy expression representing timespan overlaps.
- Parameters:
- other
type(self)
The timespan to overlap
self
with.
- other
- Returns:
- overlap
sqlalchemy.sql.ColumnElement
A boolean SQLAlchemy expression object.
- overlap
Notes
See
Timespan.overlaps
for edge-case behavior.
- abstract classmethod update(extent: _R | None, name: str | None = None, result: Dict[str, Any] | None = 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
forNULL
.- name
str
, optional Name for the logical column; a part of the name for multi-column representations. Defaults to
cls.NAME
.- result
dict
[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:
- abstract upper() ColumnElement ¶
Return a SQLAlchemy expression representing an upper bound of a timespan.
- Returns:
- upper
sqlalchemy.sql.ColumnElement
A SQLAlchemy expression for an upper bound.
- upper
Notes
If database holds
NULL
for a timespan then the returned expression should evaluate to 0. Also see notes forlower
method.