Справочник по 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, если геометрия запроса пересекает внутреннюю часть геометрического поля, но не границу (или внешний вид). [4]

Пример:

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

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

Пример:

Zipcode.objects.filter(poly__isvalid=True)

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

SELECT ... WHERE ST_IsValid(poly)

overlaps

Доступность: PostGIS, Oracle, MySQL, SpatiaLite, PGRaster (Двусторонняя)

relate

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

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

PostGIS & SpatiaLite

В этих пространственных бэкендах шаблон пересечения представляет собой строку из девяти символов, определяющих пересечения между внутренней, граничной и внешней частями геометрического поля и геометрии запроса. Матрица шаблона пересечения может использовать только следующие символы: 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*'))

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

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

Эквивалент SpatiaLite SQL:

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

Эквивалент PostGIS 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*')

Oracle

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

Пример:

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

Эквивалент Oracle SQL:

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

touches

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

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

Пример:

Zipcode.objects.filter(poly__touches=geom)

within

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

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

Пример:

Zipcode.objects.filter(poly__within=geom)

left

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

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

Пример:

Zipcode.objects.filter(poly__left=geom)

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

SELECT ... WHERE poly << geom

right

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

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

Пример:

Zipcode.objects.filter(poly__right=geom)

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

SELECT ... WHERE poly >> geom

overlaps_left

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

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

Пример:

Zipcode.objects.filter(poly__overlaps_left=geom)

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

SELECT ... WHERE poly &< geom

overlaps_right

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

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

Пример:

Zipcode.objects.filter(poly__overlaps_right=geom)

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

SELECT ... WHERE poly &> geom

overlaps_above

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

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

Пример:

Zipcode.objects.filter(poly__overlaps_above=geom)

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

SELECT ... WHERE poly |&> geom

overlaps_below

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

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

Пример:

Zipcode.objects.filter(poly__overlaps_below=geom)

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

SELECT ... WHERE poly &<| geom

strictly_above

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

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

Пример:

Zipcode.objects.filter(poly__strictly_above=geom)

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

SELECT ... WHERE poly |>> geom

strictly_below

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

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

Пример:

Zipcode.objects.filter(poly__strictly_below=geom)

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

SELECT ... WHERE poly <<| geom

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

Доступность: PostGIS, Oracle, SpatiaLite, PGRaster (Нативно)

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

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

<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>). Для передачи индекса полосы в поиск используйте кортеж из 3 элементов, где второй элемент - индекс полосы.

В PostGIS при каждом поиске по расстоянию, кроме dwithin, можно включить необязательный элемент, 'spheroid', чтобы сообщить GeoDjango использовать более точные функции расчета расстояния по сфероиду для полей с геодезической системой координат (например, ST_Distance_Spheroid вместо ST_Distance_Sphere). Более простая функция ST_Distance используется с проекционными системами координат. Растровые изображения преобразуются в геометрии для поиска на основе сфероида.

distance_gt

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

Пример:

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

distance_gte

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

Пример:

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

distance_lt

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

Пример:

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

distance_lte

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

Пример:

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 каждого элемента этого GeoQuerySet.

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)

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

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

reverse_geom

GeoQuerySet.reverse_geom(**kwargs)

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

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

scale

GeoQuerySet.scale(x, y, z=0.0, **kwargs)

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

snap_to_grid

GeoQuerySet.snap_to_grid(*args, **kwargs)

Привязывает все точки входной геометрии к сетке. Способ привязки геометрии к сетке зависит от количества числовых аргументов (float, integer или long).

transform

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

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

Метод transform преобразует поле геометрии модели в систему пространственных координат, указанную параметром srid. Если параметр srid не указан, по умолчанию используется 4326 (WGS84).

Пример:

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

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

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

Операции с геометрией

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

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

difference

GeoQuerySet.difference(geom)

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

intersection

GeoQuerySet.intersection(geom)

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

sym_difference

GeoQuerySet.sym_difference(geom)

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

union

GeoQuerySet.union(geom)

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

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

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

geohash

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

Присоединяет атрибут geohash к каждой модели в наборе запросов, содержащему представление геометрии в формате GeoHash.

geojson

GeoQuerySet.geojson(**kwargs)

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

Присоединяет атрибут geojson к каждой модели в наборе запросов, содержащему представление геометрии в формате GeoJSON.

gml

GeoQuerySet.gml(**kwargs)

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

Присоединяет атрибут gml к каждой модели в наборе запросов, содержащему представление геометрии в формате Geographic Markup Language (GML).

Пример:

>>> 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 к каждой модели в наборе запросов, содержащему представление геометрии в формате Keyhole Markup Language (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 предоставляет некоторые функции агрегирования, специфичные для ГИС. Подробнее о том, как использовать эти функции агрегирования, см. в руководстве по теме агрегирования.

Пример:

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

Collect

class Collect(geo_field) [source]

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

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

Extent

class Extent(geo_field) [source]

Доступность: 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) [source]

Доступность: 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) [source]

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

Возвращает линию, построенную из геометрий точечных полей в 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) [source]

Доступность: 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.

Примечания