SpatialRegionDatabaseRepresentation¶
- class lsst.daf.butler.SpatialRegionDatabaseRepresentation(column: ColumnElement, name: str)¶
Bases:
TopologicalExtentDatabaseRepresentation
[Region
]Class reflecting how spatial regions are represented inside the DB.
An instance of this class encapsulates how spatial regions on the sky are represented in a database engine.
Instances should be constructed via
fromSelectable
, not by calling the constructor directly.- Parameters:
- column
sqlalchemy.sql.ColumnElement
Column containing the opaque byte-string, with automatic conversion to
lsst.sphgeom.Region
implemented via SQLAlchemy hooks.- name
str
Name of the column.
- column
Notes
Unlike
TimespanDatabaseRepresentation
, this is a concrete class, because we currently do not support any database-native spatial regions, and instead rely on precomputed overlaps and opaque (to the database) byte string columns. As a result, it also does not support any in-database topological predicates.If we add support for database-native regions in the future, this class may become an ABC with multiple concrete implementations.
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
extract
(mapping[, name])Extract a region from a dictionary.
flatten
(name)Return the actual column(s) that comprise this logical column.
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.isNull
()Return expression that tests where region is
NULL
.makeFieldSpecs
(nullable[, name])Make objects that reflect the fields that must be added to table.
update
(extent[, name, result])Add a region to a dictionary.
Attributes Documentation
- NAME: ClassVar[str] = 'region'¶
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] = 1¶
Topological space where regions represented by this class exist.
- name¶
Methods Documentation
- classmethod extract(mapping: Mapping[str, Any], name: str | None = None) Region | 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.
- 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
- classmethod fromSelectable(selectable: FromClause, name: str | None = None) SpatialRegionDatabaseRepresentation ¶
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
- 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.
- 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
- 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
- classmethod update(extent: Region | 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: