class GeoQuerySet(model=None)
The spatial lookups in this section are available for GeometryField
and RasterField
.
For an introduction, see the spatial lookups introduction. For an overview of what lookups are compatible with a particular spatial backend, refer to the spatial lookup compatibility table.
Spatial lookups now support raster input.
All examples in the reference below are given for geometry fields and inputs, but the lookups can be used the same way with rasters on both sides. Whenever a lookup doesn’t support raster input, the input is automatically converted to a geometry where necessary using the ST_Polygon function. See also the introduction to raster lookups.
The database operators used by the lookups can be divided into three categories:
N
: the operator accepts rasters natively on both sides of the lookup, and raster input can be mixed with geometry inputs.B
: the operator supports rasters only if both sides of the lookup receive raster inputs. Raster data is automatically converted to geometries for mixed lookups.C
. The lookup does not have native raster support, all raster data is automatically converted to geometries.The examples below show the SQL equivalent for the lookups in the different types of raster support. The same pattern applies to all spatial lookups.
Case | Lookup | SQL Equivalent |
---|---|---|
N, B | rast__contains=rst | ST_Contains(rast, rst) |
N, B | rast__1__contains=(rst, 2) | ST_Contains(rast, 1, rst, 2) |
B, C | rast__contains=geom | ST_Contains(ST_Polygon(rast), geom) |
B, C | rast__1__contains=geom | ST_Contains(ST_Polygon(rast, 1), geom) |
B, C | poly__contains=rst | ST_Contains(poly, ST_Polygon(rst)) |
B, C | poly__contains=(rst, 1) | ST_Contains(poly, ST_Polygon(rst, 1)) |
C | rast__crosses=rst | ST_Crosses(ST_Polygon(rast), ST_Polygon(rst)) |
C | rast__1__crosses=(rst, 2) | ST_Crosses(ST_Polygon(rast, 1), ST_Polygon(rst, 2)) |
C | rast__crosses=geom | ST_Crosses(ST_Polygon(rast), geom) |
C | poly__crosses=rst | ST_Crosses(poly, ST_Polygon(rst)) |
Spatial lookups with rasters are only supported for PostGIS backends (denominated as PGRaster in this section).
bbcontains
Availability: PostGIS, MySQL, SpatiaLite, PGRaster (Native)
Tests if the geometry or raster field’s bounding box completely contains the lookup geometry’s bounding box.
Example:
Zipcode.objects.filter(poly__bbcontains=geom)
Backend | SQL Equivalent |
---|---|
PostGIS | poly ~ geom |
MySQL | MBRContains(poly, geom) |
SpatiaLite | MbrContains(poly, geom) |
bboverlaps
Availability: PostGIS, MySQL, SpatiaLite, PGRaster (Native)
Tests if the geometry field’s bounding box overlaps the lookup geometry’s bounding box.
Example:
Zipcode.objects.filter(poly__bboverlaps=geom)
Backend | SQL Equivalent |
---|---|
PostGIS | poly && geom |
MySQL | MBROverlaps(poly, geom) |
SpatiaLite | MbrOverlaps(poly, geom) |
contained
Availability: PostGIS, MySQL, SpatiaLite, PGRaster (Native)
Tests if the geometry field’s bounding box is completely contained by the lookup geometry’s bounding box.
Example:
Zipcode.objects.filter(poly__contained=geom)
Backend | SQL Equivalent |
---|---|
PostGIS | poly @ geom |
MySQL | MBRWithin(poly, geom) |
SpatiaLite | MbrWithin(poly, geom) |
contains
Availability: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)
Tests if the geometry field spatially contains the lookup geometry.
Example:
Zipcode.objects.filter(poly__contains=geom)
Backend | SQL Equivalent |
---|---|
PostGIS | ST_Contains(poly, geom) |
Oracle | SDO_CONTAINS(poly, geom) |
MySQL | MBRContains(poly, geom) |
SpatiaLite | Contains(poly, geom) |
contains_properly
Availability: PostGIS, PGRaster (Bilateral)
Returns true if the lookup geometry intersects the interior of the geometry field, but not the boundary (or exterior).
Example:
Zipcode.objects.filter(poly__contains_properly=geom)
Backend | SQL Equivalent |
---|---|
PostGIS | ST_ContainsProperly(poly, geom) |
coveredby
Availability: PostGIS, Oracle, PGRaster (Bilateral)
Tests if no point in the geometry field is outside the lookup geometry. [3]
Example:
Zipcode.objects.filter(poly__coveredby=geom)
Backend | SQL Equivalent |
---|---|
PostGIS | ST_CoveredBy(poly, geom) |
Oracle | SDO_COVEREDBY(poly, geom) |
covers
Availability: PostGIS, Oracle, PGRaster (Bilateral)
Tests if no point in the lookup geometry is outside the geometry field. [3]
Example:
Zipcode.objects.filter(poly__covers=geom)
Backend | SQL Equivalent |
---|---|
PostGIS | ST_Covers(poly, geom) |
Oracle | SDO_COVERS(poly, geom) |
crosses
Availability: PostGIS, SpatiaLite, PGRaster (Conversion)
Tests if the geometry field spatially crosses the lookup geometry.
Example:
Zipcode.objects.filter(poly__crosses=geom)
Backend | SQL Equivalent |
---|---|
PostGIS | ST_Crosses(poly, geom) |
SpatiaLite | Crosses(poly, geom) |
disjoint
Availability: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)
Tests if the geometry field is spatially disjoint from the lookup geometry.
Example:
Zipcode.objects.filter(poly__disjoint=geom)
Backend | SQL Equivalent |
---|---|
PostGIS | ST_Disjoint(poly, geom) |
Oracle | SDO_GEOM.RELATE(poly, 'DISJOINT', geom, 0.05) |
MySQL | MBRDisjoint(poly, geom) |
SpatiaLite | Disjoint(poly, geom) |
equals
Availability: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Conversion)
exact
, same_as
Availability: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)
intersects
Availability: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)
Tests if the geometry field spatially intersects the lookup geometry.
Example:
Zipcode.objects.filter(poly__intersects=geom)
Backend | SQL Equivalent |
---|---|
PostGIS | ST_Intersects(poly, geom) |
Oracle | SDO_OVERLAPBDYINTERSECT(poly, geom) |
MySQL | MBRIntersects(poly, geom) |
SpatiaLite | Intersects(poly, geom) |
isvalid
Availability: PostGIS, Oracle, SpatiaLite
Tests if the geometry is valid.
Example:
Zipcode.objects.filter(poly__isvalid=True)
Backend | SQL Equivalent |
---|---|
PostGIS, SpatiaLite | ST_IsValid(poly) |
Oracle | SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT(poly, 0.05) = 'TRUE' |
Oracle and SpatiaLite support was added.
overlaps
Availability: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)
relate
Availability: PostGIS, Oracle, SpatiaLite, PGRaster (Conversion)
Tests if the geometry field is spatially related to the lookup geometry by the values given in the given pattern. This lookup requires a tuple parameter, (geom, pattern)
; the form of pattern
will depend on the spatial backend:
On these spatial backends the intersection pattern is a string comprising nine characters, which define intersections between the interior, boundary, and exterior of the geometry field and the lookup geometry. The intersection pattern matrix may only use the following characters: 1
, 2
, T
, F
, or *
. This lookup type allows users to “fine tune” a specific geometric relationship consistent with the DE-9IM model. [1]
Geometry example:
# A tuple lookup parameter is used to specify the geometry and # the intersection pattern (the pattern here is for 'contains'). Zipcode.objects.filter(poly__relate=(geom, 'T*T***FF*'))
PostGIS SQL equivalent:
SELECT ... WHERE ST_Relate(poly, geom, 'T*T***FF*')
SpatiaLite SQL equivalent:
SELECT ... WHERE Relate(poly, geom, 'T*T***FF*')
Raster example:
Zipcode.objects.filter(poly__relate=(rast, 1, 'T*T***FF*')) Zipcode.objects.filter(rast__2__relate=(rast, 1, 'T*T***FF*'))
PostGIS SQL equivalent:
SELECT ... WHERE ST_Relate(poly, ST_Polygon(rast, 1), 'T*T***FF*') SELECT ... WHERE ST_Relate(ST_Polygon(rast, 2), ST_Polygon(rast, 1), 'T*T***FF*')
Here the relation pattern is comprised of at least one of the nine relation strings: TOUCH
, OVERLAPBDYDISJOINT
, OVERLAPBDYINTERSECT
, EQUAL
, INSIDE
, COVEREDBY
, CONTAINS
, COVERS
, ON
, and ANYINTERACT
. Multiple strings may be combined with the logical Boolean operator OR, for example, 'inside+touch'
. [2] The relation strings are case-insensitive.
Example:
Zipcode.objects.filter(poly__relate=(geom, 'anyinteract'))
Oracle SQL equivalent:
SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract')
touches
Availability: PostGIS, Oracle, MySQL, SpatiaLite
Tests if the geometry field spatially touches the lookup geometry.
Example:
Zipcode.objects.filter(poly__touches=geom)
Backend | SQL Equivalent |
---|---|
PostGIS | ST_Touches(poly, geom) |
MySQL | MBRTouches(poly, geom) |
Oracle | SDO_TOUCH(poly, geom) |
SpatiaLite | Touches(poly, geom) |
within
Availability: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)
Tests if the geometry field is spatially within the lookup geometry.
Example:
Zipcode.objects.filter(poly__within=geom)
Backend | SQL Equivalent |
---|---|
PostGIS | ST_Within(poly, geom) |
MySQL | MBRWithin(poly, geom) |
Oracle | SDO_INSIDE(poly, geom) |
SpatiaLite | Within(poly, geom) |
left
Availability: PostGIS, PGRaster (Conversion)
Tests if the geometry field’s bounding box is strictly to the left of the lookup geometry’s bounding box.
Example:
Zipcode.objects.filter(poly__left=geom)
PostGIS equivalent:
SELECT ... WHERE poly << geom
right
Availability: PostGIS, PGRaster (Conversion)
Tests if the geometry field’s bounding box is strictly to the right of the lookup geometry’s bounding box.
Example:
Zipcode.objects.filter(poly__right=geom)
PostGIS equivalent:
SELECT ... WHERE poly >> geom
overlaps_left
Availability: PostGIS, PGRaster (Bilateral)
Tests if the geometry field’s bounding box overlaps or is to the left of the lookup geometry’s bounding box.
Example:
Zipcode.objects.filter(poly__overlaps_left=geom)
PostGIS equivalent:
SELECT ... WHERE poly &< geom
overlaps_right
Availability: PostGIS, PGRaster (Bilateral)
Tests if the geometry field’s bounding box overlaps or is to the right of the lookup geometry’s bounding box.
Example:
Zipcode.objects.filter(poly__overlaps_right=geom)
PostGIS equivalent:
SELECT ... WHERE poly &> geom
overlaps_above
Availability: PostGIS, PGRaster (Conversion)
Tests if the geometry field’s bounding box overlaps or is above the lookup geometry’s bounding box.
Example:
Zipcode.objects.filter(poly__overlaps_above=geom)
PostGIS equivalent:
SELECT ... WHERE poly |&> geom
overlaps_below
Availability: PostGIS, PGRaster (Conversion)
Tests if the geometry field’s bounding box overlaps or is below the lookup geometry’s bounding box.
Example:
Zipcode.objects.filter(poly__overlaps_below=geom)
PostGIS equivalent:
SELECT ... WHERE poly &<| geom
strictly_above
Availability: PostGIS, PGRaster (Conversion)
Tests if the geometry field’s bounding box is strictly above the lookup geometry’s bounding box.
Example:
Zipcode.objects.filter(poly__strictly_above=geom)
PostGIS equivalent:
SELECT ... WHERE poly |>> geom
strictly_below
Availability: PostGIS, PGRaster (Conversion)
Tests if the geometry field’s bounding box is strictly below the lookup geometry’s bounding box.
Example:
Zipcode.objects.filter(poly__strictly_below=geom)
PostGIS equivalent:
SELECT ... WHERE poly <<| geom
Availability: PostGIS, Oracle, SpatiaLite, PGRaster (Native)
For an overview on performing distance queries, please refer to the distance queries introduction.
Distance lookups take the following form:
<field>__<distance lookup>=(<geometry/raster>, <distance value>[, 'spheroid']) <field>__<distance lookup>=(<raster>, <band_index>, <distance value>[, 'spheroid']) <field>__<band_index>__<distance lookup>=(<raster>, <band_index>, <distance value>[, 'spheroid'])
The value passed into a distance lookup is a tuple; the first two values are mandatory, and are the geometry to calculate distances to, and a distance value (either a number in units of the field, a Distance
object, or a query expression <ref/models/expressions>
). To pass a band index to the lookup, use a 3-tuple where the second entry is the band index.
On every distance lookup except dwithin
, an optional element, 'spheroid'
, may be included to use the more accurate spheroid distance calculation functions on fields with a geodetic coordinate system.
On PostgreSQL, the 'spheroid'
option uses ST_DistanceSpheroid instead of ST_DistanceSphere. The simpler ST_Distance function is used with projected coordinate systems. Rasters are converted to geometries for spheroid based lookups.
The ability to pass an expression as the distance value was added.
Support for the 'spheroid'
option on SQLite was added.
distance_gt
Returns models where the distance to the geometry field from the lookup geometry is greater than the given distance value.
Example:
Zipcode.objects.filter(poly__distance_gt=(geom, D(m=5)))
Backend | SQL Equivalent |
---|---|
PostGIS | ST_Distance/ST_Distance_Sphere(poly, geom) > 5 |
Oracle | SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) > 5 |
SpatiaLite | Distance(poly, geom) > 5 |
distance_gte
Returns models where the distance to the geometry field from the lookup geometry is greater than or equal to the given distance value.
Example:
Zipcode.objects.filter(poly__distance_gte=(geom, D(m=5)))
Backend | SQL Equivalent |
---|---|
PostGIS | ST_Distance/ST_Distance_Sphere(poly, geom) >= 5 |
Oracle | SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) >= 5 |
SpatiaLite | Distance(poly, geom) >= 5 |
distance_lt
Returns models where the distance to the geometry field from the lookup geometry is less than the given distance value.
Example:
Zipcode.objects.filter(poly__distance_lt=(geom, D(m=5)))
Backend | SQL Equivalent |
---|---|
PostGIS | ST_Distance/ST_Distance_Sphere(poly, geom) < 5 |
Oracle | SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) < 5 |
SpatiaLite | Distance(poly, geom) < 5 |
distance_lte
Returns models where the distance to the geometry field from the lookup geometry is less than or equal to the given distance value.
Example:
Zipcode.objects.filter(poly__distance_lte=(geom, D(m=5)))
Backend | SQL Equivalent |
---|---|
PostGIS | ST_Distance/ST_Distance_Sphere(poly, geom) <= 5 |
Oracle | SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) <= 5 |
SpatiaLite | Distance(poly, geom) <= 5 |
dwithin
Returns models where the distance to the geometry field from the lookup geometry are within the given distance from one another. Note that you can only provide Distance
objects if the targeted geometries are in a projected system. For geographic geometries, you should use units of the geometry field (e.g. degrees for WGS84
) .
Example:
Zipcode.objects.filter(poly__dwithin=(geom, D(m=5)))
Backend | SQL Equivalent |
---|---|
PostGIS | ST_DWithin(poly, geom, 5) |
Oracle | SDO_WITHIN_DISTANCE(poly, geom, 5) |
SpatiaLite | PtDistWithin(poly, geom, 5) |
SpatiaLite support was added.
GeoQuerySet
MethodsDeprecated since version 1.9: Using GeoQuerySet
methods is now deprecated in favor of the new Geographic Database Functions. Albeit a little more verbose, they are much more powerful in how it is possible to combine them to build more complex queries.
GeoQuerySet
methods specify that a spatial operation be performed on each spatial operation on each geographic field in the queryset and store its output in a new attribute on the model (which is generally the name of the GeoQuerySet
method).
There are also aggregate GeoQuerySet
methods which return a single value instead of a queryset. This section will describe the API and availability of every GeoQuerySet
method available in GeoDjango.
Note
What methods are available depend on your spatial backend. See the compatibility table for more details.
With a few exceptions, the following keyword arguments may be used with all GeoQuerySet
methods:
Keyword Argument | Description |
---|---|
field_name |
By default, On PostGIS, the |
model_att |
By default, This keyword is required if a method name clashes with an existing |
Availability: PostGIS, Oracle, SpatiaLite
area
GeoQuerySet.area(**kwargs)
Deprecated since version 1.9: Use the Area
function instead.
Returns the area of the geographic field in an area
attribute on each element of this GeoQuerySet.
distance
GeoQuerySet.distance(geom, **kwargs)
Deprecated since version 1.9: Use the Distance
function instead.
This method takes a geometry as a parameter, and attaches a distance
attribute to every model in the returned queryset that contains the distance (as a Distance
object) to the given geometry.
In the following example (taken from the GeoDjango distance tests), the distance from the Tasmanian city of Hobart to every other PointField
in the AustraliaCity
queryset is calculated:
>>> pnt = AustraliaCity.objects.get(name='Hobart').point >>> for city in AustraliaCity.objects.distance(pnt): print(city.name, city.distance) Wollongong 990071.220408 m Shellharbour 972804.613941 m Thirroul 1002334.36351 m Mittagong 975691.632637 m Batemans Bay 834342.185561 m Canberra 598140.268959 m Melbourne 575337.765042 m Sydney 1056978.87363 m Hobart 0.0 m Adelaide 1162031.83522 m Hillsdale 1049200.46122 m
Note
Because the distance
attribute is a Distance
object, you can easily express the value in the units of your choice. For example, city.distance.mi
is the distance value in miles and city.distance.km
is the distance value in kilometers. See Measurement Objects for usage details and the list of Supported units.
length
GeoQuerySet.length(**kwargs)
Deprecated since version 1.9: Use the Length
function instead.
Returns the length of the geometry field in a length
attribute (a Distance
object) on each model in the queryset.
perimeter
GeoQuerySet.perimeter(**kwargs)
Deprecated since version 1.9: Use the Perimeter
function instead.
Returns the perimeter of the geometry field in a perimeter
attribute (a Distance
object) on each model in the queryset.
The following methods take no arguments, and attach geometry objects each element of the GeoQuerySet
that is the result of relationship function evaluated on the geometry field.
centroid
GeoQuerySet.centroid(**kwargs)
Deprecated since version 1.9: Use the Centroid
function instead.
Availability: PostGIS, Oracle, SpatiaLite
Returns the centroid
value for the geographic field in a centroid
attribute on each element of the GeoQuerySet
.
envelope
GeoQuerySet.envelope(**kwargs)
Deprecated since version 1.9: Use the Envelope
function instead.
Availability: PostGIS, SpatiaLite
Returns a geometry representing the bounding box of the geometry field in an envelope
attribute on each element of the GeoQuerySet
.
point_on_surface
GeoQuerySet.point_on_surface(**kwargs)
Deprecated since version 1.9: Use the PointOnSurface
function instead.
Availability: PostGIS, Oracle, SpatiaLite
Returns a Point geometry guaranteed to lie on the surface of the geometry field in a point_on_surface
attribute on each element of the queryset; otherwise sets with None.
force_rhr
GeoQuerySet.force_rhr(**kwargs)
Deprecated since version 1.9: Use the ForceRHR
function instead.
Availability: PostGIS
Returns a modified version of the polygon/multipolygon in which all of the vertices follow the Right-Hand-Rule, and attaches as a force_rhr
attribute on each element of the queryset.
reverse_geom
GeoQuerySet.reverse_geom(**kwargs)
Deprecated since version 1.9: Use the Reverse
function instead.
Availability: PostGIS, Oracle
Reverse the coordinate order of the geometry field, and attaches as a reverse
attribute on each element of the queryset.
scale
GeoQuerySet.scale(x, y, z=0.0, **kwargs)
Deprecated since version 1.9: Use the Scale
function instead.
Availability: PostGIS, SpatiaLite
snap_to_grid
GeoQuerySet.snap_to_grid(*args, **kwargs)
Deprecated since version 1.9: Use the SnapToGrid
function instead.
Snap all points of the input geometry to the grid. How the geometry is snapped to the grid depends on how many numeric (either float, integer, or long) arguments are given.
Number of Arguments | Description |
---|---|
1 | A single size to snap bot the X and Y grids to. |
2 | X and Y sizes to snap the grid to. |
4 | X, Y sizes and the corresponding X, Y origins. |
transform
GeoQuerySet.transform(srid=4326, **kwargs)
Deprecated since version 1.9: Use the Transform
function instead.
Availability: PostGIS, Oracle, SpatiaLite
The transform
method transforms the geometry field of a model to the spatial reference system specified by the srid
parameter. If no srid
is given, then 4326 (WGS84) is used by default.
Note
Unlike other GeoQuerySet
methods, transform
stores its output “in-place”. In other words, no new attribute for the transformed geometry is placed on the models.
Note
What spatial reference system an integer SRID corresponds to may depend on the spatial database used. In other words, the SRID numbers used for Oracle are not necessarily the same as those used by PostGIS.
Example:
>>> qs = Zipcode.objects.all().transform() # Transforms to WGS84 >>> qs = Zipcode.objects.all().transform(32140) # Transforming to "NAD83 / Texas South Central" >>> print(qs[0].poly.srid) 32140 >>> print(qs[0].poly) POLYGON ((234055.1698884720099159 4937796.9232223574072123 ...
translate
GeoQuerySet.translate(x, y, z=0.0, **kwargs)
Deprecated since version 1.9: Use the Translate
function instead.
Availability: PostGIS, SpatiaLite
Translates the geometry field to a new location using the given numeric parameters as offsets.
Availability: PostGIS, Oracle, SpatiaLite
The following methods all take a geometry as a parameter and attach a geometry to each element of the GeoQuerySet
that is the result of the operation.
difference
GeoQuerySet.difference(geom)
Deprecated since version 1.9: Use the Difference
function instead.
Returns the spatial difference of the geographic field with the given geometry in a difference
attribute on each element of the GeoQuerySet
.
intersection
GeoQuerySet.intersection(geom)
Deprecated since version 1.9: Use the Intersection
function instead.
Returns the spatial intersection of the geographic field with the given geometry in an intersection
attribute on each element of the GeoQuerySet
.
sym_difference
GeoQuerySet.sym_difference(geom)
Deprecated since version 1.9: Use the SymDifference
function instead.
Returns the symmetric difference of the geographic field with the given geometry in a sym_difference
attribute on each element of the GeoQuerySet
.
union
GeoQuerySet.union(geom)
Deprecated since version 1.9: Use the Union
function instead.
Returns the union of the geographic field with the given geometry in an union
attribute on each element of the GeoQuerySet
.
The following GeoQuerySet
methods will return an attribute that has the value of the geometry field in each model converted to the requested output format.
geohash
GeoQuerySet.geohash(precision=20, **kwargs)
Deprecated since version 1.9: Use the GeoHash
function instead.
Attaches a geohash
attribute to every model the queryset containing the GeoHash representation of the geometry.
geojson
GeoQuerySet.geojson(**kwargs)
Deprecated since version 1.9: Use the AsGeoJSON
function instead.
Availability: PostGIS, SpatiaLite
Attaches a geojson
attribute to every model in the queryset that contains the GeoJSON representation of the geometry.
Keyword Argument | Description |
---|---|
precision | It may be used to specify the number of significant digits for the coordinates in the GeoJSON representation – the default value is 8. |
crs | Set this to True if you want the coordinate reference system to be included in the returned GeoJSON. |
bbox | Set this to True if you want the bounding box to be included in the returned GeoJSON. |
gml
GeoQuerySet.gml(**kwargs)
Deprecated since version 1.9: Use the AsGML
function instead.
Availability: PostGIS, Oracle, SpatiaLite
Attaches a gml
attribute to every model in the queryset that contains the Geographic Markup Language (GML) representation of the geometry.
Example:
>>> qs = Zipcode.objects.all().gml() >>> print(qs[0].gml) <gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ... -147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon>
Keyword Argument | Description |
---|---|
precision | 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. |
version | 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. |
kml
GeoQuerySet.kml(**kwargs)
Deprecated since version 1.9: Use the AsKML
function instead.
Availability: PostGIS, SpatiaLite
Attaches a kml
attribute to every model in the queryset that contains the Keyhole Markup Language (KML) representation of the geometry fields. It should be noted that the contents of the KML are transformed to WGS84 if necessary.
Example:
>>> qs = Zipcode.objects.all().kml() >>> print(qs[0].kml) <Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ... -103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon>
Keyword Argument | Description |
---|---|
precision | This keyword may be used to specify the number of significant digits for the coordinates in the KML representation – the default value is 8. |
svg
GeoQuerySet.svg(**kwargs)
Deprecated since version 1.9: Use the AsSVG
function instead.
Availability: PostGIS, SpatiaLite
Attaches a svg
attribute to every model in the queryset that contains the Scalable Vector Graphics (SVG) path data of the geometry fields.
Keyword Argument | Description |
---|---|
relative | If set to True , the path data will be implemented in terms of relative moves. Defaults to False , meaning that absolute moves are used instead. |
precision | This keyword may be used to specify the number of significant digits for the coordinates in the SVG representation – the default value is 8. |
mem_size
GeoQuerySet.mem_size(**kwargs)
Deprecated since version 1.9: Use the MemSize
function instead.
Availability: PostGIS
Returns the memory size (number of bytes) that the geometry field takes in a mem_size
attribute on each element of the GeoQuerySet
.
num_geom
GeoQuerySet.num_geom(**kwargs)
Deprecated since version 1.9: Use the NumGeometries
function instead.
Availability: PostGIS, Oracle, SpatiaLite
Returns the number of geometries in a num_geom
attribute on each element of the GeoQuerySet
if the geometry field is a collection (e.g., a GEOMETRYCOLLECTION
or MULTI*
field); otherwise sets with None
.
num_points
GeoQuerySet.num_points(**kwargs)
Deprecated since version 1.9: Use the NumPoints
function instead.
Availability: PostGIS, Oracle, SpatiaLite
Returns the number of points in the first linestring in the geometry field in a num_points
attribute on each element of the GeoQuerySet
; otherwise sets with None
.
Django provides some GIS-specific aggregate functions. For details on how to use these aggregate functions, see the topic guide on aggregation.
Keyword Argument | Description |
---|---|
tolerance | This keyword is for Oracle only. It is for the tolerance value used by the SDOAGGRTYPE procedure; the Oracle documentation has more details. |
Example:
>>> from django.contrib.gis.db.models import Extent, Union >>> WorldBorder.objects.aggregate(Extent('mpoly'), Union('mpoly'))
Collect
class Collect(geo_field)
Availability: PostGIS, SpatiaLite
Returns a GEOMETRYCOLLECTION
or a MULTI
geometry object from the geometry column. This is analogous to a simplified version of the Union
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.
Extent
class Extent(geo_field)
Availability: PostGIS, Oracle, SpatiaLite
Returns the extent of all geo_field
in the QuerySet
as a four-tuple, comprising the lower left coordinate and the upper right coordinate.
Example:
>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(Extent('poly')) >>> print(qs['poly__extent']) (-96.8016128540039, 29.7633724212646, -95.3631439208984, 32.782058715820)
Extent3D
class Extent3D(geo_field)
Availability: PostGIS
Returns the 3D extent of all geo_field
in the QuerySet
as a six-tuple, comprising the lower left coordinate and upper right coordinate (each with x, y, and z coordinates).
Example:
>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(Extent3D('poly')) >>> print(qs['poly__extent3d']) (-96.8016128540039, 29.7633724212646, 0, -95.3631439208984, 32.782058715820, 0)
MakeLine
class MakeLine(geo_field)
Availability: PostGIS, SpatiaLite
Returns a LineString
constructed from the point field geometries in the QuerySet
. Currently, ordering the queryset has no effect.
SpatiaLite support was added.
Example:
>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(MakeLine('poly')) >>> print(qs['poly__makeline']) LINESTRING (-95.3631510000000020 29.7633739999999989, -96.8016109999999941 32.7820570000000018)
Union
class Union(geo_field)
Availability: PostGIS, Oracle, SpatiaLite
This method returns a GEOSGeometry
object comprising the union of every geometry in the queryset. Please note that use of Union
is processor intensive and may take a significant amount of time on large querysets.
Note
If the computation time for using this method is too expensive, consider using Collect
instead.
Example:
>>> u = Zipcode.objects.aggregate(Union(poly)) # This may take a long time. >>> u = Zipcode.objects.filter(poly__within=bbox).aggregate(Union(poly)) # A more sensible approach.
[1] | See OpenGIS Simple Feature Specification For SQL, at Ch. 2.1.13.2, p. 2-13 (The Dimensionally Extended Nine-Intersection Model). |
[2] | See SDO_RELATE documentation, from the Oracle Spatial and Graph Developer’s Guide. |
[3] | (1, 2) For an explanation of this routine, read Quirks of the “Contains” Spatial Predicate by Martin Davis (a PostGIS developer). |
© Django Software Foundation and individual contributors
Licensed under the BSD License.
https://docs.djangoproject.com/en/1.11/ref/contrib/gis/geoquerysets/