0
# Spatial Types
1

2
Spatial column types for defining geometry, geography, and raster columns in SQLAlchemy models. These types provide database-agnostic spatial column definitions with automatic spatial index creation and dialect-specific optimizations.
3

4
## Capabilities
5

6
### Geometry Type
7

8
Column type for geometric data using Cartesian coordinate systems. Supports all standard geometry types with flexible SRID and dimension configuration.
9

10
```python { .api }
11
class Geometry:
12
    """
13
    Column type for geometric data in Cartesian coordinate systems.
14
    
15
    Parameters:
16
    - geometry_type: str, geometry type constraint ("GEOMETRY", "POINT", "LINESTRING", 
17
      "POLYGON", "MULTIPOINT", "MULTILINESTRING", "MULTIPOLYGON", "GEOMETRYCOLLECTION", "CURVE")
18
    - srid: int, spatial reference system identifier (default: -1)
19
    - dimension: int, coordinate dimension (2, 3, or 4, default: 2)
20
    - spatial_index: bool, create spatial index (default: True)
21
    - use_N_D_index: bool, use N-dimensional index for PostgreSQL (default: False)
22
    - use_typmod: bool, use type modifiers instead of constraints (default: None)
23
    - from_text: str, custom from-text function name (default: None)
24
    - name: str, custom type name (default: None) 
25
    - nullable: bool, allow NULL values (default: True)
26
    """
27
    
28
    def __init__(
29
        self,
30
        geometry_type: Optional[str] = "GEOMETRY",
31
        srid: int = -1, 
32
        dimension: Optional[int] = None,
33
        spatial_index: bool = True,
34
        use_N_D_index: bool = False,
35
        use_typmod: Optional[bool] = None,
36
        from_text: Optional[str] = None,
37
        name: Optional[str] = None,
38
        nullable: bool = True
39
    ): ...
40
```
41

42
Usage examples:
43

44
```python
45
from sqlalchemy import Column, Integer, String
46
from geoalchemy2 import Geometry
47

48
class Building(Base):
49
    __tablename__ = 'building'
50
    
51
    id = Column(Integer, primary_key=True)
52
    name = Column(String)
53
    
54
    # Point geometry with specific SRID
55
    location = Column(Geometry('POINT', srid=4326))
56
    
57
    # Polygon geometry with 3D coordinates
58
    footprint = Column(Geometry('POLYGON', srid=3857, dimension=3))
59
    
60
    # Generic geometry without type constraint
61
    boundary = Column(Geometry(srid=4326))
62
```
63

64
### Geography Type
65

66
Column type for geographic data using spheroidal coordinate systems. Optimized for global geographic calculations with automatic great-circle distance computations.
67

68
```python { .api }
69
class Geography:
70
    """
71
    Column type for geographic data in spheroidal coordinate systems.
72
    
73
    Parameters:
74
    - geometry_type: str, geometry type constraint (same as Geometry)
75
    - srid: int, spatial reference system identifier (default: -1) 
76
    - dimension: int, coordinate dimension (2, 3, or 4, default: 2)
77
    - spatial_index: bool, create spatial index (default: True)
78
    - use_N_D_index: bool, use N-dimensional index for PostgreSQL (default: False)
79
    - use_typmod: bool, use type modifiers instead of constraints (default: None)
80
    - from_text: str, custom from-text function name (default: None)
81
    - name: str, custom type name (default: None)
82
    - nullable: bool, allow NULL values (default: True)
83
    """
84
    
85
    def __init__(
86
        self, 
87
        geometry_type: Optional[str] = "GEOMETRY",
88
        srid: int = -1,
89
        dimension: Optional[int] = None, 
90
        spatial_index: bool = True,
91
        use_N_D_index: bool = False,
92
        use_typmod: Optional[bool] = None,
93
        from_text: Optional[str] = None,
94
        name: Optional[str] = None,
95
        nullable: bool = True
96
    ): ...
97
```
98

99
Usage examples:
100

101
```python
102
from geoalchemy2 import Geography
103

104
class Airport(Base):
105
    __tablename__ = 'airport'
106
    
107
    id = Column(Integer, primary_key=True)
108
    code = Column(String(3))
109
    
110
    # Geographic point for global positioning
111
    location = Column(Geography('POINT', srid=4326))
112
    
113
    # Flight path as geographic linestring
114
    runway = Column(Geography('LINESTRING', srid=4326))
115
```
116

117
### Raster Type
118

119
Column type for raster data including satellite imagery, digital elevation models, and gridded datasets.
120

121
```python { .api }
122
class Raster:
123
    """
124
    Column type for raster data.
125
    
126
    Parameters:
127
    - spatial_index: bool, create spatial index on raster convex hull (default: True)
128
    - nullable: bool, allow NULL values (default: True)
129
    """
130
    
131
    def __init__(
132
        self,
133
        spatial_index: bool = True,
134
        nullable: bool = True
135
    ): ...
136
```
137

138
Usage examples:
139

140
```python
141
from geoalchemy2 import Raster
142

143
class Satellite(Base):
144
    __tablename__ = 'satellite_image'
145
    
146
    id = Column(Integer, primary_key=True)
147
    scene_id = Column(String)
148
    
149
    # Raster data with spatial indexing
150
    image_data = Column(Raster())
151
    
152
    # Elevation model without spatial index
153
    elevation = Column(Raster(spatial_index=False))
154
```
155

156
### Composite Types
157

158
Specialized types for handling composite spatial values returned by certain spatial functions.
159

160
```python { .api }
161
class GeometryDump:
162
    """
163
    Return type for functions like ST_Dump that return geometry components.
164
    
165
    Components:
166
    - path: array of integers indicating component path
167
    - geom: geometry component
168
    """
169
    
170
    typemap = {
171
        "path": postgresql.ARRAY(Integer),
172
        "geom": Geometry
173
    }
174

175
class SummaryStats: 
176
    """
177
    Return type for ST_SummaryStatsAgg function.
178
    
179
    Components:
180
    - count: number of values
181
    - sum: sum of values  
182
    - mean: mean value
183
    - stddev: standard deviation
184
    - min: minimum value
185
    - max: maximum value
186
    """
187
    
188
    typemap = {
189
        "count": Integer,
190
        "sum": Float,
191
        "mean": Float, 
192
        "stddev": Float,
193
        "min": Float,
194
        "max": Float
195
    }
196
```
197

198
### Type Utilities
199

200
Helper functions for working with spatial types across different database dialects.
201

202
```python { .api }
203
def select_dialect(dialect_name: str):
204
    """
205
    Select database dialect implementation for spatial operations.
206
    
207
    Parameters:
208
    - dialect_name: str, database dialect ("postgresql", "mysql", "mariadb", "sqlite", "geopackage")
209
    
210
    Returns:
211
    Dialect-specific implementation module
212
    """
213
```
214

215
## Database-Specific Behavior
216

217
### PostgreSQL/PostGIS
218
- Full support for all geometry types and dimensions
219
- Advanced indexing options including N-D indexes
220
- Type modifiers for constraint enforcement
221
- Comprehensive raster support
222

223
### MySQL/MariaDB  
224
- Geometry type support with SRID constraints
225
- Automatic NOT NULL constraints for indexed columns
226
- SRID specification in column definition
227

228
### SQLite/SpatiaLite
229
- Flexible geometry storage without strict type enforcement
230
- Dynamic spatial indexing through SpatiaLite extension
231
- Automatic geometry column registration
232

233
### GeoPackage
234
- OGC GeoPackage standard compliance
235
- Built-in spatial reference system support
236
- Integrated spatial indexing with R-tree implementation