ClickHouse/docs/en/sql-reference/functions/geo/polygon.md

slug	sidebar_label	title
/en/sql-reference/functions/geo/polygons	Polygons	Functions for Working with Polygons

readWKTMultiPolygon

Converts a WKT (Well Known Text) MultiPolygon into a MultiPolygon type.

Example

SELECT
    toTypeName(readWKTMultiPolygon('MULTIPOLYGON(((2 0,10 0,10 10,0 10,2 0),(4 4,5 4,5 5,4 5,4 4)),((-10 -10,-10 -9,-9 10,-10 -10)))')) AS type,
    readWKTMultiPolygon('MULTIPOLYGON(((2 0,10 0,10 10,0 10,2 0),(4 4,5 4,5 5,4 5,4 4)),((-10 -10,-10 -9,-9 10,-10 -10)))') AS output FORMAT Markdown

type	output
MultiPolygon	[(2,0),(10,0),(10,10),(0,10),(2,0)],[(4,4),(5,4),(5,5),(4,5),(4,4),(-10,-10),(-10,-9),(-9,10),(-10,-10)]

Input parameters

String starting with MULTIPOLYGON

Returned value

MultiPolygon

readWKTPolygon

Converts a WKT (Well Known Text) MultiPolygon into a Polygon type.

Example

SELECT
    toTypeName(readWKTPolygon('POLYGON((2 0,10 0,10 10,0 10,2 0))')) AS type,
    readWKTPolygon('POLYGON((2 0,10 0,10 10,0 10,2 0))') AS output
FORMAT Markdown

type	output
Polygon	(2,0),(10,0),(10,10),(0,10),(2,0)

Input parameters

String starting with POLYGON

Returned value

Polygon

polygonsWithinSpherical

Returns true or false depending on whether or not one polygon lies completely inside another polygon. Reference https://www.boost.org/doc/libs/1_62_0/libs/geometry/doc/html/geometry/reference/algorithms/within/within_2.html

Example

select polygonsWithinSpherical([[[(4.3613577, 50.8651821), (4.349556, 50.8535879), (4.3602419, 50.8435626), (4.3830299, 50.8428851), (4.3904543, 50.8564867), (4.3613148, 50.8651279)]]], [[[(4.346693, 50.858306), (4.367945, 50.852455), (4.366227, 50.840809), (4.344961, 50.833264), (4.338074, 50.848677), (4.346693, 50.858306)]]]);

0

Input parameters

Returned value

UInt8, 0 for false, 1 for true

polygonsDistanceSpherical

Calculates the minimal distance between two points where one point belongs to the first polygon and the second to another polygon. Spherical means that coordinates are interpreted as coordinates on a pure and ideal sphere, which is not true for the Earth. Using this type of coordinate system speeds up execution, but of course is not precise.

Example

SELECT polygonsDistanceSpherical([[[(0, 0), (0, 0.1), (0.1, 0.1), (0.1, 0)]]], [[[(10., 10.), (10., 40.), (40., 40.), (40., 10.), (10., 10.)]]])

0.24372872211133834

Input parameters

Two polygons

Returned value

Float64

polygonsDistanceCartesian

Calculates distance between two polygons

Example

SELECT polygonsDistanceCartesian([[[(0, 0), (0, 0.1), (0.1, 0.1), (0.1, 0)]]], [[[(10., 10.), (10., 40.), (40., 40.), (40., 10.), (10., 10.)]]])

14.000714267493642

Input parameters

Two polygons

Returned value

Float64

polygonsEqualsCartesian

Returns true if two polygons are equal

Example

SELECT polygonsEqualsCartesian([[[(1., 1.), (1., 4.), (4., 4.), (4., 1.)]]], [[[(1., 1.), (1., 4.), (4., 4.), (4., 1.), (1., 1.)]]])

1

Input parameters

Two polygons

Returned value

UInt8, 0 for false, 1 for true

polygonsSymDifferenceSpherical

Calculates the spatial set theoretic symmetric difference (XOR) between two polygons

Example

SELECT

Input parameters

Returned value

polygonsSymDifferenceCartesian

The same as polygonsSymDifferenceSpherical, but the coordinates are in the Cartesian coordinate system; which is more close to the model of the real Earth.

Example

SELECT

Input parameters

Returned value

polygonsIntersectionSpherical

Calculates the intersection (AND) between polygons, coordinates are spherical.

Example

SELECT

Input parameters

Returned value

polygonsWithinCartesian

Returns true if the second polygon is within the first polygon.

Example

SELECT polygonsWithinCartesian([[[(2., 2.), (2., 3.), (3., 3.), (3., 2.)]]], [[[(1., 1.), (1., 4.), (4., 4.), (4., 1.), (1., 1.)]]])

1

Input parameters

Two polygons

Returned value

UInt8, 0 for false, 1 for true

polygonConvexHullCartesian

Calculates a convex hull. Reference

Coordinates are in Cartesian coordinate system.

Example

SELECT

Input parameters

Returned value

polygonAreaSpherical

Calculates the surface area of a polygon.

Example

SELECT

Input parameters

Returned value

MultiPolygon

polygonsUnionSpherical

Calculates a union (OR).

Example

SELECT

Input parameters

Returned value

polygonPerimeterSpherical

Calculates

Example

SELECT

Input parameters

Returned value

polygonsIntersectionCartesian

Calculates

Example

SELECT

Input parameters

Returned value

polygonAreaCartesian

Calculates the area of a polygon

Example

SELECT polygonAreaCartesian([[[(0., 0.), (0., 5.), (5., 5.), (5., 0.)]]])

25

Input parameters

One polygon

Returned value

Float64

polygonPerimeterCartesian

Calculates

Example

SELECT polygonPerimeterCartesian([[[(0., 0.), (0., 5.), (5., 5.), (5., 0.)]]])

15

Input parameters

One polygon

Returned value

Float64

polygonsUnionCartesian

Calculates

Example

SELECT

Input parameters

Returned value

For more information on geometry systems, see this presentation about the Boost library, which is what ClickHouse uses.