.. _ref-geoquerysets:

=========================

GeoQuerySet API Reference

=========================

.. currentmodule:: django.contrib.gis.db.models

.. class:: GeoQuerySet([model=None])

.. _spatial-lookups:

Spatial Lookups

===============

Just like when using the the :ref:`queryset-api`, interaction

with ``GeoQuerySet`` by :ref:`chaining filters <chaining-filters>`.

Instead of the regular Django :ref:`field-lookups`, the

spatial lookups in this section are available for :class:`GeometryField`.

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

.. fieldlookup:: bbcontains

bbcontains

----------

*Availability*: PostGIS, MySQL, SpatiaLite

Tests if the geometry 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``

MySQL       ``MBRContains(poly, geom)``

SpatiaLite  ``MbrContains(poly, geom)``

==========  ==========================

.. fieldlookup:: bboverlaps

bboverlaps

----------

*Availability*: PostGIS, MySQL, SpatiaLite

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``

MySQL       ``MBROverlaps(poly, geom)``

SpatiaLite  ``MbrOverlaps(poly, geom)``

==========  ==========================

.. fieldlookup:: contained

contained

---------

*Availability*: PostGIS, MySQL, SpatiaLite

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``

MySQL       ``MBRWithin(poly, geom)``

SpatiaLite  ``MbrWithin(poly, geom)``

==========  ==========================

.. fieldlookup:: gis-contains

contains

--------

*Availability*: PostGIS, Oracle, MySQL, SpatiaLite

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)``

MySQL       ``MBRContains(poly, geom)``

SpatiaLite  ``Contains(poly, geom)``

==========  ============================

.. fieldlookup:: contains_properly

contains_properly

-----------------

.. versionadded:: 1.2

*Availability*: PostGIS

Returns true if the lookup geometry intersects the interior of the

geometry field, but not the boundary (or exterior). [#fncontainsproperly]_

.. note::

    Requires PostGIS 1.4 and above.

Example::

    Zipcode.objects.filter(poly__contains_properly=geom)

==========  ===================================

Backend     SQL Equivalent

==========  ===================================

PostGIS     ``ST_ContainsProperly(poly, geom)``

==========  ===================================

.. fieldlookup:: coveredby

coveredby

---------

*Availability*: PostGIS, Oracle

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)``

==========  =============================

.. fieldlookup:: covers

covers

------

*Availability*: PostGIS, Oracle

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)``

==========  ==========================

.. fieldlookup:: crosses

crosses

-------

*Availability*: PostGIS, SpatiaLite

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)``

SpatiaLite  ``Crosses(poly, geom)``

==========  ==========================

.. fieldlookup:: disjoint

disjoint

--------

*Availability*: PostGIS, Oracle, MySQL, SpatiaLite

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)``

MySQL       ``MBRDisjoint(poly, geom)``

SpatiaLite  ``Disjoint(poly, geom)``

==========  =================================================

equals

------

*Availability*: PostGIS, Oracle, MySQL, SpatiaLite

.. fieldlookup:: exact

.. fieldlookup:: same_as

exact, same_as

--------------

*Availability*: PostGIS, Oracle, MySQL, SpatiaLite

.. fieldlookup:: intersects

intersects

----------

*Availability*: PostGIS, Oracle, MySQL, SpatiaLite

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)``

MySQL       ``MBRIntersects(poly, geom)``

SpatiaLite  ``Intersects(poly, geom)``

==========  =================================================

.. fieldlookup:: overlaps

overlaps

--------

*Availability*: PostGIS, Oracle, MySQL, SpatiaLite

.. fieldlookup:: relate

relate

------

*Availability*: PostGIS, Oracle, SpatiaLite

Tests if the geometry field is spatially related to the 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:

PostGIS & 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]_

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 SQL equivalent::

    SELECT ... WHERE ST_Relate(poly, geom, 'T*T***FF*')

SpatiaLite SQL equivalent::

    SELECT ... WHERE Relate(poly, geom, 'T*T***FF*')

Oracle

~~~~~~

Here the relation pattern is compreised 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::

    SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract')

.. fieldlookup:: touches

touches

-------

*Availability*: PostGIS, Oracle, 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)``

MySQL       ``MBRTouches(poly, geom)``

Oracle      ``SDO_TOUCH(poly, geom)``

SpatiaLite  ``Touches(poly, geom)``

==========  ==========================

.. fieldlookup:: within

within

------

*Availability*: PostGIS, Oracle, MySQL, SpatiaLite

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)``

MySQL       ``MBRWithin(poly, geom)``

Oracle      ``SDO_INSIDE(poly, geom)``

SpatiaLite  ``Within(poly, geom)``

==========  ==========================

.. fieldlookup:: left

left

----

*Availability*: PostGIS

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::

    SELECT ... WHERE poly << geom

.. fieldlookup:: right

right

-----

*Availability*: PostGIS

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::

    SELECT ... WHERE poly >> geom

.. fieldlookup:: overlaps_left

overlaps_left

-------------

*Availability*: PostGIS

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::

    SELECT ... WHERE poly &< geom

.. fieldlookup:: overlaps_right

overlaps_right

--------------

*Availability*: PostGIS

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::

    SELECT ... WHERE poly &> geom

.. fieldlookup:: overlaps_above

overlaps_above

--------------

*Availability*: PostGIS

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::

    SELECT ... WHERE poly |&> geom

.. fieldlookup:: overlaps_below

overlaps_below

--------------

*Availability*: PostGIS

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::

    SELECT ... WHERE poly &<| geom

.. fieldlookup:: strictly_above

strictly_above

--------------

*Availability*: PostGIS

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::

    SELECT ... WHERE poly |>> geom

.. fieldlookup:: strictly_below

strictly_below

--------------

*Availability*: PostGIS

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::

    SELECT ... WHERE poly |>> geom

.. _distance-lookups:

Distance Lookups

================

*Availability*: PostGIS, Oracle, SpatiaLite

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>, <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 or a

:class:`~django.contrib.gis.measure.Distance` object).  On every

distance lookup but :lookup:`dwithin`, an optional

third element, ``'spheroid'``, may be included to tell GeoDjango

to use the more accurate spheroid distance calculation functions on