ST_ToMultiLine method

Converts the geometry to a multilinestring value.

Syntax

geometry-expression.ST_ToMultiLine()

Returns

ST_MultiLineString If the geometry-expression is of type ST_MultiLineString, returns the geometry-expression. If the geometry-expression is a geometry collection containing only lines, returns a multilinestring object containing the elements of the geometry-expression. If the geometry-expression is of type ST_LineString then return a multilinestring value containing one element, the geometry-expression. If the geometry-expression is the empty set, returns an empty set of type ST_MultiCurve. 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_MultiLineString value, it is more efficient to use TREAT( geometry-expression AS ST_MultiLineString ) than the ST_ToMultiLine method.

Note

By default, ST_ToMultiLine 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 returns an error because the Shape column is of type ST_Geometry and ST_Geometry does not support the ST_Length method.

SELECT Shape.ST_Length() 
FROM SpatialShapes WHERE ShapeID = 29

The following uses ST_ToMultiLine to change the type of the Shape column expression to ST_MultiLineString. This example would also work with ShapeID 5, where the Shape value is of type ST_LineString. ST_Length returns the result 4.236068.

SELECT Shape.ST_ToMultiLine().ST_Length() 
FROM SpatialShapes WHERE ShapeID = 29

In this case, the value of the Shape column is known be of type ST_MultiLineString, so TREAT can be used to efficiently change the type of the expression. This example would not work with ShapeID 5, where the Shape value is of type ST_LineString. ST_Length returns the result 4.236068.

SELECT TREAT( Shape AS ST_MultiLineString ).ST_Length() 
FROM SpatialShapes WHERE ShapeID = 29

Discuss this page in DocCommentXchange.