ST_ToMultiPolygon method

Converts the geometry to a multi-polygon value.

Syntax

geometry-expression.ST_ToMultiPolygon()

Returns

ST_MultiPolygon If the geometry-expression is of type ST_MultiPolygon, returns the geometry-expression. If the geometry-expression is a geometry collection containing only polygons, returns a multi-polygon object containing the elements of the geometry-expression. If the geometry-expression is of type ST_Polygon then return a multi-polygon value containing one element, the geometry-expression. If the geometry-expression is the empty set, returns an empty set of type ST_MultiSurface. Otherwise, raises an exception condition.
The spatial reference system identifier of the result is the same as the spatial reference system of the geometry-expression.

Remarks

If geometry-expression is already known to be an ST_MultiPolygon value, it is more efficient to use TREAT( geometry-expression AS ST_MultiPolygon ) than the ST_ToMultiPolygon method.

Note

By default, ST_ToMultiPolygon uses the original format for a geometry, if it is available. Otherwise, the internal format is used. For more information about internal and original formats, see STORAGE FORMAT clause, CREATE SPATIAL REFERENCE SYSTEM statement.

Standards and compatibility

Example

The following example returns the result MultiPolygon EMPTY.

SELECT NEW ST_GeomCollection().ST_ToMultiPolygon()

The following returns an error because the Shape column is of type ST_Geometry and ST_Geometry does not support the ST_Area method.

SELECT Shape.ST_Area()
FROM SpatialShapes WHERE ShapeID = 27

The following uses ST_ToMultiPolygon to change the type of the Shape column expression to ST_MultiPolygon. This example would also work with ShapeID 22, where the Shape value is of type ST_LineString. ST_Area returns the result 8.

SELECT Shape.ST_ToMultiPolygon().ST_Area()
FROM SpatialShapes WHERE ShapeID = 27

In this case, the value of the Shape column is known be of type ST_MultiPolygon, so TREAT can be used to efficiently change the type of the expression. This example would not work with ShapeID 22, where the Shape value is of type ST_Polygon. ST_Area returns the result 8.

SELECT TREAT( Shape AS ST_MultiPolygon ).ST_Area() 
FROM SpatialShapes WHERE ShapeID = 27

Discuss this page in DocCommentXchange.