innov
/
django1
1
0
Fork 0
Code Issues Pull Requests 1 Projects Releases Wiki Activity

[1.11.x] Linked GIS QuerySet API docs to corresponding PostGIS docs. 

Backport of 7b6524e0ff from master
This commit is contained in:
Sergey Fedoseev 2017-03-22 21:21:59 +05:00 committed by Tim Graham
parent 02bc5563b8
commit 04a2fd5e00
1 changed files with 65 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
docs/ref/contrib/gis/geoquerysets.txt
View File

@ -71,7 +71,8 @@ Spatial lookups with rasters are only supported for PostGIS backends
``bbcontains`` ``bbcontains``
-------------- --------------
*Availability*: PostGIS, MySQL, SpatiaLite, PGRaster (Native) *Availability*: `PostGIS <https://postgis.net/docs/ST_Geometry_Contain.html>`__,
MySQL, SpatiaLite, PGRaster (Native)
Tests if the geometry or raster field's bounding box completely contains the Tests if the geometry or raster field's bounding box completely contains the
lookup geometry's bounding box. lookup geometry's bounding box.
@ -93,7 +94,8 @@ SpatiaLite ``MbrContains(poly, geom)``
``bboverlaps`` ``bboverlaps``
-------------- --------------
*Availability*: PostGIS, MySQL, SpatiaLite, PGRaster (Native) *Availability*: `PostGIS <https://postgis.net/docs/geometry_overlaps.html>`__,
MySQL, SpatiaLite, PGRaster (Native)
Tests if the geometry field's bounding box overlaps the lookup geometry's Tests if the geometry field's bounding box overlaps the lookup geometry's
bounding box. bounding box.
@ -115,7 +117,8 @@ SpatiaLite ``MbrOverlaps(poly, geom)``
``contained`` ``contained``
------------- -------------
*Availability*: PostGIS, MySQL, SpatiaLite, PGRaster (Native) *Availability*: `PostGIS <https://postgis.net/docs/ST_Geometry_Contained.html>`__,
MySQL, SpatiaLite, PGRaster (Native)
Tests if the geometry field's bounding box is completely contained by the Tests if the geometry field's bounding box is completely contained by the
lookup geometry's bounding box. lookup geometry's bounding box.
@ -137,7 +140,8 @@ SpatiaLite ``MbrWithin(poly, geom)``
``contains`` ``contains``
------------ ------------
*Availability*: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Bilateral) *Availability*: `PostGIS <https://postgis.net/docs/ST_Contains.html>`__,
Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)
Tests if the geometry field spatially contains the lookup geometry. Tests if the geometry field spatially contains the lookup geometry.
@ -159,10 +163,11 @@ SpatiaLite ``Contains(poly, geom)``
``contains_properly`` ``contains_properly``
--------------------- ---------------------
*Availability*: PostGIS, PGRaster (Bilateral) *Availability*: `PostGIS <https://postgis.net/docs/ST_ContainsProperly.html>`__,
PGRaster (Bilateral)
Returns true if the lookup geometry intersects the interior of the Returns true if the lookup geometry intersects the interior of the
geometry field, but not the boundary (or exterior). [#fncontainsproperly]_ geometry field, but not the boundary (or exterior).
Example:: Example::
@ -179,7 +184,8 @@ PostGIS ``ST_ContainsProperly(poly, geom)``
``coveredby`` ``coveredby``
------------- -------------
*Availability*: PostGIS, Oracle, PGRaster (Bilateral) *Availability*: `PostGIS <https://postgis.net/docs/ST_CoveredBy.html>`__,
Oracle, PGRaster (Bilateral)
Tests if no point in the geometry field is outside the lookup geometry. Tests if no point in the geometry field is outside the lookup geometry.
[#fncovers]_ [#fncovers]_
@ -200,7 +206,8 @@ Oracle ``SDO_COVEREDBY(poly, geom)``
``covers`` ``covers``
---------- ----------
*Availability*: PostGIS, Oracle, PGRaster (Bilateral) *Availability*: `PostGIS <https://postgis.net/docs/ST_Covers.html>`__,
Oracle, PGRaster (Bilateral)
Tests if no point in the lookup geometry is outside the geometry field. Tests if no point in the lookup geometry is outside the geometry field.
[#fncovers]_ [#fncovers]_
@ -221,7 +228,8 @@ Oracle ``SDO_COVERS(poly, geom)``
``crosses`` ``crosses``
----------- -----------
*Availability*: PostGIS, SpatiaLite, PGRaster (Conversion) *Availability*: `PostGIS <https://postgis.net/docs/ST_Crosses.html>`__,
SpatiaLite, PGRaster (Conversion)
Tests if the geometry field spatially crosses the lookup geometry. Tests if the geometry field spatially crosses the lookup geometry.
@ -241,7 +249,8 @@ SpatiaLite ``Crosses(poly, geom)``
``disjoint`` ``disjoint``
------------ ------------
*Availability*: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Bilateral) *Availability*: `PostGIS <https://postgis.net/docs/ST_Disjoint.html>`__,
Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)
Tests if the geometry field is spatially disjoint from the lookup geometry. Tests if the geometry field is spatially disjoint from the lookup geometry.
@ -263,7 +272,8 @@ SpatiaLite ``Disjoint(poly, geom)``
``equals`` ``equals``
---------- ----------
*Availability*: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Conversion) *Availability*: `PostGIS <https://postgis.net/docs/ST_Equals.html>`__,
Oracle, MySQL, SpatiaLite, PGRaster (Conversion)
.. fieldlookup:: exact .. fieldlookup:: exact
.. fieldlookup:: same_as .. fieldlookup:: same_as
@ -271,14 +281,16 @@ SpatiaLite ``Disjoint(poly, geom)``
``exact``, ``same_as`` ``exact``, ``same_as``
---------------------- ----------------------
*Availability*: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Bilateral) *Availability*: `PostGIS <https://postgis.net/docs/ST_Geometry_Same.html>`__,
Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)
.. fieldlookup:: intersects .. fieldlookup:: intersects
``intersects`` ``intersects``
-------------- --------------
*Availability*: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Bilateral) *Availability*: `PostGIS <https://postgis.net/docs/ST_Intersects.html>`__,
Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)
Tests if the geometry field spatially intersects the lookup geometry. Tests if the geometry field spatially intersects the lookup geometry.
@ -302,7 +314,7 @@ SpatiaLite ``Intersects(poly, geom)``
.. versionadded:: 1.10 .. versionadded:: 1.10
*Availability*: PostGIS *Availability*: `PostGIS <https://postgis.net/docs/ST_IsValid.html>`__
Tests if the geometry is valid. Tests if the geometry is valid.
@ -319,14 +331,16 @@ PostGIS equivalent::
``overlaps`` ``overlaps``
------------ ------------
*Availability*: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Bilateral) *Availability*: `PostGIS <https://postgis.net/docs/ST_Overlaps.html>`__,
Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)
.. fieldlookup:: relate .. fieldlookup:: relate
``relate`` ``relate``
---------- ----------
*Availability*: PostGIS, Oracle, SpatiaLite, PGRaster (Conversion) *Availability*: `PostGIS <https://postgis.net/docs/ST_Relate.html>`__,
Oracle, SpatiaLite, PGRaster (Conversion)
Tests if the geometry field is spatially related to the lookup geometry by Tests if the geometry field is spatially related to the lookup geometry by
the values given in the given pattern. This lookup requires a tuple parameter, the values given in the given pattern. This lookup requires a tuple parameter,
@ -388,7 +402,8 @@ Oracle SQL equivalent::
``touches`` ``touches``
----------- -----------
*Availability*: PostGIS, Oracle, MySQL, SpatiaLite *Availability*: `PostGIS <https://postgis.net/docs/ST_Touches.html>`__,
Oracle, MySQL, SpatiaLite
Tests if the geometry field spatially touches the lookup geometry. Tests if the geometry field spatially touches the lookup geometry.
@ -410,7 +425,8 @@ SpatiaLite ``Touches(poly, geom)``
``within`` ``within``
---------- ----------
*Availability*: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Bilateral) *Availability*: `PostGIS <https://postgis.net/docs/ST_Within.html>`__,
Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)
Tests if the geometry field is spatially within the lookup geometry. Tests if the geometry field is spatially within the lookup geometry.
@ -432,7 +448,8 @@ SpatiaLite ``Within(poly, geom)``
``left`` ``left``
-------- --------
*Availability*: PostGIS, PGRaster (Conversion) *Availability*: `PostGIS <https://postgis.net/docs/ST_Geometry_Left.html>`__,
PGRaster (Conversion)
Tests if the geometry field's bounding box is strictly to the left of the Tests if the geometry field's bounding box is strictly to the left of the
lookup geometry's bounding box. lookup geometry's bounding box.
@ -450,7 +467,8 @@ PostGIS equivalent::
``right`` ``right``
--------- ---------
*Availability*: PostGIS, PGRaster (Conversion) *Availability*: `PostGIS <https://postgis.net/docs/ST_Geometry_Right.html>`__,
PGRaster (Conversion)
Tests if the geometry field's bounding box is strictly to the right of the Tests if the geometry field's bounding box is strictly to the right of the
lookup geometry's bounding box. lookup geometry's bounding box.
@ -468,7 +486,8 @@ PostGIS equivalent::
``overlaps_left`` ``overlaps_left``
----------------- -----------------
*Availability*: PostGIS, PGRaster (Bilateral) *Availability*: `PostGIS <https://postgis.net/docs/ST_Geometry_Overleft.html>`__,
PGRaster (Bilateral)
Tests if the geometry field's bounding box overlaps or is to the left of the lookup Tests if the geometry field's bounding box overlaps or is to the left of the lookup
geometry's bounding box. geometry's bounding box.
@ -487,7 +506,8 @@ PostGIS equivalent::
``overlaps_right`` ``overlaps_right``
------------------ ------------------
*Availability*: PostGIS, PGRaster (Bilateral) *Availability*: `PostGIS <https://postgis.net/docs/ST_Geometry_Overright.html>`__,
PGRaster (Bilateral)
Tests if the geometry field's bounding box overlaps or is to the right of the lookup Tests if the geometry field's bounding box overlaps or is to the right of the lookup
geometry's bounding box. geometry's bounding box.
@ -505,7 +525,8 @@ PostGIS equivalent::
``overlaps_above`` ``overlaps_above``
------------------ ------------------
*Availability*: PostGIS, PGRaster (Conversion) *Availability*: `PostGIS <https://postgis.net/docs/ST_Geometry_Overabove.html>`__,
PGRaster (Conversion)
Tests if the geometry field's bounding box overlaps or is above the lookup Tests if the geometry field's bounding box overlaps or is above the lookup
geometry's bounding box. geometry's bounding box.
@ -523,7 +544,8 @@ PostGIS equivalent::
``overlaps_below`` ``overlaps_below``
------------------ ------------------
*Availability*: PostGIS, PGRaster (Conversion) *Availability*: `PostGIS <https://postgis.net/docs/ST_Geometry_Overbelow.html>`__,
PGRaster (Conversion)
Tests if the geometry field's bounding box overlaps or is below the lookup Tests if the geometry field's bounding box overlaps or is below the lookup
geometry's bounding box. geometry's bounding box.
@ -541,7 +563,8 @@ PostGIS equivalent::
``strictly_above`` ``strictly_above``
------------------ ------------------
*Availability*: PostGIS, PGRaster (Conversion) *Availability*: `PostGIS <https://postgis.net/docs/ST_Geometry_Above.html>`__,
PGRaster (Conversion)
Tests if the geometry field's bounding box is strictly above the lookup Tests if the geometry field's bounding box is strictly above the lookup
geometry's bounding box. geometry's bounding box.
@ -559,7 +582,8 @@ PostGIS equivalent::
``strictly_below`` ``strictly_below``
------------------ ------------------
*Availability*: PostGIS, PGRaster (Conversion) *Availability*: `PostGIS <https://postgis.net/docs/ST_Geometry_Below.html>`__,
PGRaster (Conversion)
Tests if the geometry field's bounding box is strictly below the lookup Tests if the geometry field's bounding box is strictly below the lookup
geometry's bounding box. geometry's bounding box.
@ -600,10 +624,12 @@ On every distance lookup except :lookup:`dwithin`, an optional element,
``'spheroid'``, may be included to use the more accurate spheroid distance ``'spheroid'``, may be included to use the more accurate spheroid distance
calculation functions on fields with a geodetic coordinate system. calculation functions on fields with a geodetic coordinate system.
On PostgreSQL, the ``'spheroid'`` option uses ``ST_Distance_Spheroid`` instead On PostgreSQL, the ``'spheroid'`` option uses `ST_DistanceSpheroid
of ``ST_Distance_Sphere``. The simpler ``ST_Distance`` function is used with <https://postgis.net/docs/ST_Distance_Spheroid.html>`__ instead of
projected coordinate systems. Rasters are converted to geometries for spheroid `ST_DistanceSphere <https://postgis.net/docs/ST_DistanceSphere.html>`__. The
based lookups. simpler `ST_Distance <https://postgis.net/docs/ST_Distance.html>`__ function is
used with projected coordinate systems. Rasters are converted to geometries for
spheroid based lookups.
.. versionadded:: 1.10 .. versionadded:: 1.10
@ -1335,7 +1361,8 @@ Example::
.. class:: Collect(geo_field) .. class:: Collect(geo_field)
*Availability*: PostGIS, SpatiaLite *Availability*: `PostGIS <https://postgis.net/docs/ST_Collect.html>`__,
SpatiaLite
Returns a ``GEOMETRYCOLLECTION`` or a ``MULTI`` geometry object from the geometry Returns a ``GEOMETRYCOLLECTION`` or a ``MULTI`` geometry object from the geometry
column. This is analogous to a simplified version of the :class:`Union` column. This is analogous to a simplified version of the :class:`Union`
@ -1348,7 +1375,8 @@ not caring about dissolving boundaries.
.. class:: Extent(geo_field) .. class:: Extent(geo_field)
*Availability*: PostGIS, Oracle, SpatiaLite *Availability*: `PostGIS <https://postgis.net/docs/ST_Extent.html>`__,
Oracle, SpatiaLite
Returns the extent of all ``geo_field`` in the ``QuerySet`` as a four-tuple, Returns the extent of all ``geo_field`` in the ``QuerySet`` as a four-tuple,
comprising the lower left coordinate and the upper right coordinate. comprising the lower left coordinate and the upper right coordinate.
@ -1364,7 +1392,7 @@ Example::
.. class:: Extent3D(geo_field) .. class:: Extent3D(geo_field)
*Availability*: PostGIS *Availability*: `PostGIS <https://postgis.net/docs/ST_3DExtent.html>`__
Returns the 3D extent of all ``geo_field`` in the ``QuerySet`` as a six-tuple, Returns the 3D extent of all ``geo_field`` in the ``QuerySet`` as a six-tuple,
comprising the lower left coordinate and upper right coordinate (each with x, y, comprising the lower left coordinate and upper right coordinate (each with x, y,
@ -1381,7 +1409,8 @@ Example::
.. class:: MakeLine(geo_field) .. class:: MakeLine(geo_field)
*Availability*: PostGIS, SpatiaLite *Availability*: `PostGIS <https://postgis.net/docs/ST_MakeLine.html>`__,
SpatiaLite
Returns a ``LineString`` constructed from the point field geometries in the Returns a ``LineString`` constructed from the point field geometries in the
``QuerySet``. Currently, ordering the queryset has no effect. ``QuerySet``. Currently, ordering the queryset has no effect.
@ -1401,7 +1430,8 @@ Example::
.. class:: Union(geo_field) .. class:: Union(geo_field)
*Availability*: PostGIS, Oracle, SpatiaLite *Availability*: `PostGIS <https://postgis.net/docs/ST_Union.html>`__,
Oracle, SpatiaLite
This method returns a :class:`~django.contrib.gis.geos.GEOSGeometry` object This method returns a :class:`~django.contrib.gis.geos.GEOSGeometry` object
comprising the union of every geometry in the queryset. Please note that use of comprising the union of every geometry in the queryset. Please note that use of
@ -1422,4 +1452,3 @@ Example::
.. [#fnde9im] *See* `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, at Ch. 2.1.13.2, p. 2-13 (The Dimensionally Extended Nine-Intersection Model). .. [#fnde9im] *See* `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, at Ch. 2.1.13.2, p. 2-13 (The Dimensionally Extended Nine-Intersection Model).
.. [#fnsdorelate] *See* `SDO_RELATE documentation <https://docs.oracle.com/database/121/SPATL/GUID-97C17C18-F05E-49B4-BE11-E89B972E2A02.htm#SPATL1039>`_, from the Oracle Spatial and Graph Developer's Guide. .. [#fnsdorelate] *See* `SDO_RELATE documentation <https://docs.oracle.com/database/121/SPATL/GUID-97C17C18-F05E-49B4-BE11-E89B972E2A02.htm#SPATL1039>`_, from the Oracle Spatial and Graph Developer's Guide.
.. [#fncovers] For an explanation of this routine, read `Quirks of the "Contains" Spatial Predicate <http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html>`_ by Martin Davis (a PostGIS developer). .. [#fncovers] For an explanation of this routine, read `Quirks of the "Contains" Spatial Predicate <http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html>`_ by Martin Davis (a PostGIS developer).
.. [#fncontainsproperly] Refer to the PostGIS ``ST_ContainsProperly`` `documentation <https://postgis.net/docs/ST_ContainsProperly.html>`_ for more details.