Debian Codegraph @

django/contrib/gis/db/backends/postgis/operations.py

raw
1 import re
2
3 from django.conf import settings
4 from django.contrib.gis.db.backends.base.operations import BaseSpatialOperations
5 from django.contrib.gis.db.backends.utils import SpatialOperator
6 from django.contrib.gis.db.models import GeometryField, RasterField
7 from django.contrib.gis.gdal import GDALRaster
8 from django.contrib.gis.geos.geometry import GEOSGeometryBase
9 from django.contrib.gis.geos.prototypes.io import wkb_r
10 from django.contrib.gis.measure import Distance
11 from django.core.exceptions import ImproperlyConfigured
12 from django.db import NotSupportedError, ProgrammingError
13 from django.db.backends.postgresql.operations import DatabaseOperations
14 from django.db.backends.postgresql.psycopg_any import is_psycopg3
15 from django.db.models import Func, Value
16 from django.utils.functional import cached_property
17 from django.utils.version import get_version_tuple
18
19 from .adapter import PostGISAdapter
20 from .models import PostGISGeometryColumns, PostGISSpatialRefSys
21 from .pgraster import from_pgraster
22
23 # Identifier to mark raster lookups as bilateral.
24 BILATERAL = "bilateral"
25
26
27 class PostGISOperator(SpatialOperator):
28 def __init__(self, geography=False, raster=False, **kwargs):
29 # Only a subset of the operators and functions are available for the
30 # geography type. Lookups that don't support geography will be cast to
31 # geometry.
32 self.geography = geography
33 # Only a subset of the operators and functions are available for the
34 # raster type. Lookups that don't support raster will be converted to
35 # polygons. If the raster argument is set to BILATERAL, then the
36 # operator cannot handle mixed geom-raster lookups.
37 self.raster = raster
38 super().__init__(**kwargs)
39
40 def as_sql(self, connection, lookup, template_params, *args):
41 template_params = self.check_raster(lookup, template_params)
42 template_params = self.check_geography(lookup, template_params)
43 return super().as_sql(connection, lookup, template_params, *args)
44
45 def check_raster(self, lookup, template_params):
46 spheroid = lookup.rhs_params and lookup.rhs_params[-1] == "spheroid"
47
48 # Check which input is a raster.
49 lhs_is_raster = lookup.lhs.field.geom_type == "RASTER"
50 rhs_is_raster = isinstance(lookup.rhs, GDALRaster)
51
52 # Look for band indices and inject them if provided.
53 if lookup.band_lhs is not None and lhs_is_raster:
54 if not isinstance(lookup.band_lhs, int):
55 name = lookup.band_lhs.__class__.__name__
56 raise TypeError(f"Band index must be an integer, but got {name!r}.")
57 if not self.func:
58 raise ValueError(
59 "Band indices are not allowed for this operator, it works on bbox "
60 "only."
61 )
62 template_params["lhs"] = "%s, %s" % (
63 template_params["lhs"],
64 lookup.band_lhs,
65 )
66
67 if lookup.band_rhs is not None and rhs_is_raster:
68 if not isinstance(lookup.band_rhs, int):
69 name = lookup.band_rhs.__class__.__name__
70 raise TypeError(f"Band index must be an integer, but got {name!r}.")
71 if not self.func:
72 raise ValueError(
73 "Band indices are not allowed for this operator, it works on bbox "
74 "only."
75 )
76 template_params["rhs"] = "%s, %s" % (
77 template_params["rhs"],
78 lookup.band_rhs,
79 )
80
81 # Convert rasters to polygons if necessary.
82 if not self.raster or spheroid:
83 # Operators without raster support.
84 if lhs_is_raster:
85 template_params["lhs"] = "ST_Polygon(%s)" % template_params["lhs"]
86 if rhs_is_raster:
87 template_params["rhs"] = "ST_Polygon(%s)" % template_params["rhs"]
88 elif self.raster == BILATERAL:
89 # Operators with raster support but don't support mixed (rast-geom)
90 # lookups.
91 if lhs_is_raster and not rhs_is_raster:
92 template_params["lhs"] = "ST_Polygon(%s)" % template_params["lhs"]
93 elif rhs_is_raster and not lhs_is_raster:
94 template_params["rhs"] = "ST_Polygon(%s)" % template_params["rhs"]
95
96 return template_params
97
98 def check_geography(self, lookup, template_params):
99 """Convert geography fields to geometry types, if necessary."""
100 if lookup.lhs.output_field.geography and not self.geography:
101 template_params["lhs"] += "::geometry"
102 return template_params
103
104
105 class ST_Polygon(Func):
106 function = "ST_Polygon"
107
108 def __init__(self, expr):
109 super().__init__(expr)
110 expr = self.source_expressions[0]
111 if isinstance(expr, Value) and not expr._output_field_or_none:
112 self.source_expressions[0] = Value(
113 expr.value, output_field=RasterField(srid=expr.value.srid)
114 )
115
116 @cached_property
117 def output_field(self):
118 return GeometryField(srid=self.source_expressions[0].field.srid)
119
120
121 class PostGISOperations(BaseSpatialOperations, DatabaseOperations):
122 name = "postgis"
123 postgis = True
124 geom_func_prefix = "ST_"
125
126 Adapter = PostGISAdapter
127
128 collect = geom_func_prefix + "Collect"
129 extent = geom_func_prefix + "Extent"
130 extent3d = geom_func_prefix + "3DExtent"
131 length3d = geom_func_prefix + "3DLength"
132 makeline = geom_func_prefix + "MakeLine"
133 perimeter3d = geom_func_prefix + "3DPerimeter"
134 unionagg = geom_func_prefix + "Union"
135
136 gis_operators = {
137 "bbcontains": PostGISOperator(op="~", raster=True),
138 "bboverlaps": PostGISOperator(op="&&", geography=True, raster=True),
139 "contained": PostGISOperator(op="@", raster=True),
140 "overlaps_left": PostGISOperator(op="&<", raster=BILATERAL),
141 "overlaps_right": PostGISOperator(op="&>", raster=BILATERAL),
142 "overlaps_below": PostGISOperator(op="&<|"),
143 "overlaps_above": PostGISOperator(op="|&>"),
144 "left": PostGISOperator(op="<<"),
145 "right": PostGISOperator(op=">>"),
146 "strictly_below": PostGISOperator(op="<<|"),
147 "strictly_above": PostGISOperator(op="|>>"),
148 "same_as": PostGISOperator(op="~=", raster=BILATERAL),
149 "exact": PostGISOperator(op="~=", raster=BILATERAL), # alias of same_as
150 "contains": PostGISOperator(func="ST_Contains", raster=BILATERAL),
151 "contains_properly": PostGISOperator(
152 func="ST_ContainsProperly", raster=BILATERAL
153 ),
154 "coveredby": PostGISOperator(
155 func="ST_CoveredBy", geography=True, raster=BILATERAL
156 ),
157 "covers": PostGISOperator(func="ST_Covers", geography=True, raster=BILATERAL),
158 "crosses": PostGISOperator(func="ST_Crosses"),
159 "disjoint": PostGISOperator(func="ST_Disjoint", raster=BILATERAL),
160 "equals": PostGISOperator(func="ST_Equals"),
161 "intersects": PostGISOperator(
162 func="ST_Intersects", geography=True, raster=BILATERAL
163 ),
164 "overlaps": PostGISOperator(func="ST_Overlaps", raster=BILATERAL),
165 "relate": PostGISOperator(func="ST_Relate"),
166 "touches": PostGISOperator(func="ST_Touches", raster=BILATERAL),
167 "within": PostGISOperator(func="ST_Within", raster=BILATERAL),
168 "dwithin": PostGISOperator(func="ST_DWithin", geography=True, raster=BILATERAL),
169 }
170
171 unsupported_functions = set()
172
173 select = "%s" if is_psycopg3 else "%s::bytea"
174
175 select_extent = None
176
177 @cached_property
178 def function_names(self):
179 function_names = {
180 "AsWKB": "ST_AsBinary",
181 "AsWKT": "ST_AsText",
182 "BoundingCircle": "ST_MinimumBoundingCircle",
183 "FromWKB": "ST_GeomFromWKB",
184 "FromWKT": "ST_GeomFromText",
185 "NumPoints": "ST_NPoints",
186 }
187 return function_names
188
189 @cached_property
190 def spatial_version(self):
191 """Determine the version of the PostGIS library."""
192 # Trying to get the PostGIS version because the function
193 # signatures will depend on the version used. The cost
194 # here is a database query to determine the version, which
195 # can be mitigated by setting `POSTGIS_VERSION` with a 3-tuple
196 # comprising user-supplied values for the major, minor, and
197 # subminor revision of PostGIS.
198 if hasattr(settings, "POSTGIS_VERSION"):
199 version = settings.POSTGIS_VERSION
200 else:
201 # Run a basic query to check the status of the connection so we're
202 # sure we only raise the error below if the problem comes from
203 # PostGIS and not from PostgreSQL itself (see #24862).
204 self._get_postgis_func("version")
205
206 try:
207 vtup = self.postgis_version_tuple()
208 except ProgrammingError:
209 raise ImproperlyConfigured(
210 'Cannot determine PostGIS version for database "%s" '
211 'using command "SELECT postgis_lib_version()". '
212 "GeoDjango requires at least PostGIS version 3.1. "
213 "Was the database created from a spatial database "
214 "template?" % self.connection.settings_dict["NAME"]
215 )
216 version = vtup[1:]
217 return version
218
219 def convert_extent(self, box):
220 """
221 Return a 4-tuple extent for the `Extent` aggregate by converting
222 the bounding box text returned by PostGIS (`box` argument), for
223 example: "BOX(-90.0 30.0, -85.0 40.0)".
224 """
225 if box is None:
226 return None
227 ll, ur = box[4:-1].split(",")
228 xmin, ymin = map(float, ll.split())
229 xmax, ymax = map(float, ur.split())
230 return (xmin, ymin, xmax, ymax)
231
232 def convert_extent3d(self, box3d):
233 """
234 Return a 6-tuple extent for the `Extent3D` aggregate by converting
235 the 3d bounding-box text returned by PostGIS (`box3d` argument), for
236 example: "BOX3D(-90.0 30.0 1, -85.0 40.0 2)".
237 """
238 if box3d is None:
239 return None
240 ll, ur = box3d[6:-1].split(",")
241 xmin, ymin, zmin = map(float, ll.split())
242 xmax, ymax, zmax = map(float, ur.split())
243 return (xmin, ymin, zmin, xmax, ymax, zmax)
244
245 def geo_db_type(self, f):
246 """
247 Return the database field type for the given spatial field.
248 """
249 if f.geom_type == "RASTER":
250 return "raster"
251
252 # Type-based geometries.
253 # TODO: Support 'M' extension.
254 if f.dim == 3:
255 geom_type = f.geom_type + "Z"
256 else:
257 geom_type = f.geom_type
258 if f.geography:
259 if f.srid != 4326:
260 raise NotSupportedError(
261 "PostGIS only supports geography columns with an SRID of 4326."
262 )
263
264 return "geography(%s,%d)" % (geom_type, f.srid)
265 else:
266 return "geometry(%s,%d)" % (geom_type, f.srid)
267
268 def get_distance(self, f, dist_val, lookup_type):
269 """
270 Retrieve the distance parameters for the given geometry field,
271 distance lookup value, and the distance lookup type.
272
273 This is the most complex implementation of the spatial backends due to
274 what is supported on geodetic geometry columns vs. what's available on
275 projected geometry columns. In addition, it has to take into account
276 the geography column type.
277 """
278 # Getting the distance parameter
279 value = dist_val[0]
280
281 # Shorthand boolean flags.
282 geodetic = f.geodetic(self.connection)
283 geography = f.geography
284
285 if isinstance(value, Distance):
286 if geography:
287 dist_param = value.m
288 elif geodetic:
289 if lookup_type == "dwithin":
290 raise ValueError(
291 "Only numeric values of degree units are "
292 "allowed on geographic DWithin queries."
293 )
294 dist_param = value.m
295 else:
296 dist_param = getattr(
297 value, Distance.unit_attname(f.units_name(self.connection))
298 )
299 else:
300 # Assuming the distance is in the units of the field.
301 dist_param = value
302
303 return [dist_param]
304
305 def get_geom_placeholder(self, f, value, compiler):
306 """
307 Provide a proper substitution value for Geometries or rasters that are
308 not in the SRID of the field. Specifically, this routine will
309 substitute in the ST_Transform() function call.
310 """
311 transform_func = self.spatial_function_name("Transform")
312 if hasattr(value, "as_sql"):
313 if value.field.srid == f.srid:
314 placeholder = "%s"
315 else:
316 placeholder = "%s(%%s, %s)" % (transform_func, f.srid)
317 return placeholder
318
319 # Get the srid for this object
320 if value is None:
321 value_srid = None
322 else:
323 value_srid = value.srid
324
325 # Adding Transform() to the SQL placeholder if the value srid
326 # is not equal to the field srid.
327 if value_srid is None or value_srid == f.srid:
328 placeholder = "%s"
329 else:
330 placeholder = "%s(%%s, %s)" % (transform_func, f.srid)
331
332 return placeholder
333
334 def _get_postgis_func(self, func):
335 """
336 Helper routine for calling PostGIS functions and returning their result.
337 """
338 # Close out the connection. See #9437.
339 with self.connection.temporary_connection() as cursor:
340 cursor.execute("SELECT %s()" % func)
341 return cursor.fetchone()[0]
342
343 def postgis_geos_version(self):
344 "Return the version of the GEOS library used with PostGIS."
345 return self._get_postgis_func("postgis_geos_version")
346
347 def postgis_lib_version(self):
348 "Return the version number of the PostGIS library used with PostgreSQL."
349 return self._get_postgis_func("postgis_lib_version")
350
351 def postgis_proj_version(self):
352 """Return the version of the PROJ library used with PostGIS."""
353 return self._get_postgis_func("postgis_proj_version")
354
355 def postgis_version(self):
356 "Return PostGIS version number and compile-time options."
357 return self._get_postgis_func("postgis_version")
358
359 def postgis_full_version(self):
360 "Return PostGIS version number and compile-time options."
361 return self._get_postgis_func("postgis_full_version")
362
363 def postgis_version_tuple(self):
364 """
365 Return the PostGIS version as a tuple (version string, major,
366 minor, subminor).
367 """
368 version = self.postgis_lib_version()
369 return (version,) + get_version_tuple(version)
370
371 def proj_version_tuple(self):
372 """
373 Return the version of PROJ used by PostGIS as a tuple of the
374 major, minor, and subminor release numbers.
375 """
376 proj_regex = re.compile(r"(\d+)\.(\d+)\.(\d+)")
377 proj_ver_str = self.postgis_proj_version()
378 m = proj_regex.search(proj_ver_str)
379 if m:
380 return tuple(map(int, m.groups()))
381 else:
382 raise Exception("Could not determine PROJ version from PostGIS.")
383
384 def spatial_aggregate_name(self, agg_name):
385 if agg_name == "Extent3D":
386 return self.extent3d
387 else:
388 return self.geom_func_prefix + agg_name
389
390 # Routines for getting the OGC-compliant models.
391 def geometry_columns(self):
392 return PostGISGeometryColumns
393
394 def spatial_ref_sys(self):
395 return PostGISSpatialRefSys
396
397 def parse_raster(self, value):
398 """Convert a PostGIS HEX String into a dict readable by GDALRaster."""
399 return from_pgraster(value)
400
401 def distance_expr_for_lookup(self, lhs, rhs, **kwargs):
402 return super().distance_expr_for_lookup(
403 self._normalize_distance_lookup_arg(lhs),
404 self._normalize_distance_lookup_arg(rhs),
405 **kwargs,
406 )
407
408 @staticmethod
409 def _normalize_distance_lookup_arg(arg):
410 is_raster = (
411 arg.field.geom_type == "RASTER"
412 if hasattr(arg, "field")
413 else isinstance(arg, GDALRaster)
414 )
415 return ST_Polygon(arg) if is_raster else arg
416
417 def get_geometry_converter(self, expression):
418 read = wkb_r().read
419 geom_class = expression.output_field.geom_class
420
421 def converter(value, expression, connection):
422 if isinstance(value, str): # Coming from hex strings.
423 value = value.encode("ascii")
424 return None if value is None else GEOSGeometryBase(read(value), geom_class)
425
426 return converter
427
428 def get_area_att_for_field(self, field):
429 return "sq_m"