Справочник по 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)

id="std:fieldlookup-intersects">intersects

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

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

Пример:

Zipcode.objects.filter(poly__intersects=geom)

id="std:fieldlookup-isempty">isempty

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

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

Пример:

Zipcode.objects.filter(poly__isempty=True)

id="std:fieldlookup-isvalid">isvalid

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

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

Пример:

Zipcode.objects.filter(poly__isvalid=True)

id="std:fieldlookup-overlaps">overlaps

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

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

id="std:fieldlookup-relate">relate

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

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

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

id="oracle">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')

id="std:fieldlookup-touches">touches

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

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

Пример:

Zipcode.objects.filter(poly__touches=geom)

id="std:fieldlookup-within">within

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

Пример:

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

Collect

class Collect(geo_field, filter=None)

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

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

Extent

class Extent(geo_field, filter=None)

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

Возвращает протяжённость всех geo_field в QuerySet в виде 4-кортежа, содержащего координаты нижнего левого и верхнего правого углов.

Пример:

>>> 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, filter=None)

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

Возвращает 3D протяжённость всех geo_field в QuerySet в виде 6-кортежа, содержащего координаты нижнего левого и верхнего правого углов (каждый с координатами 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, filter=None)

Доступность: 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, filter=None)

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

Примечания