Справочник по API GIS QuerySet

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

Пространственные запросы в этом разделе доступны для 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 (Взаимодействие), SpatiaLite

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

Пример:

Zipcode.objects.filter(poly__coveredby=geom)

covers

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

Проверяет, что ни одна точка в геометрии запроса не находится за пределами геометрического поля. [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 (Преобразование)

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

Пример:

Zipcode.objects.filter(poly__equals=geom)

exact, same_as

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

Проверяет, «равны» ли геометрическое поле и геометрия запроса. В Oracle и SpatiaLite проверяется пространственное равенство, а в MySQL и PostGIS проверяется равенство ограничивающих прямоугольных областей.

Пример:

Zipcode.objects.filter(poly=geom)

id="std:fieldlookup-intersects">intersects

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

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

Пример:

Zipcode.objects.filter(poly__intersects=geom)

id="std:fieldlookup-isvalid">isvalid

Доступность: MySQL (≥ 5.7.5), PostGIS, Oracle, SpatiaLite

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

Пример:

Zipcode.objects.filter(poly__isvalid=True)

id="std:fieldlookup-overlaps">overlaps

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

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

id="std:fieldlookup-relate">relate

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

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

id="postgis-spatialite">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*'))

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

id="oracle">Oracle

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

Пример:

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

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

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

id="std:fieldlookup-touches">touches

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

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

Пример:

Zipcode.objects.filter(poly__touches=geom)

id="std:fieldlookup-within">within

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

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

Пример:

Zipcode.objects.filter(poly__within=geom)

id="std:fieldlookup-left">left

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

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

Пример:

Zipcode.objects.filter(poly__left=geom)

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

SELECT ... WHERE poly << geom

id="std:fieldlookup-right">right

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

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

Пример:

Zipcode.objects.filter(poly__right=geom)

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

SELECT ... WHERE poly >> geom

id="std:fieldlookup-overlaps_left">overlaps_left

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

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

Пример:

Zipcode.objects.filter(poly__overlaps_left=geom)

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

SELECT ... WHERE poly &< geom

id="std:fieldlookup-overlaps_right">overlaps_right

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

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

Пример:

Zipcode.objects.filter(poly__overlaps_right=geom)

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

SELECT ... WHERE poly &> geom

id="std:fieldlookup-overlaps_above">overlaps_above

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

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

Пример:

Zipcode.objects.filter(poly__overlaps_above=geom)

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

SELECT ... WHERE poly |&> geom

id="std:fieldlookup-overlaps_below">overlaps_below

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

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

Пример:

Zipcode.objects.filter(poly__overlaps_below=geom)

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

SELECT ... WHERE poly &<| geom

id="std:fieldlookup-strictly_above">strictly_above

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

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

Пример:

Zipcode.objects.filter(poly__strictly_above=geom)

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

SELECT ... WHERE poly |>> geom

id="std:fieldlookup-strictly_below">strictly_below

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

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

Пример:

Zipcode.objects.filter(poly__strictly_below=geom)

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

SELECT ... WHERE poly <<| geom

id="id6">Поиск по расстоянию

Доступность: PostGIS, Oracle, MySQL, 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 элементов, где второй элемент — индекс полосы.

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

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

id="std:fieldlookup-distance_gt">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)))

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

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.

Примечания