GeoDjango 数据库 API

空间后端

GeoDjango currently provides the following spatial database backends:

• django.contrib.gis.db.backends.postgis
• django.contrib.gis.db.backends.mysql
• django.contrib.gis.db.backends.oracle
• django.contrib.gis.db.backends.spatialite

MySQL 的空间限制

Before MySQL 5.6.1, spatial extensions only support bounding box operations (what MySQL calls minimum bounding rectangles, or MBR). Specifically, MySQL did not conform to the OGC standard. Django supports spatial functions operating on real geometries available in modern MySQL versions. However, the spatial functions are not as rich as other backends like PostGIS.

栅格支持

RasterField is currently only implemented for the PostGIS backend. Spatial lookups are available for raster fields, but spatial database functions and aggregates aren't implemented for raster fields.

Creating and Saving Models with Geometry Fields

Here is an example of how to create a geometry object (assuming the Zipcode model):

>>> from zipcode.models import Zipcode
>>> z = Zipcode(code=77096, poly='POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))')
>>> z.save()

GEOSGeometry objects may also be used to save geometric models:

>>> from django.contrib.gis.geos import GEOSGeometry
>>> poly = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))')
>>> z = Zipcode(code=77096, poly=poly)
>>> z.save()

Moreover, if the GEOSGeometry is in a different coordinate system (has a different SRID value) than that of the field, then it will be implicitly transformed into the SRID of the model's field, using the spatial database's transform procedure:

>>> poly_3084 = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))', srid=3084)  # SRID 3084 is 'NAD83(HARN) / Texas Centric Lambert Conformal'
>>> z = Zipcode(code=78212, poly=poly_3084)
>>> z.save()
>>> from django.db import connection
>>> print(connection.queries[-1]['sql']) # printing the last SQL statement executed (requires DEBUG=True)
INSERT INTO "geoapp_zipcode" ("code", "poly") VALUES (78212, ST_Transform(ST_GeomFromWKB('\\001 ... ', 3084), 4326))

Thus, geometry parameters may be passed in using the GEOSGeometry object, WKT (Well Known Text [1]), HEXEWKB (PostGIS specific -- a WKB geometry in hexadecimal [2]), and GeoJSON (see RFC 7946). Essentially, if the input is not a GEOSGeometry object, the geometry field will attempt to create a GEOSGeometry instance from the input.

For more information creating GEOSGeometry objects, refer to the GEOS tutorial.

使用栅格字段创建和保存模型

When creating raster models, the raster field will implicitly convert the input into a GDALRaster using lazy-evaluation. The raster field will therefore accept any input that is accepted by the GDALRaster constructor.

Here is an example of how to create a raster object from a raster file volcano.tif (assuming the Elevation model):

>>> from elevation.models import Elevation
>>> dem = Elevation(name='Volcano', rast='/path/to/raster/volcano.tif')
>>> dem.save()

GDALRaster objects may also be used to save raster models:

>>> from django.contrib.gis.gdal import GDALRaster
>>> rast = GDALRaster({'width': 10, 'height': 10, 'name': 'Canyon', 'srid': 4326,
...                    'scale': [0.1, -0.1], 'bands': [{"data": range(100)}]})
>>> dem = Elevation(name='Canyon', rast=rast)
>>> dem.save()

注意这相当于：

>>> dem = Elevation.objects.create(
...     name='Canyon',
...     rast={'width': 10, 'height': 10, 'name': 'Canyon', 'srid': 4326,
...           'scale': [0.1, -0.1], 'bands': [{"data": range(100)}]},
... )

空间查找

GeoDjango's lookup types may be used with any manager method like filter(), exclude(), etc. However, the lookup types unique to GeoDjango are only available on spatial fields.

Filters on 'normal' fields (e.g. CharField) may be chained with those on geographic fields. Geographic lookups accept geometry and raster input on both sides and input types can be mixed freely.

The general structure of geographic lookups is described below. A complete reference can be found in the spatial lookup reference.

空间查找

Geographic queries with geometries take the following general form (assuming the Zipcode model used in the GeoDjango Model API):

>>> qs = Zipcode.objects.filter(<field>__<lookup_type>=<parameter>)
>>> qs = Zipcode.objects.exclude(...)

例子：

>>> qs = Zipcode.objects.filter(poly__contains=pnt)
>>> qs = Elevation.objects.filter(poly__contains=rst)

In this case, poly is the geographic field, contains is the spatial lookup type, pnt is the parameter (which may be a GEOSGeometry object or a string of GeoJSON , WKT, or HEXEWKB), and rst is a GDALRaster object.

栅格查找

The raster lookup syntax is similar to the syntax for geometries. The only difference is that a band index can be specified as additional input. If no band index is specified, the first band is used by default (index 0). In that case the syntax is identical to the syntax for geometry lookups.

To specify the band index, an additional parameter can be specified on both sides of the lookup. On the left hand side, the double underscore syntax is used to pass a band index. On the right hand side, a tuple of the raster and band index can be specified.

This results in the following general form for lookups involving rasters (assuming the Elevation model used in the GeoDjango Model API):

>>> qs = Elevation.objects.filter(<field>__<lookup_type>=<parameter>)
>>> qs = Elevation.objects.filter(<field>__<band_index>__<lookup_type>=<parameter>)
>>> qs = Elevation.objects.filter(<field>__<lookup_type>=(<raster_input, <band_index>)

例子：

>>> qs = Elevation.objects.filter(rast__contains=geom)
>>> qs = Elevation.objects.filter(rast__contains=rst)
>>> qs = Elevation.objects.filter(rast__1__contains=geom)
>>> qs = Elevation.objects.filter(rast__contains=(rst, 1))
>>> qs = Elevation.objects.filter(rast__1__contains=(rst, 1))

On the left hand side of the example, rast is the geographic raster field and contains is the spatial lookup type. On the right hand side, geom is a geometry input and rst is a GDALRaster object. The band index defaults to 0 in the first two queries and is set to 1 on the others.

While all spatial lookups can be used with raster objects on both sides, not all underlying operators natively accept raster input. For cases where the operator expects geometry input, the raster is automatically converted to a geometry. It's important to keep this in mind when interpreting the lookup results.

The type of raster support is listed for all lookups in the compatibility table. Lookups involving rasters are currently only available for the PostGIS backend.

距离查询

介绍

Distance calculations with spatial data is tricky because, unfortunately, the Earth is not flat. Some distance queries with fields in a geographic coordinate system may have to be expressed differently because of limitations in PostGIS. Please see the Selecting an SRID section in the GeoDjango Model API documentation for more details.

距离查找

可用性 ：PostGIS, MariaDB, MySQL, Oracle, SpatiaLite, PGRaster (Native)

以下是可用的距离查找：

• distance_lt
• distance_lte
• distance_gt
• distance_gte
• dwithin （除了 MariaDB 和 MySQL）

备注

对于 测量，而不是查询距离，使用 Distance 函数。

距离查找需要一个元组参数，包括：

1. 用于计算的几何体或栅格；和
2. 一个数字或 Distance 对象，包含距离。

If a Distance object is used, it may be expressed in any units (the SQL generated will use units converted to those of the field); otherwise, numeric parameters are assumed to be in the units of the field.

备注

In PostGIS, ST_Distance_Sphere does not limit the geometry types geographic distance queries are performed with. [3] However, these queries may take a long time, as great-circle distances must be calculated on the fly for every row in the query. This is because the spatial index on traditional geometry fields cannot be used.

For much better performance on WGS84 distance queries, consider using geography columns in your database instead because they are able to use their spatial index in distance queries. You can tell GeoDjango to use a geography column by setting geography=True in your field definition.

For example, let's say we have a SouthTexasCity model (from the GeoDjango distance tests ) on a projected coordinate system valid for cities in southern Texas:

from django.contrib.gis.db import models

class SouthTexasCity(models.Model):
    name = models.CharField(max_length=30)
    # A projected coordinate system (only valid for South Texas!)
    # is used, units are in meters.
    point = models.PointField(srid=32140)

那么可以进行距离查询，具体如下：

>>> from django.contrib.gis.geos import GEOSGeometry
>>> from django.contrib.gis.measure import D # ``D`` is a shortcut for ``Distance``
>>> from geoapp.models import SouthTexasCity
# Distances will be calculated from this point, which does not have to be projected.
>>> pnt = GEOSGeometry('POINT(-96.876369 29.905320)', srid=4326)
# If numeric parameter, units of field (meters in this case) are assumed.
>>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, 7000))
# Find all Cities within 7 km, > 20 miles away, and > 100 chains away (an obscure unit)
>>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, D(km=7)))
>>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(mi=20)))
>>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(chain=100)))

Raster queries work the same way by replacing the geometry field point with a raster field, or the pnt object with a raster object, or both. To specify the band index of a raster input on the right hand side, a 3-tuple can be passed to the lookup as follows:

>>> qs = SouthTexasCity.objects.filter(point__distance_gte=(rst, 2, D(km=7)))

Where the band with index 2 (the third band) of the raster rst would be used for the lookup.

兼容性表

空间查找

The following table provides a summary of what spatial lookups are available for each spatial database backend. The PostGIS Raster (PGRaster) lookups are divided into the three categories described in the raster lookup details: native support N, bilateral native support B, and geometry conversion support C.

查找类型	PostGIS	Oracle	MariaDB	MySQL [4]	SpatiaLite	PGRaster
bbcontains	X		X	X	X	N
bboverlaps	X		X	X	X	N
contained	X		X	X	X	N
contains	X	X	X	X	X	B
contains_properly	X					B
coveredby	X	X			X	B
covers	X	X			X	B
crosses	X		X	X	X	C
disjoint	X	X	X	X	X	B
distance_gt	X	X	X	X	X	N
distance_gte	X	X	X	X	X	N
distance_lt	X	X	X	X	X	N
distance_lte	X	X	X	X	X	N
dwithin	X	X			X	B
equals	X	X	X	X	X	C
exact	X	X	X	X	X	B
intersects	X	X	X	X	X	B
isvalid	X	X		X (≥ 5.7.5)	X
overlaps	X	X	X	X	X	B
relate	X	X	X		X	C
same_as	X	X	X	X	X	B
touches	X	X	X	X	X	B
within	X	X	X	X	X	B
left	X					C
right	X					C
overlaps_left	X					B
overlaps_right	X					B
overlaps_above	X					C
overlaps_below	X					C
strictly_above	X					C
strictly_below	X					C

数据库函数

The following table provides a summary of what geography-specific database functions are available on each spatial backend.

函数	PostGIS	Oracle	MariaDB	MySQL	SpatiaLite
Area	X	X	X	X	X
AsGeoJSON	X	X	X	X (≥ 5.7.5)	X
AsGML	X	X			X
AsKML	X				X
AsSVG	X				X
AsWKB	X	X	X	X	X
AsWKT	X	X	X	X	X
Azimuth	X				X (LWGEOM/RTTOPO)
BoundingCircle	X	X
Centroid	X	X	X	X	X
Difference	X	X	X	X	X
Distance	X	X	X	X	X
Envelope	X	X	X	X	X
ForcePolygonCW	X				X
GeoHash	X			X (≥ 5.7.5)	X (LWGEOM/RTTOPO)
Intersection	X	X	X	X	X
IsValid	X	X		X (≥ 5.7.5)	X
Length	X	X	X	X	X
LineLocatePoint	X				X
MakeValid	X				X (LWGEOM/RTTOPO)
MemSize	X
NumGeometries	X	X	X	X	X
NumPoints	X	X	X	X	X
Perimeter	X	X			X
PointOnSurface	X	X	X		X
Reverse	X	X			X
Scale	X				X
SnapToGrid	X				X
SymDifference	X	X	X	X	X
Transform	X	X			X
Translate	X				X
Union	X	X	X	X	X

聚合函数

The following table provides a summary of what GIS-specific aggregate functions are available on each spatial backend. Please note that MySQL does not support any of these aggregates, and is thus excluded from the table.

聚合	PostGIS	Oracle	SpatiaLite
Collect	X		X
Extent	X	X	X
Extent3D	X
MakeLine	X		X
Union	X	X	X

脚注

[1]	See Open Geospatial Consortium, Inc., OpenGIS Simple Feature Specification For SQL, Document 99-049 (May 5, 1999), at Ch. 3.2.5, p. 3-11 (SQL Textual Representation of Geometry).

[2]	See PostGIS EWKB, EWKT and Canonical Forms, PostGIS documentation at Ch. 4.1.2.

[3]	See PostGIS documentation on ST_DistanceSphere.

[4]	详情请参考 MySQL 的空间限制 部分。