ST_DISTANCE

Описание

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

В отличие от ST_DISTANCE_SPHERE, которая принимает координаты долготы и широты, ST_DISTANCE принимает в качестве параметров геометрические объекты (точки, линии, многоугольники, круги и т. д.) и вычисляет кратчайшее расстояние между их границами. Если две фигуры пересекаются (в том числе соприкасаются или одна содержит другую), функция возвращает 0.

Синтаксис

ST_DISTANCE( <shape1>, <shape2> )

Параметры

Параметр	Описание
<shape1>	Первый геометрический объект. Поддерживаются типы Point, Line, Polygon, Circle, MultiPolygon.
<shape2>	Второй геометрический объект. Поддерживаются типы Point, Line, Polygon, Circle, MultiPolygon.

Возвращаемое значение

Возвращает кратчайшее расстояние по поверхности сферы между границами двух геометрических объектов в метрах (тип DOUBLE).

Для ST_DISTANCE предусмотрены следующие особые случаи:

• Если любой из входных параметров равен NULL, возвращает NULL.
• Если любой из входных параметров не удаётся преобразовать в допустимый геометрический объект, возвращает NULL.
• Если два геометрических объекта пересекаются (в том числе один содержит другой), возвращает 0.0.
• Поддерживаются следующие типы геометрических объектов: POINT, LINESTRING, POLYGON, CIRCLE, MULTIPOLYGON.

Пример

Расстояние между точками

-- Calculate the distance between two points with a 1-degree longitude difference on the equator
SELECT ST_DISTANCE(ST_GeometryFromText('POINT(0 0)'), ST_GeometryFromText('POINT(1 0)'));

+------------------------------------------------------------------------------------+
| ST_DISTANCE(ST_GeometryFromText('POINT(0 0)'), ST_GeometryFromText('POINT(1 0)')) |
+------------------------------------------------------------------------------------+
|                                                                  111195.1011774839 |
+------------------------------------------------------------------------------------+

Расстояние между точкой и линией

-- Calculate the shortest distance from a point to a line
SELECT ST_DISTANCE(ST_GeometryFromText('POINT(2 2)'), ST_GeometryFromText('LINESTRING(0 0, 10 0)'));

+----------------------------------------------------------------------------------------------+
| ST_DISTANCE(ST_GeometryFromText('POINT(2 2)'), ST_GeometryFromText('LINESTRING(0 0, 10 0)')) |
+----------------------------------------------------------------------------------------------+
|                                                                            222390.2023549678 |
+----------------------------------------------------------------------------------------------+

Пересечение многоугольника и круга (расстояние 0)

-- Circle intersects polygon; the center is outside but the circle covers part of the polygon's boundary
SELECT ST_DISTANCE(
    ST_GeometryFromText('POLYGON ((-0.00045 -0.00045, 0.00045 -0.00045, 0.00045 0.00045, -0.00045 0.00045, -0.00045 -0.00045))'),
    ST_Circle(0.0006, 0, 50)
);

+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ST_DISTANCE(
    ST_GeometryFromText('POLYGON ((-0.00045 -0.00045, 0.00045 -0.00045, 0.00045 0.00045, -0.00045 0.00045, -0.00045 -0.00045))'),
    ST_Circle(0.0006, 0, 50)
) |
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|                                                                                                                                                                             0 |
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Недопустимый параметр (возвращает NULL)

-- Invalid WKT string
SELECT ST_DISTANCE(ST_GeometryFromText('NOT_A_GEOMETRY'), ST_GeometryFromText('POINT(1 1)'));

+---------------------------------------------------------------------------------------+
| ST_DISTANCE(ST_GeometryFromText('NOT_A_GEOMETRY'), ST_GeometryFromText('POINT(1 1)')) |
+---------------------------------------------------------------------------------------+
|                                                                                  NULL |
+---------------------------------------------------------------------------------------+

Параметр NULL

SELECT ST_DISTANCE(NULL, ST_GeometryFromText('POINT(1 1)'));

+------------------------------------------------------+
| ST_DISTANCE(NULL, ST_GeometryFromText('POINT(1 1)')) |
+------------------------------------------------------+
|                                                 NULL |
+------------------------------------------------------+