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

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

Геопространственные функции Trino поддерживают формы пространственных объектов 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(), чтобы создавать объекты geometry из WKT или WKB.

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

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

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

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

Используйте функцию to_spherical_geography(), чтобы преобразовать объект geometry в объект 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-представление geometry.

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

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

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

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

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

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

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

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

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

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

to_spherical_geography(Geometry) → SphericalGeography#: Преобразует объект Geometry в объект SphericalGeography на сфере радиуса Земли. Эта функция применима только к геометриям POINT, MULTIPOINT, LINESTRING, MULTILINESTRING, POLYGON, MULTIPOLYGON, определенным в 2D-пространстве, или к GEOMETRYCOLLECTION из таких геометрий. Для каждой точки входной геометрии функция проверяет, что point.x находится в диапазоне [-180.0, 180.0], а point.y — в диапазоне [-90.0, 90.0], и использует их как (longitude, latitude) в градусах для построения формы результата 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, если нет (если они disjoint).

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

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

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

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

Операции#

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

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

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

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

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

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

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

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

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

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

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

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

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

Аксессоры#

ST_Area(Geometry) → double#

Возвращает 2D-евклидову площадь geometry.

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

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

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

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

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

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

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

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

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

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

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

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

ST_IsEmpty(Geometry) → boolean#: Возвращает true, если эта Geometry является пустой geometrycollection, polygon, point и т.д.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

line_locate_point(LineString, Point) → double#

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

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

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

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

to_geojson_geometry(SphericalGeography) → varchar#: Возвращает GeoJSON-представление, определяемое входной spherical geography.

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

Агрегации#

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

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

Bing tiles#

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

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

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

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

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

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

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

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

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

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

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

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

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

to_encoded_polyline(Geometry) → varchar#: Кодирует linestring или multipoint в polyline.

from_encoded_polyline(varchar) → Geometry#: Декодирует polyline в linestring.