Справочник 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 (Взаимодействие)

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

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

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

Пример:

Zipcode.objects.filter(poly__isvalid=True)

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, 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 используется с проекционными системами координат. Растры преобразуются в геометрии для поиска по сфере.

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

Пример:

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

Возвращает объём всех 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.

Примечания