mirror of https://github.com/django/django.git
992 lines
29 KiB
Plaintext
992 lines
29 KiB
Plaintext
==========================
|
|
GIS QuerySet API Reference
|
|
==========================
|
|
|
|
.. currentmodule:: django.contrib.gis.db.models
|
|
|
|
.. _spatial-lookups:
|
|
|
|
Spatial Lookups
|
|
===============
|
|
|
|
The spatial lookups in this section are available for :class:`GeometryField`
|
|
and :class:`RasterField`.
|
|
|
|
For an introduction, see the :ref:`spatial lookups introduction
|
|
<spatial-lookups-intro>`. For an overview of what lookups are
|
|
compatible with a particular spatial backend, refer to the
|
|
:ref:`spatial lookup compatibility table <spatial-lookup-compatibility>`.
|
|
|
|
Lookups with rasters
|
|
--------------------
|
|
|
|
All examples in the reference below are given for geometry fields and inputs,
|
|
but the lookups can be used the same way with rasters on both sides. Whenever
|
|
a lookup doesn't support raster input, the input is automatically
|
|
converted to a geometry where necessary using the `ST_Polygon
|
|
<https://postgis.net/docs/RT_ST_Polygon.html>`_ function. See also the
|
|
:ref:`introduction to raster lookups <spatial-lookup-raster>`.
|
|
|
|
The database operators used by the lookups can be divided into three categories:
|
|
|
|
- Native raster support ``N``: the operator accepts rasters natively on both
|
|
sides of the lookup, and raster input can be mixed with geometry inputs.
|
|
|
|
- Bilateral raster support ``B``: the operator supports rasters only if both
|
|
sides of the lookup receive raster inputs. Raster data is automatically
|
|
converted to geometries for mixed lookups.
|
|
|
|
- Geometry conversion support ``C``. The lookup does not have native raster
|
|
support, all raster data is automatically converted to geometries.
|
|
|
|
The examples below show the SQL equivalent for the lookups in the different
|
|
types of raster support. The same pattern applies to all spatial lookups.
|
|
|
|
==== ============================== =======================================================
|
|
Case Lookup SQL Equivalent
|
|
==== ============================== =======================================================
|
|
N, B ``rast__contains=rst`` ``ST_Contains(rast, rst)``
|
|
N, B ``rast__1__contains=(rst, 2)`` ``ST_Contains(rast, 1, rst, 2)``
|
|
B, C ``rast__contains=geom`` ``ST_Contains(ST_Polygon(rast), geom)``
|
|
B, C ``rast__1__contains=geom`` ``ST_Contains(ST_Polygon(rast, 1), geom)``
|
|
B, C ``poly__contains=rst`` ``ST_Contains(poly, ST_Polygon(rst))``
|
|
B, C ``poly__contains=(rst, 1)`` ``ST_Contains(poly, ST_Polygon(rst, 1))``
|
|
C ``rast__crosses=rst`` ``ST_Crosses(ST_Polygon(rast), ST_Polygon(rst))``
|
|
C ``rast__1__crosses=(rst, 2)`` ``ST_Crosses(ST_Polygon(rast, 1), ST_Polygon(rst, 2))``
|
|
C ``rast__crosses=geom`` ``ST_Crosses(ST_Polygon(rast), geom)``
|
|
C ``poly__crosses=rst`` ``ST_Crosses(poly, ST_Polygon(rst))``
|
|
==== ============================== =======================================================
|
|
|
|
Spatial lookups with rasters are only supported for PostGIS backends
|
|
(denominated as PGRaster in this section).
|
|
|
|
.. fieldlookup:: bbcontains
|
|
|
|
``bbcontains``
|
|
--------------
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Geometry_Contain.html>`__,
|
|
MariaDB, MySQL, SpatiaLite, PGRaster (Native)
|
|
|
|
Tests if the geometry or raster field's bounding box completely contains the
|
|
lookup geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__bbcontains=geom)
|
|
|
|
========== ==========================
|
|
Backend SQL Equivalent
|
|
========== ==========================
|
|
PostGIS ``poly ~ geom``
|
|
MariaDB ``MBRContains(poly, geom)``
|
|
MySQL ``MBRContains(poly, geom)``
|
|
SpatiaLite ``MbrContains(poly, geom)``
|
|
========== ==========================
|
|
|
|
.. fieldlookup:: bboverlaps
|
|
|
|
``bboverlaps``
|
|
--------------
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/geometry_overlaps.html>`__,
|
|
MariaDB, MySQL, SpatiaLite, PGRaster (Native)
|
|
|
|
Tests if the geometry field's bounding box overlaps the lookup geometry's
|
|
bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__bboverlaps=geom)
|
|
|
|
========== ==========================
|
|
Backend SQL Equivalent
|
|
========== ==========================
|
|
PostGIS ``poly && geom``
|
|
MariaDB ``MBROverlaps(poly, geom)``
|
|
MySQL ``MBROverlaps(poly, geom)``
|
|
SpatiaLite ``MbrOverlaps(poly, geom)``
|
|
========== ==========================
|
|
|
|
.. fieldlookup:: contained
|
|
|
|
``contained``
|
|
-------------
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Geometry_Contained.html>`__,
|
|
MariaDB, MySQL, SpatiaLite, PGRaster (Native)
|
|
|
|
Tests if the geometry field's bounding box is completely contained by the
|
|
lookup geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__contained=geom)
|
|
|
|
========== ==========================
|
|
Backend SQL Equivalent
|
|
========== ==========================
|
|
PostGIS ``poly @ geom``
|
|
MariaDB ``MBRWithin(poly, geom)``
|
|
MySQL ``MBRWithin(poly, geom)``
|
|
SpatiaLite ``MbrWithin(poly, geom)``
|
|
========== ==========================
|
|
|
|
.. fieldlookup:: gis-contains
|
|
|
|
``contains``
|
|
------------
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Contains.html>`__,
|
|
Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)
|
|
|
|
Tests if the geometry field spatially contains the lookup geometry.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__contains=geom)
|
|
|
|
========== ============================
|
|
Backend SQL Equivalent
|
|
========== ============================
|
|
PostGIS ``ST_Contains(poly, geom)``
|
|
Oracle ``SDO_CONTAINS(poly, geom)``
|
|
MariaDB ``ST_Contains(poly, geom)``
|
|
MySQL ``ST_Contains(poly, geom)``
|
|
SpatiaLite ``Contains(poly, geom)``
|
|
========== ============================
|
|
|
|
.. versionchanged:: 3.0
|
|
|
|
In older versions, MySQL uses ``MBRContains`` and operates only on bounding
|
|
boxes.
|
|
|
|
.. fieldlookup:: contains_properly
|
|
|
|
``contains_properly``
|
|
---------------------
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_ContainsProperly.html>`__,
|
|
PGRaster (Bilateral)
|
|
|
|
Returns true if the lookup geometry intersects the interior of the
|
|
geometry field, but not the boundary (or exterior).
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__contains_properly=geom)
|
|
|
|
========== ===================================
|
|
Backend SQL Equivalent
|
|
========== ===================================
|
|
PostGIS ``ST_ContainsProperly(poly, geom)``
|
|
========== ===================================
|
|
|
|
.. fieldlookup:: coveredby
|
|
|
|
``coveredby``
|
|
-------------
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_CoveredBy.html>`__,
|
|
Oracle, PGRaster (Bilateral), SpatiaLite
|
|
|
|
Tests if no point in the geometry field is outside the lookup geometry.
|
|
[#fncovers]_
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__coveredby=geom)
|
|
|
|
========== =============================
|
|
Backend SQL Equivalent
|
|
========== =============================
|
|
PostGIS ``ST_CoveredBy(poly, geom)``
|
|
Oracle ``SDO_COVEREDBY(poly, geom)``
|
|
SpatiaLite ``CoveredBy(poly, geom)``
|
|
========== =============================
|
|
|
|
.. fieldlookup:: covers
|
|
|
|
``covers``
|
|
----------
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Covers.html>`__,
|
|
Oracle, PGRaster (Bilateral), SpatiaLite
|
|
|
|
Tests if no point in the lookup geometry is outside the geometry field.
|
|
[#fncovers]_
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__covers=geom)
|
|
|
|
========== ==========================
|
|
Backend SQL Equivalent
|
|
========== ==========================
|
|
PostGIS ``ST_Covers(poly, geom)``
|
|
Oracle ``SDO_COVERS(poly, geom)``
|
|
SpatiaLite ``Covers(poly, geom)``
|
|
========== ==========================
|
|
|
|
.. fieldlookup:: crosses
|
|
|
|
``crosses``
|
|
-----------
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Crosses.html>`__,
|
|
MariaDB, MySQL, SpatiaLite, PGRaster (Conversion)
|
|
|
|
Tests if the geometry field spatially crosses the lookup geometry.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__crosses=geom)
|
|
|
|
========== ==========================
|
|
Backend SQL Equivalent
|
|
========== ==========================
|
|
PostGIS ``ST_Crosses(poly, geom)``
|
|
MariaDB ``ST_Crosses(poly, geom)``
|
|
MySQL ``ST_Crosses(poly, geom)``
|
|
SpatiaLite ``Crosses(poly, geom)``
|
|
========== ==========================
|
|
|
|
.. versionchanged:: 3.0
|
|
|
|
MySQL support was added.
|
|
|
|
.. fieldlookup:: disjoint
|
|
|
|
``disjoint``
|
|
------------
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Disjoint.html>`__,
|
|
Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)
|
|
|
|
Tests if the geometry field is spatially disjoint from the lookup geometry.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__disjoint=geom)
|
|
|
|
========== =================================================
|
|
Backend SQL Equivalent
|
|
========== =================================================
|
|
PostGIS ``ST_Disjoint(poly, geom)``
|
|
Oracle ``SDO_GEOM.RELATE(poly, 'DISJOINT', geom, 0.05)``
|
|
MariaDB ``ST_Disjoint(poly, geom)``
|
|
MySQL ``ST_Disjoint(poly, geom)``
|
|
SpatiaLite ``Disjoint(poly, geom)``
|
|
========== =================================================
|
|
|
|
.. versionchanged:: 3.0
|
|
|
|
In older versions, MySQL uses ``MBRDisjoint`` and operates only on bounding
|
|
boxes.
|
|
|
|
.. fieldlookup:: equals
|
|
|
|
``equals``
|
|
----------
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Equals.html>`__,
|
|
Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Conversion)
|
|
|
|
Tests if the geometry field is spatially equal to the lookup geometry.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__equals=geom)
|
|
|
|
========== =================================================
|
|
Backend SQL Equivalent
|
|
========== =================================================
|
|
PostGIS ``ST_Equals(poly, geom)``
|
|
Oracle ``SDO_EQUAL(poly, geom)``
|
|
MariaDB ``ST_Equals(poly, geom)``
|
|
MySQL ``ST_Equals(poly, geom)``
|
|
SpatiaLite ``Equals(poly, geom)``
|
|
========== =================================================
|
|
|
|
.. versionchanged:: 3.0
|
|
|
|
In older versions, MySQL uses ``MBREquals`` and operates only on bounding
|
|
boxes.
|
|
|
|
.. fieldlookup:: exact
|
|
:noindex:
|
|
.. fieldlookup:: same_as
|
|
|
|
``exact``, ``same_as``
|
|
----------------------
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Geometry_Same.html>`__,
|
|
Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)
|
|
|
|
Tests if the geometry field is "equal" to the lookup geometry. On Oracle,
|
|
MySQL, and SpatiaLite, it tests spatial equality, while on PostGIS it tests
|
|
equality of bounding boxes.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly=geom)
|
|
|
|
========== =================================================
|
|
Backend SQL Equivalent
|
|
========== =================================================
|
|
PostGIS ``poly ~= geom``
|
|
Oracle ``SDO_EQUAL(poly, geom)``
|
|
MariaDB ``ST_Equals(poly, geom)``
|
|
MySQL ``ST_Equals(poly, geom)``
|
|
SpatiaLite ``Equals(poly, geom)``
|
|
========== =================================================
|
|
|
|
.. versionchanged:: 3.0
|
|
|
|
In older versions, MySQL uses ``MBREquals`` and operates only on bounding
|
|
boxes.
|
|
|
|
.. fieldlookup:: intersects
|
|
|
|
``intersects``
|
|
--------------
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Intersects.html>`__,
|
|
Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)
|
|
|
|
Tests if the geometry field spatially intersects the lookup geometry.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__intersects=geom)
|
|
|
|
========== =================================================
|
|
Backend SQL Equivalent
|
|
========== =================================================
|
|
PostGIS ``ST_Intersects(poly, geom)``
|
|
Oracle ``SDO_OVERLAPBDYINTERSECT(poly, geom)``
|
|
MariaDB ``ST_Intersects(poly, geom)``
|
|
MySQL ``ST_Intersects(poly, geom)``
|
|
SpatiaLite ``Intersects(poly, geom)``
|
|
========== =================================================
|
|
|
|
.. versionchanged:: 3.0
|
|
|
|
In older versions, MySQL uses ``MBRIntersects`` and operates only on
|
|
bounding boxes.
|
|
|
|
.. fieldlookup:: isvalid
|
|
|
|
``isvalid``
|
|
-----------
|
|
|
|
*Availability*: MySQL (≥ 5.7.5), `PostGIS
|
|
<https://postgis.net/docs/ST_IsValid.html>`__, Oracle, SpatiaLite
|
|
|
|
Tests if the geometry is valid.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__isvalid=True)
|
|
|
|
========================== ================================================================
|
|
Backend SQL Equivalent
|
|
========================== ================================================================
|
|
MySQL, PostGIS, SpatiaLite ``ST_IsValid(poly)``
|
|
Oracle ``SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT(poly, 0.05) = 'TRUE'``
|
|
========================== ================================================================
|
|
|
|
.. fieldlookup:: overlaps
|
|
|
|
``overlaps``
|
|
------------
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Overlaps.html>`__,
|
|
Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)
|
|
|
|
Tests if the geometry field spatially overlaps the lookup geometry.
|
|
|
|
========== ============================
|
|
Backend SQL Equivalent
|
|
========== ============================
|
|
PostGIS ``ST_Overlaps(poly, geom)``
|
|
Oracle ``SDO_OVERLAPS(poly, geom)``
|
|
MariaDB ``ST_Overlaps(poly, geom)``
|
|
MySQL ``ST_Overlaps(poly, geom)``
|
|
SpatiaLite ``Overlaps(poly, geom)``
|
|
========== ============================
|
|
|
|
.. versionchanged:: 3.0
|
|
|
|
In older versions, MySQL uses ``MBROverlaps`` and operates only on bounding
|
|
boxes.
|
|
|
|
.. fieldlookup:: relate
|
|
|
|
``relate``
|
|
----------
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Relate.html>`__,
|
|
MariaDB, Oracle, SpatiaLite, PGRaster (Conversion)
|
|
|
|
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,
|
|
``(geom, pattern)``; the form of ``pattern`` will depend on the spatial backend:
|
|
|
|
MariaDB, PostGIS, and SpatiaLite
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
On these spatial backends the intersection pattern is a string comprising
|
|
nine characters, which define intersections between the interior, boundary,
|
|
and exterior of the geometry field and the lookup geometry.
|
|
The intersection pattern matrix may only use the following characters:
|
|
``1``, ``2``, ``T``, ``F``, or ``*``. This lookup type allows users to "fine tune"
|
|
a specific geometric relationship consistent with the DE-9IM model. [#fnde9im]_
|
|
|
|
Geometry example::
|
|
|
|
# A tuple lookup parameter is used to specify the geometry and
|
|
# the intersection pattern (the pattern here is for 'contains').
|
|
Zipcode.objects.filter(poly__relate=(geom, 'T*T***FF*'))
|
|
|
|
PostGIS and MariaDB SQL equivalent:
|
|
|
|
.. code-block:: sql
|
|
|
|
SELECT ... WHERE ST_Relate(poly, geom, 'T*T***FF*')
|
|
|
|
SpatiaLite SQL equivalent:
|
|
|
|
.. code-block:: sql
|
|
|
|
SELECT ... WHERE Relate(poly, geom, 'T*T***FF*')
|
|
|
|
Raster example::
|
|
|
|
Zipcode.objects.filter(poly__relate=(rast, 1, 'T*T***FF*'))
|
|
Zipcode.objects.filter(rast__2__relate=(rast, 1, 'T*T***FF*'))
|
|
|
|
PostGIS SQL equivalent:
|
|
|
|
.. code-block:: sql
|
|
|
|
SELECT ... WHERE ST_Relate(poly, ST_Polygon(rast, 1), 'T*T***FF*')
|
|
SELECT ... WHERE ST_Relate(ST_Polygon(rast, 2), ST_Polygon(rast, 1), 'T*T***FF*')
|
|
|
|
.. versionchanged:: 3.1
|
|
|
|
MariaDB support was added.
|
|
|
|
Oracle
|
|
~~~~~~
|
|
|
|
Here the relation pattern is comprised of at least one of the nine relation
|
|
strings: ``TOUCH``, ``OVERLAPBDYDISJOINT``, ``OVERLAPBDYINTERSECT``,
|
|
``EQUAL``, ``INSIDE``, ``COVEREDBY``, ``CONTAINS``, ``COVERS``, ``ON``, and
|
|
``ANYINTERACT``. Multiple strings may be combined with the logical Boolean
|
|
operator OR, for example, ``'inside+touch'``. [#fnsdorelate]_ The relation
|
|
strings are case-insensitive.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__relate=(geom, 'anyinteract'))
|
|
|
|
Oracle SQL equivalent:
|
|
|
|
.. code-block:: sql
|
|
|
|
SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract')
|
|
|
|
.. fieldlookup:: touches
|
|
|
|
``touches``
|
|
-----------
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Touches.html>`__,
|
|
Oracle, MariaDB, MySQL, SpatiaLite
|
|
|
|
Tests if the geometry field spatially touches the lookup geometry.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__touches=geom)
|
|
|
|
========== ==========================
|
|
Backend SQL Equivalent
|
|
========== ==========================
|
|
PostGIS ``ST_Touches(poly, geom)``
|
|
MariaDB ``ST_Touches(poly, geom)``
|
|
MySQL ``ST_Touches(poly, geom)``
|
|
Oracle ``SDO_TOUCH(poly, geom)``
|
|
SpatiaLite ``Touches(poly, geom)``
|
|
========== ==========================
|
|
|
|
.. versionchanged:: 3.0
|
|
|
|
In older versions, MySQL uses ``MBRTouches`` and operates only on bounding
|
|
boxes.
|
|
|
|
.. fieldlookup:: within
|
|
|
|
``within``
|
|
----------
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Within.html>`__,
|
|
Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)
|
|
|
|
Tests if the geometry field is spatially within the lookup geometry.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__within=geom)
|
|
|
|
========== ==========================
|
|
Backend SQL Equivalent
|
|
========== ==========================
|
|
PostGIS ``ST_Within(poly, geom)``
|
|
MariaDB ``ST_Within(poly, geom)``
|
|
MySQL ``ST_Within(poly, geom)``
|
|
Oracle ``SDO_INSIDE(poly, geom)``
|
|
SpatiaLite ``Within(poly, geom)``
|
|
========== ==========================
|
|
|
|
.. versionchanged:: 3.0
|
|
|
|
In older versions, MySQL uses ``MBRWithin`` and operates only on bounding
|
|
boxes.
|
|
|
|
.. fieldlookup:: left
|
|
|
|
``left``
|
|
--------
|
|
|
|
*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
|
|
lookup geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__left=geom)
|
|
|
|
PostGIS equivalent:
|
|
|
|
.. code-block:: sql
|
|
|
|
SELECT ... WHERE poly << geom
|
|
|
|
.. fieldlookup:: right
|
|
|
|
``right``
|
|
---------
|
|
|
|
*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
|
|
lookup geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__right=geom)
|
|
|
|
PostGIS equivalent:
|
|
|
|
.. code-block:: sql
|
|
|
|
SELECT ... WHERE poly >> geom
|
|
|
|
.. fieldlookup:: overlaps_left
|
|
|
|
``overlaps_left``
|
|
-----------------
|
|
|
|
*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
|
|
geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__overlaps_left=geom)
|
|
|
|
PostGIS equivalent:
|
|
|
|
.. code-block:: sql
|
|
|
|
SELECT ... WHERE poly &< geom
|
|
|
|
|
|
.. fieldlookup:: overlaps_right
|
|
|
|
``overlaps_right``
|
|
------------------
|
|
|
|
*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
|
|
geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__overlaps_right=geom)
|
|
|
|
PostGIS equivalent:
|
|
|
|
.. code-block:: sql
|
|
|
|
SELECT ... WHERE poly &> geom
|
|
|
|
.. fieldlookup:: overlaps_above
|
|
|
|
``overlaps_above``
|
|
------------------
|
|
|
|
*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
|
|
geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__overlaps_above=geom)
|
|
|
|
PostGIS equivalent:
|
|
|
|
.. code-block:: sql
|
|
|
|
SELECT ... WHERE poly |&> geom
|
|
|
|
.. fieldlookup:: overlaps_below
|
|
|
|
``overlaps_below``
|
|
------------------
|
|
|
|
*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
|
|
geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__overlaps_below=geom)
|
|
|
|
PostGIS equivalent:
|
|
|
|
.. code-block:: sql
|
|
|
|
SELECT ... WHERE poly &<| geom
|
|
|
|
.. fieldlookup:: strictly_above
|
|
|
|
``strictly_above``
|
|
------------------
|
|
|
|
*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
|
|
geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__strictly_above=geom)
|
|
|
|
PostGIS equivalent:
|
|
|
|
.. code-block:: sql
|
|
|
|
SELECT ... WHERE poly |>> geom
|
|
|
|
.. fieldlookup:: strictly_below
|
|
|
|
``strictly_below``
|
|
------------------
|
|
|
|
*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
|
|
geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__strictly_below=geom)
|
|
|
|
PostGIS equivalent:
|
|
|
|
.. code-block:: sql
|
|
|
|
SELECT ... WHERE poly <<| geom
|
|
|
|
|
|
.. _distance-lookups:
|
|
|
|
Distance Lookups
|
|
================
|
|
|
|
*Availability*: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Native)
|
|
|
|
For an overview on performing distance queries, please refer to
|
|
the :ref:`distance queries introduction <distance-queries>`.
|
|
|
|
Distance lookups take the following form::
|
|
|
|
<field>__<distance lookup>=(<geometry/raster>, <distance value>[, 'spheroid'])
|
|
<field>__<distance lookup>=(<raster>, <band_index>, <distance value>[, 'spheroid'])
|
|
<field>__<band_index>__<distance lookup>=(<raster>, <band_index>, <distance value>[, 'spheroid'])
|
|
|
|
The value passed into a distance lookup is a tuple; the first two
|
|
values are mandatory, and are the geometry to calculate distances to,
|
|
and a distance value (either a number in units of the field, a
|
|
:class:`~django.contrib.gis.measure.Distance` object, or a :doc:`query
|
|
expression </ref/models/expressions>`). To pass a band index to the lookup, use
|
|
a 3-tuple where the second entry is the band index.
|
|
|
|
On every distance lookup except :lookup:`dwithin`, an optional element,
|
|
``'spheroid'``, may be included to use the more accurate spheroid distance
|
|
calculation functions on fields with a geodetic coordinate system.
|
|
|
|
On PostgreSQL, the ``'spheroid'`` option uses `ST_DistanceSpheroid
|
|
<https://postgis.net/docs/ST_Distance_Spheroid.html>`__ instead of
|
|
`ST_DistanceSphere <https://postgis.net/docs/ST_DistanceSphere.html>`__. The
|
|
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.
|
|
|
|
.. fieldlookup:: distance_gt
|
|
|
|
``distance_gt``
|
|
---------------
|
|
|
|
Returns models where the distance to the geometry field from the lookup
|
|
geometry is greater than the given distance value.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__distance_gt=(geom, D(m=5)))
|
|
|
|
========== ==================================================
|
|
Backend SQL Equivalent
|
|
========== ==================================================
|
|
PostGIS ``ST_Distance/ST_Distance_Sphere(poly, geom) > 5``
|
|
MariaDB ``ST_Distance(poly, geom) > 5``
|
|
MySQL ``ST_Distance(poly, geom) > 5``
|
|
Oracle ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) > 5``
|
|
SpatiaLite ``Distance(poly, geom) > 5``
|
|
========== ==================================================
|
|
|
|
.. fieldlookup:: distance_gte
|
|
|
|
``distance_gte``
|
|
----------------
|
|
|
|
Returns models where the distance to the geometry field from the lookup
|
|
geometry is greater than or equal to the given distance value.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__distance_gte=(geom, D(m=5)))
|
|
|
|
========== ===================================================
|
|
Backend SQL Equivalent
|
|
========== ===================================================
|
|
PostGIS ``ST_Distance/ST_Distance_Sphere(poly, geom) >= 5``
|
|
MariaDB ``ST_Distance(poly, geom) >= 5``
|
|
MySQL ``ST_Distance(poly, geom) >= 5``
|
|
Oracle ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) >= 5``
|
|
SpatiaLite ``Distance(poly, geom) >= 5``
|
|
========== ===================================================
|
|
|
|
.. fieldlookup:: distance_lt
|
|
|
|
``distance_lt``
|
|
---------------
|
|
|
|
Returns models where the distance to the geometry field from the lookup
|
|
geometry is less than the given distance value.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__distance_lt=(geom, D(m=5)))
|
|
|
|
========== ==================================================
|
|
Backend SQL Equivalent
|
|
========== ==================================================
|
|
PostGIS ``ST_Distance/ST_Distance_Sphere(poly, geom) < 5``
|
|
MariaDB ``ST_Distance(poly, geom) < 5``
|
|
MySQL ``ST_Distance(poly, geom) < 5``
|
|
Oracle ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) < 5``
|
|
SpatiaLite ``Distance(poly, geom) < 5``
|
|
========== ==================================================
|
|
|
|
.. fieldlookup:: distance_lte
|
|
|
|
``distance_lte``
|
|
----------------
|
|
|
|
Returns models where the distance to the geometry field from the lookup
|
|
geometry is less than or equal to the given distance value.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__distance_lte=(geom, D(m=5)))
|
|
|
|
========== ===================================================
|
|
Backend SQL Equivalent
|
|
========== ===================================================
|
|
PostGIS ``ST_Distance/ST_Distance_Sphere(poly, geom) <= 5``
|
|
MariaDB ``ST_Distance(poly, geom) <= 5``
|
|
MySQL ``ST_Distance(poly, geom) <= 5``
|
|
Oracle ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) <= 5``
|
|
SpatiaLite ``Distance(poly, geom) <= 5``
|
|
========== ===================================================
|
|
|
|
.. fieldlookup:: dwithin
|
|
|
|
``dwithin``
|
|
-----------
|
|
|
|
Returns models where the distance to the geometry field from the lookup
|
|
geometry are within the given distance from one another. Note that you can only
|
|
provide :class:`~django.contrib.gis.measure.Distance` objects if the targeted
|
|
geometries are in a projected system. For geographic geometries, you should use
|
|
units of the geometry field (e.g. degrees for ``WGS84``) .
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__dwithin=(geom, D(m=5)))
|
|
|
|
========== ======================================
|
|
Backend SQL Equivalent
|
|
========== ======================================
|
|
PostGIS ``ST_DWithin(poly, geom, 5)``
|
|
Oracle ``SDO_WITHIN_DISTANCE(poly, geom, 5)``
|
|
SpatiaLite ``PtDistWithin(poly, geom, 5)``
|
|
========== ======================================
|
|
|
|
Aggregate Functions
|
|
-------------------
|
|
|
|
Django provides some GIS-specific aggregate functions. For details on how to
|
|
use these aggregate functions, see :doc:`the topic guide on aggregation
|
|
</topics/db/aggregation>`.
|
|
|
|
===================== =====================================================
|
|
Keyword Argument Description
|
|
===================== =====================================================
|
|
``tolerance`` This keyword is for Oracle only. It is for the
|
|
tolerance value used by the ``SDOAGGRTYPE``
|
|
procedure; the `Oracle documentation`__ has more
|
|
details.
|
|
===================== =====================================================
|
|
|
|
__ https://docs.oracle.com/en/database/oracle/oracle-database/18/spatl/
|
|
spatial-concepts.html#GUID-CE10AB14-D5EA-43BA-A647-DAC9EEF41EE6
|
|
|
|
Example::
|
|
|
|
>>> from django.contrib.gis.db.models import Extent, Union
|
|
>>> WorldBorder.objects.aggregate(Extent('mpoly'), Union('mpoly'))
|
|
|
|
``Collect``
|
|
~~~~~~~~~~~
|
|
|
|
.. class:: Collect(geo_field)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Collect.html>`__,
|
|
SpatiaLite
|
|
|
|
Returns a ``GEOMETRYCOLLECTION`` or a ``MULTI`` geometry object from the geometry
|
|
column. This is analogous to a simplified version of the :class:`Union`
|
|
aggregate, except it can be several orders of magnitude faster than performing
|
|
a union because it rolls up geometries into a collection or multi object, not
|
|
caring about dissolving boundaries.
|
|
|
|
``Extent``
|
|
~~~~~~~~~~
|
|
|
|
.. class:: Extent(geo_field)
|
|
|
|
*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,
|
|
comprising the lower left coordinate and the upper right coordinate.
|
|
|
|
Example::
|
|
|
|
>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(Extent('poly'))
|
|
>>> print(qs['poly__extent'])
|
|
(-96.8016128540039, 29.7633724212646, -95.3631439208984, 32.782058715820)
|
|
|
|
``Extent3D``
|
|
~~~~~~~~~~~~
|
|
|
|
.. class:: Extent3D(geo_field)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_3DExtent.html>`__
|
|
|
|
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,
|
|
and z coordinates).
|
|
|
|
Example::
|
|
|
|
>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(Extent3D('poly'))
|
|
>>> print(qs['poly__extent3d'])
|
|
(-96.8016128540039, 29.7633724212646, 0, -95.3631439208984, 32.782058715820, 0)
|
|
|
|
``MakeLine``
|
|
~~~~~~~~~~~~
|
|
|
|
.. class:: MakeLine(geo_field)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_MakeLine.html>`__,
|
|
SpatiaLite
|
|
|
|
Returns a ``LineString`` constructed from the point field geometries in the
|
|
``QuerySet``. Currently, ordering the queryset has no effect.
|
|
|
|
Example::
|
|
|
|
>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(MakeLine('poly'))
|
|
>>> print(qs['poly__makeline'])
|
|
LINESTRING (-95.3631510000000020 29.7633739999999989, -96.8016109999999941 32.7820570000000018)
|
|
|
|
``Union``
|
|
~~~~~~~~~
|
|
|
|
.. class:: Union(geo_field)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Union.html>`__,
|
|
Oracle, SpatiaLite
|
|
|
|
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
|
|
``Union`` is processor intensive and may take a significant amount of time on
|
|
large querysets.
|
|
|
|
.. note::
|
|
|
|
If the computation time for using this method is too expensive, consider
|
|
using :class:`Collect` instead.
|
|
|
|
Example::
|
|
|
|
>>> u = Zipcode.objects.aggregate(Union(poly)) # This may take a long time.
|
|
>>> u = Zipcode.objects.filter(poly__within=bbox).aggregate(Union(poly)) # A more sensible approach.
|
|
|
|
.. rubric:: Footnotes
|
|
.. [#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/en/
|
|
database/oracle/oracle-database/18/spatl/spatial-operators-reference.html#
|
|
GUID-97C17C18-F05E-49B4-BE11-E89B972E2A02>`_, from the Oracle Spatial and
|
|
Graph Developer's Guide.
|
|
.. [#fncovers] For an explanation of this routine, read `Quirks of the "Contains" Spatial Predicate <https://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html>`_ by Martin Davis (a PostGIS developer).
|