[[TOC(GeoDjangoDatabaseAPI)]] = Database API = '''Note:''' The following database lookup types can only be used with on geographic fields with `filter()`. Filters on 'normal' fields (e.g. `CharField`) may be chained with those on geographic fields. Thus, geographic queries take the following form (assuming the `Zip` model used in the [wiki:GeoDjangoModelAPI GeoDjango Model API docs]: {{{ #!python >>> qs = Zip.objects.filter(__=) >>> qs = Zip.objects.exclude(...) }}} For example: {{{ #!python >>> qs = Zip.objects.filter(poly__contains=pnt) }}} In this case, `poly` is the geographic field, `contains` is the lookup type, and `pnt` is the parameter (which may be a `GEOSGeometry` object, a string of WKT, or a string of HEXEWKB). == Creating and Saving Geographic Models == Here is an example of how to create a geometry object (assuming the `Zip` model): {{{ #!python >>> from zipcode.models import Zip >>> z = Zip(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: {{{ #!python >>> from django.contrib.gis.geos import GEOSGeometry >>> z = Zip(code=77096, poly=GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))')) >>> 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: {{{ #!python >>> 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 = Zip(code=78212, poly=poly_3084) >>> z.save() >>> from django.db import connection >>> print connection.queries[-1]['sql'] # printing the last SQL statement executed INSERT INTO "geoapp_zip" ("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) or HEXEWKB (PostGIS specific, essentially a WKB geometry in hexadecimal). Essentially, if the input is not a `GEOSGeometry` object, it wFor example: * GEOS Geometry: {{{ #!python >>> from django.contrib.gis.geos import * >>> pnt = Point(5, 23) >>> ls = LineString((0, 0), (5, 23)) >>> poly = GEOSGeometry('POLYGON (( 10 10, 10 20, 20 20, 20 15, 10 10))') }}} * WKT Polygon: `'POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))'` * ''See'' Open GIS Consortium, Inc., ''[http://www.opengis.org/docs/99-049.pdf OpenGIS Simple Feature Specification For SQL]'', Document 99-049 (May 5, 1999), at Ch. 3.2.5 (SQL Textual Representation of Geometry, pg. 53). * HEXEWKB Polygon: '`0103000000010000000 ... 00000000000002440'` * ''See'' [http://postgis.refractions.net/docs/ch04.html#id2904792 "PostGIS EWKB, EWKT and Canonical Forms"], PostGIS documentation at Ch. 4.1.2. == PostGIS == === PostGIS Operator Field Lookup Types === For more information, see generally, [http://postgis.refractions.net/docs/ch06.html#id2854381 "Operators", PostGIS Documentation at Ch. 6.2.2] * `overlaps_left` * Returns true if A's bounding box overlaps or is to the left of B's bounding box. * PostGIS equivalent "`&<`" * `overlaps_right` * Returns true if A's bounding box overlaps or is to the right of B's bounding box. * PostGIS equivalent "`&>`" * `left` * Returns true if A's bounding box is strictly to the left of B's bounding box. * PostGIS equivalent "`<<`" * `right` * Returns true if A's bounding box is strictly to the right of B's bounding box. * PostGIS equivalent "`>>`" * `overlaps_below` * Returns true if A's bounding box overlaps or is below B's bounding box. * PostGIS equivalent "`&<|`" * `overlaps_above` * Returns true if A's bounding box overlaps or is above B's bounding box. * PostGIS equivalent "`|&>`" * `strictly_below` * Returns true if A's bounding box is strictly below B's bounding box. * PostGIS equivalent "`<<|`" * `strictly_above` * Returns true if A's bounding box is strictly above B's bounding box. * PostGIS equivalent "`|>>`" * `same_as` or `exact` * The "same as" operator. It tests actual geometric equality of two features. So if A and B are the same feature, vertex-by-vertex, the operator returns true. * PostGIS equivalent "`~=`" * `contained` * Returns true if A's bounding box is completely contained by B's bounding box. * PostGIS equivalent "`@`" * `bbcontains` * Returns true if A's bounding box completely contains B's bounding box. * PostGIS equivalent "`~`" * `bboverlaps` * Returns true if A's bounding box overlaps B's bounding box. * PostGIS equivalent "`&&`" === PostGIS GEOS Function Field Lookup Types === For more information, see generally [http://postgis.refractions.net/docs/ch06.html#id2615853 "Geometry Relationship Functions"], PostGIS Documentation at Ch. 6.1.2. Please note that when using PostGIS 1.3.1 and above, index support is automatically "inlined" -- in other words, the bounding box equivalent is automatically evaluated prior to calling these, more computationally expensive, functions. * `equals` * Returns 1 (TRUE) if the given Geometries are "spatially equal". * Use this for a 'better' answer than '='. equals('LINESTRING(0 0, 10 10)','LINESTRING(0 0, 5 5, 10 10)') is true. * PostGIS equivalent `Equals(geometry, geometry)`, OGC SPEC s2.1.1.2 * `disjoint` * Returns 1 (TRUE) if the Geometries are "spatially disjoint". * PostGIS equivalent `Disjoint(geometry, geometry)` * `touches` * Returns 1 (TRUE) if the Geometries "spatially touch". * PostGIS equivalent `Touches(geometry, geometry)` * `crosses` * Returns 1 (TRUE) if the Geometries "spatially cross". * PostGIS equivalent `Crosses(geometry, geometry)` * `within` * Returns 1 (TRUE) if Geometry A is "spatially within" Geometry B. * PostGIS equivalent `Within(geometry, geometry)` * `overlaps` * Returns 1 (TRUE) if the Geometries "spatially overlap". * PostGIS equivalent `Overlaps(geometry, geometry)` * `contains` * Returns 1 (TRUE) if Geometry A "spatially contains" Geometry B. * PostGIS equivalent `Contains(geometry, geometry)` * `relate` * Returns the DE-9IM (dimensionally extended nine-intersection matrix) between the two geometries. * Tuple parameter `(geom, pattern)` required for lookup type, where `pattern` is an intersection pattern -- a string comprising nine characters, where each character is one of `T`, `F`, or `*`.). * PostGIS equivelent `Relate(geometry, geometry, intersectionPatternMatrix)` The following lookup types are only available in PostGIS versions 1.3.1 and above: * `dwithin` * Returns true if geometries are within the specified distance of one another. Uses indexes if available. * Tuple parameter `(geom, distance)` required for lookup type. * `coveredby` * Returns 1 (TRUE) if no point in Geometry A is outside Geometry B * Refer to [http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html this resource] for an explaination of the need of this function. * `covers` * Returns 1 (TRUE) if no point in Geometry B is outside Geometry A * See link in `coveredby` documentation above for more information. == Oracle == For more information, see generally, [http://download.oracle.com/docs/html/B14255_01/sdo_operat.htm Spatial Operators], Oracle Spatial User's Guide and Manual, at Ch. 11. * `contains` * Oracle equivalent `SDO_CONTAINS(geometry1, geometry2)` * `coveredby` * Oracle equivalent `SDO_COVEREDBY(geometry1, geometry2)` * `covers` * Oracle equivalent `SDO_COVERS(geometry1, geometry2)` * `dwithin` * Oracle equivalent `SDO_WITHIN_DISTANCE(geometry1, geometry2, 'distance=')` * Tuple parameter `(geom, distance)` required for lookup type. * `equals`, `exact`, `same_as` * Oracle equivalent, `SDO_EQUALS(geometry1, geometry2)` * `intersects` * Oracle equivalent `SDO_OVERLAPBDYINTERSECT(geometry1, geometry2)` * `overlaps` * Oracle equivalent `SDO_OVERLAPS(geometry1, geometry2)` * `touches` * Oracle equivalent `SDO_TOUCH(geometry1, geometry2)` * `within` * Oracle equivalent `SDO_INSIDE(geometry1, geometry2)` == MySQL == For more information, see generally, [http://dev.mysql.com/doc/refman/5.0/en/relations-on-geometry-mbr.html Relations on Geometry Minimal Bounding Rectangles (MBRs)], MySQL 5.0 Reference Manual, at Ch. 17.5.5. * `bbcontains`, `contains` * MySQL equivalent `MBRContains(g1, g2)` * `contained`, `within` * MySQL equivalent `MBRWithin(g1, g2)` * `disjoint` * MySQL equivalent `MBRDisjoint(g1, g2)` * `equals`, `exact`, `same_as` * MySQL equivalent `MBREqual(g1, g2)` * `intersects` * MySQL equivalent `MBRIntersects(g1, g2)` * `overlaps` * MySQL equivalent `MBROverlaps(g1, g2)` * `touches` * MySQL equivalent `MBRTouches(g1, g2)` = Extra Instance Methods = '''Update:''' All of the extra instance methods haave been deprecated as of r6467 because lazy geometry support includes all of their functionality (including OGR geometries and OSR spatial references with the `ogr` and `srs` properties, respectively). In other words, these properties may be directly accessed as attributes from the geometry field.