SpatialRegionDatabaseRepresentation¶
-
class
lsst.daf.butler.
SpatialRegionDatabaseRepresentation
(column: sqlalchemy.sql.elements.ColumnElement, name: str)¶ Bases:
lsst.daf.butler.TopologicalExtentDatabaseRepresentation
An object that 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.
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
SPACE
name
Base logical name for the topological extent ( str
).Methods Summary
extract
(mapping, Any], name)Extract a region from a dictionary that represents a database row in this representation. flatten
(name)Return the actual column or columns that comprise this logical column. fromSelectable
(selectable, name)Construct an instance that represents a logical column (which may actually be backed by multiple columns) in the given table or subquery. getFieldNames
(name)Return the actual field names used by this representation. hasExclusionConstraint
()Return True
if this representation supports exclusion constraints.isNull
()Return a SQLAlchemy expression that tests whether this region is logically NULL
.makeFieldSpecs
(nullable, name, **kwargs)Make one or more ddl.FieldSpec
objects that reflect the fields that must be added to a table for this representation.update
(extent, name, result, Any]] = None)Add a region to a dictionary that represents a database row in this representation. Attributes Documentation
-
NAME
= 'region'¶
-
SPACE
= 1¶
-
name
¶ 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
-
classmethod
extract
(mapping: Mapping[str, Any], name: Optional[str] = None) → Optional[lsst.sphgeom._sphgeom.Region]¶ Extract a region from a dictionary that 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
.
Returns: - region
Python representation of the region.
- mapping :
-
flatten
(name: Optional[str]) → Iterator[sqlalchemy.sql.elements.ColumnElement]¶ Return the actual column or columns 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.
Returns: - columns :
Iterator
[sqlalchemy.sql.ColumnElement
] The true column or columns that back this object.
- name :
-
classmethod
fromSelectable
(selectable: sqlalchemy.sql.selectable.FromClause, name: Optional[str] = None) → lsst.daf.butler.core._topology.SpatialRegionDatabaseRepresentation¶ Construct 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
.
Returns: - representation :
TopologicalExtentDatabaseRepresentation
Object representing a logical column.
- selectable :
-
classmethod
getFieldNames
(name: Optional[str] = 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
.
Returns: - names :
tuple
[str
] Field name(s). Guaranteed to be the same as the names of the field specifications returned by
makeFieldSpecs
.
- name :
-
classmethod
hasExclusionConstraint
() → bool¶ Return
True
if this representation supports exclusion constraints.Returns:
-
isNull
() → sqlalchemy.sql.elements.ColumnElement¶ Return 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: Optional[str] = None, **kwargs) → Tuple[lsst.daf.butler.core.ddl.FieldSpec, ...]¶ Make 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.
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
.
- nullable :
-
classmethod
update
(extent: Optional[lsst.sphgeom._sphgeom.Region], name: Optional[str] = None, result: Optional[Dict[str, Any]] = None) → Dict[str, Any]¶ Add a region to a dictionary that 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:
- column :