GIS QuerySet API ReferenceLink para este cabeçalho

Spatial LookupsLink para este cabeçalho

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.

Lookups with rastersLink para este cabeçalho

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:

  • Native raster support N: the operator accepts rasters natively on both sides of the lookup, and raster input can be mixed with geometry inputs.

  • Bilateral raster support B: the operator supports rasters only if both sides of the lookup receive raster inputs. Raster data is automatically converted to geometries for mixed lookups.

  • Geometry conversion support C. The lookup does not have native raster support, all raster data is automatically converted to geometries.

The examples below show the SQL equivalent for the lookups in the different types of raster support. The same pattern applies to all spatial lookups.

Case

Lookup

SQL Equivalent

N, B

rast__contains=rst

ST_Contains(rast, rst)

N, B

rast__1__contains=(rst, 2)

ST_Contains(rast, 1, rst, 2)

B, C

rast__contains=geom

ST_Contains(ST_Polygon(rast), geom)

B, C

rast__1__contains=geom

ST_Contains(ST_Polygon(rast, 1), geom)

B, C

poly__contains=rst

ST_Contains(poly, ST_Polygon(rst))

B, C

poly__contains=(rst, 1)

ST_Contains(poly, ST_Polygon(rst, 1))

C

rast__crosses=rst

ST_Crosses(ST_Polygon(rast), ST_Polygon(rst))

C

rast__1__crosses=(rst, 2)

ST_Crosses(ST_Polygon(rast, 1), ST_Polygon(rst, 2))

C

rast__crosses=geom

ST_Crosses(ST_Polygon(rast), geom)

C

poly__crosses=rst

ST_Crosses(poly, ST_Polygon(rst))

Spatial lookups with rasters are only supported for PostGIS backends (denominated as PGRaster in this section).

bbcontainsLink para este cabeçalho

Availability: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Native)

Tests if the geometry or raster field’s bounding box completely contains the lookup geometry’s bounding box.

Exemplo

Code
Zipcode.objects.filter(poly__bbcontains=geom)

Backend

SQL Equivalent

PostGIS

poly ~ geom

MariaDB

MBRContains(poly, geom)

MySQL

MBRContains(poly, geom)

SpatiaLite

MbrContains(poly, geom)

bboverlapsLink para este cabeçalho

Availability: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Native)

Tests if the geometry field’s bounding box overlaps the lookup geometry’s bounding box.

Exemplo

Code
Zipcode.objects.filter(poly__bboverlaps=geom)

Backend

SQL Equivalent

PostGIS

poly && geom

MariaDB

MBROverlaps(poly, geom)

MySQL

MBROverlaps(poly, geom)

SpatiaLite

MbrOverlaps(poly, geom)

containedLink para este cabeçalho

Availability: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Native)

Tests if the geometry field’s bounding box is completely contained by the lookup geometry’s bounding box.

Exemplo

Code
Zipcode.objects.filter(poly__contained=geom)

Backend

SQL Equivalent

PostGIS

poly @ geom

MariaDB

MBRWithin(poly, geom)

MySQL

MBRWithin(poly, geom)

SpatiaLite

MbrWithin(poly, geom)

containsLink para este cabeçalho

Availability: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)

Tests if the geometry field spatially contains the lookup geometry.

Exemplo

Code
Zipcode.objects.filter(poly__contains=geom)

Backend

SQL Equivalent

PostGIS

ST_Contains(poly, geom)

Oracle

SDO_CONTAINS(poly, geom)

MariaDB

ST_Contains(poly, geom)

MySQL

ST_Contains(poly, geom)

SpatiaLite

Contains(poly, geom)

contains_properlyLink para este cabeçalho

Availability: PostGIS, PGRaster (Bilateral)

Returns true if the lookup geometry intersects the interior of the geometry field, but not the boundary (or exterior).

Exemplo

Code
Zipcode.objects.filter(poly__contains_properly=geom)

Backend

SQL Equivalent

PostGIS

ST_ContainsProperly(poly, geom)

coveredbyLink para este cabeçalho

Availability: PostGIS, Oracle, MariaDB, MySQL, PGRaster (Bilateral), SpatiaLite

Tests if no point in the geometry field is outside the lookup geometry. [3]

Exemplo

Code
Zipcode.objects.filter(poly__coveredby=geom)

Backend

SQL Equivalent

PostGIS

ST_CoveredBy(poly, geom)

Oracle

SDO_COVEREDBY(poly, geom)

MariaDB

MBRCoveredBy(poly, geom)

MySQL

MBRCoveredBy(poly, geom)

SpatiaLite

CoveredBy(poly, geom)

coversLink para este cabeçalho

Availability: PostGIS, Oracle, MySQL, PGRaster (Bilateral), SpatiaLite

Tests if no point in the lookup geometry is outside the geometry field. [3]

Exemplo

Code
Zipcode.objects.filter(poly__covers=geom)

Backend

SQL Equivalent

PostGIS

ST_Covers(poly, geom)

Oracle

SDO_COVERS(poly, geom)

MySQL

MBRCovers(poly, geom)

SpatiaLite

Covers(poly, geom)

crossesLink para este cabeçalho

Availability: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Conversion)

Tests if the geometry field spatially crosses the lookup geometry.

Exemplo

Code
Zipcode.objects.filter(poly__crosses=geom)

Backend

SQL Equivalent

PostGIS

ST_Crosses(poly, geom)

MariaDB

ST_Crosses(poly, geom)

MySQL

ST_Crosses(poly, geom)

SpatiaLite

Crosses(poly, geom)

disjointLink para este cabeçalho

Availability: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)

Tests if the geometry field is spatially disjoint from the lookup geometry.

Exemplo

Code
Zipcode.objects.filter(poly__disjoint=geom)

Backend

SQL Equivalent

PostGIS

ST_Disjoint(poly, geom)

Oracle

SDO_GEOM.RELATE(poly, 'DISJOINT', geom, 0.05)

MariaDB

ST_Disjoint(poly, geom)

MySQL

ST_Disjoint(poly, geom)

SpatiaLite

Disjoint(poly, geom)

equalsLink para este cabeçalho

Availability: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Conversion)

Tests if the geometry field is spatially equal to the lookup geometry.

Exemplo

Code
Zipcode.objects.filter(poly__equals=geom)

Backend

SQL Equivalent

PostGIS

ST_Equals(poly, geom)

Oracle

SDO_EQUAL(poly, geom)

MariaDB

ST_Equals(poly, geom)

MySQL

ST_Equals(poly, geom)

SpatiaLite

Equals(poly, geom)

exact, same_asLink para este cabeçalho

Availability: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)

Tests if the geometry field is “equal” to the lookup geometry. On Oracle, MySQL, and SpatiaLite, it tests spatial equality, while on PostGIS it tests equality of bounding boxes.

Exemplo

Code
Zipcode.objects.filter(poly=geom)

Backend

SQL Equivalent

PostGIS

poly ~= geom

Oracle

SDO_EQUAL(poly, geom)

MariaDB

ST_Equals(poly, geom)

MySQL

ST_Equals(poly, geom)

SpatiaLite

Equals(poly, geom)

intersectsLink para este cabeçalho

Availability: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)

Tests if the geometry field spatially intersects the lookup geometry.

Exemplo

Code
Zipcode.objects.filter(poly__intersects=geom)

Backend

SQL Equivalent

PostGIS

ST_Intersects(poly, geom)

Oracle

SDO_OVERLAPBDYINTERSECT(poly, geom)

MariaDB

ST_Intersects(poly, geom)

MySQL

ST_Intersects(poly, geom)

SpatiaLite

Intersects(poly, geom)

isemptyLink para este cabeçalho

Availability: PostGIS, SpatiaLite

Tests if the geometry is empty.

Exemplo

Code
Zipcode.objects.filter(poly__isempty=True)

isvalidLink para este cabeçalho

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Tests if the geometry is valid.

Exemplo

Code
Zipcode.objects.filter(poly__isvalid=True)

Backend

SQL Equivalent

MariaDB, MySQL, PostGIS, SpatiaLite

ST_IsValid(poly)

Oracle

SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT(poly, 0.05) = 'TRUE'

geom_typeLink para este cabeçalho

Availability: PostGIS, Oracle 23c+, MariaDB, MySQL, SpatiaLite

Returns the geometry type of the geometry field.

Exemplo

Code
Zipcode.objects.filter(poly__geom_type="POLYGON")

Backend

SQL Equivalent

PostGIS

GeometryType(geom)

MariaDB

ST_GeometryType(geom)

MySQL

ST_GeometryType(geom)

Oracle

SDO_GEOMETRY.GET_GTYPE(geom)

SpatiaLite

GeometryType(geom)

num_dimensionsLink para este cabeçalho

Availability: PostGIS, SpatiaLite

Returns the number of dimensions used by the geometry.

Exemplo

Code
Zipcode.objects.filter(geom__num_dimensions=3)

Backend

SQL Equivalent

PostGIS, SpatiaLite

ST_NDims(geom)

overlapsLink para este cabeçalho

Availability: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)

Tests if the geometry field spatially overlaps the lookup geometry.

Backend

SQL Equivalent

PostGIS

ST_Overlaps(poly, geom)

Oracle

SDO_OVERLAPS(poly, geom)

MariaDB

ST_Overlaps(poly, geom)

MySQL

ST_Overlaps(poly, geom)

SpatiaLite

Overlaps(poly, geom)

relateLink para este cabeçalho

Availability: PostGIS, MariaDB, Oracle, SpatiaLite, PGRaster (Conversion)

Tests if the geometry field is spatially related to the lookup geometry by the values given in the given pattern. This lookup requires a tuple parameter, (geom, pattern); the form of pattern will depend on the spatial backend:

MariaDB, PostGIS, and SpatiaLiteLink para este cabeçalho

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:

Code
# A tuple lookup parameter is used to specify the geometry and
# the intersection pattern (the pattern here is for 'contains').
Zipcode.objects.filter(poly__relate=(geom, "T*T***FF*"))

PostGIS and MariaDB SQL equivalent:

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

SpatiaLite SQL equivalent:

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

Raster example:

Code
Zipcode.objects.filter(poly__relate=(rast, 1, "T*T***FF*"))
Zipcode.objects.filter(rast__2__relate=(rast, 1, "T*T***FF*"))

PostGIS SQL equivalent:

SQL
SELECT ... WHERE ST_Relate(poly, ST_Polygon(rast, 1), 'T*T***FF*')
SELECT ... WHERE ST_Relate(ST_Polygon(rast, 2), ST_Polygon(rast, 1), 'T*T***FF*')

OracleLink para este cabeçalho

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.

Exemplo

Code
Zipcode.objects.filter(poly__relate=(geom, "anyinteract"))

Oracle SQL equivalent:

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

touchesLink para este cabeçalho

Availability: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite

Tests if the geometry field spatially touches the lookup geometry.

Exemplo

Code
Zipcode.objects.filter(poly__touches=geom)

Backend

SQL Equivalent

PostGIS

ST_Touches(poly, geom)

MariaDB

ST_Touches(poly, geom)

MySQL

ST_Touches(poly, geom)

Oracle

SDO_TOUCH(poly, geom)

SpatiaLite

Touches(poly, geom)

withinLink para este cabeçalho

Availability: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)

Tests if the geometry field is spatially within the lookup geometry.

Exemplo

Code
Zipcode.objects.filter(poly__within=geom)

Backend

SQL Equivalent

PostGIS

ST_Within(poly, geom)

MariaDB

ST_Within(poly, geom)

MySQL

ST_Within(poly, geom)

Oracle

SDO_INSIDE(poly, geom)

SpatiaLite

Within(poly, geom)

leftLink para este cabeçalho

Availability: PostGIS, PGRaster (Conversion)

Tests if the geometry field’s bounding box is strictly to the left of the lookup geometry’s bounding box.

Exemplo

Code
Zipcode.objects.filter(poly__left=geom)

PostGIS equivalent:

SQL
SELECT ... WHERE poly << geom

overlaps_leftLink para este cabeçalho

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.

Exemplo

Code
Zipcode.objects.filter(poly__overlaps_left=geom)

PostGIS equivalent:

SQL
SELECT ... WHERE poly &< geom

overlaps_rightLink para este cabeçalho

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.

Exemplo

Code
Zipcode.objects.filter(poly__overlaps_right=geom)

PostGIS equivalent:

SQL
SELECT ... WHERE poly &> geom

overlaps_aboveLink para este cabeçalho

Availability: PostGIS, PGRaster (Conversion)

Tests if the geometry field’s bounding box overlaps or is above the lookup geometry’s bounding box.

Exemplo

Code
Zipcode.objects.filter(poly__overlaps_above=geom)

PostGIS equivalent:

SQL
SELECT ... WHERE poly |&> geom

overlaps_belowLink para este cabeçalho

Availability: PostGIS, PGRaster (Conversion)

Tests if the geometry field’s bounding box overlaps or is below the lookup geometry’s bounding box.

Exemplo

Code
Zipcode.objects.filter(poly__overlaps_below=geom)

PostGIS equivalent:

SQL
SELECT ... WHERE poly &<| geom

strictly_aboveLink para este cabeçalho

Availability: PostGIS, PGRaster (Conversion)

Tests if the geometry field’s bounding box is strictly above the lookup geometry’s bounding box.

Exemplo

Code
Zipcode.objects.filter(poly__strictly_above=geom)

PostGIS equivalent:

SQL
SELECT ... WHERE poly |>> geom

strictly_belowLink para este cabeçalho

Availability: PostGIS, PGRaster (Conversion)

Tests if the geometry field’s bounding box is strictly below the lookup geometry’s bounding box.

Exemplo

Code
Zipcode.objects.filter(poly__strictly_below=geom)

PostGIS equivalent:

SQL
SELECT ... WHERE poly <<| geom

Distance LookupsLink para este cabeçalho

Availability: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Native)

For an overview on performing distance queries, please refer to the distance queries introduction.

Distance lookups take the following form:

Text
<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). 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.

distance_gtLink para este cabeçalho

Returns models where the distance to the geometry field from the lookup geometry is greater than the given distance value.

Exemplo

Code
Zipcode.objects.filter(poly__distance_gt=(geom, D(m=5)))

Backend

SQL Equivalent

PostGIS

ST_Distance/ST_Distance_Sphere(poly, geom) > 5

MariaDB

ST_Distance(poly, geom) > 5

MySQL

ST_Distance(poly, geom) > 5

Oracle

SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) > 5

SpatiaLite

Distance(poly, geom) > 5

distance_gteLink para este cabeçalho

Returns models where the distance to the geometry field from the lookup geometry is greater than or equal to the given distance value.

Exemplo

Code
Zipcode.objects.filter(poly__distance_gte=(geom, D(m=5)))

Backend

SQL Equivalent

PostGIS

ST_Distance/ST_Distance_Sphere(poly, geom) >= 5

MariaDB

ST_Distance(poly, geom) >= 5

MySQL

ST_Distance(poly, geom) >= 5

Oracle

SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) >= 5

SpatiaLite

Distance(poly, geom) >= 5

distance_ltLink para este cabeçalho

Returns models where the distance to the geometry field from the lookup geometry is less than the given distance value.

Exemplo

Code
Zipcode.objects.filter(poly__distance_lt=(geom, D(m=5)))

Backend

SQL Equivalent

PostGIS

ST_Distance/ST_Distance_Sphere(poly, geom) < 5

MariaDB

ST_Distance(poly, geom) < 5

MySQL

ST_Distance(poly, geom) < 5

Oracle

SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) < 5

SpatiaLite

Distance(poly, geom) < 5

distance_lteLink para este cabeçalho

Returns models where the distance to the geometry field from the lookup geometry is less than or equal to the given distance value.

Exemplo

Code
Zipcode.objects.filter(poly__distance_lte=(geom, D(m=5)))

Backend

SQL Equivalent

PostGIS

ST_Distance/ST_Distance_Sphere(poly, geom) <= 5

MariaDB

ST_Distance(poly, geom) <= 5

MySQL

ST_Distance(poly, geom) <= 5

Oracle

SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) <= 5

SpatiaLite

Distance(poly, geom) <= 5

dwithinLink para este cabeçalho

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

Exemplo

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

Funções de AgregaçãoLink para este cabeçalho

Django provides some GIS-specific aggregate functions. For details on how to use these aggregate functions, see the topic guide on aggregation.

Keyword Argument

Descrição

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:

Python console
>>> from django.contrib.gis.db.models import Extent, Union
>>> WorldBorder.objects.aggregate(Extent("mpoly"), Union("mpoly"))

CollectLink para este cabeçalho

class Collect(geo_field, filter=None)Link para esta definição

Availability: PostGIS, MariaDB, MySQL, 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 rolls up geometries into a collection or multi object, not caring about dissolving boundaries.

ExtentLink para este cabeçalho

class Extent(geo_field, filter=None)Link para esta definição

Availability: PostGIS, Oracle, SpatiaLite

Returns the extent of all geo_field in the QuerySet as a 4-tuple, comprising the lower left coordinate and the upper right coordinate.

Example:

Python console
>>> qs = City.objects.filter(name__in=("Houston", "Dallas")).aggregate(Extent("poly"))
>>> print(qs["poly__extent"])
(-96.8016128540039, 29.7633724212646, -95.3631439208984, 32.782058715820)

Extent3DLink para este cabeçalho

class Extent3D(geo_field, filter=None)Link para esta definição

Availability: PostGIS

Returns the 3D extent of all geo_field in the QuerySet as a 6-tuple, comprising the lower left coordinate and upper right coordinate (each with x, y, and z coordinates).

Example:

Python console
>>> 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)

MakeLineLink para este cabeçalho

class MakeLine(geo_field, filter=None)Link para esta definição

Availability: PostGIS, SpatiaLite

Returns a LineString constructed from the point field geometries in the QuerySet. Currently, ordering the queryset has no effect.

Example:

Python console
>>> qs = City.objects.filter(name__in=("Houston", "Dallas")).aggregate(MakeLine("poly"))
>>> print(qs["poly__makeline"])
LINESTRING (-95.3631510000000020 29.7633739999999989, -96.8016109999999941 32.7820570000000018)

UnionLink para este cabeçalho

class Union(geo_field, filter=None)Link para esta definição

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.

Example:

Python console
>>> 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.

Notas de rodapé