TimespanDatabaseRepresentation¶
- class lsst.daf.butler.timespan_database_representation.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
orfromLiteral
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 theTimespan
class. They are also guaranteed to round-tripTimespan
instances exactly.Attributes Summary
Return base logical name for the timespan column or expression (
str
).Methods Summary
apply_any_aggregate
(func)Apply the given ANY_VALUE aggregate function (or equivalent) to the timespan column(s).
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.
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¶
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 apply_any_aggregate(func: Callable[[ColumnElement[Any]], ColumnElement[Any]]) TimespanDatabaseRepresentation ¶
Apply the given ANY_VALUE aggregate function (or equivalent) to the timespan column(s).
- Parameters:
- func
Callable
Callable that takes a
sqlalchemy.ColumnElement
and returns asqlalchemy.ColumnElement
.
- func
- Returns:
- timespan
TimespanDatabaseRepresentation
A timespan database representation usable in the SELECT clause of a query with GROUP BY where it does not matter which of the grouped values is selected.
- timespan
- 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[Any, Any], name: str | None = None) Timespan | None ¶
Extract a timespan from a dictionary that represents a database row.
- Parameters:
- mapping
Mapping
[Any
,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:
- timespan
Timespan
orNone
Python representation of the timespan.
- timespan
- abstract flatten(name: str | None = None) tuple[sqlalchemy.sql.elements.ColumnElement, ...] ¶
Return the actual column(s) that comprise this logical column.
- abstract classmethod fromLiteral(timespan: Timespan | None) _S ¶
Construct a database timespan from a literal
Timespan
instance.- Parameters:
- Returns:
- tsRepr
TimespanDatabaseRepresentation
A timespan expression object backed by
sqlalchemy.sql.literal
column expressions.
- tsRepr
- abstract classmethod from_columns(columns: ColumnCollection, name: str | None = None) _S ¶
Construct a database timespan from the columns of a table or subquery.
- Parameters:
- columns
sqlalchemy.sql.ColumnCollections
SQLAlchemy container for raw columns.
- name
str
, optional Name for the logical column; a part of the name for multi-column representations. Defaults to
cls.NAME
.
- columns
- Returns:
- tsRepr
TimespanDatabaseRepresentation
A timespan expression object backed by
sqlalchemy.sql.literal
column expressions.
- tsRepr
- 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 whether the timespan 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[lsst.daf.butler.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:
- nullable
bool
If
True
, the timespan is permitted to be logicallyNULL
(mapped toNone
in Python), though the corresponding value(s) in the database are implementation-defined. Nullable timespan 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) ColumnElement ¶
Return a SQLAlchemy expression representing timespan overlaps.
- Parameters:
- other
type(self)
The timespan or time to overlap
self
with. If a single time, this is a synonym forcontains
.
- other
- Returns:
- overlap
sqlalchemy.sql.ColumnElement
A boolean SQLAlchemy expression object.
- overlap
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
Timespan
orNone
A timespan literal, 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.
- timespan
- 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.