Documented GeoQuerySet replacement by functions

docs/ref/contrib/gis/db-api.txt

@@ -115,13 +115,6 @@ GeoJSON , WKT, or HEXEWKB).
 A complete reference can be found in the :ref:`spatial lookup reference
 <spatial-lookups>`.
 
-.. note::
-
-    GeoDjango constructs spatial SQL with the :class:`GeoQuerySet`, a
-    subclass of :class:`~django.db.models.query.QuerySet`.  The
-    :class:`GeoManager` instance attached to your model is what
-    enables use of :class:`GeoQuerySet`.
-
 .. _distance-queries:
 
 Distance Queries
@@ -152,7 +145,7 @@ The following distance lookups are available:
 .. note::
 
     For *measuring*, rather than querying on distances, use the
-    :meth:`GeoQuerySet.distance` method.
+    :class:`~django.contrib.gis.db.models.functions.Distance` function.
 
 Distance lookups take a tuple parameter comprising:
 
@@ -255,43 +248,47 @@ Lookup Type                        PostGIS    Oracle    MySQL [#]_   SpatiaLite
 :lookup:`strictly_below`           X
 =================================  =========  ========  ============ ==========
 
-.. _geoqueryset-method-compatibility:
+.. _database-functions-compatibility:
 
-``GeoQuerySet`` Methods
+Database functions
------------------------
+------------------
-The following table provides a summary of what :class:`GeoQuerySet` methods
-are available on each spatial backend.  Please note that MySQL does not
-support any of these methods, and is thus excluded from the table.
 
-====================================  =======  ======  ==========
+.. module:: django.contrib.gis.db.models.functions
-Method                                PostGIS  Oracle  SpatiaLite
+   :synopsis: GeoDjango's database functions.
-====================================  =======  ======  ==========
+
-:meth:`GeoQuerySet.area`              X        X       X
+The following table provides a summary of what geography-specific database
-:meth:`GeoQuerySet.centroid`          X        X       X
+functions are available on each spatial backend.
-:meth:`GeoQuerySet.difference`        X        X       X
+
-:meth:`GeoQuerySet.distance`          X        X       X
+====================================  =======  ======  =====  ==========
-:meth:`GeoQuerySet.envelope`          X                X
+Method                                PostGIS  Oracle  MySQL  SpatiaLite
-:meth:`GeoQuerySet.force_rhr`         X
+====================================  =======  ======  =====  ==========
-:meth:`GeoQuerySet.geohash`           X
+:class:`Area`                         X        X       X      X
-:meth:`GeoQuerySet.geojson`           X                X
+:class:`AsGeoJSON`                    X                       X
-:meth:`GeoQuerySet.gml`               X        X       X
+:class:`AsGML`                        X        X              X
-:meth:`GeoQuerySet.intersection`      X        X       X
+:class:`AsKML`                        X                       X
-:meth:`GeoQuerySet.kml`               X                X
+:class:`AsSVG`                        X                       X
-:meth:`GeoQuerySet.length`            X        X       X
+:class:`BoundingCircle`               X
-:meth:`GeoQuerySet.mem_size`          X
+:class:`Centroid`                     X        X              X
-:meth:`GeoQuerySet.num_geom`          X        X       X
+:class:`Difference`                   X        X              X
-:meth:`GeoQuerySet.num_points`        X        X       X
+:class:`Distance`                     X        X       X      X
-:meth:`GeoQuerySet.perimeter`         X        X
+:class:`Envelope`                     X                       X
-:meth:`GeoQuerySet.point_on_surface`  X        X       X
+:class:`ForceRHR`                     X
-:meth:`GeoQuerySet.reverse_geom`      X        X
+:class:`GeoHash`                      X
-:meth:`GeoQuerySet.scale`             X                X
+:class:`Intersection`                 X        X              X
-:meth:`GeoQuerySet.snap_to_grid`      X
+:class:`Length`                       X        X       X      X
-:meth:`GeoQuerySet.svg`               X                X
+:class:`MemSize`                      X
-:meth:`GeoQuerySet.sym_difference`    X        X       X
+:class:`NumGeometries`                X        X              X
-:meth:`GeoQuerySet.transform`         X        X       X
+:class:`NumPoints`                    X        X              X
-:meth:`GeoQuerySet.translate`         X                X
+:class:`Perimeter`                    X        X              X
-:meth:`GeoQuerySet.union`             X        X       X
+:class:`PointOnSurface`               X        X              X
-====================================  =======  ======  ==========
+:class:`Reverse`                      X        X              X (≥ 4.0)
+:class:`Scale`                        X                       X
+:class:`SnapToGrid`                   X                       X
+:class:`SymDifference`                X        X              X
+:class:`Transform`                    X        X              X
+:class:`Translate`                    X                       X
+:class:`Union`                        X        X              X
+====================================  =======  ======  =====  ==========
 
 Aggregate Functions
 -------------------
@@ -300,15 +297,17 @@ 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.
 
-====================================  =======  ======  ==========
+.. currentmodule:: django.contrib.gis.db.models
-Aggregate                             PostGIS  Oracle  SpatiaLite
+
-====================================  =======  ======  ==========
+=======================  =======  ======  ==========
-:class:`Collect`                      X                (from v3.0)
+Aggregate                PostGIS  Oracle  SpatiaLite
-:class:`Extent`                       X        X       (from v3.0)
+=======================  =======  ======  ==========
-:class:`Extent3D`                     X
+:class:`Collect`         X                (from v3.0)
-:class:`MakeLine`                     X
+:class:`Extent`          X        X       (from v3.0)
-:class:`Union`                        X        X       X
+:class:`Extent3D`        X
-====================================  =======  ======  ==========
+:class:`MakeLine`        X
+:class:`Union`           X        X       X
+=======================  =======  ======  ==========
 
 .. rubric:: Footnotes
 .. [#fnwkt] *See* Open Geospatial Consortium, Inc., `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999), at  Ch. 3.2.5, p. 3-11 (SQL Textual Representation of Geometry).

docs/ref/contrib/gis/functions.txt

@@ -0,0 +1,437 @@
+=============================
+Geographic Database Functions
+=============================
+
+.. module:: django.contrib.gis.db.models.functions
+    :synopsis: Geographic Database Functions
+
+.. versionadded:: 1.9
+
+The functions documented on this page allow users to access geographic database
+functions to be used in annotations, aggregations, or filters in Django.
+
+Example::
+
+    >>> from django.contrib.gis.db.models.functions import Length
+    >>> Track.objects.annotate(length=Length('line')).filter(length__gt=100)
+
+Not all backends support all functions, so refer to the documentation of each
+function to see if your database backend supports the function you want to use.
+If you call a geographic function on a backend that doesn't support it, you'll
+get a ``NotImplementedError`` exception.
+
+Function's summary:
+
+==================  =======================   ======================  ===================  ==================  =====================
+Measurement         Relationships             Operations              Editors              Output format       Miscellaneous
+==================  =======================   ======================  ===================  ==================  =====================
+:class:`Area`       :class:`BoundingCircle`   :class:`Difference`     :class:`ForceRHR`    :class:`AsGeoJSON`  :class:`MemSize`
+:class:`Distance`   :class:`Centroid`         :class:`Intersection`   :class:`Reverse`     :class:`AsGML`      :class:`NumGeometries`
+:class:`Length`     :class:`Envelope`         :class:`SymDifference`  :class:`Scale`       :class:`AsKML`      :class:`NumPoints`
+:class:`Perimeter`  :class:`PointOnSurface`   :class:`Union`          :class:`SnapToGrid`  :class:`AsSVG`
+
+                                                                      :class:`Transform`   :class:`GeoHash`
+
+                                                                      :class:`Translate`
+==================  =======================   ======================  ===================  ==================  =====================
+
+Area
+----
+
+.. class:: Area(expression, **extra)
+
+*Availability*: MySQL, Oracle, PostGIS, SpatiaLite
+
+Accepts a single geographic field or expression and returns the area of the
+field as an :class:`~django.contrib.gis.measure.Area` measure. On MySQL, a raw
+float value is returned, as it's not possible to automatically determine the
+unit of the field.
+
+AsGeoJSON
+---------
+
+.. class:: AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)
+
+*Availability*: PostGIS, SpatiaLite
+
+Accepts a single geographic field or expression and returns a `GeoJSON
+<http://geojson.org/>`_ representation of the geometry.
+
+Example::
+
+    >>> City.objects.annotate(json=AsGeoJSON('point')).get(name='Chicago').json
+    {"type":"Point","coordinates":[-87.65018,41.85039]}
+
+=====================  =====================================================
+Keyword Argument       Description
+=====================  =====================================================
+``bbox``               Set this to ``True`` if you want the bounding box
+                       to be included in the returned GeoJSON.
+
+``crs``                Set this to ``True`` if you want the coordinate
+                       reference system to be included in the returned
+                       GeoJSON.
+
+``precision``          It may be used to specify the number of significant
+                       digits for the coordinates in the GeoJSON
+                       representation -- the default value is 8.
+=====================  =====================================================
+
+AsGML
+-----
+
+.. class:: AsGML(expression, version=2, precision=8, **extra)
+
+*Availability*: Oracle, PostGIS, SpatiaLite
+
+Accepts a single geographic field or expression and returns a `Geographic Markup
+Language (GML)`__ representation of the geometry.
+
+Example::
+
+    >>> qs = Zipcode.objects.annotate(gml=AsGML('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 Argument       Description
+=====================  =====================================================
+``precision``          Not used on Oracle. It may be used to specify the number
+                       of significant digits for the coordinates in the GML
+                       representation -- the default value is 8.
+
+``version``            Not used on Oracle. It may be used to specify the GML
+                       version used, and may only be values of 2 or 3.  The
+                       default value is 2.
+=====================  =====================================================
+
+__ http://en.wikipedia.org/wiki/Geography_Markup_Language
+
+AsKML
+-----
+
+.. class:: AsKML(expression, precision=8, **extra)
+
+*Availability*: PostGIS, SpatiaLite
+
+Accepts a single geographic field or expression and returns a `Keyhole Markup
+Language (KML)`__ representation of the geometry.
+
+Example::
+
+    >>> qs = Zipcode.objects.annotate(kml=AsKML('poly'))
+    >>> print(qs[0].kml)
+    <Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ...
+    -103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon>
+
+=====================  =====================================================
+Keyword Argument       Description
+=====================  =====================================================
+``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.
+=====================  =====================================================
+
+__ https://developers.google.com/kml/documentation/
+
+AsSVG
+-----
+
+.. class:: AsSVG(expression, relative=False, precision=8, **extra)
+
+*Availability*: PostGIS, SpatiaLite
+
+Accepts a single geographic field or expression and returns a `Scalable Vector
+Graphics (SVG)`__ representation of the geometry.
+
+=====================  =====================================================
+Keyword Argument       Description
+=====================  =====================================================
+``relative``           If set to ``True``, the path data will be implemented
+                       in terms of relative moves. Defaults to ``False``,
+                       meaning that absolute moves are used instead.
+
+``precision``          This keyword may be used to specify the number of
+                       significant digits for the coordinates in the SVG
+                       representation -- the default value is 8.
+=====================  =====================================================
+
+__ http://www.w3.org/Graphics/SVG/
+
+BoundingCircle
+--------------
+
+.. class:: BoundingCircle(expression, num_seg=48, **extra)
+
+*Availability*: `PostGIS <http://postgis.net/docs/ST_MinimumBoundingCircle.html>`__
+
+Accepts a single geographic field or expression and returns the smallest circle
+polygon that can fully contain the geometry.
+
+Centroid
+--------
+
+.. class:: Centroid(expression, **extra)
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+Accepts a single geographic field or expression and returns the ``centroid``
+value of the geometry.
+
+Difference
+----------
+
+.. class:: Difference(expr1, expr2, **extra)
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+Accepts two geographic fields or expressions and returns the geometric
+difference, that is the part of geometry A that does not intersect with
+geometry B.
+
+Distance
+--------
+
+.. class:: Distance(expr1, expr2, spheroid=None, **extra)
+
+*Availability*: MySQL, PostGIS, Oracle, SpatiaLite
+
+Accepts two geographic fields or expressions and returns the distance between
+them, as a :class:`~django.contrib.gis.measure.Distance` object. On MySQL, a raw
+float value is returned, as it's not possible to automatically determine the
+unit of the field.
+
+On backends that support distance calculation on geodetic coordinates, the
+proper backend function is automatically chosen depending on the SRID value of
+the geometries (e.g. ``ST_Distance_Sphere`` on PostGIS).
+
+When distances are calculated with geodetic (angular) coordinates, as is the
+case with the default WGS84 (4326) SRID, you can set the ``spheroid`` keyword
+argument to decide if the calculation should be based on a simple sphere (less
+accurate, less resource-intensive) or on a spheroid (more accurate, more
+resource-intensive).
+
+In the following example, the distance from the city of Hobart to every other
+:class:`~django.contrib.gis.db.models.PointField` in the ``AustraliaCity``
+queryset is calculated::
+
+    >>> pnt = AustraliaCity.objects.get(name='Hobart').point
+    >>> for city in AustraliaCity.objects.distance('point', pnt):
+    ...     print(city.name, city.distance)
+    Wollongong 990071.220408 m
+    Shellharbour 972804.613941 m
+    Thirroul 1002334.36351 m
+    ...
+
+.. note::
+
+    Because the ``distance`` attribute is a
+    :class:`~django.contrib.gis.measure.Distance` object, you can easily express
+    the value in the units of your choice. For example, ``city.distance.mi`` is
+    the distance value in miles and ``city.distance.km`` is the distance value
+    in kilometers. See :doc:`measure` for usage details and the list of
+    :ref:`supported_units`.
+
+Envelope
+--------
+
+.. class:: Envelope(expression, **extra)
+
+*Availability*: PostGIS, SpatiaLite
+
+Accepts a single geographic field or expression and returns the geometry
+representing the bounding box of the geometry.
+
+ForceRHR
+--------
+
+.. class:: ForceRHR(expression, **extra)
+
+*Availability*: `PostGIS <http://postgis.net/docs/ST_ForceRHR.html>`__
+
+Accepts a single geographic field or expression and returns a modified version
+of the polygon/multipolygon in which all of the vertices follow the
+right-hand rule.
+
+GeoHash
+-------
+
+.. class:: GeoHash(expression, **extra)
+
+*Availability*: PostGIS
+
+Accepts a single geographic field or expression and returns a `GeoHash`__
+representation of the geometry.
+
+__ http://en.wikipedia.org/wiki/Geohash
+
+Intersection
+------------
+
+.. class:: Intersection(expr1, expr2, **extra)
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+Accepts two geographic fields or expressions and returns the geometric
+intersection between them.
+
+Length
+------
+
+.. class:: Length(expression, spheroid=True, **extra)
+
+*Availability*: MySQL, Oracle, PostGIS, SpatiaLite
+
+Accepts a single geographic linestring or multilinestring field or expression
+and returns its length as an :class:`~django.contrib.gis.measure.Distance`
+measure. On MySQL, a raw float value is returned, as it's not possible to
+automatically determine the unit of the field.
+
+On PostGIS and SpatiaLite, when the coordinates are geodetic (angular), you can
+specify if the calculation should be based on a simple sphere (less
+accurate, less resource-intensive) or on a spheroid (more accurate, more
+resource-intensive) with the ``spheroid`` keyword argument.
+
+MemSize
+-------
+
+.. class:: MemSize(expression, **extra)
+
+*Availability*: PostGIS
+
+Accepts a single geographic field or expression and returns the memory size
+(number of bytes) that the geometry field takes.
+
+NumGeometries
+-------------
+
+.. class:: NumGeometries(expression, **extra)
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+Accepts a single geographic field or expression and returns the number of
+geometries if the geometry field is a collection (e.g., a ``GEOMETRYCOLLECTION``
+or ``MULTI*`` field); otherwise returns ``None``.
+
+NumPoints
+---------
+
+.. class:: NumPoints(expression, **extra)
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+Accepts a single geographic field or expression and returns the number of points
+in the first linestring in the geometry field; otherwise returns ``None``.
+
+Perimeter
+---------
+
+.. class:: Perimeter(expression, **extra)
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+Accepts a single geographic field or expression and returns the perimeter of the
+geometry field as a :class:`~django.contrib.gis.measure.Distance` object. On
+MySQL, a raw float value is returned, as it's not possible to automatically
+determine the unit of the field.
+
+PointOnSurface
+--------------
+
+.. class:: PointOnSurface(expression, **extra)
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+Accepts a single geographic field or expression and returns a ``Point`` geometry
+guaranteed to lie on the surface of the field; otherwise returns ``None``.
+
+Reverse
+-------
+
+.. class:: Reverse(expression, **extra)
+
+*Availability*: PostGIS, Oracle, SpatiaLite (≥ 4.0)
+
+Accepts a single geographic field or expression and returns a geometry with
+reversed coordinates.
+
+Scale
+-----
+
+.. class:: Scale(expression, x, y, z=0.0, **extra)
+
+*Availability*: PostGIS, SpatiaLite
+
+Accepts a single geographic field or expression and returns a geometry with
+scaled coordinates by multiplying them with the ``x``, ``y``, and optionally
+``z`` parameters.
+
+SnapToGrid
+----------
+
+.. class:: SnapToGrid(expression, *args, **extra)
+
+*Availability*: PostGIS, SpatiaLite
+
+Accepts a single geographic field or expression and returns a geometry with all
+points snapped to the given grid.  How the geometry is snapped to the grid
+depends on how many numeric (either float, integer, or long) arguments are
+given.
+
+===================  =====================================================
+Number of Arguments  Description
+===================  =====================================================
+1                    A single size to snap both the X and Y grids to.
+2                    X and Y sizes to snap the grid to.
+4                    X, Y sizes and the corresponding X, Y origins.
+===================  =====================================================
+
+SymDifference
+-------------
+
+.. class:: SymDifference(expr1, expr2, **extra)
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+Accepts two geographic fields or expressions and returns the geometric
+symmetric difference (union without the intersection) between the given
+parameters.
+
+Transform
+---------
+
+.. class:: Transform(expression, srid, **extra)
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+Accepts a geographic field or expression and a SRID integer code, and returns
+the transformed geometry to the spatial reference system specified by the
+``srid`` parameter.
+
+.. note::
+
+    What spatial reference system an integer SRID corresponds to may depend on
+    the spatial database used.  In other words, the SRID numbers used for Oracle
+    are not necessarily the same as those used by PostGIS.
+
+Translate
+---------
+
+.. class:: Translate(expression, x, y, z=0.0, **extra)
+
+*Availability*: PostGIS, SpatiaLite
+
+Accepts a single geographic field or expression and returns a geometry with
+its coordinates offset by the ``x``, ``y``, and optionally ``z`` numeric
+parameters.
+
+Union
+-----
+
+.. class:: Union(expr1, expr2, **extra)
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+Accepts two geographic fields or expressions and returns the union of both
+geometries.

docs/ref/contrib/gis/geoquerysets.txt

@@ -633,6 +633,12 @@ Oracle      ``SDO_WITHIN_DISTANCE(poly, geom, 5)``
 ``GeoQuerySet`` Methods
 =======================
 
+.. deprecated:: 1.9
+
+    Using ``GeoQuerySet`` methods is now deprecated in favor of the new
+    :doc:`functions`. Albeit a little more verbose, they are much more powerful
+    in how it is possible to combine them to build more complex queries.
+
 ``GeoQuerySet`` methods specify that a spatial operation be performed
 on each spatial operation on each geographic
 field in the queryset and store its output in a new attribute on the model
@@ -645,7 +651,7 @@ of every ``GeoQuerySet`` method available in GeoDjango.
 .. note::
 
     What methods are available depend on your spatial backend.  See
-    the :ref:`compatibility table <geoqueryset-method-compatibility>`
+    the :ref:`compatibility table <database-functions-compatibility>`
     for more details.
 
 With a few exceptions, the following keyword arguments may be used with all
@@ -691,6 +697,11 @@ Measurement
 
 .. method:: GeoQuerySet.area(**kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.Area` function
+    instead.
+
 Returns the area of the geographic field in an ``area`` attribute on
 each element of this GeoQuerySet.
 
@@ -699,6 +710,11 @@ each element of this GeoQuerySet.
 
 .. method:: GeoQuerySet.distance(geom, **kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.Distance` function
+    instead.
+
 This method takes a geometry as a parameter, and attaches a ``distance``
 attribute to every model in the returned queryset that contains the
 distance (as a :class:`~django.contrib.gis.measure.Distance` object) to the given geometry.
@@ -738,6 +754,11 @@ __ http://en.wikipedia.org/wiki/Tasmania
 
 .. method:: GeoQuerySet.length(**kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.Length` function
+    instead.
+
 Returns the length of the geometry field in a ``length`` attribute
 (a :class:`~django.contrib.gis.measure.Distance` object) on each model in
 the queryset.
@@ -747,6 +768,11 @@ the queryset.
 
 .. method:: GeoQuerySet.perimeter(**kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.Perimeter` function
+    instead.
+
 Returns the perimeter of the geometry field in a ``perimeter`` attribute
 (a :class:`~django.contrib.gis.measure.Distance` object) on each model in
 the queryset.
@@ -763,6 +789,11 @@ function evaluated on the geometry field.
 
 .. method:: GeoQuerySet.centroid(**kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.Centroid` function
+    instead.
+
 *Availability*: PostGIS, Oracle, SpatiaLite
 
 Returns the ``centroid`` value for the geographic field in a ``centroid``
@@ -773,6 +804,11 @@ attribute on each element of the ``GeoQuerySet``.
 
 .. method:: GeoQuerySet.envelope(**kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.Envelope` function
+    instead.
+
 *Availability*: PostGIS, SpatiaLite
 
 Returns a geometry representing the bounding box of the geometry field in
@@ -783,6 +819,11 @@ an ``envelope`` attribute on each element of the ``GeoQuerySet``.
 
 .. method:: GeoQuerySet.point_on_surface(**kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.PointOnSurface`
+    function instead.
+
 *Availability*: PostGIS, Oracle, SpatiaLite
 
 Returns a Point geometry guaranteed to lie on the surface of the
@@ -797,6 +838,11 @@ Geometry Editors
 
 .. method:: GeoQuerySet.force_rhr(**kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.ForceRHR` function
+    instead.
+
 *Availability*: PostGIS
 
 Returns a modified version of the polygon/multipolygon in which all
@@ -808,6 +854,11 @@ of the vertices follow the Right-Hand-Rule, and attaches as a
 
 .. method:: GeoQuerySet.reverse_geom(**kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.Reverse` function
+    instead.
+
 *Availability*: PostGIS, Oracle
 
 Reverse the coordinate order of the geometry field, and attaches as a
@@ -818,6 +869,11 @@ Reverse the coordinate order of the geometry field, and attaches as a
 
 .. method:: GeoQuerySet.scale(x, y, z=0.0, **kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.Scale` function
+    instead.
+
 *Availability*: PostGIS, SpatiaLite
 
 ``snap_to_grid``
@@ -825,6 +881,11 @@ Reverse the coordinate order of the geometry field, and attaches as a
 
 .. method:: GeoQuerySet.snap_to_grid(*args, **kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.SnapToGrid` function
+    instead.
+
 Snap all points of the input geometry to the grid.  How the
 geometry is snapped to the grid depends on how many numeric
 (either float, integer, or long) arguments are given.
@@ -842,6 +903,11 @@ Number of Arguments  Description
 
 .. method:: GeoQuerySet.transform(srid=4326, **kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.Transform` function
+    instead.
+
 *Availability*: PostGIS, Oracle, SpatiaLite
 
 The ``transform`` method transforms the geometry field of a model to the spatial
@@ -873,6 +939,11 @@ Example::
 ~~~~~~~~~~~~~
 .. method:: GeoQuerySet.translate(x, y, z=0.0, **kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.Translate` function
+    instead.
+
 *Availability*: PostGIS, SpatiaLite
 
 Translates the geometry field to a new location using the given numeric
@@ -890,6 +961,11 @@ to each element of the ``GeoQuerySet`` that is the result of the operation.
 
 .. method:: GeoQuerySet.difference(geom)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.Difference` function
+    instead.
+
 Returns the spatial difference of the geographic field with the given
 geometry in a ``difference`` attribute on each element of the
 ``GeoQuerySet``.
@@ -900,6 +976,11 @@ geometry in a ``difference`` attribute on each element of the
 
 .. method:: GeoQuerySet.intersection(geom)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.Intersection`
+    function instead.
+
 Returns the spatial intersection of the geographic field with the
 given geometry in an ``intersection`` attribute on each element of the
 ``GeoQuerySet``.
@@ -909,6 +990,11 @@ given geometry in an ``intersection`` attribute on each element of the
 
 .. method:: GeoQuerySet.sym_difference(geom)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.SymDifference`
+    function instead.
+
 Returns the symmetric difference of the geographic field with the
 given geometry in a ``sym_difference`` attribute on each element of the
 ``GeoQuerySet``.
@@ -918,6 +1004,11 @@ given geometry in a ``sym_difference`` attribute on each element of the
 
 .. method:: GeoQuerySet.union(geom)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.Union` function
+    instead.
+
 Returns the union of the geographic field with the given
 geometry in an ``union`` attribute on each element of the
 ``GeoQuerySet``.
@@ -933,6 +1024,11 @@ of the geometry field in each model converted to the requested output format.
 
 .. method:: GeoQuerySet.geohash(precision=20, **kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.GeoHash` function
+    instead.
+
 Attaches a ``geohash`` attribute to every model the queryset
 containing the `GeoHash`__ representation of the geometry.
 
@@ -943,6 +1039,11 @@ __ http://geohash.org/
 
 .. method:: GeoQuerySet.geojson(**kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.AsGeoJSON` function
+    instead.
+
 *Availability*: PostGIS, SpatiaLite
 
 Attaches a ``geojson`` attribute to every model in the queryset that contains the
@@ -970,6 +1071,11 @@ __ http://geojson.org/
 
 .. method:: GeoQuerySet.gml(**kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.AsGML` function
+    instead.
+
 *Availability*: PostGIS, Oracle, SpatiaLite
 
 Attaches a ``gml`` attribute to every model in the queryset that contains the
@@ -1001,6 +1107,11 @@ __ http://en.wikipedia.org/wiki/Geography_Markup_Language
 
 .. method:: GeoQuerySet.kml(**kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.AsKML` function
+    instead.
+
 *Availability*: PostGIS, SpatiaLite
 
 Attaches a ``kml`` attribute to every model in the queryset that contains the
@@ -1029,6 +1140,11 @@ __ https://developers.google.com/kml/documentation/
 
 .. method:: GeoQuerySet.svg(**kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.AsSVG` function
+    instead.
+
 *Availability*: PostGIS, SpatiaLite
 
 Attaches a ``svg`` attribute to every model in the queryset that contains
@@ -1056,6 +1172,11 @@ Miscellaneous
 
 .. method:: GeoQuerySet.mem_size(**kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.MemSize` function
+    instead.
+
 *Availability*: PostGIS
 
 Returns the memory size (number of bytes) that the geometry field takes
@@ -1066,6 +1187,11 @@ in a ``mem_size`` attribute  on each element of the ``GeoQuerySet``.
 
 .. method:: GeoQuerySet.num_geom(**kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.NumGeometries`
+    function instead.
+
 *Availability*: PostGIS, Oracle, SpatiaLite
 
 Returns the number of geometries in a ``num_geom`` attribute on
@@ -1078,6 +1204,11 @@ otherwise sets with ``None``.
 
 .. method:: GeoQuerySet.num_points(**kwargs)
 
+.. deprecated:: 1.9
+
+    Use the :class:`~django.contrib.gis.db.models.functions.NumPoints` function
+    instead.
+
 *Availability*: PostGIS, Oracle, SpatiaLite
 
 Returns the number of points in the first linestring in the

docs/ref/contrib/gis/index.txt

@@ -18,6 +18,7 @@ of spatially enabled data.
    db-api
    forms-api
    geoquerysets
+   functions
    measure
    geos
    gdal

docs/ref/contrib/gis/tutorial.txt

@@ -631,8 +631,8 @@ a ``contains`` lookup using the ``pnt_wkt`` as the parameter::
     >>> qs
     [<WorldBorder: United States>]
 
-Here, you retrieved a ``GeoQuerySet`` with only one model: the border of
+Here, you retrieved a ``QuerySet`` with only one model: the border of the
-the United States (exactly what you would expect).
+United States (exactly what you would expect).
 
 Similarly, you may also use a :doc:`GEOS geometry object <geos>`.
 Here, you can combine the ``intersects`` spatial lookup with the ``get``
@@ -718,8 +718,12 @@ the GEOS library::
     >>> pnt.contains(sm.mpoly)
     False
 
-``GeoQuerySet`` Methods
+Geographic annotations
------------------------
+----------------------
+
+GeoDjango also offers a set of geographic annotations to compute distances and
+several other operations (intersection, difference, etc.). See the
+:doc:`functions` documentation.
 
 
 Putting your data on the map

docs/releases/1.9.txt

@@ -62,6 +62,11 @@ Minor features
 :mod:`django.contrib.gis`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+* All ``GeoQuerySet`` methods have been deprecated and replaced by
+  :doc:`equivalent database functions </ref/contrib/gis/functions>`. As soon
+  as the legacy methods have been replaced in your code, you should even be
+  able to remove the special ``GeoManager`` from your GIS-enabled classes.
+
 * The GDAL interface now supports instantiating file-based and in-memory
   :ref:`GDALRaster objects <raster-data-source-objects>` from raw data.
   Setters for raster properties such as projection or pixel values have

docs/spelling_wordlist

@@ -492,6 +492,7 @@ Multi
 multicolumn
 multijoins
 multiline
+multilinestring
 multipart
 multipolygon
 multithreaded