ST_Point function

The ST_Point function constructs a point from coordinate information or a resulting point of a representation.

ST_Point constructs a point from one of the following sets of input:

X and Y coordinates only
X, Y, and Z coordinates
X, Y, Z, and M coordinates
Well-known text (WKT) format
Well-known binary (WKB) format
ESRI shape format
GeoJSON format
A representation in the Geography Markup Language (GML)

An optional spatial reference system identifier can be specified to indicate the spatial reference system that the resulting point is in.

If the point is constructed from coordinates, and if the X or Y coordinate is null, then an exception condition is raised (SQLSTATE 38SUP).

If the Z or M coordinate is null, then the resulting point will not have a Z or M coordinate, respectively.

If the point is constructed from its WKT, WKB, ESRI shape, or GML format, and if the representation is null, then null is returned.

If the point is constructed from its WKT, WKB, ESRI shape, GeoJSON, or GML format, and if the representation is null, then null is returned.

For details about the supported formats, see Supported data formats.

Syntax

coordinates

Parameters

wkt

A value of type VARCHAR or CLOB(2G) that contains the WKT format of the resulting point.

wkb

A value of type VARBINARY or BLOB(2G) that contains the well-known binary format of the resulting point.

shape

A value of type VARBINARY or BLOB(2G) that represents the ESRI shape format of the resulting point.

geojson

A value of type VARCHAR or CLOB(2G) that represents the resulting point using GeoJSON.

gml

A value of type VARCHAR or CLOB(2G) that represents the resulting point using the Geography Markup Language.

srs_id

A value of type INTEGER that identifies the spatial reference system for the resulting point.

If the srs_id parameter is omitted, the spatial reference system with the numeric identifier 4326 is used.

If srs_id does not identify a spatial reference system listed in the catalog view SYSGEO.ST_SPATIAL_REFERENCE_SYSTEMS, then an exception condition is raised (SQLSTATE 38SU1).

x_coordinate

A value of type DOUBLE that specifies the X coordinate for the resulting point.

y_coordinate

A value of type DOUBLE that specifies the Y coordinate for the resulting point.

z_coordinate

A value of type DOUBLE that specifies the Z coordinate for the resulting point.

If the z_coordinate parameter is omitted, the resulting point will not have a Z coordinate. The result of ST_Is3D is 0 (zero) for such a point.

m_coordinate

A value of type DOUBLE that specifies the M coordinate for the resulting point.

If the m_coordinate parameter is omitted, the resulting point will not have a measure. The result of ST_IsMeasured is 0 (zero) for such a point.

Return type

ST_Point

Examples

In the following examples, the lines of results have been reformatted for readability. The spacing in your results will vary according to your online display. Also note that for illustration purposes of how different spatial reference systems affect the representation of the geometries, the examples use different spatial reference systems for inserts into the same spatial column. This is not a recommended practice.

Example 1:

This example illustrates how ST_Point can be used to create and insert points. The first point is created using a set of X and Y coordinates. The second point is created using its well-known text representation. Both points are geometries in spatial reference system 4326.


CREATE TABLE sample_points (id INTEGER, geometry ST_Point)

INSERT INTO sample_points
  VALUES (1100, ST_Point (10, 20))

INSERT INTO sample_points
  VALUES (1101, ST_Point ('point (30 40)', 4326))

The following SELECT statement returns the points that were recorded in the table:


SELECT id, CAST( ST_AsText( geometry ) AS VARCHAR(90)) POINTS
  FROM sample_points

Results:


ID          POINTS
----------- ------------------------------------
       1100 POINT (10.000000000 20.000000000)                                           
       1101 POINT (30.000000000 40.000000000)

Example 2:

This example inserts a record into the SAMPLE_POINTS table with ID 1103 and a point value with an X coordinate of 120, a Y coordinate of 358, an M coordinate of 34, but no Z coordinate, using the spatial reference system 4326.


INSERT INTO SAMPLE_POINTS(ID, GEOMETRY) 
 VALUES(1103, ST_Point(120, 358, CAST(NULL AS DOUBLE), 34, 4326))
 SELECT id, CAST( ST_AsText( geometry ) AS VARCHAR(90) ) POINTS
 FROM sample_points WHERE ID = 1103

Results:


ID          POINTS
 ---------- ------------------------------------------------
       1103 POINT M(120.000000000 358.000000000 34.000)

Example 3:

This example inserts a row into the SAMPLE_POINTS table with ID 1104 and a point value with an X coordinate of 1003, a Y coordinate of 9876, a Z coordinate of 20, with the default spatial reference system (4326), and using the Geography Markup Language for its representation.


INSERT INTO SAMPLE_POINTS(ID, GEOMETRY)
 VALUES(1104, ST_Point('<gml:Point><gml:coord>
    <gml:x>1003</gml:X><gml:Y>9876</gml:Y><gml:Z>20</gml:Z>
    </gml:coord></gml:Point>'))
 SELECT id, CAST( ST_AsText( geometry ) AS VARCHAR(90) ) POINTS
 FROM sample_points WHERE ID = 1104

Results:


ID          POINTS
 ---------- ----------------------------------------------------
       1104 POINT Z(1003.000000000 9876.000000000 20.000)

Example 4:

This example inserts a row into the SAMPLE_POINTS table with ID 1105 and a point value with an X coordinate of 1003, a Y coordinate of 9876, a Z coordinate of 20, with the default spatial reference system (4326), and using the Geography Markup Language for its representation.


INSERT INTO SAMPLE_POINTS(ID, GEOMETRY)
 VALUES(1105, ST_Point('{ "type": "point", "coordinates": [1003, 9876, 20] }'))

 SELECT id, CAST( ST_AsText( geometry ) AS VARCHAR(90) ) POINTS
 FROM sample_points WHERE ID = 1105

Results:


ID          POINTS
----------- ------------------------------------------------------------------------------------------
       1105 POINT Z(1003.000000000 9876.000000000 20.000)