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
MySQL's spatial extensions only support bounding box operations\n(what MySQL calls minimum bounding rectangles, or MBR). Specifically,\nMySQL does not conform to the OGC standard:
\n\n\nCurrently, MySQL does not implement these functions\n[
\nContains,Crosses,Disjoint,Intersects,Overlaps,\nTouches,Within]\naccording to the specification. Those that are implemented return\nthe same result as the corresponding MBR-based functions.
In other words, while spatial lookups such as contains\nare available in GeoDjango when using MySQL, the results returned are really\nequivalent to what would be returned when using bbcontains\non a different spatial backend.
RasterField is currently only implemented for the PostGIS backend. Spatial\nqueries (such as lookups and distance) are not yet available 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 geometric 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('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))', srid=3084) # 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(connection.queries[-1]['sql']) # 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, WKT\n(Well Known Text [1]), HEXEWKB (PostGIS specific -- a WKB geometry in\nhexadecimal [2]), and GeoJSON [3] (requires GDAL). Essentially,\nif the input 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({'width': 10, 'height': 10, 'name': 'Canyon', 'srid': 4326,\n... 'scale': [0.1, -0.1], 'bands': [{"data": range(100)}]})\n>>> dem = Elevation(name='Canyon', rast=rast)\n>>> dem.save()\nNote that this equivalent to:
\n>>> dem = Elevation.objects.create(\n... name='Canyon',\n... rast={'width': 10, 'height': 10, 'name': 'Canyon', 'srid': 4326,\n... 'scale': [0.1, -0.1], 'bands': [{"data": range(100)}]},\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 geometry fields.\nFilters on 'normal' fields (e.g. CharField)\nmay be chained with those on geographic fields. Thus, geographic queries\ntake the following general form (assuming the Zipcode model used in the\nGeoDjango 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)\nIn this case, poly is the geographic field, contains\nis the spatial lookup type, and pnt is the parameter (which may be a\nGEOSGeometry object or a string of\nGeoJSON , WKT, or HEXEWKB).
A complete reference can be found in the spatial lookup reference.
\nDistance calculations with spatial data is tricky because, unfortunately,\nthe Earth is not flat. Some distance queries with fields in a geographic\ncoordinate system may have to be expressed differently because of\nlimitations in PostGIS. Please see the Selecting an SRID section\nin the GeoDjango Model API documentation for more details.
\nAvailability: PostGIS, Oracle, SpatiaLite
\nThe following distance lookups are available:
\n\n\nDistance lookups take a tuple parameter comprising:
\nA geometry to base calculations from; and
A number or Distance object containing the 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 projected coordinate system valid for cities\nin southern Texas:
from django.contrib.gis.db import models\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)))\nThe following table provides a summary of what spatial lookups are available\nfor each spatial database backend.
\nLookup Type | \nPostGIS | \nOracle | \nMySQL [6] | \nSpatiaLite | \n
|---|---|---|---|---|
| \n | X | \n\n | X | \nX | \n
| \n | X | \n\n | X | \nX | \n
| \n | X | \n\n | X | \nX | \n
| \n | X | \nX | \nX | \nX | \n
| \n | X | \n\n | \n | \n |
| \n | X | \nX | \n\n | \n |
| \n | X | \nX | \n\n | \n |
| \n | X | \n\n | \n | X | \n
| \n | X | \nX | \nX | \nX | \n
| \n | X | \nX | \n\n | X | \n
| \n | X | \nX | \n\n | X | \n
| \n | X | \nX | \n\n | X | \n
| \n | X | \nX | \n\n | X | \n
| \n | X | \nX | \n\n | \n |
| \n | X | \nX | \nX | \nX | \n
| \n | X | \nX | \nX | \nX | \n
| \n | X | \nX | \nX | \nX | \n
| \n | X | \nX | \nX | \nX | \n
| \n | X | \nX | \n\n | X | \n
| \n | X | \nX | \nX | \nX | \n
| \n | X | \nX | \nX | \nX | \n
| \n | X | \nX | \nX | \nX | \n
| \n | X | \n\n | \n | \n |
| \n | X | \n\n | \n | \n |
| \n | X | \n\n | \n | \n |
| \n | X | \n\n | \n | \n |
| \n | X | \n\n | \n | \n |
| \n | X | \n\n | \n | \n |
| \n | X | \n\n | \n | \n |
| \n | X | \n\n | \n | \n |
The following table provides a summary of what geography-specific database\nfunctions are available on each spatial backend.
\nFunction | \nPostGIS | \nOracle | \nMySQL | \nSpatiaLite | \n
|---|---|---|---|---|
| \n | X | \nX | \nX | \nX | \n
| \n | X | \n\n | \n | X | \n
| \n | X | \n\n | \n | X | \n
| \n | X | \n\n | \n | X | \n
| \n | X | \n\n | \n | X | \n
| \n | X | \n\n | \n | \n |
| \n | X | \nX | \nX | \nX | \n
| \n | X | \nX | \n\n | X | \n
| \n | X | \nX | \nX (≥ 5.6.1) | \nX | \n
| \n | X | \n\n | X | \nX | \n
| \n | X | \n\n | \n | \n |
| \n | X | \n\n | \n | \n |
| \n | X | \nX | \n\n | X | \n
| \n | X | \nX | \nX | \nX | \n
| \n | X | \n\n | \n | \n |
| \n | X | \nX | \nX | \nX | \n
| \n | X | \nX | \nX | \nX | \n
| \n | X | \nX | \n\n | X (≥ 4.0) | \n
| \n | X | \nX | \n\n | X | \n
| \n | X | \nX | \n\n | X (≥ 4.0) | \n
| \n | X | \n\n | \n | X | \n
| \n | X | \n\n | \n | X (≥ 3.1) | \n
| \n | X | \nX | \n\n | X | \n
| \n | X | \nX | \n\n | X | \n
| \n | X | \n\n | \n | X | \n
| \n | X | \nX | \nX (≥ 5.6.1) | \nX | \n
The following table provides a summary of what GIS-specific aggregate functions\nare available on each spatial backend. Please note that MySQL does not\nsupport any of these aggregates, and is thus excluded from the table.
\nAggregate | \nPostGIS | \nOracle | \nSpatiaLite | \n
|---|---|---|---|
| \n | X | \n\n | (from v3.0) | \n
| \n | X | \nX | \n(from v3.0) | \n
| \n | X | \n\n | \n |
| \n | X | \n\n | \n |
| \n | X | \nX | \nX | \n
Footnotes
\n\n