Справочник API набора запросов GIS

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

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

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

Запросы с растровыми данными

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

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

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

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

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

bbcontains

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

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

Пример:

Zipcode.objects.filter(poly__bbcontains=geom)

bboverlaps

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

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

Пример:

Zipcode.objects.filter(poly__bboverlaps=geom)

contained

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

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

Пример:

Zipcode.objects.filter(poly__contained=geom)

contains

Доступность: PostGIS, Oracle, MariaDB, 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, MariaDB, MySQL, SpatiaLite, PGRaster (Преобразование)

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

Пример:

Zipcode.objects.filter(poly__crosses=geom)

disjoint

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

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

Пример:

Zipcode.objects.filter(poly__disjoint=geom)

equals

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

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

Пример:

Zipcode.objects.filter(poly__equals=geom)

exact, same_as

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

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

Пример:

Zipcode.objects.filter(poly=geom)

intersects

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

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

Пример:

Zipcode.objects.filter(poly__intersects=geom)

isempty

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

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

Пример:

Zipcode.objects.filter(poly__isempty=True)

isvalid

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

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

Пример:

Zipcode.objects.filter(poly__isvalid=True)

overlaps

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

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

relate

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

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

MariaDB, 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 и MariaDB:

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. Несколько строк могут быть объединены логическим булевым оператором OR, например, 'inside+touch'. [2] Строки отношений нечувствительны к регистру.

Пример:

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

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

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

touches

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

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

Пример:

Zipcode.objects.filter(poly__touches=geom)

within

Доступность: PostGIS, Oracle, MariaDB, 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, MariaDB, MySQL, 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, либо выражение запроса). Для передачи индекса полосы используйте кортеж из 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 предоставляет некоторые специализированные функции агрегирования 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

Возвращает трехмерную область всех 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.

Примечания