ST_Z function

The ST_Z function takes a point as an input parameter and returns its Y coordinate. You can optionally indicate a Z coordinate as input parameter in addition to the point and the function returns the point itself with its Y coordinate set to the given value.

ST_Z takes either:

A point as an input parameter and returns its Z coordinate
A point and a Z coordinate and returns the point itself with its Z coordinate set to the given value, even if the specified point has no existing Z coordinate.

If the specified Z coordinate is null, then the Z coordinate is removed from the point.

If the specified point is null or empty, then null is returned.

This function can also be called as a method.

Syntax

Parameters

point: A value of type ST_Point for which the Z coordinate is returned or modified.
z_coordinate: A value of type DOUBLE that represents the new Z coordinate for point.
If z_coordinate is null, then the Z coordinate is removed from point.

Return types

DOUBLE, if z_coordinate is not specified
db2gse.ST_Point, if z_coordinate is specified

Examples

Example 1

This example illustrates use of the ST_Z function. Geometries are created and inserted into the SAMPLE_POINTS table.


SET CURRENT FUNCTION PATH = CURRENT FUNCTION PATH, db2gse
CREATE TABLE sample_points (id INTEGER, geometry ST_Point)

INSERT INTO sample_points (id, geometry)
  VALUES (1, ST_Point (2, 3, 32, 5, 1) ),
         (2, ST_Point (4, 5, 20, 4, 1) ),
         (3, ST_Point (3, 8, 23, 7, 1) )

Example 2

This example finds the Z coordinates of the points in the table.


SELECT id, ST_Z (geometry) Z_COORD
  FROM sample_points

Results:


ID         Z_COORD
---------- ----------------------
         1 +3.20000000000000E+001
         2 +2.00000000000000E+001
         3 +2.30000000000000E+001

Example 3

This example returns a point with its Z coordinate set to 40.


SELECT id, CAST( ST_AsText( ST_Z (geometry, 40)) AS VARCHAR(60) )
  Z_40
  FROM sample_points
  WHERE id=3

Results:


ID         Z_40
------ -------------------------------------------------------
     3 POINT ZM ( 3.00000000 8.00000000 40.00000000 7.00000000)