[[TOC(GeoDjangoDatabaseAPI)]]
= Database API =

'''Note:''' All !GeoDjango queries are performed via the `GeoQuerySet`, a modified version of Django's `QuerySet` that enables the construction of spatial SQL. 

!GeoDjango's 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(<field>__<lookup type>=<parameter>)
>>> 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 will attempt to instantiate a `GEOSGeometry` object from the input.

Below are some examples and references for GEOS Geometry objects, WKT, and HEXEWKB.
 * 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=<param>')`
   * 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)` 

= !GeoQuerySet Methods =

== gml ==
''Availability'': PostGIS, Oracle

The `gml` method takes the name of the geographic field (a string) as a parameter, and will attach a `gml` attribute to every model in the queryset that contains the [http://en.wikipedia.org/wiki/Geography_Markup_Language Geographic Markup Language] (GML) representation of the geometry.
{{{
>>> qs = Zip.objects.all().gml('poly')
>>> print qs[0].gml
<gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ...  -147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon>
}}}

Keyword arguments:
=== precision ===
This keyword may be used to specify the number of significant digits for the coordinates in the GML representation -- the default value is 8.  This keyword may not be used on Oracle.

== kml ==

''Availability'': PostGIS 1.2.1+

The `kml` method takes the name of the geographic field (a string) as a parameter, and will attach a `kml` attribute to every model in the queryset that contains the [http://code.google.com/apis/kml/documentation/ Keyhole Markup Language] (KML) representation of the geometry.  It should be noted that the contents of the KML are in WGS84, and will be transformed if necessary -- the geometry field attribute itself is not affected.

{{{
>>> qs = Zip.objects.all().kml('poly')
>>> print qs[0].kml
<Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ... -103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon>
}}}

Keyword arguments:
=== precision ===
This keyword may be used to specify the number of significant digits for the coordinates in the KML representation -- the default value is 8.

== transform ==
''Availability'': PostGIS, Oracle

The `transform` method takes the name of the geographic field (a string) as a parameter, and transforms the geometries to a different spatial refrence system.  If the `srid` keyword is not specified, WGS84 is used by default.

{{{
>>> qs = Zip.objects.all().transform('poly') # Transforms to WGS84
>>> qs = Zip.objects.all().transform('poly', 32140) # Transforming to "NAD83 / Texas South Central"
>>> print qs[0].poly.srid
32140
>>> print qs[0].poly
POLYGON ((234055.1698884720099159 4937796.9232223574072123 ...
}}}

Keyword arguments:
=== srid ===
The `srid` keyword may be used to specify the spatial reference system identifier.  Please note that this may depend on your spatial database backend, ''e.g.'', those used for Oracle are not the same as those used by PostGIS.

== union ==
''Availability'': PostGIS, Oracle

This `union` method takes the name of the geographic field (a string) as a parameter, and returns a `GEOSGeometry` object comprising the union of every geometry in the queryset.  Please note that use of `union` is processor intensive and may take a significant amount of time on large querysets.

{{{
>>> u = Zip.objects.union('poly') # This may take a LONG time, but returns a geometry representing the union of all Zip code polygons.
>>> u = Zip.objects.filter(poly__within=bbox).union('poly') # A more sensible approach.
}}}

Keyword arguments:
=== tolerance ===
This keyword is only available on Oracle platforms, and is for the tolerance value for `SDOAGGRTYPE`.  ''See'' the Oracle [http://download.oracle.com/docs/html/B14255_01/sdo_intro.htm#sthref150 documentation] for more details.

= 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.