Справочник по API GeoQuerySet

class GeoQuerySet(model=None)

Пространственные запросы

Пространственные запросы в этом разделе доступны для GeometryField и RasterField.

Для ознакомления см. введение в пространственные запросы. Для обзора совместимости запросов с конкретным пространственным бэкендом, см. таблицу совместимости пространственных запросов.

Запросы с растрами

Все примеры в справочнике ниже приведены для геометрических полей и ввода, но запросы можно использовать аналогичным образом с растрами с обеих сторон. В тех случаях, когда запрос не поддерживает растровый ввод, вход автоматически преобразуется в геометрию, когда это необходимо, с использованием функции ST_Polygon. См. также введение в запросы с растрами.

Базовые операторы, используемые запросами, можно разделить на три категории:

• Прямая поддержка растров N: оператор принимает растры непосредственно с обеих сторон запроса, и растровый ввод может быть смешан с геометрическими вводами.
• Взаимодействие с растрами B: оператор поддерживает растры только если с обеих сторон запроса используются растровые вводы. Растровые данные автоматически преобразуются в геометрию для смешанных запросов.
• Поддержка преобразования в геометрию C. Запрос не имеет прямой поддержки растров, все растровые данные автоматически преобразуются в геометрию.

Примеры ниже демонстрируют эквивалентный SQL для запросов в различных типах поддержки растров. Такая же структура применима ко всем пространственным запросам.

Пространственные запросы с растрами поддерживаются только для бэкэндов PostGIS (обозначаются как PGRaster в этом разделе).

bbcontains

Доступность: PostGIS, MySQL, SpatiaLite, PGRaster (Прямая поддержка)

Проверяет, полностью ли ограничивающая прямоугольная область геометрического или растрового поля содержит ограничивающую прямоугольную область геометрического объекта запроса.

Пример:

Zipcode.objects.filter(poly__bbcontains=geom)

bboverlaps

Доступность: PostGIS, MySQL, SpatiaLite, PGRaster (Прямая поддержка)

Проверяет, пересекаются ли ограничивающие прямоугольные области геометрического поля и геометрического объекта запроса.

Пример:

Zipcode.objects.filter(poly__bboverlaps=geom)

contained

Доступность: PostGIS, MySQL, SpatiaLite, PGRaster (Прямая поддержка)

Проверяет, полностью ли ограничивающая прямоугольная область геометрического поля содержится внутри ограничивающей прямоугольной области геометрического объекта запроса.

Пример:

Zipcode.objects.filter(poly__contained=geom)

contains

Доступность: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Взаимодействие)

Проверяет, содержит ли геометрическое поле пространственно геометрический объект запроса.

Пример:

Zipcode.objects.filter(poly__contains=geom)

contains_properly

Доступность: PostGIS, PGRaster (Взаимодействие)

Возвращает true, если геометрический объект запроса пересекает внутреннюю часть геометрического поля, но не границу (или внешнюю часть).

Пример:

Zipcode.objects.filter(poly__contains_properly=geom)

coveredby

Доступность: PostGIS, Oracle, PGRaster (Взаимодействие)

Проверяет, что ни одна точка в геометрическом поле не находится вне геометрического объекта запроса. [3]

Пример:

Zipcode.objects.filter(poly__coveredby=geom)

covers

Доступность: PostGIS, Oracle, PGRaster (Взаимодействие)

Проверяет, что ни одна точка в геометрическом объекте запроса не находится вне геометрического поля. [3]

Пример:

Zipcode.objects.filter(poly__covers=geom)

crosses

Доступность: PostGIS, SpatiaLite, PGRaster (Преобразование)

Проверяет, пересекает ли геометрическое поле пространственно геометрический объект запроса.

Пример:

Zipcode.objects.filter(poly__crosses=geom)

disjoint

Доступность: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Взаимодействие)

Проверяет, являются ли геометрическое поле и геометрический объект запроса пространственно непересекающимися.

Пример:

Zipcode.objects.filter(poly__disjoint=geom)

equals

Доступность: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Преобразование)

exact, same_as

Доступность: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Взаимодействие)

intersects

Доступность: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Взаимодействие)

Проверяет, пересекаются ли геометрическое поле и геометрический объект запроса.

Пример:

Zipcode.objects.filter(poly__intersects=geom)

isvalid

Доступность: PostGIS, Oracle, SpatiaLite

Проверяет, является ли геометрия валидной.

Пример:

Zipcode.objects.filter(poly__isvalid=True)

overlaps

Доступность: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Взаимно)

relate

Доступность: PostGIS, Oracle, SpatiaLite, PGRaster (Преобразование)

Проверяет, пространственно ли поле geometry связано с геометрией поиска в соответствии со значениями, заданными в указанном шаблоне. Этот поиск требует параметра кортежа, (geom, pattern); форма pattern будет зависеть от пространственного бэкэнда:

PostGIS и SpatiaLite

В этих пространственных бэкендах шаблон пересечения представляет собой строку из девяти символов, определяющих пересечения между внутренней, граничной и внешней частями поля geometry и геометрией поиска. Матрица шаблона пересечения может использовать только следующие символы: 1, 2, T, F, или *. Этот тип поиска позволяет пользователям «точно настроить» определённое геометрическое соотношение, соответствующее модели DE-9IM. [1]

Пример геометрии:

# 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*'))

SQL-эквивалент для PostGIS:

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

SQL-эквивалент для SpatiaLite:

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

Пример растрового изображения:

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

SQL-эквивалент для PostGIS:

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*')

Oracle

Здесь шаблон соотношения состоит как минимум из одной из девяти строк соотношений: TOUCH, OVERLAPBDYDISJOINT, OVERLAPBDYINTERSECT, EQUAL, INSIDE, COVEREDBY, CONTAINS, COVERS, ON, и ANYINTERACT. Несколько строк могут быть объединены логическим булевым оператором ИЛИ, например, 'inside+touch'. [2] Строки соотношений нечувствительны к регистру.

Пример:

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

SQL-эквивалент для Oracle:

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

touches

Доступность: PostGIS, Oracle, MySQL, SpatiaLite

Проверяет, касается ли поле geometry геометрию поиска.

Пример:

Zipcode.objects.filter(poly__touches=geom)

within

Доступность: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Взаимно)

Проверяет, находится ли поле geometry внутри геометрии поиска.

Пример:

Zipcode.objects.filter(poly__within=geom)

left

Доступность: PostGIS, PGRaster (Преобразование)

Проверяет, находится ли прямоугольник ограничивающей области поля geometry строго слева от прямоугольника ограничивающей области геометрии поиска.

Пример:

Zipcode.objects.filter(poly__left=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly << geom

right

Доступность: PostGIS, PGRaster (Преобразование)

Проверяет, находится ли прямоугольник ограничивающей области поля geometry строго справа от прямоугольника ограничивающей области геометрии поиска.

Пример:

Zipcode.objects.filter(poly__right=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly >> geom

overlaps_left

Доступность: PostGIS, PGRaster (Взаимно)

Проверяет, пересекается ли или находится ли прямоугольник ограничивающей области поля geometry слева от прямоугольника ограничивающей области геометрии поиска.

Пример:

Zipcode.objects.filter(poly__overlaps_left=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly &< geom

overlaps_right

Доступность: PostGIS, PGRaster (Взаимно)

Проверяет, пересекается ли или находится ли прямоугольник ограничивающей области поля geometry справа от прямоугольника ограничивающей области геометрии поиска.

Пример:

Zipcode.objects.filter(poly__overlaps_right=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly &> geom

overlaps_above

Доступность: PostGIS, PGRaster (Преобразование)

Проверяет, пересекается ли или находится ли прямоугольник ограничивающей области поля geometry сверху от прямоугольника ограничивающей области геометрии поиска.

Пример:

Zipcode.objects.filter(poly__overlaps_above=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly |&> geom

overlaps_below

Доступность: PostGIS, PGRaster (Преобразование)

Проверяет, пересекается ли или находится ли прямоугольник ограничивающей области поля geometry снизу от прямоугольника ограничивающей области геометрии поиска.

Пример:

Zipcode.objects.filter(poly__overlaps_below=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly &<| geom

strictly_above

Доступность: PostGIS, PGRaster (Преобразование)

Проверяет, находится ли прямоугольник ограничивающей области поля geometry строго над прямоугольником ограничивающей области геометрии поиска.

Пример:

Zipcode.objects.filter(poly__strictly_above=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly |>> geom

strictly_below

Доступность: PostGIS, PGRaster (Преобразование)

Проверяет, находится ли прямоугольник ограничивающей области поля geometry строго под прямоугольником ограничивающей области геометрии поиска.

Пример:

Zipcode.objects.filter(poly__strictly_below=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly <<| geom

Поиск по расстоянию

Доступность: PostGIS, Oracle, SpatiaLite, PGRaster (Native)

Для получения обзора по выполнению запросов по расстоянию обратитесь к введению в запросы по расстоянию.

Поиск по расстоянию имеет следующий вид:

<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'])

Передаваемое значение в поиске по расстоянию — кортеж; первые два значения обязательны и представляют собой геометрию, к которой необходимо вычислить расстояния, и значение расстояния (число в единицах поля, объект Distance, или query expression <ref/models/expressions>). Чтобы передать индекс полосы в поиск, используйте кортеж из трёх элементов, где вторым элементом является индекс полосы.

Во всех поисках по расстоянию, кроме dwithin, можно включить необязательный элемент, 'spheroid', чтобы использовать более точные функции вычисления расстояний по сфероиду для полей с геодезической системой координат.

В PostgreSQL опция 'spheroid' использует ST_DistanceSpheroid вместо ST_DistanceSphere. Простая функция ST_Distance используется с проекционными системами координат. Растровые данные преобразуются в геометрию для поисков, основанных на сфероиде.

distance_gt

Возвращает модели, где расстояние до поля geometry от геометрии поиска больше заданного значения расстояния.

Пример:

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

distance_gte

Возвращает модели, где расстояние до поля geometry от геометрии поиска больше или равно заданному значению расстояния.

Пример:

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

distance_lt

Возвращает модели, где расстояние до поля geometry от геометрии поиска меньше заданного значения расстояния.

Пример:

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

distance_lte

Возвращает модели, где расстояние до поля geometry от геометрии поиска меньше или равно заданному значению расстояния.

Пример:

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

dwithin

Возвращает модели, где расстояние до геометрического поля от геометрии поиска находится в пределах заданного расстояния друг от друга. Обратите внимание, что вы можете указать только объекты Distance, если целевые геометрии находятся в проектной системе координат. Для географических геометрий следует использовать единицы измерения поля геометрии (например, градусы для WGS84) .

Пример:

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

GeoQuerySet Методы

GeoQuerySet методы указывают, что пространственная операция должна быть выполнена над каждым пространственным полем в наборе запросов и результат должен быть сохранён в новом атрибуте модели (в общем случае, это имя GeoQuerySet метода).

Также существуют агрегирующие GeoQuerySet методы, которые возвращают одно значение вместо набора запросов. В этом разделе будет описан API и доступность каждого GeoQuerySet метода, доступного в GeoDjango.

За исключением нескольких случаев, следующие ключевые аргументы могут быть использованы со всеми GeoQuerySet методами:

Измерение

Доступность: PostGIS, Oracle, SpatiaLite

area

GeoQuerySet.area(**kwargs)

Возвращает площадь геометрического поля в атрибуте area каждого элемента этого набора запросов.

distance

GeoQuerySet.distance(geom, **kwargs)

Этот метод принимает геометрию в качестве параметра и прикрепляет атрибут distance к каждой модели в возвращаемом наборе запросов, содержащему расстояние (в виде объекта Distance) до заданной геометрии.

В следующем примере (взятом из GeoDjango тестов расстояния) вычисляется расстояние от города Хобарт (Тасмания) до каждой другой точки PointField в наборе запросов AustraliaCity.

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

length

GeoQuerySet.length(**kwargs)

Возвращает длину поля геометрии в атрибуте length (объект Distance) каждой модели в наборе запросов.

perimeter

GeoQuerySet.perimeter(**kwargs)

Возвращает периметр поля геометрии в атрибуте perimeter (объект Distance) каждой модели в наборе запросов.

Геометрические отношения

Следующие методы не принимают аргументов и прикрепляют геометрические объекты к каждому элементу набора запросов GeoQuerySet, являющегося результатом вычисления функции отношения над полем геометрии.

centroid

GeoQuerySet.centroid(**kwargs)

Доступность: PostGIS, Oracle, SpatiaLite

Возвращает значение centroid для геометрического поля в атрибуте centroid каждого элемента GeoQuerySet.

envelope

GeoQuerySet.envelope(**kwargs)

Доступность: PostGIS, SpatiaLite

Возвращает геометрию, представляющую прямоугольник, окружающий геометрическое поле в атрибуте envelope каждого элемента набора запросов GeoQuerySet.

point_on_surface

GeoQuerySet.point_on_surface(**kwargs)

Доступность: PostGIS, Oracle, SpatiaLite

Возвращает геометрию типа Point, гарантированно лежащую на поверхности геометрического поля в атрибуте point_on_surface каждого элемента набора запросов; в противном случае устанавливает None.

Редактор геометрии

force_rhr

GeoQuerySet.force_rhr(**kwargs)

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)

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)

Availability: PostGIS, SpatiaLite

snap_to_grid

GeoQuerySet.snap_to_grid(*args, **kwargs)

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.

transform

GeoQuerySet.transform(srid=4326, **kwargs)

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.

Пример:

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

Availability: PostGIS, SpatiaLite

Translates the geometry field to a new location using the given numeric parameters as offsets.

Геометрические операции

Availability: PostGIS, Oracle, SpatiaLite

Следующие методы принимают геометрию в качестве параметра и прикрепляют геометрию к каждому элементу GeoQuerySet, являющегося результатом операции.

difference

GeoQuerySet.difference(geom)

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)

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)

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)

Returns the union of the geographic field with the given geometry in an union attribute on each element of the GeoQuerySet.

Вывод геометрии

Следующие GeoQuerySet методы вернут атрибут, содержащий значение поля геометрии в каждой модели, преобразованное в указанный формат вывода.

geohash

GeoQuerySet.geohash(precision=20, **kwargs)

Attaches a geohash attribute to every model the queryset containing the GeoHash representation of the geometry.

geojson

GeoQuerySet.geojson(**kwargs)

Availability: PostGIS, SpatiaLite

Attaches a geojson attribute to every model in the queryset that contains the GeoJSON representation of the geometry.

gml

GeoQuerySet.gml(**kwargs)

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>

kml

GeoQuerySet.kml(**kwargs)

Доступность: PostGIS, SpatiaLite

Прикрепляет атрибут kml к каждой модели в наборе запросов, содержащем представление языка разметки ключей (KML) геометрических полей. Следует отметить, что содержимое KML преобразуется в WGS84 при необходимости.

Пример:

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

svg

GeoQuerySet.svg(**kwargs)

Доступность: PostGIS, SpatiaLite

Прикрепляет атрибут svg к каждой модели в наборе запросов, содержащем данные пути в формате Scalable Vector Graphics (SVG) геометрических полей.

Разное

mem_size

GeoQuerySet.mem_size(**kwargs)

Доступность: PostGIS

Возвращает размер памяти (количество байтов), занимаемый геометрическим полем в атрибуте mem_size на каждом элементе набора запросов GeoQuerySet.

num_geom

GeoQuerySet.num_geom(**kwargs)

Доступность: PostGIS, Oracle, SpatiaLite

Возвращает количество геометрий в атрибуте num_geom на каждом элементе набора запросов GeoQuerySet, если геометрическое поле представляет собой коллекцию (например, поле GEOMETRYCOLLECTION или MULTI*); в противном случае устанавливается значение None.

num_points

GeoQuerySet.num_points(**kwargs)

Доступность: PostGIS, Oracle, SpatiaLite

Возвращает количество точек в первом полилинии в геометрическом поле в атрибуте num_points на каждом элементе набора запросов GeoQuerySet; в противном случае устанавливается значение None.

Функции агрегирования

Django предоставляет некоторые специфичные для GIS функции агрегирования. Подробнее о том, как использовать эти функции агрегирования, см. в руководстве по агрегированию.

Пример:

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

Collect

class Collect(geo_field)

Доступность: PostGIS, SpatiaLite

Возвращает объект геометрии типа GEOMETRYCOLLECTION или MULTI из столбца геометрии. Это аналогично упрощенной версии агрегата Union, за исключением того, что она может быть на несколько порядков быстрее при выполнении объединения, так как просто сворачивает геометрии в коллекцию или многоугольник, не обращая внимания на растворение границ.

Extent

class Extent(geo_field)

Доступность: PostGIS, Oracle, SpatiaLite

Возвращает область всех geo_field в наборе запросов QuerySet в виде четвёрки, включающей координаты нижнего левого и верхнего правого углов.

Пример:

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

Доступность: PostGIS

Возвращает 3D-объём всех geo_field в наборе запросов QuerySet в виде шестерки, включающей координаты нижнего левого и верхнего правого углов (каждая с координатами x, y и z).

Пример:

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

Доступность: PostGIS, SpatiaLite

Возвращает LineString, построенную из геометрий точек в поле QuerySet. В настоящее время упорядочивание набора запросов не влияет на результат.

Пример:

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

Доступность: PostGIS, Oracle, SpatiaLite

Этот метод возвращает объект GEOSGeometry, представляющий объединение всех геометрий в наборе запросов. Обратите внимание, что использование Union является ресурсоемким и может занять значительное время на больших наборах запросов.

Пример:

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

Примечания