<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>GeoQuerySet API Reference — Django 1.11.20 documentation</title>
<link rel="stylesheet" href="../../../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../../../" src="../../../_static/documentation_options.js"></script>
<script type="text/javascript" src="../../../_static/jquery.js"></script>
<script type="text/javascript" src="../../../_static/underscore.js"></script>
<script type="text/javascript" src="../../../_static/doctools.js"></script>
<script type="text/javascript" src="../../../_static/language_data.js"></script>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Geographic Database Functions" href="functions.html" />
<link rel="prev" title="GeoDjango Forms API" href="forms-api.html" />
<script type="text/javascript" src="../../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../../templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head><body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../../../index.html">Django 1.11.20 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../../../index.html">Home</a> |
<a title="Table of contents" href="../../../contents.html">Table of contents</a> |
<a title="Global index" href="../../../genindex.html">Index</a> |
<a title="Module index" href="../../../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="forms-api.html" title="GeoDjango Forms API">previous</a>
|
<a href="../../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="functions.html" title="Geographic Database Functions">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="ref-contrib-gis-geoquerysets">
<div class="section" id="s-geoqueryset-api-reference">
<span id="geoqueryset-api-reference"></span><h1>GeoQuerySet API Reference<a class="headerlink" href="#geoqueryset-api-reference" title="Permalink to this headline">¶</a></h1>
<dl class="class">
<dt id="django.contrib.gis.db.models.GeoQuerySet">
<em class="property">class </em><code class="descname">GeoQuerySet</code>(<em>model=None</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="section" id="s-spatial-lookups">
<span id="s-id1"></span><span id="spatial-lookups"></span><span id="id1"></span><h2>Spatial Lookups<a class="headerlink" href="#spatial-lookups" title="Permalink to this headline">¶</a></h2>
<p>The spatial lookups in this section are available for <a class="reference internal" href="model-api.html#django.contrib.gis.db.models.GeometryField" title="django.contrib.gis.db.models.GeometryField"><code class="xref py py-class docutils literal notranslate"><span class="pre">GeometryField</span></code></a>
and <a class="reference internal" href="model-api.html#django.contrib.gis.db.models.RasterField" title="django.contrib.gis.db.models.RasterField"><code class="xref py py-class docutils literal notranslate"><span class="pre">RasterField</span></code></a>.</p>
<p>For an introduction, see the <a class="reference internal" href="db-api.html#spatial-lookups-intro"><span class="std std-ref">spatial lookups introduction</span></a>. For an overview of what lookups are
compatible with a particular spatial backend, refer to the
<a class="reference internal" href="db-api.html#spatial-lookup-compatibility"><span class="std std-ref">spatial lookup compatibility table</span></a>.</p>
<div class="versionchanged">
<span class="title">Changed in Django 1.10:</span> <p>Spatial lookups now support raster input.</p>
</div>
<div class="section" id="s-lookups-with-rasters">
<span id="lookups-with-rasters"></span><h3>Lookups with rasters<a class="headerlink" href="#lookups-with-rasters" title="Permalink to this headline">¶</a></h3>
<p>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 <a class="reference external" href="https://postgis.net/docs/RT_ST_Polygon.html">ST_Polygon</a> function. See also the
<a class="reference internal" href="db-api.html#spatial-lookup-raster"><span class="std std-ref">introduction to raster lookups</span></a>.</p>
<p>The database operators used by the lookups can be divided into three categories:</p>
<ul class="simple">
<li>Native raster support <code class="docutils literal notranslate"><span class="pre">N</span></code>: the operator accepts rasters natively on both
sides of the lookup, and raster input can be mixed with geometry inputs.</li>
<li>Bilateral raster support <code class="docutils literal notranslate"><span class="pre">B</span></code>: the operator supports rasters only if both
sides of the lookup receive raster inputs. Raster data is automatically
converted to geometries for mixed lookups.</li>
<li>Geometry conversion support <code class="docutils literal notranslate"><span class="pre">C</span></code>. The lookup does not have native raster
support, all raster data is automatically converted to geometries.</li>
</ul>
<p>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.</p>
<table class="docutils">
<colgroup>
<col width="4%" />
<col width="34%" />
<col width="62%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Case</th>
<th class="head">Lookup</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>N, B</td>
<td><code class="docutils literal notranslate"><span class="pre">rast__contains=rst</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Contains(rast,</span> <span class="pre">rst)</span></code></td>
</tr>
<tr class="row-odd"><td>N, B</td>
<td><code class="docutils literal notranslate"><span class="pre">rast__1__contains=(rst,</span> <span class="pre">2)</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Contains(rast,</span> <span class="pre">1,</span> <span class="pre">rst,</span> <span class="pre">2)</span></code></td>
</tr>
<tr class="row-even"><td>B, C</td>
<td><code class="docutils literal notranslate"><span class="pre">rast__contains=geom</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Contains(ST_Polygon(rast),</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-odd"><td>B, C</td>
<td><code class="docutils literal notranslate"><span class="pre">rast__1__contains=geom</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Contains(ST_Polygon(rast,</span> <span class="pre">1),</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-even"><td>B, C</td>
<td><code class="docutils literal notranslate"><span class="pre">poly__contains=rst</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Contains(poly,</span> <span class="pre">ST_Polygon(rst))</span></code></td>
</tr>
<tr class="row-odd"><td>B, C</td>
<td><code class="docutils literal notranslate"><span class="pre">poly__contains=(rst,</span> <span class="pre">1)</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Contains(poly,</span> <span class="pre">ST_Polygon(rst,</span> <span class="pre">1))</span></code></td>
</tr>
<tr class="row-even"><td>C</td>
<td><code class="docutils literal notranslate"><span class="pre">rast__crosses=rst</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Crosses(ST_Polygon(rast),</span> <span class="pre">ST_Polygon(rst))</span></code></td>
</tr>
<tr class="row-odd"><td>C</td>
<td><code class="docutils literal notranslate"><span class="pre">rast__1__crosses=(rst,</span> <span class="pre">2)</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Crosses(ST_Polygon(rast,</span> <span class="pre">1),</span> <span class="pre">ST_Polygon(rst,</span> <span class="pre">2))</span></code></td>
</tr>
<tr class="row-even"><td>C</td>
<td><code class="docutils literal notranslate"><span class="pre">rast__crosses=geom</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Crosses(ST_Polygon(rast),</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-odd"><td>C</td>
<td><code class="docutils literal notranslate"><span class="pre">poly__crosses=rst</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Crosses(poly,</span> <span class="pre">ST_Polygon(rst))</span></code></td>
</tr>
</tbody>
</table>
<p>Spatial lookups with rasters are only supported for PostGIS backends
(denominated as PGRaster in this section).</p>
</div>
<div class="section" id="s-bbcontains">
<span id="s-std:fieldlookup-bbcontains"></span><span id="bbcontains"></span><span id="std:fieldlookup-bbcontains"></span><h3><code class="docutils literal notranslate"><span class="pre">bbcontains</span></code><a class="headerlink" href="#bbcontains" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Geometry_Contain.html">PostGIS</a>,
MySQL, SpatiaLite, PGRaster (Native)</p>
<p>Tests if the geometry or raster field’s bounding box completely contains the
lookup geometry’s bounding box.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__bbcontains</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="27%" />
<col width="73%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS</td>
<td><code class="docutils literal notranslate"><span class="pre">poly</span> <span class="pre">~</span> <span class="pre">geom</span></code></td>
</tr>
<tr class="row-odd"><td>MySQL</td>
<td><code class="docutils literal notranslate"><span class="pre">MBRContains(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-even"><td>SpatiaLite</td>
<td><code class="docutils literal notranslate"><span class="pre">MbrContains(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-bboverlaps">
<span id="s-std:fieldlookup-bboverlaps"></span><span id="bboverlaps"></span><span id="std:fieldlookup-bboverlaps"></span><h3><code class="docutils literal notranslate"><span class="pre">bboverlaps</span></code><a class="headerlink" href="#bboverlaps" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/geometry_overlaps.html">PostGIS</a>,
MySQL, SpatiaLite, PGRaster (Native)</p>
<p>Tests if the geometry field’s bounding box overlaps the lookup geometry’s
bounding box.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__bboverlaps</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="27%" />
<col width="73%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS</td>
<td><code class="docutils literal notranslate"><span class="pre">poly</span> <span class="pre">&&</span> <span class="pre">geom</span></code></td>
</tr>
<tr class="row-odd"><td>MySQL</td>
<td><code class="docutils literal notranslate"><span class="pre">MBROverlaps(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-even"><td>SpatiaLite</td>
<td><code class="docutils literal notranslate"><span class="pre">MbrOverlaps(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-contained">
<span id="s-std:fieldlookup-contained"></span><span id="contained"></span><span id="std:fieldlookup-contained"></span><h3><code class="docutils literal notranslate"><span class="pre">contained</span></code><a class="headerlink" href="#contained" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Geometry_Contained.html">PostGIS</a>,
MySQL, SpatiaLite, PGRaster (Native)</p>
<p>Tests if the geometry field’s bounding box is completely contained by the
lookup geometry’s bounding box.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__contained</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="28%" />
<col width="72%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS</td>
<td><code class="docutils literal notranslate"><span class="pre">poly</span> <span class="pre">@</span> <span class="pre">geom</span></code></td>
</tr>
<tr class="row-odd"><td>MySQL</td>
<td><code class="docutils literal notranslate"><span class="pre">MBRWithin(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-even"><td>SpatiaLite</td>
<td><code class="docutils literal notranslate"><span class="pre">MbrWithin(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-contains">
<span id="s-std:fieldlookup-gis-contains"></span><span id="contains"></span><span id="std:fieldlookup-gis-contains"></span><h3><code class="docutils literal notranslate"><span class="pre">contains</span></code><a class="headerlink" href="#contains" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Contains.html">PostGIS</a>,
Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)</p>
<p>Tests if the geometry field spatially contains the lookup geometry.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__contains</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="26%" />
<col width="74%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS</td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Contains(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-odd"><td>Oracle</td>
<td><code class="docutils literal notranslate"><span class="pre">SDO_CONTAINS(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-even"><td>MySQL</td>
<td><code class="docutils literal notranslate"><span class="pre">MBRContains(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-odd"><td>SpatiaLite</td>
<td><code class="docutils literal notranslate"><span class="pre">Contains(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-contains-properly">
<span id="s-std:fieldlookup-contains_properly"></span><span id="contains-properly"></span><span id="std:fieldlookup-contains_properly"></span><h3><code class="docutils literal notranslate"><span class="pre">contains_properly</span></code><a class="headerlink" href="#contains-properly" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_ContainsProperly.html">PostGIS</a>,
PGRaster (Bilateral)</p>
<p>Returns true if the lookup geometry intersects the interior of the
geometry field, but not the boundary (or exterior).</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__contains_properly</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="22%" />
<col width="78%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS</td>
<td><code class="docutils literal notranslate"><span class="pre">ST_ContainsProperly(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-coveredby">
<span id="s-std:fieldlookup-coveredby"></span><span id="coveredby"></span><span id="std:fieldlookup-coveredby"></span><h3><code class="docutils literal notranslate"><span class="pre">coveredby</span></code><a class="headerlink" href="#coveredby" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_CoveredBy.html">PostGIS</a>,
Oracle, PGRaster (Bilateral)</p>
<p>Tests if no point in the geometry field is outside the lookup geometry.
<a class="footnote-reference" href="#fncovers" id="id2">[3]</a></p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__coveredby</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="26%" />
<col width="74%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS</td>
<td><code class="docutils literal notranslate"><span class="pre">ST_CoveredBy(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-odd"><td>Oracle</td>
<td><code class="docutils literal notranslate"><span class="pre">SDO_COVEREDBY(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-covers">
<span id="s-std:fieldlookup-covers"></span><span id="covers"></span><span id="std:fieldlookup-covers"></span><h3><code class="docutils literal notranslate"><span class="pre">covers</span></code><a class="headerlink" href="#covers" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Covers.html">PostGIS</a>,
Oracle, PGRaster (Bilateral)</p>
<p>Tests if no point in the lookup geometry is outside the geometry field.
<a class="footnote-reference" href="#fncovers" id="id3">[3]</a></p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__covers</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="28%" />
<col width="72%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS</td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Covers(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-odd"><td>Oracle</td>
<td><code class="docutils literal notranslate"><span class="pre">SDO_COVERS(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-crosses">
<span id="s-std:fieldlookup-crosses"></span><span id="crosses"></span><span id="std:fieldlookup-crosses"></span><h3><code class="docutils literal notranslate"><span class="pre">crosses</span></code><a class="headerlink" href="#crosses" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Crosses.html">PostGIS</a>,
SpatiaLite, PGRaster (Conversion)</p>
<p>Tests if the geometry field spatially crosses the lookup geometry.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__crosses</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="28%" />
<col width="72%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS</td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Crosses(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-odd"><td>SpatiaLite</td>
<td><code class="docutils literal notranslate"><span class="pre">Crosses(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-disjoint">
<span id="s-std:fieldlookup-disjoint"></span><span id="disjoint"></span><span id="std:fieldlookup-disjoint"></span><h3><code class="docutils literal notranslate"><span class="pre">disjoint</span></code><a class="headerlink" href="#disjoint" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Disjoint.html">PostGIS</a>,
Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)</p>
<p>Tests if the geometry field is spatially disjoint from the lookup geometry.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__disjoint</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="17%" />
<col width="83%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS</td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Disjoint(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-odd"><td>Oracle</td>
<td><code class="docutils literal notranslate"><span class="pre">SDO_GEOM.RELATE(poly,</span> <span class="pre">'DISJOINT',</span> <span class="pre">geom,</span> <span class="pre">0.05)</span></code></td>
</tr>
<tr class="row-even"><td>MySQL</td>
<td><code class="docutils literal notranslate"><span class="pre">MBRDisjoint(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-odd"><td>SpatiaLite</td>
<td><code class="docutils literal notranslate"><span class="pre">Disjoint(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-equals">
<span id="s-std:fieldlookup-equals"></span><span id="equals"></span><span id="std:fieldlookup-equals"></span><h3><code class="docutils literal notranslate"><span class="pre">equals</span></code><a class="headerlink" href="#equals" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Equals.html">PostGIS</a>,
Oracle, MySQL, SpatiaLite, PGRaster (Conversion)</p>
<span class="target" id="std:fieldlookup-exact"></span></div>
<div class="section" id="s-exact-same-as">
<span id="s-std:fieldlookup-same_as"></span><span id="exact-same-as"></span><span id="std:fieldlookup-same_as"></span><h3><code class="docutils literal notranslate"><span class="pre">exact</span></code>, <code class="docutils literal notranslate"><span class="pre">same_as</span></code><a class="headerlink" href="#exact-same-as" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Geometry_Same.html">PostGIS</a>,
Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)</p>
</div>
<div class="section" id="s-intersects">
<span id="s-std:fieldlookup-intersects"></span><span id="intersects"></span><span id="std:fieldlookup-intersects"></span><h3><code class="docutils literal notranslate"><span class="pre">intersects</span></code><a class="headerlink" href="#intersects" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Intersects.html">PostGIS</a>,
Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)</p>
<p>Tests if the geometry field spatially intersects the lookup geometry.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__intersects</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="17%" />
<col width="83%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS</td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Intersects(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-odd"><td>Oracle</td>
<td><code class="docutils literal notranslate"><span class="pre">SDO_OVERLAPBDYINTERSECT(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-even"><td>MySQL</td>
<td><code class="docutils literal notranslate"><span class="pre">MBRIntersects(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-odd"><td>SpatiaLite</td>
<td><code class="docutils literal notranslate"><span class="pre">Intersects(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-isvalid">
<span id="s-std:fieldlookup-isvalid"></span><span id="isvalid"></span><span id="std:fieldlookup-isvalid"></span><h3><code class="docutils literal notranslate"><span class="pre">isvalid</span></code><a class="headerlink" href="#isvalid" title="Permalink to this headline">¶</a></h3>
<div class="versionadded">
<span class="title">New in Django 1.10.</span> </div>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_IsValid.html">PostGIS</a>,
Oracle, SpatiaLite</p>
<p>Tests if the geometry is valid.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__isvalid</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="23%" />
<col width="77%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS, SpatiaLite</td>
<td><code class="docutils literal notranslate"><span class="pre">ST_IsValid(poly)</span></code></td>
</tr>
<tr class="row-odd"><td>Oracle</td>
<td><code class="docutils literal notranslate"><span class="pre">SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT(poly,</span> <span class="pre">0.05)</span> <span class="pre">=</span> <span class="pre">'TRUE'</span></code></td>
</tr>
</tbody>
</table>
<div class="versionchanged">
<span class="title">Changed in Django 1.11:</span> <p>Oracle and SpatiaLite support was added.</p>
</div>
</div>
<div class="section" id="s-overlaps">
<span id="s-std:fieldlookup-overlaps"></span><span id="overlaps"></span><span id="std:fieldlookup-overlaps"></span><h3><code class="docutils literal notranslate"><span class="pre">overlaps</span></code><a class="headerlink" href="#overlaps" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Overlaps.html">PostGIS</a>,
Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)</p>
</div>
<div class="section" id="s-relate">
<span id="s-std:fieldlookup-relate"></span><span id="relate"></span><span id="std:fieldlookup-relate"></span><h3><code class="docutils literal notranslate"><span class="pre">relate</span></code><a class="headerlink" href="#relate" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Relate.html">PostGIS</a>,
Oracle, SpatiaLite, PGRaster (Conversion)</p>
<p>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,
<code class="docutils literal notranslate"><span class="pre">(geom,</span> <span class="pre">pattern)</span></code>; the form of <code class="docutils literal notranslate"><span class="pre">pattern</span></code> will depend on the spatial backend:</p>
<div class="section" id="s-postgis-spatialite">
<span id="postgis-spatialite"></span><h4>PostGIS & SpatiaLite<a class="headerlink" href="#postgis-spatialite" title="Permalink to this headline">¶</a></h4>
<p>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:
<code class="docutils literal notranslate"><span class="pre">1</span></code>, <code class="docutils literal notranslate"><span class="pre">2</span></code>, <code class="docutils literal notranslate"><span class="pre">T</span></code>, <code class="docutils literal notranslate"><span class="pre">F</span></code>, or <code class="docutils literal notranslate"><span class="pre">*</span></code>. This lookup type allows users to “fine tune”
a specific geometric relationship consistent with the DE-9IM model. <a class="footnote-reference" href="#fnde9im" id="id4">[1]</a></p>
<p>Geometry example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># A tuple lookup parameter is used to specify the geometry and</span>
<span class="c1"># the intersection pattern (the pattern here is for 'contains').</span>
<span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__relate</span><span class="o">=</span><span class="p">(</span><span class="n">geom</span><span class="p">,</span> <span class="s1">'T*T***FF*'</span><span class="p">))</span>
</pre></div>
</div>
<p>PostGIS SQL equivalent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="o">...</span> <span class="n">WHERE</span> <span class="n">ST_Relate</span><span class="p">(</span><span class="n">poly</span><span class="p">,</span> <span class="n">geom</span><span class="p">,</span> <span class="s1">'T*T***FF*'</span><span class="p">)</span>
</pre></div>
</div>
<p>SpatiaLite SQL equivalent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="o">...</span> <span class="n">WHERE</span> <span class="n">Relate</span><span class="p">(</span><span class="n">poly</span><span class="p">,</span> <span class="n">geom</span><span class="p">,</span> <span class="s1">'T*T***FF*'</span><span class="p">)</span>
</pre></div>
</div>
<p>Raster example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__relate</span><span class="o">=</span><span class="p">(</span><span class="n">rast</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="s1">'T*T***FF*'</span><span class="p">))</span>
<span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">rast__2__relate</span><span class="o">=</span><span class="p">(</span><span class="n">rast</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="s1">'T*T***FF*'</span><span class="p">))</span>
</pre></div>
</div>
<p>PostGIS SQL equivalent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="o">...</span> <span class="n">WHERE</span> <span class="n">ST_Relate</span><span class="p">(</span><span class="n">poly</span><span class="p">,</span> <span class="n">ST_Polygon</span><span class="p">(</span><span class="n">rast</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="s1">'T*T***FF*'</span><span class="p">)</span>
<span class="n">SELECT</span> <span class="o">...</span> <span class="n">WHERE</span> <span class="n">ST_Relate</span><span class="p">(</span><span class="n">ST_Polygon</span><span class="p">(</span><span class="n">rast</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="n">ST_Polygon</span><span class="p">(</span><span class="n">rast</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="s1">'T*T***FF*'</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="s-oracle">
<span id="oracle"></span><h4>Oracle<a class="headerlink" href="#oracle" title="Permalink to this headline">¶</a></h4>
<p>Here the relation pattern is comprised of at least one of the nine relation
strings: <code class="docutils literal notranslate"><span class="pre">TOUCH</span></code>, <code class="docutils literal notranslate"><span class="pre">OVERLAPBDYDISJOINT</span></code>, <code class="docutils literal notranslate"><span class="pre">OVERLAPBDYINTERSECT</span></code>,
<code class="docutils literal notranslate"><span class="pre">EQUAL</span></code>, <code class="docutils literal notranslate"><span class="pre">INSIDE</span></code>, <code class="docutils literal notranslate"><span class="pre">COVEREDBY</span></code>, <code class="docutils literal notranslate"><span class="pre">CONTAINS</span></code>, <code class="docutils literal notranslate"><span class="pre">COVERS</span></code>, <code class="docutils literal notranslate"><span class="pre">ON</span></code>, and
<code class="docutils literal notranslate"><span class="pre">ANYINTERACT</span></code>. Multiple strings may be combined with the logical Boolean
operator OR, for example, <code class="docutils literal notranslate"><span class="pre">'inside+touch'</span></code>. <a class="footnote-reference" href="#fnsdorelate" id="id5">[2]</a> The relation
strings are case-insensitive.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__relate</span><span class="o">=</span><span class="p">(</span><span class="n">geom</span><span class="p">,</span> <span class="s1">'anyinteract'</span><span class="p">))</span>
</pre></div>
</div>
<p>Oracle SQL equivalent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="o">...</span> <span class="n">WHERE</span> <span class="n">SDO_RELATE</span><span class="p">(</span><span class="n">poly</span><span class="p">,</span> <span class="n">geom</span><span class="p">,</span> <span class="s1">'anyinteract'</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-touches">
<span id="s-std:fieldlookup-touches"></span><span id="touches"></span><span id="std:fieldlookup-touches"></span><h3><code class="docutils literal notranslate"><span class="pre">touches</span></code><a class="headerlink" href="#touches" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Touches.html">PostGIS</a>,
Oracle, MySQL, SpatiaLite</p>
<p>Tests if the geometry field spatially touches the lookup geometry.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__touches</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="28%" />
<col width="72%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS</td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Touches(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-odd"><td>MySQL</td>
<td><code class="docutils literal notranslate"><span class="pre">MBRTouches(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-even"><td>Oracle</td>
<td><code class="docutils literal notranslate"><span class="pre">SDO_TOUCH(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-odd"><td>SpatiaLite</td>
<td><code class="docutils literal notranslate"><span class="pre">Touches(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-within">
<span id="s-std:fieldlookup-within"></span><span id="within"></span><span id="std:fieldlookup-within"></span><h3><code class="docutils literal notranslate"><span class="pre">within</span></code><a class="headerlink" href="#within" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Within.html">PostGIS</a>,
Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)</p>
<p>Tests if the geometry field is spatially within the lookup geometry.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__within</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="28%" />
<col width="72%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS</td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Within(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-odd"><td>MySQL</td>
<td><code class="docutils literal notranslate"><span class="pre">MBRWithin(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-even"><td>Oracle</td>
<td><code class="docutils literal notranslate"><span class="pre">SDO_INSIDE(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
<tr class="row-odd"><td>SpatiaLite</td>
<td><code class="docutils literal notranslate"><span class="pre">Within(poly,</span> <span class="pre">geom)</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-left">
<span id="s-std:fieldlookup-left"></span><span id="left"></span><span id="std:fieldlookup-left"></span><h3><code class="docutils literal notranslate"><span class="pre">left</span></code><a class="headerlink" href="#left" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Geometry_Left.html">PostGIS</a>,
PGRaster (Conversion)</p>
<p>Tests if the geometry field’s bounding box is strictly to the left of the
lookup geometry’s bounding box.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__left</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<p>PostGIS equivalent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="o">...</span> <span class="n">WHERE</span> <span class="n">poly</span> <span class="o"><<</span> <span class="n">geom</span>
</pre></div>
</div>
</div>
<div class="section" id="s-right">
<span id="s-std:fieldlookup-right"></span><span id="right"></span><span id="std:fieldlookup-right"></span><h3><code class="docutils literal notranslate"><span class="pre">right</span></code><a class="headerlink" href="#right" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Geometry_Right.html">PostGIS</a>,
PGRaster (Conversion)</p>
<p>Tests if the geometry field’s bounding box is strictly to the right of the
lookup geometry’s bounding box.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__right</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<p>PostGIS equivalent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="o">...</span> <span class="n">WHERE</span> <span class="n">poly</span> <span class="o">>></span> <span class="n">geom</span>
</pre></div>
</div>
</div>
<div class="section" id="s-overlaps-left">
<span id="s-std:fieldlookup-overlaps_left"></span><span id="overlaps-left"></span><span id="std:fieldlookup-overlaps_left"></span><h3><code class="docutils literal notranslate"><span class="pre">overlaps_left</span></code><a class="headerlink" href="#overlaps-left" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Geometry_Overleft.html">PostGIS</a>,
PGRaster (Bilateral)</p>
<p>Tests if the geometry field’s bounding box overlaps or is to the left of the lookup
geometry’s bounding box.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__overlaps_left</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<p>PostGIS equivalent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="o">...</span> <span class="n">WHERE</span> <span class="n">poly</span> <span class="o">&<</span> <span class="n">geom</span>
</pre></div>
</div>
</div>
<div class="section" id="s-overlaps-right">
<span id="s-std:fieldlookup-overlaps_right"></span><span id="overlaps-right"></span><span id="std:fieldlookup-overlaps_right"></span><h3><code class="docutils literal notranslate"><span class="pre">overlaps_right</span></code><a class="headerlink" href="#overlaps-right" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Geometry_Overright.html">PostGIS</a>,
PGRaster (Bilateral)</p>
<p>Tests if the geometry field’s bounding box overlaps or is to the right of the lookup
geometry’s bounding box.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__overlaps_right</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<p>PostGIS equivalent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="o">...</span> <span class="n">WHERE</span> <span class="n">poly</span> <span class="o">&></span> <span class="n">geom</span>
</pre></div>
</div>
</div>
<div class="section" id="s-overlaps-above">
<span id="s-std:fieldlookup-overlaps_above"></span><span id="overlaps-above"></span><span id="std:fieldlookup-overlaps_above"></span><h3><code class="docutils literal notranslate"><span class="pre">overlaps_above</span></code><a class="headerlink" href="#overlaps-above" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Geometry_Overabove.html">PostGIS</a>,
PGRaster (Conversion)</p>
<p>Tests if the geometry field’s bounding box overlaps or is above the lookup
geometry’s bounding box.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__overlaps_above</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<p>PostGIS equivalent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="o">...</span> <span class="n">WHERE</span> <span class="n">poly</span> <span class="o">|&></span> <span class="n">geom</span>
</pre></div>
</div>
</div>
<div class="section" id="s-overlaps-below">
<span id="s-std:fieldlookup-overlaps_below"></span><span id="overlaps-below"></span><span id="std:fieldlookup-overlaps_below"></span><h3><code class="docutils literal notranslate"><span class="pre">overlaps_below</span></code><a class="headerlink" href="#overlaps-below" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Geometry_Overbelow.html">PostGIS</a>,
PGRaster (Conversion)</p>
<p>Tests if the geometry field’s bounding box overlaps or is below the lookup
geometry’s bounding box.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__overlaps_below</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<p>PostGIS equivalent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="o">...</span> <span class="n">WHERE</span> <span class="n">poly</span> <span class="o">&<|</span> <span class="n">geom</span>
</pre></div>
</div>
</div>
<div class="section" id="s-strictly-above">
<span id="s-std:fieldlookup-strictly_above"></span><span id="strictly-above"></span><span id="std:fieldlookup-strictly_above"></span><h3><code class="docutils literal notranslate"><span class="pre">strictly_above</span></code><a class="headerlink" href="#strictly-above" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Geometry_Above.html">PostGIS</a>,
PGRaster (Conversion)</p>
<p>Tests if the geometry field’s bounding box is strictly above the lookup
geometry’s bounding box.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__strictly_above</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<p>PostGIS equivalent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="o">...</span> <span class="n">WHERE</span> <span class="n">poly</span> <span class="o">|>></span> <span class="n">geom</span>
</pre></div>
</div>
</div>
<div class="section" id="s-strictly-below">
<span id="s-std:fieldlookup-strictly_below"></span><span id="strictly-below"></span><span id="std:fieldlookup-strictly_below"></span><h3><code class="docutils literal notranslate"><span class="pre">strictly_below</span></code><a class="headerlink" href="#strictly-below" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Geometry_Below.html">PostGIS</a>,
PGRaster (Conversion)</p>
<p>Tests if the geometry field’s bounding box is strictly below the lookup
geometry’s bounding box.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__strictly_below</span><span class="o">=</span><span class="n">geom</span><span class="p">)</span>
</pre></div>
</div>
<p>PostGIS equivalent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="o">...</span> <span class="n">WHERE</span> <span class="n">poly</span> <span class="o"><<|</span> <span class="n">geom</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-distance-lookups">
<span id="s-id6"></span><span id="distance-lookups"></span><span id="id6"></span><h2>Distance Lookups<a class="headerlink" href="#distance-lookups" title="Permalink to this headline">¶</a></h2>
<p><em>Availability</em>: PostGIS, Oracle, SpatiaLite, PGRaster (Native)</p>
<p>For an overview on performing distance queries, please refer to
the <a class="reference internal" href="db-api.html#distance-queries"><span class="std std-ref">distance queries introduction</span></a>.</p>
<p>Distance lookups take the following form:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">field</span><span class="o">></span><span class="n">__</span><span class="o"><</span><span class="n">distance</span> <span class="n">lookup</span><span class="o">>=</span><span class="p">(</span><span class="o"><</span><span class="n">geometry</span><span class="o">/</span><span class="n">raster</span><span class="o">></span><span class="p">,</span> <span class="o"><</span><span class="n">distance</span> <span class="n">value</span><span class="o">></span><span class="p">[,</span> <span class="s1">'spheroid'</span><span class="p">])</span>
<span class="o"><</span><span class="n">field</span><span class="o">></span><span class="n">__</span><span class="o"><</span><span class="n">distance</span> <span class="n">lookup</span><span class="o">>=</span><span class="p">(</span><span class="o"><</span><span class="n">raster</span><span class="o">></span><span class="p">,</span> <span class="o"><</span><span class="n">band_index</span><span class="o">></span><span class="p">,</span> <span class="o"><</span><span class="n">distance</span> <span class="n">value</span><span class="o">></span><span class="p">[,</span> <span class="s1">'spheroid'</span><span class="p">])</span>
<span class="o"><</span><span class="n">field</span><span class="o">></span><span class="n">__</span><span class="o"><</span><span class="n">band_index</span><span class="o">></span><span class="n">__</span><span class="o"><</span><span class="n">distance</span> <span class="n">lookup</span><span class="o">>=</span><span class="p">(</span><span class="o"><</span><span class="n">raster</span><span class="o">></span><span class="p">,</span> <span class="o"><</span><span class="n">band_index</span><span class="o">></span><span class="p">,</span> <span class="o"><</span><span class="n">distance</span> <span class="n">value</span><span class="o">></span><span class="p">[,</span> <span class="s1">'spheroid'</span><span class="p">])</span>
</pre></div>
</div>
<p>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
<a class="reference internal" href="measure.html#django.contrib.gis.measure.Distance" title="django.contrib.gis.measure.Distance"><code class="xref py py-class docutils literal notranslate"><span class="pre">Distance</span></code></a> object, or a <cite>query expression
<ref/models/expressions></cite>). To pass a band index to the lookup, use a 3-tuple
where the second entry is the band index.</p>
<p>On every distance lookup except <a class="reference internal" href="#std:fieldlookup-dwithin"><code class="xref std std-lookup docutils literal notranslate"><span class="pre">dwithin</span></code></a>, an optional element,
<code class="docutils literal notranslate"><span class="pre">'spheroid'</span></code>, may be included to use the more accurate spheroid distance
calculation functions on fields with a geodetic coordinate system.</p>
<p>On PostgreSQL, the <code class="docutils literal notranslate"><span class="pre">'spheroid'</span></code> option uses <a class="reference external" href="https://postgis.net/docs/ST_Distance_Spheroid.html">ST_DistanceSpheroid</a> instead of
<a class="reference external" href="https://postgis.net/docs/ST_DistanceSphere.html">ST_DistanceSphere</a>. The
simpler <a class="reference external" href="https://postgis.net/docs/ST_Distance.html">ST_Distance</a> function is
used with projected coordinate systems. Rasters are converted to geometries for
spheroid based lookups.</p>
<div class="versionadded">
<span class="title">New in Django 1.10:</span> <p>The ability to pass an expression as the distance value was added.</p>
</div>
<div class="versionadded">
<span class="title">New in Django 1.11:</span> <p>Support for the <code class="docutils literal notranslate"><span class="pre">'spheroid'</span></code> option on SQLite was added.</p>
</div>
<div class="section" id="s-distance-gt">
<span id="s-std:fieldlookup-distance_gt"></span><span id="distance-gt"></span><span id="std:fieldlookup-distance_gt"></span><h3><code class="docutils literal notranslate"><span class="pre">distance_gt</span></code><a class="headerlink" href="#distance-gt" title="Permalink to this headline">¶</a></h3>
<p>Returns models where the distance to the geometry field from the lookup
geometry is greater than the given distance value.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__distance_gt</span><span class="o">=</span><span class="p">(</span><span class="n">geom</span><span class="p">,</span> <span class="n">D</span><span class="p">(</span><span class="n">m</span><span class="o">=</span><span class="mi">5</span><span class="p">)))</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="17%" />
<col width="83%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS</td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Distance/ST_Distance_Sphere(poly,</span> <span class="pre">geom)</span> <span class="pre">></span> <span class="pre">5</span></code></td>
</tr>
<tr class="row-odd"><td>Oracle</td>
<td><code class="docutils literal notranslate"><span class="pre">SDO_GEOM.SDO_DISTANCE(poly,</span> <span class="pre">geom,</span> <span class="pre">0.05)</span> <span class="pre">></span> <span class="pre">5</span></code></td>
</tr>
<tr class="row-even"><td>SpatiaLite</td>
<td><code class="docutils literal notranslate"><span class="pre">Distance(poly,</span> <span class="pre">geom)</span> <span class="pre">></span> <span class="pre">5</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-distance-gte">
<span id="s-std:fieldlookup-distance_gte"></span><span id="distance-gte"></span><span id="std:fieldlookup-distance_gte"></span><h3><code class="docutils literal notranslate"><span class="pre">distance_gte</span></code><a class="headerlink" href="#distance-gte" title="Permalink to this headline">¶</a></h3>
<p>Returns models where the distance to the geometry field from the lookup
geometry is greater than or equal to the given distance value.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__distance_gte</span><span class="o">=</span><span class="p">(</span><span class="n">geom</span><span class="p">,</span> <span class="n">D</span><span class="p">(</span><span class="n">m</span><span class="o">=</span><span class="mi">5</span><span class="p">)))</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="16%" />
<col width="84%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS</td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Distance/ST_Distance_Sphere(poly,</span> <span class="pre">geom)</span> <span class="pre">>=</span> <span class="pre">5</span></code></td>
</tr>
<tr class="row-odd"><td>Oracle</td>
<td><code class="docutils literal notranslate"><span class="pre">SDO_GEOM.SDO_DISTANCE(poly,</span> <span class="pre">geom,</span> <span class="pre">0.05)</span> <span class="pre">>=</span> <span class="pre">5</span></code></td>
</tr>
<tr class="row-even"><td>SpatiaLite</td>
<td><code class="docutils literal notranslate"><span class="pre">Distance(poly,</span> <span class="pre">geom)</span> <span class="pre">>=</span> <span class="pre">5</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-distance-lt">
<span id="s-std:fieldlookup-distance_lt"></span><span id="distance-lt"></span><span id="std:fieldlookup-distance_lt"></span><h3><code class="docutils literal notranslate"><span class="pre">distance_lt</span></code><a class="headerlink" href="#distance-lt" title="Permalink to this headline">¶</a></h3>
<p>Returns models where the distance to the geometry field from the lookup
geometry is less than the given distance value.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__distance_lt</span><span class="o">=</span><span class="p">(</span><span class="n">geom</span><span class="p">,</span> <span class="n">D</span><span class="p">(</span><span class="n">m</span><span class="o">=</span><span class="mi">5</span><span class="p">)))</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="17%" />
<col width="83%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS</td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Distance/ST_Distance_Sphere(poly,</span> <span class="pre">geom)</span> <span class="pre"><</span> <span class="pre">5</span></code></td>
</tr>
<tr class="row-odd"><td>Oracle</td>
<td><code class="docutils literal notranslate"><span class="pre">SDO_GEOM.SDO_DISTANCE(poly,</span> <span class="pre">geom,</span> <span class="pre">0.05)</span> <span class="pre"><</span> <span class="pre">5</span></code></td>
</tr>
<tr class="row-even"><td>SpatiaLite</td>
<td><code class="docutils literal notranslate"><span class="pre">Distance(poly,</span> <span class="pre">geom)</span> <span class="pre"><</span> <span class="pre">5</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-distance-lte">
<span id="s-std:fieldlookup-distance_lte"></span><span id="distance-lte"></span><span id="std:fieldlookup-distance_lte"></span><h3><code class="docutils literal notranslate"><span class="pre">distance_lte</span></code><a class="headerlink" href="#distance-lte" title="Permalink to this headline">¶</a></h3>
<p>Returns models where the distance to the geometry field from the lookup
geometry is less than or equal to the given distance value.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__distance_lte</span><span class="o">=</span><span class="p">(</span><span class="n">geom</span><span class="p">,</span> <span class="n">D</span><span class="p">(</span><span class="n">m</span><span class="o">=</span><span class="mi">5</span><span class="p">)))</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="16%" />
<col width="84%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS</td>
<td><code class="docutils literal notranslate"><span class="pre">ST_Distance/ST_Distance_Sphere(poly,</span> <span class="pre">geom)</span> <span class="pre"><=</span> <span class="pre">5</span></code></td>
</tr>
<tr class="row-odd"><td>Oracle</td>
<td><code class="docutils literal notranslate"><span class="pre">SDO_GEOM.SDO_DISTANCE(poly,</span> <span class="pre">geom,</span> <span class="pre">0.05)</span> <span class="pre"><=</span> <span class="pre">5</span></code></td>
</tr>
<tr class="row-even"><td>SpatiaLite</td>
<td><code class="docutils literal notranslate"><span class="pre">Distance(poly,</span> <span class="pre">geom)</span> <span class="pre"><=</span> <span class="pre">5</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-dwithin">
<span id="s-std:fieldlookup-dwithin"></span><span id="dwithin"></span><span id="std:fieldlookup-dwithin"></span><h3><code class="docutils literal notranslate"><span class="pre">dwithin</span></code><a class="headerlink" href="#dwithin" title="Permalink to this headline">¶</a></h3>
<p>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 <a class="reference internal" href="measure.html#django.contrib.gis.measure.Distance" title="django.contrib.gis.measure.Distance"><code class="xref py py-class docutils literal notranslate"><span class="pre">Distance</span></code></a> 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 <code class="docutils literal notranslate"><span class="pre">WGS84</span></code>) .</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__dwithin</span><span class="o">=</span><span class="p">(</span><span class="n">geom</span><span class="p">,</span> <span class="n">D</span><span class="p">(</span><span class="n">m</span><span class="o">=</span><span class="mi">5</span><span class="p">)))</span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="21%" />
<col width="79%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Backend</th>
<th class="head">SQL Equivalent</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>PostGIS</td>
<td><code class="docutils literal notranslate"><span class="pre">ST_DWithin(poly,</span> <span class="pre">geom,</span> <span class="pre">5)</span></code></td>
</tr>
<tr class="row-odd"><td>Oracle</td>
<td><code class="docutils literal notranslate"><span class="pre">SDO_WITHIN_DISTANCE(poly,</span> <span class="pre">geom,</span> <span class="pre">5)</span></code></td>
</tr>
<tr class="row-even"><td>SpatiaLite</td>
<td><code class="docutils literal notranslate"><span class="pre">PtDistWithin(poly,</span> <span class="pre">geom,</span> <span class="pre">5)</span></code></td>
</tr>
</tbody>
</table>
<div class="versionchanged">
<span class="title">Changed in Django 1.11:</span> <p>SpatiaLite support was added.</p>
</div>
</div>
</div>
<div class="section" id="s-geoqueryset-methods">
<span id="s-id7"></span><span id="geoqueryset-methods"></span><span id="id7"></span><h2><code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code> Methods<a class="headerlink" href="#geoqueryset-methods" title="Permalink to this headline">¶</a></h2>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Using <code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code> methods is now deprecated in favor of the new
<a class="reference internal" href="functions.html"><span class="doc">Geographic Database Functions</span></a>. Albeit a little more verbose, they are much more powerful
in how it is possible to combine them to build more complex queries.</p>
</div>
<p><code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code> 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
(which is generally the name of the <code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code> method).</p>
<p>There are also aggregate <code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code> methods which return a single value
instead of a queryset. This section will describe the API and availability
of every <code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code> method available in GeoDjango.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">What methods are available depend on your spatial backend. See
the <a class="reference internal" href="db-api.html#database-functions-compatibility"><span class="std std-ref">compatibility table</span></a>
for more details.</p>
</div>
<p>With a few exceptions, the following keyword arguments may be used with all
<code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code> methods:</p>
<table class="docutils">
<colgroup>
<col width="28%" />
<col width="72%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Keyword Argument</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">field_name</span></code></td>
<td><p class="first">By default, <code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code> methods use the first
geographic field encountered in the model. This
keyword should be used to specify another
geographic field (e.g., <code class="docutils literal notranslate"><span class="pre">field_name='point2'</span></code>)
when there are multiple geographic fields in a model.</p>
<p class="last">On PostGIS, the <code class="docutils literal notranslate"><span class="pre">field_name</span></code> keyword may also be
used on geometry fields in models that are related
via a <code class="docutils literal notranslate"><span class="pre">ForeignKey</span></code> relation (e.g.,
<code class="docutils literal notranslate"><span class="pre">field_name='related__point'</span></code>).</p>
</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">model_att</span></code></td>
<td><p class="first">By default, <code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code> methods typically attach
their output in an attribute with the same name as
the <code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code> method. Setting this keyword
with the desired attribute name will override this
default behavior. For example,
<code class="docutils literal notranslate"><span class="pre">qs</span> <span class="pre">=</span> <span class="pre">Zipcode.objects.centroid(model_att='c')</span></code> will
attach the centroid of the <code class="docutils literal notranslate"><span class="pre">Zipcode</span></code> geometry field
in a <code class="docutils literal notranslate"><span class="pre">c</span></code> attribute on every model rather than in a
<code class="docutils literal notranslate"><span class="pre">centroid</span></code> attribute.</p>
<p class="last">This keyword is required if
a method name clashes with an existing
<code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code> method – if you wanted to use the
<code class="docutils literal notranslate"><span class="pre">area()</span></code> method on model with a <code class="docutils literal notranslate"><span class="pre">PolygonField</span></code>
named <code class="docutils literal notranslate"><span class="pre">area</span></code>, for example.</p>
</td>
</tr>
</tbody>
</table>
<div class="section" id="s-measurement">
<span id="measurement"></span><h3>Measurement<a class="headerlink" href="#measurement" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: PostGIS, Oracle, SpatiaLite</p>
<div class="section" id="s-area">
<span id="area"></span><h4><code class="docutils literal notranslate"><span class="pre">area</span></code><a class="headerlink" href="#area" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.area">
<code class="descclassname">GeoQuerySet.</code><code class="descname">area</code>(<em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.area" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.Area" title="django.contrib.gis.db.models.functions.Area"><code class="xref py py-class docutils literal notranslate"><span class="pre">Area</span></code></a> function
instead.</p>
</div>
<p>Returns the area of the geographic field in an <code class="docutils literal notranslate"><span class="pre">area</span></code> attribute on
each element of this GeoQuerySet.</p>
</div>
<div class="section" id="s-distance">
<span id="distance"></span><h4><code class="docutils literal notranslate"><span class="pre">distance</span></code><a class="headerlink" href="#distance" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.distance">
<code class="descclassname">GeoQuerySet.</code><code class="descname">distance</code>(<em>geom</em>, <em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.distance" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.Distance" title="django.contrib.gis.db.models.functions.Distance"><code class="xref py py-class docutils literal notranslate"><span class="pre">Distance</span></code></a> function
instead.</p>
</div>
<p>This method takes a geometry as a parameter, and attaches a <code class="docutils literal notranslate"><span class="pre">distance</span></code>
attribute to every model in the returned queryset that contains the
distance (as a <a class="reference internal" href="measure.html#django.contrib.gis.measure.Distance" title="django.contrib.gis.measure.Distance"><code class="xref py py-class docutils literal notranslate"><span class="pre">Distance</span></code></a> object) to the given geometry.</p>
<p>In the following example (taken from the <a class="reference external" href="https://github.com/django/django/blob/master/tests/gis_tests/distapp/models.py">GeoDjango distance tests</a>),
the distance from the <a class="reference external" href="https://en.wikipedia.org/wiki/Tasmania">Tasmanian</a> city of Hobart to every other
<a class="reference internal" href="model-api.html#django.contrib.gis.db.models.PointField" title="django.contrib.gis.db.models.PointField"><code class="xref py py-class docutils literal notranslate"><span class="pre">PointField</span></code></a> in the <code class="docutils literal notranslate"><span class="pre">AustraliaCity</span></code> queryset is calculated:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">pnt</span> <span class="o">=</span> <span class="n">AustraliaCity</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'Hobart'</span><span class="p">)</span><span class="o">.</span><span class="n">point</span>
<span class="gp">>>> </span><span class="k">for</span> <span class="n">city</span> <span class="ow">in</span> <span class="n">AustraliaCity</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">distance</span><span class="p">(</span><span class="n">pnt</span><span class="p">):</span> <span class="nb">print</span><span class="p">(</span><span class="n">city</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">city</span><span class="o">.</span><span class="n">distance</span><span class="p">)</span>
<span class="go">Wollongong 990071.220408 m</span>
<span class="go">Shellharbour 972804.613941 m</span>
<span class="go">Thirroul 1002334.36351 m</span>
<span class="go">Mittagong 975691.632637 m</span>
<span class="go">Batemans Bay 834342.185561 m</span>
<span class="go">Canberra 598140.268959 m</span>
<span class="go">Melbourne 575337.765042 m</span>
<span class="go">Sydney 1056978.87363 m</span>
<span class="go">Hobart 0.0 m</span>
<span class="go">Adelaide 1162031.83522 m</span>
<span class="go">Hillsdale 1049200.46122 m</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Because the <code class="docutils literal notranslate"><span class="pre">distance</span></code> attribute is a
<a class="reference internal" href="measure.html#django.contrib.gis.measure.Distance" title="django.contrib.gis.measure.Distance"><code class="xref py py-class docutils literal notranslate"><span class="pre">Distance</span></code></a> object, you can easily express
the value in the units of your choice. For example, <code class="docutils literal notranslate"><span class="pre">city.distance.mi</span></code> is
the distance value in miles and <code class="docutils literal notranslate"><span class="pre">city.distance.km</span></code> is the distance value
in kilometers. See <a class="reference internal" href="measure.html"><span class="doc">Measurement Objects</span></a> for usage details and the list of
<a class="reference internal" href="measure.html#supported-units"><span class="std std-ref">Supported units</span></a>.</p>
</div>
</div>
<div class="section" id="s-length">
<span id="length"></span><h4><code class="docutils literal notranslate"><span class="pre">length</span></code><a class="headerlink" href="#length" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.length">
<code class="descclassname">GeoQuerySet.</code><code class="descname">length</code>(<em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.length" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.Length" title="django.contrib.gis.db.models.functions.Length"><code class="xref py py-class docutils literal notranslate"><span class="pre">Length</span></code></a> function
instead.</p>
</div>
<p>Returns the length of the geometry field in a <code class="docutils literal notranslate"><span class="pre">length</span></code> attribute
(a <a class="reference internal" href="measure.html#django.contrib.gis.measure.Distance" title="django.contrib.gis.measure.Distance"><code class="xref py py-class docutils literal notranslate"><span class="pre">Distance</span></code></a> object) on each model in
the queryset.</p>
</div>
<div class="section" id="s-perimeter">
<span id="perimeter"></span><h4><code class="docutils literal notranslate"><span class="pre">perimeter</span></code><a class="headerlink" href="#perimeter" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.perimeter">
<code class="descclassname">GeoQuerySet.</code><code class="descname">perimeter</code>(<em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.perimeter" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.Perimeter" title="django.contrib.gis.db.models.functions.Perimeter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Perimeter</span></code></a> function
instead.</p>
</div>
<p>Returns the perimeter of the geometry field in a <code class="docutils literal notranslate"><span class="pre">perimeter</span></code> attribute
(a <a class="reference internal" href="measure.html#django.contrib.gis.measure.Distance" title="django.contrib.gis.measure.Distance"><code class="xref py py-class docutils literal notranslate"><span class="pre">Distance</span></code></a> object) on each model in
the queryset.</p>
</div>
</div>
<div class="section" id="s-geometry-relationships">
<span id="geometry-relationships"></span><h3>Geometry Relationships<a class="headerlink" href="#geometry-relationships" title="Permalink to this headline">¶</a></h3>
<p>The following methods take no arguments, and attach geometry objects
each element of the <a class="reference internal" href="#django.contrib.gis.db.models.GeoQuerySet" title="django.contrib.gis.db.models.GeoQuerySet"><code class="xref py py-class docutils literal notranslate"><span class="pre">GeoQuerySet</span></code></a> that is the result of relationship
function evaluated on the geometry field.</p>
<div class="section" id="s-centroid">
<span id="centroid"></span><h4><code class="docutils literal notranslate"><span class="pre">centroid</span></code><a class="headerlink" href="#centroid" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.centroid">
<code class="descclassname">GeoQuerySet.</code><code class="descname">centroid</code>(<em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.centroid" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.Centroid" title="django.contrib.gis.db.models.functions.Centroid"><code class="xref py py-class docutils literal notranslate"><span class="pre">Centroid</span></code></a> function
instead.</p>
</div>
<p><em>Availability</em>: PostGIS, Oracle, SpatiaLite</p>
<p>Returns the <code class="docutils literal notranslate"><span class="pre">centroid</span></code> value for the geographic field in a <code class="docutils literal notranslate"><span class="pre">centroid</span></code>
attribute on each element of the <code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code>.</p>
</div>
<div class="section" id="s-envelope">
<span id="envelope"></span><h4><code class="docutils literal notranslate"><span class="pre">envelope</span></code><a class="headerlink" href="#envelope" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.envelope">
<code class="descclassname">GeoQuerySet.</code><code class="descname">envelope</code>(<em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.envelope" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.Envelope" title="django.contrib.gis.db.models.functions.Envelope"><code class="xref py py-class docutils literal notranslate"><span class="pre">Envelope</span></code></a> function
instead.</p>
</div>
<p><em>Availability</em>: PostGIS, SpatiaLite</p>
<p>Returns a geometry representing the bounding box of the geometry field in
an <code class="docutils literal notranslate"><span class="pre">envelope</span></code> attribute on each element of the <code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code>.</p>
</div>
<div class="section" id="s-point-on-surface">
<span id="point-on-surface"></span><h4><code class="docutils literal notranslate"><span class="pre">point_on_surface</span></code><a class="headerlink" href="#point-on-surface" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.point_on_surface">
<code class="descclassname">GeoQuerySet.</code><code class="descname">point_on_surface</code>(<em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.point_on_surface" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.PointOnSurface" title="django.contrib.gis.db.models.functions.PointOnSurface"><code class="xref py py-class docutils literal notranslate"><span class="pre">PointOnSurface</span></code></a>
function instead.</p>
</div>
<p><em>Availability</em>: PostGIS, Oracle, SpatiaLite</p>
<p>Returns a Point geometry guaranteed to lie on the surface of the
geometry field in a <code class="docutils literal notranslate"><span class="pre">point_on_surface</span></code> attribute on each element
of the queryset; otherwise sets with None.</p>
</div>
</div>
<div class="section" id="s-geometry-editors">
<span id="geometry-editors"></span><h3>Geometry Editors<a class="headerlink" href="#geometry-editors" title="Permalink to this headline">¶</a></h3>
<div class="section" id="s-force-rhr">
<span id="force-rhr"></span><h4><code class="docutils literal notranslate"><span class="pre">force_rhr</span></code><a class="headerlink" href="#force-rhr" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.force_rhr">
<code class="descclassname">GeoQuerySet.</code><code class="descname">force_rhr</code>(<em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.force_rhr" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.ForceRHR" title="django.contrib.gis.db.models.functions.ForceRHR"><code class="xref py py-class docutils literal notranslate"><span class="pre">ForceRHR</span></code></a> function
instead.</p>
</div>
<p><em>Availability</em>: PostGIS</p>
<p>Returns a modified version of the polygon/multipolygon in which all
of the vertices follow the Right-Hand-Rule, and attaches as a
<code class="docutils literal notranslate"><span class="pre">force_rhr</span></code> attribute on each element of the queryset.</p>
</div>
<div class="section" id="s-reverse-geom">
<span id="reverse-geom"></span><h4><code class="docutils literal notranslate"><span class="pre">reverse_geom</span></code><a class="headerlink" href="#reverse-geom" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.reverse_geom">
<code class="descclassname">GeoQuerySet.</code><code class="descname">reverse_geom</code>(<em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.reverse_geom" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.Reverse" title="django.contrib.gis.db.models.functions.Reverse"><code class="xref py py-class docutils literal notranslate"><span class="pre">Reverse</span></code></a> function
instead.</p>
</div>
<p><em>Availability</em>: PostGIS, Oracle</p>
<p>Reverse the coordinate order of the geometry field, and attaches as a
<code class="docutils literal notranslate"><span class="pre">reverse</span></code> attribute on each element of the queryset.</p>
</div>
<div class="section" id="s-scale">
<span id="scale"></span><h4><code class="docutils literal notranslate"><span class="pre">scale</span></code><a class="headerlink" href="#scale" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.scale">
<code class="descclassname">GeoQuerySet.</code><code class="descname">scale</code>(<em>x</em>, <em>y</em>, <em>z=0.0</em>, <em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.scale" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.Scale" title="django.contrib.gis.db.models.functions.Scale"><code class="xref py py-class docutils literal notranslate"><span class="pre">Scale</span></code></a> function
instead.</p>
</div>
<p><em>Availability</em>: PostGIS, SpatiaLite</p>
</div>
<div class="section" id="s-snap-to-grid">
<span id="snap-to-grid"></span><h4><code class="docutils literal notranslate"><span class="pre">snap_to_grid</span></code><a class="headerlink" href="#snap-to-grid" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.snap_to_grid">
<code class="descclassname">GeoQuerySet.</code><code class="descname">snap_to_grid</code>(<em>*args</em>, <em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.snap_to_grid" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.SnapToGrid" title="django.contrib.gis.db.models.functions.SnapToGrid"><code class="xref py py-class docutils literal notranslate"><span class="pre">SnapToGrid</span></code></a> function
instead.</p>
</div>
<p>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.</p>
<table class="docutils">
<colgroup>
<col width="26%" />
<col width="74%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Number of Arguments</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>1</td>
<td>A single size to snap bot the X and Y grids to.</td>
</tr>
<tr class="row-odd"><td>2</td>
<td>X and Y sizes to snap the grid to.</td>
</tr>
<tr class="row-even"><td>4</td>
<td>X, Y sizes and the corresponding X, Y origins.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-transform">
<span id="transform"></span><h4><code class="docutils literal notranslate"><span class="pre">transform</span></code><a class="headerlink" href="#transform" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.transform">
<code class="descclassname">GeoQuerySet.</code><code class="descname">transform</code>(<em>srid=4326</em>, <em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.transform" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.Transform" title="django.contrib.gis.db.models.functions.Transform"><code class="xref py py-class docutils literal notranslate"><span class="pre">Transform</span></code></a> function
instead.</p>
</div>
<p><em>Availability</em>: PostGIS, Oracle, SpatiaLite</p>
<p>The <code class="docutils literal notranslate"><span class="pre">transform</span></code> method transforms the geometry field of a model to the spatial
reference system specified by the <code class="docutils literal notranslate"><span class="pre">srid</span></code> parameter. If no <code class="docutils literal notranslate"><span class="pre">srid</span></code> is given,
then 4326 (WGS84) is used by default.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Unlike other <code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code> methods, <code class="docutils literal notranslate"><span class="pre">transform</span></code> stores its output
“in-place”. In other words, no new attribute for the transformed
geometry is placed on the models.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">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.</p>
</div>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">qs</span> <span class="o">=</span> <span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">all</span><span class="p">()</span><span class="o">.</span><span class="n">transform</span><span class="p">()</span> <span class="c1"># Transforms to WGS84</span>
<span class="gp">>>> </span><span class="n">qs</span> <span class="o">=</span> <span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">all</span><span class="p">()</span><span class="o">.</span><span class="n">transform</span><span class="p">(</span><span class="mi">32140</span><span class="p">)</span> <span class="c1"># Transforming to "NAD83 / Texas South Central"</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">qs</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">poly</span><span class="o">.</span><span class="n">srid</span><span class="p">)</span>
<span class="go">32140</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">qs</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">poly</span><span class="p">)</span>
<span class="go">POLYGON ((234055.1698884720099159 4937796.9232223574072123 ...</span>
</pre></div>
</div>
</div>
<div class="section" id="s-translate">
<span id="translate"></span><h4><code class="docutils literal notranslate"><span class="pre">translate</span></code><a class="headerlink" href="#translate" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.translate">
<code class="descclassname">GeoQuerySet.</code><code class="descname">translate</code>(<em>x</em>, <em>y</em>, <em>z=0.0</em>, <em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.translate" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.Translate" title="django.contrib.gis.db.models.functions.Translate"><code class="xref py py-class docutils literal notranslate"><span class="pre">Translate</span></code></a> function
instead.</p>
</div>
<p><em>Availability</em>: PostGIS, SpatiaLite</p>
<p>Translates the geometry field to a new location using the given numeric
parameters as offsets.</p>
</div>
</div>
<div class="section" id="s-geometry-operations">
<span id="geometry-operations"></span><h3>Geometry Operations<a class="headerlink" href="#geometry-operations" title="Permalink to this headline">¶</a></h3>
<p><em>Availability</em>: PostGIS, Oracle, SpatiaLite</p>
<p>The following methods all take a geometry as a parameter and attach a geometry
to each element of the <code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code> that is the result of the operation.</p>
<div class="section" id="s-difference">
<span id="difference"></span><h4><code class="docutils literal notranslate"><span class="pre">difference</span></code><a class="headerlink" href="#difference" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.difference">
<code class="descclassname">GeoQuerySet.</code><code class="descname">difference</code>(<em>geom</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.difference" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.Difference" title="django.contrib.gis.db.models.functions.Difference"><code class="xref py py-class docutils literal notranslate"><span class="pre">Difference</span></code></a> function
instead.</p>
</div>
<p>Returns the spatial difference of the geographic field with the given
geometry in a <code class="docutils literal notranslate"><span class="pre">difference</span></code> attribute on each element of the
<code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code>.</p>
</div>
<div class="section" id="s-intersection">
<span id="intersection"></span><h4><code class="docutils literal notranslate"><span class="pre">intersection</span></code><a class="headerlink" href="#intersection" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.intersection">
<code class="descclassname">GeoQuerySet.</code><code class="descname">intersection</code>(<em>geom</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.intersection" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.Intersection" title="django.contrib.gis.db.models.functions.Intersection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Intersection</span></code></a>
function instead.</p>
</div>
<p>Returns the spatial intersection of the geographic field with the
given geometry in an <code class="docutils literal notranslate"><span class="pre">intersection</span></code> attribute on each element of the
<code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code>.</p>
</div>
<div class="section" id="s-sym-difference">
<span id="sym-difference"></span><h4><code class="docutils literal notranslate"><span class="pre">sym_difference</span></code><a class="headerlink" href="#sym-difference" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.sym_difference">
<code class="descclassname">GeoQuerySet.</code><code class="descname">sym_difference</code>(<em>geom</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.sym_difference" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.SymDifference" title="django.contrib.gis.db.models.functions.SymDifference"><code class="xref py py-class docutils literal notranslate"><span class="pre">SymDifference</span></code></a>
function instead.</p>
</div>
<p>Returns the symmetric difference of the geographic field with the
given geometry in a <code class="docutils literal notranslate"><span class="pre">sym_difference</span></code> attribute on each element of the
<code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code>.</p>
</div>
<div class="section" id="s-union">
<span id="union"></span><h4><code class="docutils literal notranslate"><span class="pre">union</span></code><a class="headerlink" href="#union" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.union">
<code class="descclassname">GeoQuerySet.</code><code class="descname">union</code>(<em>geom</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.union" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.Union" title="django.contrib.gis.db.models.functions.Union"><code class="xref py py-class docutils literal notranslate"><span class="pre">Union</span></code></a> function
instead.</p>
</div>
<p>Returns the union of the geographic field with the given
geometry in an <code class="docutils literal notranslate"><span class="pre">union</span></code> attribute on each element of the
<code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code>.</p>
</div>
</div>
<div class="section" id="s-geometry-output">
<span id="geometry-output"></span><h3>Geometry Output<a class="headerlink" href="#geometry-output" title="Permalink to this headline">¶</a></h3>
<p>The following <code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code> methods will return an attribute that has the value
of the geometry field in each model converted to the requested output format.</p>
<div class="section" id="s-geohash">
<span id="geohash"></span><h4><code class="docutils literal notranslate"><span class="pre">geohash</span></code><a class="headerlink" href="#geohash" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.geohash">
<code class="descclassname">GeoQuerySet.</code><code class="descname">geohash</code>(<em>precision=20</em>, <em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.geohash" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.GeoHash" title="django.contrib.gis.db.models.functions.GeoHash"><code class="xref py py-class docutils literal notranslate"><span class="pre">GeoHash</span></code></a> function
instead.</p>
</div>
<p>Attaches a <code class="docutils literal notranslate"><span class="pre">geohash</span></code> attribute to every model the queryset
containing the <a class="reference external" href="http://geohash.org/">GeoHash</a> representation of the geometry.</p>
</div>
<div class="section" id="s-geojson">
<span id="geojson"></span><h4><code class="docutils literal notranslate"><span class="pre">geojson</span></code><a class="headerlink" href="#geojson" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.geojson">
<code class="descclassname">GeoQuerySet.</code><code class="descname">geojson</code>(<em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.geojson" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.AsGeoJSON" title="django.contrib.gis.db.models.functions.AsGeoJSON"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsGeoJSON</span></code></a> function
instead.</p>
</div>
<p><em>Availability</em>: PostGIS, SpatiaLite</p>
<p>Attaches a <code class="docutils literal notranslate"><span class="pre">geojson</span></code> attribute to every model in the queryset that contains the
<a class="reference external" href="http://geojson.org/">GeoJSON</a> representation of the geometry.</p>
<table class="docutils">
<colgroup>
<col width="28%" />
<col width="72%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Keyword Argument</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">precision</span></code></td>
<td>It may be used to specify the number of significant
digits for the coordinates in the GeoJSON
representation – the default value is 8.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">crs</span></code></td>
<td>Set this to <code class="docutils literal notranslate"><span class="pre">True</span></code> if you want the coordinate
reference system to be included in the returned
GeoJSON.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">bbox</span></code></td>
<td>Set this to <code class="docutils literal notranslate"><span class="pre">True</span></code> if you want the bounding box
to be included in the returned GeoJSON.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-gml">
<span id="gml"></span><h4><code class="docutils literal notranslate"><span class="pre">gml</span></code><a class="headerlink" href="#gml" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.gml">
<code class="descclassname">GeoQuerySet.</code><code class="descname">gml</code>(<em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.gml" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.AsGML" title="django.contrib.gis.db.models.functions.AsGML"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsGML</span></code></a> function
instead.</p>
</div>
<p><em>Availability</em>: PostGIS, Oracle, SpatiaLite</p>
<p>Attaches a <code class="docutils literal notranslate"><span class="pre">gml</span></code> attribute to every model in the queryset that contains the
<a class="reference external" href="https://en.wikipedia.org/wiki/Geography_Markup_Language">Geographic Markup Language (GML)</a> representation of the geometry.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">qs</span> <span class="o">=</span> <span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">all</span><span class="p">()</span><span class="o">.</span><span class="n">gml</span><span class="p">()</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">qs</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">gml</span><span class="p">)</span>
<span class="go"><gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ... -147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon></span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="28%" />
<col width="72%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Keyword Argument</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">precision</span></code></td>
<td>This keyword is for PostGIS only. It may be used
to specify the number of significant digits for the
coordinates in the GML representation – the default
value is 8.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">version</span></code></td>
<td>This keyword is for PostGIS only. It may be used to
specify the GML version used, and may only be values
of 2 or 3. The default value is 2.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-kml">
<span id="kml"></span><h4><code class="docutils literal notranslate"><span class="pre">kml</span></code><a class="headerlink" href="#kml" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.kml">
<code class="descclassname">GeoQuerySet.</code><code class="descname">kml</code>(<em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.kml" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.AsKML" title="django.contrib.gis.db.models.functions.AsKML"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsKML</span></code></a> function
instead.</p>
</div>
<p><em>Availability</em>: PostGIS, SpatiaLite</p>
<p>Attaches a <code class="docutils literal notranslate"><span class="pre">kml</span></code> attribute to every model in the queryset that contains the
<a class="reference external" href="https://developers.google.com/kml/documentation/">Keyhole Markup Language (KML)</a> representation of the geometry fields. It
should be noted that the contents of the KML are transformed to WGS84 if
necessary.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">qs</span> <span class="o">=</span> <span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">all</span><span class="p">()</span><span class="o">.</span><span class="n">kml</span><span class="p">()</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">qs</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">kml</span><span class="p">)</span>
<span class="go"><Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ... -103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon></span>
</pre></div>
</div>
<table class="docutils">
<colgroup>
<col width="28%" />
<col width="72%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Keyword Argument</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">precision</span></code></td>
<td>This keyword may be used to specify the number of
significant digits for the coordinates in the KML
representation – the default value is 8.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-svg">
<span id="svg"></span><h4><code class="docutils literal notranslate"><span class="pre">svg</span></code><a class="headerlink" href="#svg" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.svg">
<code class="descclassname">GeoQuerySet.</code><code class="descname">svg</code>(<em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.svg" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.AsSVG" title="django.contrib.gis.db.models.functions.AsSVG"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsSVG</span></code></a> function
instead.</p>
</div>
<p><em>Availability</em>: PostGIS, SpatiaLite</p>
<p>Attaches a <code class="docutils literal notranslate"><span class="pre">svg</span></code> attribute to every model in the queryset that contains
the <a class="reference external" href="http://www.w3.org/Graphics/SVG/">Scalable Vector Graphics (SVG)</a> path data of the geometry fields.</p>
<table class="docutils">
<colgroup>
<col width="28%" />
<col width="72%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Keyword Argument</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">relative</span></code></td>
<td>If set to <code class="docutils literal notranslate"><span class="pre">True</span></code>, the path data will be implemented
in terms of relative moves. Defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>,
meaning that absolute moves are used instead.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">precision</span></code></td>
<td>This keyword may be used to specify the number of
significant digits for the coordinates in the SVG
representation – the default value is 8.</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="s-miscellaneous">
<span id="miscellaneous"></span><h3>Miscellaneous<a class="headerlink" href="#miscellaneous" title="Permalink to this headline">¶</a></h3>
<div class="section" id="s-mem-size">
<span id="mem-size"></span><h4><code class="docutils literal notranslate"><span class="pre">mem_size</span></code><a class="headerlink" href="#mem-size" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.mem_size">
<code class="descclassname">GeoQuerySet.</code><code class="descname">mem_size</code>(<em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.mem_size" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.MemSize" title="django.contrib.gis.db.models.functions.MemSize"><code class="xref py py-class docutils literal notranslate"><span class="pre">MemSize</span></code></a> function
instead.</p>
</div>
<p><em>Availability</em>: PostGIS</p>
<p>Returns the memory size (number of bytes) that the geometry field takes
in a <code class="docutils literal notranslate"><span class="pre">mem_size</span></code> attribute on each element of the <code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code>.</p>
</div>
<div class="section" id="s-num-geom">
<span id="num-geom"></span><h4><code class="docutils literal notranslate"><span class="pre">num_geom</span></code><a class="headerlink" href="#num-geom" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.num_geom">
<code class="descclassname">GeoQuerySet.</code><code class="descname">num_geom</code>(<em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.num_geom" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.NumGeometries" title="django.contrib.gis.db.models.functions.NumGeometries"><code class="xref py py-class docutils literal notranslate"><span class="pre">NumGeometries</span></code></a>
function instead.</p>
</div>
<p><em>Availability</em>: PostGIS, Oracle, SpatiaLite</p>
<p>Returns the number of geometries in a <code class="docutils literal notranslate"><span class="pre">num_geom</span></code> attribute on
each element of the <code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code> if the geometry field is a
collection (e.g., a <code class="docutils literal notranslate"><span class="pre">GEOMETRYCOLLECTION</span></code> or <code class="docutils literal notranslate"><span class="pre">MULTI*</span></code> field);
otherwise sets with <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
</div>
<div class="section" id="s-num-points">
<span id="num-points"></span><h4><code class="docutils literal notranslate"><span class="pre">num_points</span></code><a class="headerlink" href="#num-points" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="django.contrib.gis.db.models.GeoQuerySet.num_points">
<code class="descclassname">GeoQuerySet.</code><code class="descname">num_points</code>(<em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.db.models.GeoQuerySet.num_points" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.9: </span>Use the <a class="reference internal" href="functions.html#django.contrib.gis.db.models.functions.NumPoints" title="django.contrib.gis.db.models.functions.NumPoints"><code class="xref py py-class docutils literal notranslate"><span class="pre">NumPoints</span></code></a> function
instead.</p>
</div>
<p><em>Availability</em>: PostGIS, Oracle, SpatiaLite</p>
<p>Returns the number of points in the first linestring in the
geometry field in a <code class="docutils literal notranslate"><span class="pre">num_points</span></code> attribute on each element of
the <code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code>; otherwise sets with <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
</div>
</div>
<div class="section" id="s-aggregate-functions">
<span id="aggregate-functions"></span><h3>Aggregate Functions<a class="headerlink" href="#aggregate-functions" title="Permalink to this headline">¶</a></h3>
<p>Django provides some GIS-specific aggregate functions. For details on how to
use these aggregate functions, see <a class="reference internal" href="../../../topics/db/aggregation.html"><span class="doc">the topic guide on aggregation</span></a>.</p>
<table class="docutils">
<colgroup>
<col width="28%" />
<col width="72%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Keyword Argument</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">tolerance</span></code></td>
<td>This keyword is for Oracle only. It is for the
tolerance value used by the <code class="docutils literal notranslate"><span class="pre">SDOAGGRTYPE</span></code>
procedure; the <a class="reference external" href="https://docs.oracle.com/database/121/SPATL/GUID-3BD00273-E74F-4830-9444-A3BB15AA0AC4.htm#SPATL466">Oracle documentation</a> has more
details.</td>
</tr>
</tbody>
</table>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.contrib.gis.db.models</span> <span class="k">import</span> <span class="n">Extent</span><span class="p">,</span> <span class="n">Union</span>
<span class="gp">>>> </span><span class="n">WorldBorder</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">aggregate</span><span class="p">(</span><span class="n">Extent</span><span class="p">(</span><span class="s1">'mpoly'</span><span class="p">),</span> <span class="n">Union</span><span class="p">(</span><span class="s1">'mpoly'</span><span class="p">))</span>
</pre></div>
</div>
<div class="section" id="s-collect">
<span id="collect"></span><h4><code class="docutils literal notranslate"><span class="pre">Collect</span></code><a class="headerlink" href="#collect" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.contrib.gis.db.models.Collect">
<em class="property">class </em><code class="descname">Collect</code>(<em>geo_field</em>)<a class="headerlink" href="#django.contrib.gis.db.models.Collect" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Collect.html">PostGIS</a>,
SpatiaLite</p>
<p>Returns a <code class="docutils literal notranslate"><span class="pre">GEOMETRYCOLLECTION</span></code> or a <code class="docutils literal notranslate"><span class="pre">MULTI</span></code> geometry object from the geometry
column. This is analogous to a simplified version of the <a class="reference internal" href="#django.contrib.gis.db.models.Union" title="django.contrib.gis.db.models.Union"><code class="xref py py-class docutils literal notranslate"><span class="pre">Union</span></code></a>
aggregate, except it can be several orders of magnitude faster than performing
a union because it simply rolls up geometries into a collection or multi object,
not caring about dissolving boundaries.</p>
</div>
<div class="section" id="s-extent">
<span id="extent"></span><h4><code class="docutils literal notranslate"><span class="pre">Extent</span></code><a class="headerlink" href="#extent" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.contrib.gis.db.models.Extent">
<em class="property">class </em><code class="descname">Extent</code>(<em>geo_field</em>)<a class="headerlink" href="#django.contrib.gis.db.models.Extent" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Extent.html">PostGIS</a>,
Oracle, SpatiaLite</p>
<p>Returns the extent of all <code class="docutils literal notranslate"><span class="pre">geo_field</span></code> in the <code class="docutils literal notranslate"><span class="pre">QuerySet</span></code> as a four-tuple,
comprising the lower left coordinate and the upper right coordinate.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">qs</span> <span class="o">=</span> <span class="n">City</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">name__in</span><span class="o">=</span><span class="p">(</span><span class="s1">'Houston'</span><span class="p">,</span> <span class="s1">'Dallas'</span><span class="p">))</span><span class="o">.</span><span class="n">aggregate</span><span class="p">(</span><span class="n">Extent</span><span class="p">(</span><span class="s1">'poly'</span><span class="p">))</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">qs</span><span class="p">[</span><span class="s1">'poly__extent'</span><span class="p">])</span>
<span class="go">(-96.8016128540039, 29.7633724212646, -95.3631439208984, 32.782058715820)</span>
</pre></div>
</div>
</div>
<div class="section" id="s-extent3d">
<span id="extent3d"></span><h4><code class="docutils literal notranslate"><span class="pre">Extent3D</span></code><a class="headerlink" href="#extent3d" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.contrib.gis.db.models.Extent3D">
<em class="property">class </em><code class="descname">Extent3D</code>(<em>geo_field</em>)<a class="headerlink" href="#django.contrib.gis.db.models.Extent3D" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_3DExtent.html">PostGIS</a></p>
<p>Returns the 3D extent of all <code class="docutils literal notranslate"><span class="pre">geo_field</span></code> in the <code class="docutils literal notranslate"><span class="pre">QuerySet</span></code> as a six-tuple,
comprising the lower left coordinate and upper right coordinate (each with x, y,
and z coordinates).</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">qs</span> <span class="o">=</span> <span class="n">City</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">name__in</span><span class="o">=</span><span class="p">(</span><span class="s1">'Houston'</span><span class="p">,</span> <span class="s1">'Dallas'</span><span class="p">))</span><span class="o">.</span><span class="n">aggregate</span><span class="p">(</span><span class="n">Extent3D</span><span class="p">(</span><span class="s1">'poly'</span><span class="p">))</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">qs</span><span class="p">[</span><span class="s1">'poly__extent3d'</span><span class="p">])</span>
<span class="go">(-96.8016128540039, 29.7633724212646, 0, -95.3631439208984, 32.782058715820, 0)</span>
</pre></div>
</div>
</div>
<div class="section" id="s-makeline">
<span id="makeline"></span><h4><code class="docutils literal notranslate"><span class="pre">MakeLine</span></code><a class="headerlink" href="#makeline" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.contrib.gis.db.models.MakeLine">
<em class="property">class </em><code class="descname">MakeLine</code>(<em>geo_field</em>)<a class="headerlink" href="#django.contrib.gis.db.models.MakeLine" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_MakeLine.html">PostGIS</a>,
SpatiaLite</p>
<p>Returns a <code class="docutils literal notranslate"><span class="pre">LineString</span></code> constructed from the point field geometries in the
<code class="docutils literal notranslate"><span class="pre">QuerySet</span></code>. Currently, ordering the queryset has no effect.</p>
<div class="versionchanged">
<span class="title">Changed in Django 1.10:</span> <p>SpatiaLite support was added.</p>
</div>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">qs</span> <span class="o">=</span> <span class="n">City</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">name__in</span><span class="o">=</span><span class="p">(</span><span class="s1">'Houston'</span><span class="p">,</span> <span class="s1">'Dallas'</span><span class="p">))</span><span class="o">.</span><span class="n">aggregate</span><span class="p">(</span><span class="n">MakeLine</span><span class="p">(</span><span class="s1">'poly'</span><span class="p">))</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">qs</span><span class="p">[</span><span class="s1">'poly__makeline'</span><span class="p">])</span>
<span class="go">LINESTRING (-95.3631510000000020 29.7633739999999989, -96.8016109999999941 32.7820570000000018)</span>
</pre></div>
</div>
</div>
<div class="section" id="s-id16">
<span id="id16"></span><h4><code class="docutils literal notranslate"><span class="pre">Union</span></code><a class="headerlink" href="#id16" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="django.contrib.gis.db.models.Union">
<em class="property">class </em><code class="descname">Union</code>(<em>geo_field</em>)<a class="headerlink" href="#django.contrib.gis.db.models.Union" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p><em>Availability</em>: <a class="reference external" href="https://postgis.net/docs/ST_Union.html">PostGIS</a>,
Oracle, SpatiaLite</p>
<p>This method returns a <a class="reference internal" href="geos.html#django.contrib.gis.geos.GEOSGeometry" title="django.contrib.gis.geos.GEOSGeometry"><code class="xref py py-class docutils literal notranslate"><span class="pre">GEOSGeometry</span></code></a> object
comprising the union of every geometry in the queryset. Please note that use of
<code class="docutils literal notranslate"><span class="pre">Union</span></code> is processor intensive and may take a significant amount of time on
large querysets.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If the computation time for using this method is too expensive, consider
using <a class="reference internal" href="#django.contrib.gis.db.models.Collect" title="django.contrib.gis.db.models.Collect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Collect</span></code></a> instead.</p>
</div>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">u</span> <span class="o">=</span> <span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">aggregate</span><span class="p">(</span><span class="n">Union</span><span class="p">(</span><span class="n">poly</span><span class="p">))</span> <span class="c1"># This may take a long time.</span>
<span class="gp">>>> </span><span class="n">u</span> <span class="o">=</span> <span class="n">Zipcode</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">poly__within</span><span class="o">=</span><span class="n">bbox</span><span class="p">)</span><span class="o">.</span><span class="n">aggregate</span><span class="p">(</span><span class="n">Union</span><span class="p">(</span><span class="n">poly</span><span class="p">))</span> <span class="c1"># A more sensible approach.</span>
</pre></div>
</div>
<p class="rubric">Footnotes</p>
<table class="docutils footnote" frame="void" id="fnde9im" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id4">[1]</a></td><td><em>See</em> <a class="reference external" href="http://www.opengis.org/docs/99-049.pdf">OpenGIS Simple Feature Specification For SQL</a>, at Ch. 2.1.13.2, p. 2-13 (The Dimensionally Extended Nine-Intersection Model).</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="fnsdorelate" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id5">[2]</a></td><td><em>See</em> <a class="reference external" href="https://docs.oracle.com/database/121/SPATL/sdo_relate.htm#SPATL1039">SDO_RELATE documentation</a>, from the Oracle Spatial and Graph Developer’s Guide.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="fncovers" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[3]</td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id3">2</a>)</em> For an explanation of this routine, read <a class="reference external" href="http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html">Quirks of the “Contains” Spatial Predicate</a> by Martin Davis (a PostGIS developer).</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../../../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">GeoQuerySet API Reference</a><ul>
<li><a class="reference internal" href="#spatial-lookups">Spatial Lookups</a><ul>
<li><a class="reference internal" href="#lookups-with-rasters">Lookups with rasters</a></li>
<li><a class="reference internal" href="#bbcontains"><code class="docutils literal notranslate"><span class="pre">bbcontains</span></code></a></li>
<li><a class="reference internal" href="#bboverlaps"><code class="docutils literal notranslate"><span class="pre">bboverlaps</span></code></a></li>
<li><a class="reference internal" href="#contained"><code class="docutils literal notranslate"><span class="pre">contained</span></code></a></li>
<li><a class="reference internal" href="#contains"><code class="docutils literal notranslate"><span class="pre">contains</span></code></a></li>
<li><a class="reference internal" href="#contains-properly"><code class="docutils literal notranslate"><span class="pre">contains_properly</span></code></a></li>
<li><a class="reference internal" href="#coveredby"><code class="docutils literal notranslate"><span class="pre">coveredby</span></code></a></li>
<li><a class="reference internal" href="#covers"><code class="docutils literal notranslate"><span class="pre">covers</span></code></a></li>
<li><a class="reference internal" href="#crosses"><code class="docutils literal notranslate"><span class="pre">crosses</span></code></a></li>
<li><a class="reference internal" href="#disjoint"><code class="docutils literal notranslate"><span class="pre">disjoint</span></code></a></li>
<li><a class="reference internal" href="#equals"><code class="docutils literal notranslate"><span class="pre">equals</span></code></a></li>
<li><a class="reference internal" href="#exact-same-as"><code class="docutils literal notranslate"><span class="pre">exact</span></code>, <code class="docutils literal notranslate"><span class="pre">same_as</span></code></a></li>
<li><a class="reference internal" href="#intersects"><code class="docutils literal notranslate"><span class="pre">intersects</span></code></a></li>
<li><a class="reference internal" href="#isvalid"><code class="docutils literal notranslate"><span class="pre">isvalid</span></code></a></li>
<li><a class="reference internal" href="#overlaps"><code class="docutils literal notranslate"><span class="pre">overlaps</span></code></a></li>
<li><a class="reference internal" href="#relate"><code class="docutils literal notranslate"><span class="pre">relate</span></code></a><ul>
<li><a class="reference internal" href="#postgis-spatialite">PostGIS & SpatiaLite</a></li>
<li><a class="reference internal" href="#oracle">Oracle</a></li>
</ul>
</li>
<li><a class="reference internal" href="#touches"><code class="docutils literal notranslate"><span class="pre">touches</span></code></a></li>
<li><a class="reference internal" href="#within"><code class="docutils literal notranslate"><span class="pre">within</span></code></a></li>
<li><a class="reference internal" href="#left"><code class="docutils literal notranslate"><span class="pre">left</span></code></a></li>
<li><a class="reference internal" href="#right"><code class="docutils literal notranslate"><span class="pre">right</span></code></a></li>
<li><a class="reference internal" href="#overlaps-left"><code class="docutils literal notranslate"><span class="pre">overlaps_left</span></code></a></li>
<li><a class="reference internal" href="#overlaps-right"><code class="docutils literal notranslate"><span class="pre">overlaps_right</span></code></a></li>
<li><a class="reference internal" href="#overlaps-above"><code class="docutils literal notranslate"><span class="pre">overlaps_above</span></code></a></li>
<li><a class="reference internal" href="#overlaps-below"><code class="docutils literal notranslate"><span class="pre">overlaps_below</span></code></a></li>
<li><a class="reference internal" href="#strictly-above"><code class="docutils literal notranslate"><span class="pre">strictly_above</span></code></a></li>
<li><a class="reference internal" href="#strictly-below"><code class="docutils literal notranslate"><span class="pre">strictly_below</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#distance-lookups">Distance Lookups</a><ul>
<li><a class="reference internal" href="#distance-gt"><code class="docutils literal notranslate"><span class="pre">distance_gt</span></code></a></li>
<li><a class="reference internal" href="#distance-gte"><code class="docutils literal notranslate"><span class="pre">distance_gte</span></code></a></li>
<li><a class="reference internal" href="#distance-lt"><code class="docutils literal notranslate"><span class="pre">distance_lt</span></code></a></li>
<li><a class="reference internal" href="#distance-lte"><code class="docutils literal notranslate"><span class="pre">distance_lte</span></code></a></li>
<li><a class="reference internal" href="#dwithin"><code class="docutils literal notranslate"><span class="pre">dwithin</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#geoqueryset-methods"><code class="docutils literal notranslate"><span class="pre">GeoQuerySet</span></code> Methods</a><ul>
<li><a class="reference internal" href="#measurement">Measurement</a><ul>
<li><a class="reference internal" href="#area"><code class="docutils literal notranslate"><span class="pre">area</span></code></a></li>
<li><a class="reference internal" href="#distance"><code class="docutils literal notranslate"><span class="pre">distance</span></code></a></li>
<li><a class="reference internal" href="#length"><code class="docutils literal notranslate"><span class="pre">length</span></code></a></li>
<li><a class="reference internal" href="#perimeter"><code class="docutils literal notranslate"><span class="pre">perimeter</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#geometry-relationships">Geometry Relationships</a><ul>
<li><a class="reference internal" href="#centroid"><code class="docutils literal notranslate"><span class="pre">centroid</span></code></a></li>
<li><a class="reference internal" href="#envelope"><code class="docutils literal notranslate"><span class="pre">envelope</span></code></a></li>
<li><a class="reference internal" href="#point-on-surface"><code class="docutils literal notranslate"><span class="pre">point_on_surface</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#geometry-editors">Geometry Editors</a><ul>
<li><a class="reference internal" href="#force-rhr"><code class="docutils literal notranslate"><span class="pre">force_rhr</span></code></a></li>
<li><a class="reference internal" href="#reverse-geom"><code class="docutils literal notranslate"><span class="pre">reverse_geom</span></code></a></li>
<li><a class="reference internal" href="#scale"><code class="docutils literal notranslate"><span class="pre">scale</span></code></a></li>
<li><a class="reference internal" href="#snap-to-grid"><code class="docutils literal notranslate"><span class="pre">snap_to_grid</span></code></a></li>
<li><a class="reference internal" href="#transform"><code class="docutils literal notranslate"><span class="pre">transform</span></code></a></li>
<li><a class="reference internal" href="#translate"><code class="docutils literal notranslate"><span class="pre">translate</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#geometry-operations">Geometry Operations</a><ul>
<li><a class="reference internal" href="#difference"><code class="docutils literal notranslate"><span class="pre">difference</span></code></a></li>
<li><a class="reference internal" href="#intersection"><code class="docutils literal notranslate"><span class="pre">intersection</span></code></a></li>
<li><a class="reference internal" href="#sym-difference"><code class="docutils literal notranslate"><span class="pre">sym_difference</span></code></a></li>
<li><a class="reference internal" href="#union"><code class="docutils literal notranslate"><span class="pre">union</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#geometry-output">Geometry Output</a><ul>
<li><a class="reference internal" href="#geohash"><code class="docutils literal notranslate"><span class="pre">geohash</span></code></a></li>
<li><a class="reference internal" href="#geojson"><code class="docutils literal notranslate"><span class="pre">geojson</span></code></a></li>
<li><a class="reference internal" href="#gml"><code class="docutils literal notranslate"><span class="pre">gml</span></code></a></li>
<li><a class="reference internal" href="#kml"><code class="docutils literal notranslate"><span class="pre">kml</span></code></a></li>
<li><a class="reference internal" href="#svg"><code class="docutils literal notranslate"><span class="pre">svg</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#miscellaneous">Miscellaneous</a><ul>
<li><a class="reference internal" href="#mem-size"><code class="docutils literal notranslate"><span class="pre">mem_size</span></code></a></li>
<li><a class="reference internal" href="#num-geom"><code class="docutils literal notranslate"><span class="pre">num_geom</span></code></a></li>
<li><a class="reference internal" href="#num-points"><code class="docutils literal notranslate"><span class="pre">num_points</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#aggregate-functions">Aggregate Functions</a><ul>
<li><a class="reference internal" href="#collect"><code class="docutils literal notranslate"><span class="pre">Collect</span></code></a></li>
<li><a class="reference internal" href="#extent"><code class="docutils literal notranslate"><span class="pre">Extent</span></code></a></li>
<li><a class="reference internal" href="#extent3d"><code class="docutils literal notranslate"><span class="pre">Extent3D</span></code></a></li>
<li><a class="reference internal" href="#makeline"><code class="docutils literal notranslate"><span class="pre">MakeLine</span></code></a></li>
<li><a class="reference internal" href="#id16"><code class="docutils literal notranslate"><span class="pre">Union</span></code></a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="forms-api.html"
title="previous chapter">GeoDjango Forms API</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="functions.html"
title="next chapter">Geographic Database Functions</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../../_sources/ref/contrib/gis/geoquerysets.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Feb 11, 2019</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="forms-api.html" title="GeoDjango Forms API">previous</a>
|
<a href="../../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="functions.html" title="Geographic Database Functions">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
