Геопространственные функции#

Геопространственные функции CedrusData, начинающиеся с префикса ST_, поддерживают спецификацию SQL/MM и соответствуют спецификациям OpenGIS Консорциума Open Geospatial (OGC). Многие геопространственные функции CedrusData предполагают, что обрабатываемые геометрии являются одновременно простыми и валидными. Например, не имеет смысла вычислять площадь полигона, у которого отверстие определено за пределами полигона, или строить полигон из непростой граничной линии.

Геопространственные функции CedrusData поддерживают формы пространственных объектов Well-Known Text (WKT) и Well-Known Binary (WKB):

POINT (0 0)
LINESTRING (0 0, 1 1, 1 2)
POLYGON ((0 0, 4 0, 4 4, 0 4, 0 0), (1 1, 2 1, 2 2, 1 2, 1 1))
MULTIPOINT (0 0, 1 2)
MULTILINESTRING ((0 0, 1 1, 1 2), (2 3, 3 2, 5 4))
MULTIPOLYGON (((0 0, 4 0, 4 4, 0 4, 0 0), (1 1, 2 1, 2 2, 1 2, 1 1)), ((-1 -1, -1 -2, -2 -2, -2 -1, -1 -1)))
GEOMETRYCOLLECTION (POINT(2 3), LINESTRING (2 3, 3 4))

Используйте функции ST_GeometryFromText() и ST_GeomFromBinary() для создания объектов геометрии из WKT или WKB.

Тип SphericalGeography обеспечивает нативную поддержку пространственных объектов, представленных в географических координатах (иногда называемых геодезическими координатами, или lat/lon, или lon/lat). Географические координаты — это сферические координаты, выраженные в угловых единицах (градусах).

Основой типа Geometry является плоскость. Кратчайший путь между двумя точками на плоскости — это прямая линия. Это означает, что вычисления над геометриями (площади, расстояния, длины, пересечения и т.д.) могут выполняться с использованием декартовой математики и прямолинейных векторов.

Основой типа SphericalGeography является сфера. Кратчайший путь между двумя точками на сфере — это дуга большого круга. Это означает, что вычисления над географиями (площади, расстояния, длины, пересечения и т.д.) должны выполняться на сфере с использованием более сложной математики. Более точные измерения, учитывающие реальную сфероидальную форму Земли, не поддерживаются.

Значения, возвращаемые функциями измерения ST_Distance() и ST_Length(), выражены в метрах; значения, возвращаемые ST_Area() — в квадратных метрах.

Используйте функцию to_spherical_geography() для преобразования объекта геометрии в объект географии.

Например, ST_Distance(ST_Point(-71.0882, 42.3607), ST_Point(-74.1197, 40.6976)) возвращает 3.4577 в единицах переданных значений на евклидовой плоскости, тогда как ST_Distance(to_spherical_geography(ST_Point(-71.0882, 42.3607)), to_spherical_geography(ST_Point(-74.1197, 40.6976))) возвращает 312822.179 в метрах.

Конструкторы#

ST_AsBinary(Geometry) → varbinary#: Возвращает WKB-представление геометрии.

ST_AsText(Geometry) → varchar#: Возвращает WKT-представление геометрии. Для пустых геометрий ST_AsText(ST_LineFromText('LINESTRING EMPTY')) вернёт 'MULTILINESTRING EMPTY', а ST_AsText(ST_Polygon('POLYGON EMPTY')) вернёт 'MULTIPOLYGON EMPTY'.

ST_GeometryFromText(varchar) → Geometry#: Возвращает объект типа геометрии из WKT-представления.

ST_GeomFromBinary(varbinary) → Geometry#: Возвращает объект типа геометрии из WKB- или EWKB-представления.

ST_GeomFromKML(varchar) → Geometry#: Возвращает объект типа геометрии из KML-представления.

geometry_from_hadoop_shape(varbinary) → Geometry#: Возвращает объект типа геометрии из представления Spatial Framework for Hadoop.

ST_LineFromText(varchar) → LineString#: Возвращает объект типа геометрии LineString из WKT-представления.

ST_LineString(array(Point)) → LineString#: Возвращает LineString, сформированный из массива точек. Если во входном массиве менее двух непустых точек, будет возвращён пустой LineString. Элементы массива не должны быть NULL или совпадать с предыдущим элементом. Возвращаемая геометрия может быть непростой, например, может самопересекаться или содержать дублирующиеся вершины в зависимости от входных данных.

ST_MultiPoint(array(Point)) → MultiPoint#: Возвращает объект геометрии MultiPoint, сформированный из указанных точек. Возвращает NULL, если входной массив пуст. Элементы массива не должны быть NULL или пустыми. Возвращаемая геометрия может быть непростой и содержать дублирующиеся точки, если входной массив содержит дубликаты.

ST_Point(lon: double, lat: double) → Point#: Возвращает объект типа геометрии Point с заданными значениями координат.

ST_Polygon(varchar) → Polygon#: Возвращает объект типа геометрии Polygon из WKT-представления.

to_spherical_geography(Geometry) → SphericalGeography#: Преобразует объект Geometry в объект SphericalGeography на сфере с радиусом Земли. Эта функция применима только к геометриям POINT, MULTIPOINT, LINESTRING, MULTILINESTRING, POLYGON, MULTIPOLYGON, определённым в двумерном пространстве, или GEOMETRYCOLLECTION таких геометрий. Для каждой точки входной геометрии проверяется, что point.x находится в пределах [-180.0, 180.0], а point.y — в пределах [-90.0, 90.0], и они используются как (долгота, широта) в градусах для построения формы результата SphericalGeography.

to_geometry(SphericalGeography) → Geometry#: Преобразует объект SphericalGeography в объект Geometry.

Проверки отношений#

ST_Contains(geometryA: Geometry, geometryB: Geometry) → boolean#: Возвращает true тогда и только тогда, когда ни одна точка второй геометрии не лежит вне первой геометрии и хотя бы одна точка внутренней области первой геометрии лежит во внутренней области второй геометрии.

ST_Crosses(first: Geometry, second: Geometry) → boolean#: Возвращает true, если переданные геометрии имеют некоторые, но не все, общие внутренние точки.

ST_Disjoint(first: Geometry, second: Geometry) → boolean#: Возвращает true, если данные геометрии пространственно не пересекаются, то есть не имеют общего пространства.

ST_Equals(first: Geometry, second: Geometry) → boolean#: Возвращает true, если данные геометрии представляют одну и ту же геометрию.

ST_Intersects(first: Geometry, second: Geometry) → boolean#: Возвращает true, если данные геометрии пространственно пересекаются в двух измерениях (имеют общую часть пространства), и false, если нет (они непересекающиеся).

ST_Overlaps(first: Geometry, second: Geometry) → boolean#: Возвращает true, если данные геометрии имеют общее пространство, имеют одинаковую размерность, но не полностью содержатся друг в друге.

ST_Relate(first: Geometry, second: Geometry) → boolean#: Возвращает true, если первая геометрия пространственно связана со второй геометрией.

ST_Touches(first: Geometry, second: Geometry) → boolean#: Возвращает true, если данные геометрии имеют хотя бы одну общую точку, но их внутренние области не пересекаются.

ST_Within(first: Geometry, second: Geometry) → boolean#: Возвращает true, если первая геометрия полностью находится внутри второй геометрии.

Операции#

geometry_nearest_points(first: Geometry, second: Geometry)#: Возвращает точки на каждой геометрии, ближайшие к другой. Если любая из геометрий пуста, возвращает NULL. В противном случае возвращает строку из двух точек, имеющих минимальное расстояние среди всех пар точек на геометриях. Первая точка берётся из первого аргумента Geometry, вторая — из второго аргумента Geometry. Если существует несколько пар с минимальным расстоянием, одна пара выбирается произвольно.

geometry_union(array(Geometry)) → Geometry#: Возвращает геометрию, представляющую объединение множеств точек входных геометрий. Производительность этой функции в сочетании с array_agg() для предварительной агрегации входных геометрий может быть лучше, чем у geometry_union_agg(), за счёт более высокого потребления памяти.

ST_Boundary(Geometry) → Geometry#: Возвращает замыкание комбинаторной границы данной геометрии.

ST_Buffer(Geometry, distance) → Geometry#: Возвращает геометрию, представляющую все точки, расстояние от которых до указанной геометрии меньше или равно указанному расстоянию. Если точки геометрии расположены крайне близко друг к другу (delta < 1e-8), функция может вернуть пустую геометрию.

ST_Difference(first: Geometry, second: Geometry) → Geometry#: Возвращает значение геометрии, представляющее разность множеств точек данных геометрий.

ST_Envelope(Geometry) → Geometry#: Возвращает ограничивающий прямоугольный полигон геометрии.

ST_EnvelopeAsPts(Geometry)#: Возвращает массив из двух точек: нижний левый и верхний правый углы ограничивающего прямоугольного полигона геометрии. Возвращает NULL, если входная геометрия пуста.

ST_ExteriorRing(Geometry) → Geometry#: Возвращает линию, представляющую внешнее кольцо входного полигона.

ST_Intersection(first: Geometry, second: Geometry) → Geometry#: Возвращает значение геометрии, представляющее пересечение множеств точек двух геометрий.

ST_SymDifference(first: Geometry, second: Geometry) → Geometry#: Возвращает значение геометрии, представляющее симметрическую разность множеств точек двух геометрий.

ST_Union(first: Geometry, second: Geometry) → Geometry#

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

См. также: geometry_union(), geometry_union_agg()

Accessors#

ST_Area(Geometry) → double#

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

Для типов Point и LineString возвращает 0.0. Для типов GeometryCollection возвращает сумму площадей отдельных геометрий.

ST_Area(SphericalGeography) → double: Возвращает площадь полигона или мультиполигона в квадратных метрах, используя сферическую модель Земли.

ST_Centroid(Geometry) → Geometry#: Возвращает точку, являющуюся математическим центроидом геометрии.

ST_ConvexHull(Geometry) → Geometry#: Возвращает минимальную выпуклую геометрию, охватывающую все входные геометрии.

ST_CoordDim(Geometry) → bigint#: Возвращает размерность координат геометрии.

ST_Dimension(Geometry) → bigint#: Возвращает собственную размерность данного объекта геометрии, которая должна быть меньше или равна размерности координат.

ST_Distance(first: Geometry, second: Geometry) → double: Возвращает двумерное декартово минимальное расстояние (на основе пространственной привязки) между двумя геометриями в проецируемых единицах.

ST_Distance(first: SphericalGeography, second: SphericalGeography) → double#: Возвращает расстояние по дуге большого круга в метрах между двумя точками SphericalGeography.

ST_GeometryN(Geometry, index) → Geometry#: Возвращает элемент геометрии по заданному индексу (индексы начинаются с 1). Если геометрия является коллекцией геометрий (например, GEOMETRYCOLLECTION или MULTI*), возвращает геометрию по заданному индексу. Если заданный индекс меньше 1 или больше общего количества элементов в коллекции, возвращает NULL. Используйте ST_NumGeometries() для определения общего количества элементов. Единичные геометрии (например, POINT, LINESTRING, POLYGON) рассматриваются как коллекции из одного элемента. Пустые геометрии рассматриваются как пустые коллекции.

ST_InteriorRingN(Geometry, index) → Geometry#: Возвращает элемент внутреннего кольца по указанному индексу (индексы начинаются с 1). Если заданный индекс меньше 1 или больше общего количества внутренних колец во входной геометрии, возвращает NULL. Входная геометрия должна быть полигоном. Используйте ST_NumInteriorRing() для определения общего количества элементов.

ST_GeometryType(Geometry) → varchar#: Возвращает тип геометрии.

ST_IsClosed(Geometry) → boolean#: Возвращает true, если начальная и конечная точки линии совпадают.

ST_IsEmpty(Geometry) → boolean#: Возвращает true, если данная геометрия является пустой коллекцией геометрий, полигоном, точкой и т.д.

ST_IsSimple(Geometry) → boolean#: Возвращает true, если данная геометрия не имеет аномальных геометрических точек, таких как самопересечение или самокасание.

ST_IsRing(Geometry) → boolean#: Возвращает true тогда и только тогда, когда линия замкнута и проста.

ST_IsValid(Geometry) → boolean#: Возвращает true тогда и только тогда, когда входная геометрия корректно сформирована. Используйте geometry_invalid_reason() для определения причины некорректности геометрии.

ST_Length(Geometry) → double#: Возвращает длину линии или мультилинии с использованием евклидова измерения на двумерной плоскости (на основе пространственной привязки) в проецируемых единицах.

ST_Length(SphericalGeography) → double: Возвращает длину линии или мультилинии на сферической модели Земли. Это эквивалентно сумме расстояний по дугам большого круга между соседними точками линии.

ST_PointN(LineString, index) → Point#: Возвращает вершину линии по заданному индексу (индексы начинаются с 1). Если заданный индекс меньше 1 или больше общего количества элементов в коллекции, возвращает NULL. Используйте ST_NumPoints() для определения общего количества элементов.

ST_Points(Geometry)#: Возвращает массив точек линии.

ST_XMax(Geometry) → double#: Возвращает максимум X ограничивающего прямоугольника геометрии.

ST_YMax(Geometry) → double#: Возвращает максимум Y ограничивающего прямоугольника геометрии.

ST_XMin(Geometry) → double#: Возвращает минимум X ограничивающего прямоугольника геометрии.

ST_YMin(Geometry) → double#: Возвращает минимум Y ограничивающего прямоугольника геометрии.

ST_StartPoint(Geometry) → point#: Возвращает первую точку геометрии LineString в виде Point. Это сокращение для ST_PointN(geometry, 1).

simplify_geometry(Geometry, double) → Geometry#: Возвращает «упрощённую» версию входной геометрии с использованием алгоритма Дугласа-Пекера. Избегает создания производных геометрий (в частности, полигонов), которые являются невалидными.

ST_EndPoint(Geometry) → point#: Возвращает последнюю точку геометрии LineString в виде Point. Это сокращение для ST_PointN(geometry, ST_NumPoints(geometry)).

ST_X(Point) → double#: Возвращает координату X точки.

ST_Y(Point) → double#: Возвращает координату Y точки.

ST_InteriorRings(Geometry)#: Возвращает массив всех внутренних колец входной геометрии или пустой массив, если полигон не имеет внутренних колец. Возвращает NULL, если входная геометрия пуста. Входная геометрия должна быть полигоном.

ST_NumGeometries(Geometry) → bigint#: Возвращает количество геометрий в коллекции. Если геометрия является коллекцией геометрий (например, GEOMETRYCOLLECTION или MULTI*), возвращает количество геометрий; для единичных геометрий возвращает 1; для пустых геометрий возвращает 0.

ST_Geometries(Geometry)#: Возвращает массив геометрий в указанной коллекции. Возвращает массив из одного элемента, если входная геометрия не является мультигеометрией. Возвращает NULL, если входная геометрия пуста.

ST_NumPoints(Geometry) → bigint#: Возвращает количество точек в геометрии. Это расширение функции SQL/MM ST_NumPoints, которая применяется только к точкам и линиям.

ST_NumInteriorRing(Geometry) → bigint#: Возвращает количество внутренних колец полигона.

line_interpolate_point(LineString, double) → Geometry#: Возвращает точку, интерполированную вдоль LineString на заданной доле. Доля должна быть в диапазоне от 0 до 1 включительно.

line_interpolate_points(LineString, double, repeated)#: Возвращает массив точек, интерполированных вдоль LineString. Доля должна быть в диапазоне от 0 до 1 включительно.

line_locate_point(LineString, Point) → double#

Возвращает число с плавающей точкой от 0 до 1, представляющее расположение ближайшей точки на LineString к заданной точке, как долю от общей двумерной длины линии.

Возвращает NULL, если LineString или Point пусты, или равны NULL.

geometry_invalid_reason(Geometry) → varchar#: Возвращает причину, по которой входная геометрия не является валидной. Возвращает NULL, если входные данные валидны.

great_circle_distance(latitude1, longitude1, latitude2, longitude2) → double#: Возвращает расстояние по дуге большого круга между двумя точками на поверхности Земли в километрах.

to_geojson_geometry(SphericalGeography) → varchar#: Возвращает GeoJSON-представление, определённое входной сферической географией.

from_geojson_geometry(varchar) → SphericalGeography#: Возвращает объект типа сферической географии из GeoJSON-представления, отбрасывая негеометрические ключи/значения. Feature и FeatureCollection не поддерживаются.

Агрегации#

convex_hull_agg(Geometry) → Geometry#: Возвращает минимальную выпуклую геометрию, охватывающую все входные геометрии.

geometry_union_agg(Geometry) → Geometry#: Возвращает геометрию, представляющую объединение множеств точек всех входных геометрий.

Тайлы Bing#

Эти функции выполняют преобразования между геометриями и тайлами Bing.

bing_tile(x, y, zoom_level) → BingTile#: Создаёт объект тайла Bing из координат XY и уровня масштабирования. Поддерживаются уровни масштабирования от 1 до 23.

bing_tile(quadKey) → BingTile: Создаёт объект тайла Bing из quadkey.

bing_tile_at(latitude, longitude, zoom_level) → BingTile#: Возвращает тайл Bing на заданном уровне масштабирования, содержащий точку с заданной широтой и долготой. Широта должна быть в диапазоне [-85.05112878, 85.05112878]. Долгота должна быть в диапазоне [-180, 180]. Поддерживаются уровни масштабирования от 1 до 23.

bing_tiles_around(latitude, longitude, zoom_level)#: Возвращает коллекцию тайлов Bing, окружающих точку, заданную аргументами широты и долготы, на заданном уровне масштабирования.

bing_tiles_around(latitude, longitude, zoom_level, radius_in_km): Возвращает минимальный набор тайлов Bing на указанном уровне масштабирования, покрывающих круг заданного радиуса в км вокруг указанной точки (широта, долгота).

bing_tile_coordinates(tile) → row<x, y>#: Возвращает координаты XY заданного тайла Bing.

bing_tile_polygon(tile) → Geometry#: Возвращает полигональное представление заданного тайла Bing.

bing_tile_quadkey(tile) → varchar#: Возвращает quadkey заданного тайла Bing.

bing_tile_zoom_level(tile) → tinyint#: Возвращает уровень масштабирования заданного тайла Bing.

geometry_to_bing_tiles(geometry, zoom_level)#: Возвращает минимальный набор тайлов Bing, полностью покрывающих заданную геометрию на заданном уровне масштабирования. Поддерживаются уровни масштабирования от 1 до 23.

Кодированные полилинии#

Эти функции выполняют преобразования между геометриями и кодированными полилиниями.

to_encoded_polyline(Geometry) → varchar#: Кодирует линию или мультиточку в полилинию.

from_encoded_polyline(varchar) → Geometry#: Декодирует полилинию в линию.