GIS QuerySet API ReferenceLink to this heading

Pencarian SpasialLink to this heading

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.

Pencarian dengan rasterLink to this heading

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.

Kasus	Cari	Setara SQL
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`Link to this heading

Tersedia: PostGIS, MySQL, SpatiaLite, PGRaster (Asli)

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

Contoh:

Code

Zipcode.objects.filter(poly__bbcontains=geom)

Backend	Setara SQL
PostGIS	`poly ~ geom`
MySQL	`MBRContains(poly, geom)`
SpatiaLite	`MbrContains(poly, geom)`

`bboverlaps`Link to this heading

Tersedia: PostGIS, MySQL, SpatiaLite, PGRaster (Asli)

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

Contoh:

Code

Zipcode.objects.filter(poly__bboverlaps=geom)

Backend	Setara SQL
PostGIS	`poly && geom`
MySQL	`MBROverlaps(poly, geom)`
SpatiaLite	`MbrOverlaps(poly, geom)`

`contained`Link to this heading

Tersedia: PostGIS, MySQL, SpatiaLite, PGRaster (Asli)

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

Contoh:

Code

Zipcode.objects.filter(poly__contained=geom)

Backend	Setara SQL
PostGIS	`poly @ geom`
MySQL	`MBRWithin(poly, geom)`
SpatiaLite	`MbrWithin(poly, geom)`

`contains`Link to this heading

Tersedia: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Timbal balik)

Tests if the geometry field spatially contains the lookup geometry.

Contoh:

Code

Zipcode.objects.filter(poly__contains=geom)

Backend	Setara SQL
PostGIS	`ST_Contains(poly, geom)`
Oracle	`SDO_CONTAINS(poly, geom)`
MySQL	`MBRContains(poly, geom)`
SpatiaLite	`Contains(poly, geom)`

`contains_properly`Link to this heading

Tersedia: PostGIS, PGRaster (Timbal balik)

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

Contoh:

Code

Zipcode.objects.filter(poly__contains_properly=geom)

Backend	Setara SQL
PostGIS	`ST_ContainsProperly(poly, geom)`

`coveredby`Link to this heading

Tersedia: PostGIS, Oracle, PGRaster (Timbal balik)

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

Contoh:

Code

Zipcode.objects.filter(poly__coveredby=geom)

Backend	Setara SQL
PostGIS	`ST_CoveredBy(poly, geom)`
Oracle	`SDO_COVEREDBY(poly, geom)`

`covers`Link to this heading

Tersedia: PostGIS, Oracle, PGRaster (Timbal balik)

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

Contoh:

Code

Zipcode.objects.filter(poly__covers=geom)

Backend	Setara SQL
PostGIS	`ST_Covers(poly, geom)`
Oracle	`SDO_COVERS(poly, geom)`

`crosses`Link to this heading

Tersedia: PostGIS, SpatiaLite, PGRaster (Perubahan)

Tests if the geometry field spatially crosses the lookup geometry.

Contoh:

Code

Zipcode.objects.filter(poly__crosses=geom)

Backend	Setara SQL
PostGIS	`ST_Crosses(poly, geom)`
SpatiaLite	`Crosses(poly, geom)`

`disjoint`Link to this heading

Tersedia: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Timbal balik)

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

Contoh:

Code

Zipcode.objects.filter(poly__disjoint=geom)

Backend	Setara SQL
PostGIS	`ST_Disjoint(poly, geom)`
Oracle	`SDO_GEOM.RELATE(poly, 'DISJOINT', geom, 0.05)`
MySQL	`MBRDisjoint(poly, geom)`
SpatiaLite	`Disjoint(poly, geom)`

`equals`Link to this heading

Tersedia: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Perubahan)

`exact`, `same_as`Link to this heading

Tersedia: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Timbal balik)

`intersects`Link to this heading

Tersedia: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Timbal balik)

Tests if the geometry field spatially intersects the lookup geometry.

Contoh:

Code

Zipcode.objects.filter(poly__intersects=geom)

Backend	Setara SQL
PostGIS	`ST_Intersects(poly, geom)`
Oracle	`SDO_OVERLAPBDYINTERSECT(poly, geom)`
MySQL	`MBRIntersects(poly, geom)`
SpatiaLite	`Intersects(poly, geom)`

`isvalid`Link to this heading

Availability: MySQL (≥ 5.7.5), PostGIS, Oracle, SpatiaLite

Coba jika geometri adalah sah.

Contoh:

Code

Zipcode.objects.filter(poly__isvalid=True)

Backend	Setara SQL
MySQL, PostGIS, SpatiaLite	`ST_IsValid(poly)`
Oracle	`SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT(poly, 0.05) = 'TRUE'`

`overlaps`Link to this heading

Tersedia: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Timbal balik)

`relate`Link to this heading

Tersedia: PostGIS, Oracle, SpatiaLite, PGRaster (Perubahan)

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:

PostGIS & SpatiaLiteLink to this heading

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]

Contoh geometri:

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

Code

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

SpatiaLite SQL setara:

Code

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

Code

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 to this heading

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.

Contoh:

Code

Zipcode.objects.filter(poly__relate=(geom, 'anyinteract'))

Oracle SQL setara:

Code

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

`touches`Link to this heading

Tersedia: PostGIS, Oracle, MySQL, SpatiaLite

Tests if the geometry field spatially touches the lookup geometry.

Contoh:

Code

Zipcode.objects.filter(poly__touches=geom)

Backend	Setara SQL
PostGIS	ST_Touches(poly, geom)``
MySQL	`MBRTouches(poly, geom)`
Oracle	`SDO_TOUCH(poly, geom)`
SpatiaLite	`Touches(poly, geom)`

`within`Link to this heading

Tersedia: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Timbal balik)

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

Contoh:

Code

Zipcode.objects.filter(poly__within=geom)

Backend	Setara SQL
PostGIS	`ST_Within(poly, geom)`
MySQL	`MBRWithin(poly, geom)`
Oracle	`SDO_INSIDE(poly, geom)`
SpatiaLite	`Within(poly, geom)`

`left`Link to this heading

Tersedia: PostGIS, PGRaster (Perubahan)

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

Contoh:

Code

Zipcode.objects.filter(poly__left=geom)

PostGIS Setara:

Code

SELECT ... WHERE poly << geom

`right`Link to this heading

Tersedia: PostGIS, PGRaster (Perubahan)

Tests if the geometry field's bounding box is strictly to the right of the lookup geometry's bounding box.

Contoh:

Code

Zipcode.objects.filter(poly__right=geom)

PostGIS Setara:

Code

SELECT ... WHERE poly >> geom

`overlaps_left`Link to this heading

Tersedia: PostGIS, PGRaster (Timbal balik)

Tests if the geometry field's bounding box overlaps or is to the left of the lookup geometry's bounding box.

Contoh:

Code

Zipcode.objects.filter(poly__overlaps_left=geom)

PostGIS Setara:

Code

SELECT ... WHERE poly &< geom

`overlaps_right`Link to this heading

Tersedia: PostGIS, PGRaster (Timbal balik)

Tests if the geometry field's bounding box overlaps or is to the right of the lookup geometry's bounding box.

Contoh:

Code

Zipcode.objects.filter(poly__overlaps_right=geom)

PostGIS Setara:

Code

SELECT ... WHERE poly &> geom

`overlaps_above`Link to this heading

Tersedia: PostGIS, PGRaster (Perubahan)

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

Contoh:

Code

Zipcode.objects.filter(poly__overlaps_above=geom)

PostGIS Setara:

Code

SELECT ... WHERE poly |&> geom

`overlaps_below`Link to this heading

Tersedia: PostGIS, PGRaster (Perubahan)

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

Contoh:

Code

Zipcode.objects.filter(poly__overlaps_below=geom)

PostGIS Setara:

Code

SELECT ... WHERE poly &<| geom

`strictly_above`Link to this heading

Tersedia: PostGIS, PGRaster (Perubahan)

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

Contoh:

Code

Zipcode.objects.filter(poly__strictly_above=geom)

PostGIS Setara:

Code

SELECT ... WHERE poly |>> geom

`strictly_below`Link to this heading

Tersedia: PostGIS, PGRaster (Perubahan)

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

Contoh:

Code

Zipcode.objects.filter(poly__strictly_below=geom)

PostGIS Setara:

Code

SELECT ... WHERE poly <<| geom

Pencarian JarakLink to this heading

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

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

Pencarian jarak mengambil formulir berikut:

Code

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

Pada PostgreSQL, pilihan 'spheroid' menggunakan ST_DistanceSpheroid daripada ST_DistanceSphere. Fungsi ST_Distance paling sederhana digunakan dengan sistem kordinat yang sudah dihitung. Raster dirubah ke geometri untuk pencarian berdasarkan spheroid.

`distance_gt`Link to this heading

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

Contoh:

Code

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

Backend	Setara SQL
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`Link to this heading

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

Contoh:

Code

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

Backend	Setara SQL
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`Link to this heading

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

Contoh:

Code

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

Backend	Setara SQL
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`Link to this heading

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

Contoh:

Code

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

Backend	Setara SQL
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`Link to this heading

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

Contoh:

Code

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

Backend	Setara SQL
PostGIS	`ST_DWithin(poly, geom, 5)`
Oracle	`SDO_WITHIN_DISTANCE(poly, geom, 5)`
SpatiaLite	`PtDistWithin(poly, geom, 5)`

Fungsi KumpulanLink to this heading

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

Argumen Katakunci	Deskripsi
`tolerance`	This keyword is for Oracle only. It is for the tolerance value used by the `SDOAGGRTYPE` procedure; the Oracle documentation has more details.

Contoh:

Code

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

`Collect`Link to this heading

class Collect(geo_field)Link to this definition

Tersedia: 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`Link to this heading

class Extent(geo_field)Link to this definition

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

Contoh:

Code

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

`Extent3D`Link to this heading

class Extent3D(geo_field)Link to this definition

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

Contoh:

Code

>>> 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`Link to this heading

class MakeLine(geo_field)Link to this definition

Tersedia: PostGIS, SpatiaLite

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

Contoh:

Code

>>> 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`Link to this heading

class Union(geo_field)Link to this definition

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

Contoh:

Code

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

Catatan kaki

GIS QuerySet API ReferenceLink to this heading#

Pencarian SpasialLink to this heading#

Pencarian dengan rasterLink to this heading#

bbcontainsLink to this heading#

bboverlapsLink to this heading#

containedLink to this heading#

containsLink to this heading#

contains_properlyLink to this heading#

coveredbyLink to this heading#

coversLink to this heading#

crossesLink to this heading#

disjointLink to this heading#

equalsLink to this heading#

exact, same_asLink to this heading#

intersectsLink to this heading#

isvalidLink to this heading#

overlapsLink to this heading#

relateLink to this heading#

PostGIS & SpatiaLiteLink to this heading#

OracleLink to this heading#

touchesLink to this heading#

withinLink to this heading#

leftLink to this heading#

rightLink to this heading#

overlaps_leftLink to this heading#

overlaps_rightLink to this heading#

overlaps_aboveLink to this heading#

overlaps_belowLink to this heading#

strictly_aboveLink to this heading#

strictly_belowLink to this heading#

Pencarian JarakLink to this heading#

distance_gtLink to this heading#

distance_gteLink to this heading#

distance_ltLink to this heading#

distance_lteLink to this heading#

dwithinLink to this heading#

Fungsi KumpulanLink to this heading#

CollectLink to this heading#

ExtentLink to this heading#

Extent3DLink to this heading#

MakeLineLink to this heading#

UnionLink to this heading#

GIS QuerySet API ReferenceLink to this heading

Pencarian SpasialLink to this heading

Pencarian dengan rasterLink to this heading

`bbcontains`Link to this heading

`bboverlaps`Link to this heading

`contained`Link to this heading

`contains`Link to this heading

`contains_properly`Link to this heading

`coveredby`Link to this heading

`covers`Link to this heading

`crosses`Link to this heading

`disjoint`Link to this heading

`equals`Link to this heading

`exact`, `same_as`Link to this heading

`intersects`Link to this heading

`isvalid`Link to this heading

`overlaps`Link to this heading

`relate`Link to this heading

PostGIS & SpatiaLiteLink to this heading

OracleLink to this heading

`touches`Link to this heading

`within`Link to this heading

`left`Link to this heading

`right`Link to this heading

`overlaps_left`Link to this heading

`overlaps_right`Link to this heading

`overlaps_above`Link to this heading

`overlaps_below`Link to this heading

`strictly_above`Link to this heading

`strictly_below`Link to this heading

Pencarian JarakLink to this heading

`distance_gt`Link to this heading

`distance_gte`Link to this heading

`distance_lt`Link to this heading

`distance_lte`Link to this heading

`dwithin`Link to this heading

Fungsi KumpulanLink to this heading

`Collect`Link to this heading

`Extent`Link to this heading

`Extent3D`Link to this heading

`MakeLine`Link to this heading

`Union`Link to this heading