GeoDjango currently provides the following spatial database backends:
\ndjango.contrib.gis.db.backends.postgis
django.contrib.gis.db.backends.mysql
django.contrib.gis.db.backends.oracle
django.contrib.gis.db.backends.spatialite
Django supports spatial functions operating on real geometries available in\nmodern MySQL versions. However, the spatial functions are not as rich as other\nbackends like PostGIS.
\nRasterField is currently only implemented for the PostGIS backend. Spatial\nlookups are available for raster fields, but spatial database functions and\naggregates aren’t implemented for raster fields.
Here is an example of how to create a geometry object (assuming the Zipcode\nmodel):
>>> from zipcode.models import Zipcode\n>>> z = Zipcode(code=77096, poly="POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))")\n>>> z.save()\nGEOSGeometry objects may also be used to save\ngeometric models:
>>> from django.contrib.gis.geos import GEOSGeometry\n>>> poly = GEOSGeometry("POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))")\n>>> z = Zipcode(code=77096, poly=poly)\n>>> z.save()\nMoreover, if the GEOSGeometry is in a different coordinate system (has a\ndifferent SRID value) than that of the field, then it will be implicitly\ntransformed into the SRID of the model’s field, using the spatial database’s\ntransform procedure:
>>> poly_3084 = GEOSGeometry(\n... "POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))", srid=3084\n... ) # SRID 3084 is 'NAD83(HARN) / Texas Centric Lambert Conformal'\n>>> z = Zipcode(code=78212, poly=poly_3084)\n>>> z.save()\n>>> from django.db import connection\n>>> print(\n... connection.queries[-1]["sql"]\n... ) # printing the last SQL statement executed (requires DEBUG=True)\nINSERT INTO "geoapp_zipcode" ("code", "poly") VALUES (78212, ST_Transform(ST_GeomFromWKB('\\\\001 ... ', 3084), 4326))\nThus, geometry parameters may be passed in using the GEOSGeometry object,\nWKT (Well Known Text [1]), HEXEWKB (PostGIS specific – a WKB geometry in\nhexadecimal [2]), and GeoJSON (see RFC 7946). Essentially, if the\ninput is not a GEOSGeometry object, the geometry field will attempt to\ncreate a GEOSGeometry instance from the input.
For more information creating GEOSGeometry\nobjects, refer to the GEOS tutorial.
When creating raster models, the raster field will implicitly convert the input\ninto a GDALRaster using lazy-evaluation.\nThe raster field will therefore accept any input that is accepted by the\nGDALRaster constructor.
Here is an example of how to create a raster object from a raster file\nvolcano.tif (assuming the Elevation model):
>>> from elevation.models import Elevation\n>>> dem = Elevation(name="Volcano", rast="/path/to/raster/volcano.tif")\n>>> dem.save()\nGDALRaster objects may also be used to save\nraster models:
>>> from django.contrib.gis.gdal import GDALRaster\n>>> rast = GDALRaster(\n... {\n... "width": 10,\n... "height": 10,\n... "name": "Canyon",\n... "srid": 4326,\n... "scale": [0.1, -0.1],\n... "bands": [{"data": range(100)}],\n... }\n... )\n>>> dem = Elevation(name="Canyon", rast=rast)\n>>> dem.save()\nNote that this is equivalent to:
\n>>> dem = Elevation.objects.create(\n... name="Canyon",\n... rast={\n... "width": 10,\n... "height": 10,\n... "name": "Canyon",\n... "srid": 4326,\n... "scale": [0.1, -0.1],\n... "bands": [{"data": range(100)}],\n... },\n... )\nGeoDjango’s lookup types may be used with any manager method like\nfilter(), exclude(), etc. However, the lookup types unique to\nGeoDjango are only available on spatial fields.
Filters on ‘normal’ fields (e.g. CharField)\nmay be chained with those on geographic fields. Geographic lookups accept\ngeometry and raster input on both sides, and input types can be mixed freely in\nmost cases. However, unlike assignments to model fields, with lookups,\ntypes such as str, pathlib.Path, and dict must be wrapped by\nGDALRaster to signify that the potential for\nfile writing or network fetching is acceptable. For the rationale, see\nraster security considerations.
The general structure of geographic lookups is described below. A complete\nreference can be found in the spatial lookup reference.
\n\nGeographic queries with geometries take the following general form (assuming\nthe Zipcode model used in the GeoDjango Model API):
>>> qs = Zipcode.objects.filter(<field>__<lookup_type>=<parameter>)\n>>> qs = Zipcode.objects.exclude(...)\nFor example:
\n>>> qs = Zipcode.objects.filter(poly__contains=pnt)\n>>> qs = Elevation.objects.filter(poly__contains=rst)\nIn this case, poly is the geographic field,\ncontains is the spatial lookup type, pnt is the\nparameter (which may be a GEOSGeometry object\nor a string of GeoJSON , WKT, or HEXEWKB), and rst is a\nGDALRaster object.
The raster lookup syntax is similar to the syntax for geometries. The only\ndifference is that a band index can be specified as additional input. If no\nband index is specified, the first band is used by default (index 0). In\nthat case the syntax is identical to the syntax for geometry lookups.
To specify the band index, an additional parameter can be specified on both\nsides of the lookup. On the left hand side, the double underscore syntax is\nused to pass a band index. On the right hand side, a tuple of the raster and\nband index can be specified.
\nThis results in the following general form for lookups involving rasters\n(assuming the Elevation model used in the\nGeoDjango Model API):
>>> qs = Elevation.objects.filter(<field>__<lookup_type>=<parameter>)\n>>> qs = Elevation.objects.filter(<field>__<band_index>__<lookup_type>=<parameter>)\n>>> qs = Elevation.objects.filter(<field>__<lookup_type>=(<raster_input, <band_index>)\nFor example:
\n>>> qs = Elevation.objects.filter(rast__contains=geom)\n>>> qs = Elevation.objects.filter(rast__contains=rst)\n>>> qs = Elevation.objects.filter(rast__1__contains=geom)\n>>> qs = Elevation.objects.filter(rast__contains=(rst, 1))\n>>> qs = Elevation.objects.filter(rast__1__contains=(rst, 1))\nOn the left hand side of the example, rast is the geographic raster field\nand contains is the spatial lookup type. On the right\nhand side, geom is a geometry input and rst is a\nGDALRaster object. The band index defaults to\n0 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\nall underlying operators natively accept raster input. For cases where the\noperator expects geometry input, the raster is automatically converted to a\ngeometry. It’s important to keep this in mind when interpreting the lookup\nresults.
\nThe type of raster support is listed for all lookups in the compatibility\ntable. Lookups involving rasters are currently\nonly available for the PostGIS backend.
\nDistance calculations with spatial data is tricky because, unfortunately, the\nEarth is not flat. Some distance queries with fields in a geographic coordinate\nsystem may have to be expressed differently because of limitations in PostGIS.\nPlease see the Selecting an SRID section for more details.
\nAvailability: PostGIS, MariaDB, MySQL, Oracle, SpatiaLite, PGRaster (Native)
\nThe following distance lookups are available:
\ndwithin (except MariaDB and MySQL)
Distance lookups take a tuple parameter comprising:
\nA geometry or raster to base calculations from; and
A number or Distance object containing\nthe distance.
If a Distance object is used,\nit may be expressed in any units (the SQL generated will use units\nconverted to those of the field); otherwise, numeric parameters are assumed\nto be in the units of the field.
For example, let’s say we have a SouthTexasCity model (from the\nGeoDjango distance tests ) on a\nprojected coordinate system valid for cities in southern Texas:
from django.contrib.gis.db import models\n\n\nclass SouthTexasCity(models.Model):\n name = models.CharField(max_length=30)\n # A projected coordinate system (only valid for South Texas!)\n # is used, units are in meters.\n point = models.PointField(srid=32140)\nThen distance queries may be performed as follows:
\n>>> from django.contrib.gis.geos import GEOSGeometry\n>>> from django.contrib.gis.measure import D # ``D`` is a shortcut for ``Distance``\n>>> from geoapp.models import SouthTexasCity\n# Distances will be calculated from this point, which does not have to be projected.\n>>> pnt = GEOSGeometry("POINT(-96.876369 29.905320)", srid=4326)\n# If numeric parameter, units of field (meters in this case) are assumed.\n>>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, 7000))\n# Find all Cities within 7 km, > 20 miles away, and > 100 chains away (an obscure unit)\n>>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, D(km=7)))\n>>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(mi=20)))\n>>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(chain=100)))\nRaster queries work the same way by replacing the geometry field point with\na raster field, or the pnt object with a raster object, or both. To specify\nthe band index of a raster input on the right hand side, a 3-tuple can be\npassed to the lookup as follows:
>>> qs = SouthTexasCity.objects.filter(point__distance_gte=(rst, 2, D(km=7)))\nWhere the band with index 2 (the third band) of the raster rst would be\nused for the lookup.
The following table provides a summary of what spatial lookups are available\nfor each spatial database backend. The PostGIS Raster (PGRaster) lookups are\ndivided into the three categories described in the raster lookup details: native support N, bilateral native support B,\nand geometry conversion support C.
Lookup Type | \nPostGIS | \nOracle | \nMariaDB | \nMySQL [4] | \nSpatiaLite | \nPGRaster | \n
|---|---|---|---|---|---|---|
| \n | X | \n\n | X | \nX | \nX | \nN | \n
| \n | X | \n\n | X | \nX | \nX | \nN | \n
| \n | X | \n\n | X | \nX | \nX | \nN | \n
| \n | X | \nX | \nX | \nX | \nX | \nB | \n
| \n | X | \n\n | \n | \n | \n | B | \n
| \n | X | \nX | \nX (≥ 12.0.1) | \nX | \nX | \nB | \n
| \n | X | \nX | \n\n | X | \nX | \nB | \n
| \n | X | \n\n | X | \nX | \nX | \nC | \n
| \n | X | \nX | \nX | \nX | \nX | \nB | \n
| \n | X | \nX | \nX | \nX | \nX | \nN | \n
| \n | X | \nX | \nX | \nX | \nX | \nN | \n
| \n | X | \nX | \nX | \nX | \nX | \nN | \n
| \n | X | \nX | \nX | \nX | \nX | \nN | \n
| \n | X | \nX | \n\n | \n | X | \nB | \n
| \n | X | \nX | \nX | \nX | \nX | \nC | \n
| \n | X | \nX | \nX | \nX | \nX | \nB | \n
| \n | X | \nX (≥ 23c) | \nX | \nX | \nX | \n\n |
| \n | X | \nX | \nX | \nX | \nX | \nB | \n
| \n | X | \n\n | \n | \n | \n | \n |
| \n | X | \nX | \nX (≥ 12.0.1) | \nX | \nX | \n\n |
| \n | X | \nX | \nX | \nX | \nX | \nB | \n
| \n | X | \nX | \nX | \n\n | X | \nC | \n
| \n | X | \nX | \nX | \nX | \nX | \nB | \n
| \n | X | \nX | \nX | \nX | \nX | \nB | \n
| \n | X | \nX | \nX | \nX | \nX | \nB | \n
| \n | X | \n\n | \n | \n | \n | C | \n
| \n | X | \n\n | \n | \n | \n | C | \n
| \n | X | \n\n | \n | \n | \n | B | \n
| \n | X | \n\n | \n | \n | \n | B | \n
| \n | X | \n\n | \n | \n | \n | C | \n
| \n | X | \n\n | \n | \n | \n | C | \n
| \n | X | \n\n | \n | \n | \n | C | \n
| \n | X | \n\n | \n | \n | \n | C | \n
The following table provides a summary of what geography-specific database\nfunctions are available on each spatial backend.
\nFunction | \nPostGIS | \nOracle | \nMariaDB | \nMySQL | \nSpatiaLite | \n
|---|---|---|---|---|---|
| \n | X | \nX | \nX | \nX | \nX | \n
| \n | X | \nX | \nX | \nX | \nX | \n
| \n | X | \nX | \n\n | \n | X | \n
| \n | X | \n\n | \n | \n | X | \n
| \n | X | \n\n | \n | \n | X | \n
| \n | X | \nX | \nX | \nX | \nX | \n
| \n | X | \nX | \nX | \nX | \nX | \n
| \n | X | \n\n | \n | \n | X (LWGEOM/RTTOPO) | \n
| \n | X | \nX | \n\n | \n | X (≥ 5.1) | \n
| \n | X | \nX | \nX | \nX | \nX | \n
| \n | X | \n\n | \n | \n | X | \n
| \n | X | \nX | \nX | \nX | \nX | \n
| \n | X | \nX | \nX | \nX | \nX | \n
| \n | X | \nX | \nX | \nX | \nX | \n
| \n | X | \n\n | \n | \n | X | \n
| \n | X | \nX | \nX | \nX | \nX | \n
| \n | X | \nX | \nX | \nX | \nX | \n
| \n | X | \n\n | X (≥ 12.0.1) | \nX | \nX (LWGEOM/RTTOPO) | \n
| \n | X | \n\n | \n | \n | \n |
| \n | X | \nX (≥ 23c) | \nX | \nX | \nX | \n
| \n | X | \nX | \nX | \nX | \nX | \n
| \n | X | \n\n | \n | \n | \n |
| \n | X | \nX | \nX (≥ 12.0.1) | \nX | \nX | \n
| \n | X | \nX | \nX | \nX | \nX | \n
| \n | X | \n\n | \n | \n | X | \n
| \n | X | \n\n | \n | \n | X (LWGEOM/RTTOPO) | \n
| \n | X | \n\n | \n | \n | \n |
| \n | X | \nX | \nX | \nX | \nX | \n
| \n | X | \nX | \nX | \nX | \nX | \n
| \n | X | \nX | \n\n | \n | X | \n
| \n | X | \nX | \nX | \n\n | X | \n
| \n | X | \nX | \n\n | \n | X | \n
| \n | X | \n\n | \n | \n | \n |
| \n | X | \n\n | \n | \n | X | \n
| \n | X | \n\n | \n | \n | X | \n
| \n | X | \nX | \nX | \nX | \nX | \n
| \n | X | \nX | \n\n | \n | X | \n
| \n | X | \n\n | \n | \n | X | \n
| \n | X | \nX | \nX | \nX | \nX | \n
The following table provides a summary of what GIS-specific aggregate functions\nare available on each spatial backend.
\nAggregate | \nPostGIS | \nOracle | \nMariaDB | \nMySQL | \nSpatiaLite | \n
|---|---|---|---|---|---|
| \n | X | \n\n | X (≥ 12.0.1) | \nX (≥ 8.0.24) | \nX | \n
| \n | X | \nX | \n\n | \n | X | \n
| \n | X | \n\n | \n | \n | \n |
| \n | X | \n\n | \n | \n | X | \n
| \n | X | \nX | \n\n | \n | X | \n
Footnotes
\n\n