ST_Length function

The ST_Length function takes a curve or multicurve and, optionally, a unit as input parameters and returns the length of the given curve or multicurve in the default or given unit of measure.

If the given curve or multicurve is null or is empty, null is returned.

This function can also be called as a method.

Syntax

Parameter

curve: A value of type ST_Curve or ST_MultiCurve that represents the curves for which the length is returned.
unit: A VARCHAR(128) value that identifies the units in which the length of the curve is measured. The supported units of measure are listed in the DB2GSE.ST_UNITS_OF_MEASURE catalog view.

If the unit parameter is omitted, the following rules are used to determine the unit in which the length is measured:

If curve is in a projected or geocentric coordinate system, the linear unit associated with this coordinate system is the default.
If curve is in a geographic coordinate system, the angular unit associated with this coordinate system is the default.

Restrictions on unit conversions: An error (SQLSTATE 38SU4) is returned if any of the following conditions occur:

The curve is in an unspecified coordinate system and the unit parameter is specified.
The curve is in a projected coordinate system and an angular unit is specified.
The curve is in a geographic coordinate system, and a linear unit is specified.

Return type

DOUBLE

Examples

Example 1

The following SQL statements create a table SAMPLE_GEOMETRIES and insert a line and a multiline into the table.


SET CURRENT FUNCTION PATH = CURRENT FUNCTION PATH, db2gse 

CREATE TABLE sample_geometries(id SMALLINT, spatial_type varchar(20), 
    geometry ST_GEOMETRY)

INSERT INTO sample_geometries(id, spatial_type, geometry)
VALUES
    (1110, 'ST_LineString', ST_LineString('linestring(50 10, 50 20)', 1)),
    (1111, 'ST_MultiLineString', ST_MultiLineString('multilinestring
                           ((33 2, 34 3, 35 6),
                           (28 4, 29 5, 31 8, 43 12),
                           (39 3, 37 4, 36 7))', 1))

Example 2

The following SELECT statement calculates the length of the line in the SAMPLE_GEOMTRIES table.


SELECT id, spatial_type, cast(ST_Length(geometry..ST_ToLineString)
   AS DECIMAL(7, 2)) AS "Line Length"
FROM   sample_geometries
WHERE  id = 1110

Results:


ID     SPATIAL_TYPE         Line Length
------ -------------------- -----------
  1110 ST_LineString              10.00

Example 3

The following SELECT statement calculates the length of the multiline in the SAMPLE_GEOMTRIES table.


SELECT id, spatial_type, ST_Length(ST_ToMultiLine(geometry))
   AS multiline_length
FROM   sample_geometries
WHERE  id = 1111

Results:


ID     SPATIAL_TYPE         MULTILINE_LENGTH
 ------ -------------------- ------------------------
   1111 ST_MultiLineString     +2.76437123387202E+001