ST_Polygon function

The ST_Polygon function constructs a polygon from a specified input.

The input can be specified in one of the following formats:

Well-known text (WKT) format
Well-known binary (WKB) format
ESRI shape format
GeoJSON format
Geography Markup Language (GML) format

An optional spatial reference system identifier can be specified to identify the spatial reference system that contains the resulting polygon.

If the specified input is null, then null is returned.

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

Syntax

Parameters

wkt

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

wkb

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

shape

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

geojson

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

gml

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

srs_id

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

If the polygon is constructed from a specified linestring parameter and the srs_id parameter is omitted, then the spatial reference system from linestring is used implicitly. Otherwise, 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).

Return type

ST_Polygon

Example

In the following example, the lines of results have been reformatted for readability. The spacing in your results will vary according to your online display.

This example illustrates how ST_Polygon can be used to create and insert polygons. Three polygons are created and inserted. All of them are geometries in spatial reference system 1.

The first polygon is created from a ring (a closed and simple linestring). The X and Y coordinates for this polygon are: (10, 20) (10, 40) (20, 30).
The second polygon is created using its WKT format. The X and Y coordinates for this polygon are: (110, 120) (110, 140) (120, 130).
The third polygon is a donut polygon. A donut polygon consists of an interior and an exterior polygon. This donut polygon is created using its WKT format. The X and Y coordinates for the exterior polygon are: (110, 120) (110, 140) (130, 140) (130, 120) (110, 120). The X and Y coordinates for the interior polygon are: (115, 125) (115, 135) (125, 135) (125, 135) (115, 125).


CREATE TABLE sample_polys (id INTEGER, geometry ST_Polygon)

INSERT INTO sample_polys
  VALUES (1100,
          ST_Polygon ('polygon 
                    ((10 20, 10 40, 20 30, 10 20))', 1))

INSERT INTO sample_polys
  VALUES (1101,
          ST_Polygon ('polygon 
                    ((110 120, 110 140, 120 130, 110 120))', 1))

INSERT INTO sample_polys
  VALUES (1102,
          ST_Polygon ('polygon 
                    ((110 120, 110 140, 130 140, 130 120, 110 120),
                    (115 125, 115 135, 125 135, 125 135, 115 125))', 1))

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


SELECT id, CAST( ST_AsText( geometry ) AS VARCHAR(220) ) POLYGONS
  FROM sample_polys

Results:


ID    POLYGONS
----- -------------------------------------------------------------------
 1100 POLYGON ((10.000000 20.000000, 20.000000 30.000000, 
                10.000000 40.000000, 10.000000 20.000000))                                                          
 1101 POLYGON ((110.000000 120.000000, 120.000000 130.000000, 
                110.000000 140.000000, 110.000000 120.000000))                                                  
 1102 POLYGON ((110.000000 120.000000, 130.000000 120.000000, 
                130.000000 140.000000, 110.000000 140.000000, 
                110.000000 120.000000),
               (115.000000 125.000000, 115.000000 135.000000, 
                125.000000 135.000000, 115.000000 125.000000))

Examples

Example 1:

In the following example, the lines of results have been reformatted for readability. The spacing in your results will vary according to your online display.

This example illustrates how ST_Polygon can be used to create and insert polygons. Three polygons are created and inserted. All of them are geometries in spatial reference system 1.

The first polygon is created from a ring (a closed and simple linestring). The X and Y coordinates for this polygon are: (10, 20) (10, 40) (20, 30).
The second polygon is created using its WKT format. The X and Y coordinates for this polygon are: (110, 120) (110, 140) (120, 130).
The third polygon is a donut polygon. A donut polygon consists of an interior and an exterior polygon. This donut polygon is created using its WKT format. The X and Y coordinates for the exterior polygon are: (110, 120) (110, 140) (130, 140) (130, 120) (110, 120). The X and Y coordinates for the interior polygon are: (115, 125) (115, 135) (125, 135) (125, 135) (115, 125).


CREATE TABLE sample_polys (id INTEGER, geometry ST_Polygon)

INSERT INTO sample_polys
  VALUES (1100,
          ST_Polygon ('polygon 
                    ((10 20, 10 40, 20 30, 10 20))', 1))

INSERT INTO sample_polys
  VALUES (1101,
          ST_Polygon ('polygon 
                    ((110 120, 110 140, 120 130, 110 120))', 1))

INSERT INTO sample_polys
  VALUES (1102,
          ST_Polygon ('polygon 
                    ((110 120, 110 140, 130 140, 130 120, 110 120),
                    (115 125, 115 135, 125 135, 125 135, 115 125))', 1))

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


SELECT id, CAST( ST_AsText( geometry ) AS VARCHAR(220) ) POLYGONS
  FROM sample_polys

Results:


ID    POLYGONS
----- -------------------------------------------------------------------
 1100 POLYGON ((10.000000 20.000000, 20.000000 30.000000, 
                10.000000 40.000000, 10.000000 20.000000))                                                          
 1101 POLYGON ((110.000000 120.000000, 120.000000 130.000000, 
                110.000000 140.000000, 110.000000 120.000000))                                                  
 1102 POLYGON ((110.000000 120.000000, 130.000000 120.000000, 
                130.000000 140.000000, 110.000000 140.000000, 
                110.000000 120.000000),
               (115.000000 125.000000, 115.000000 135.000000, 
                125.000000 135.000000, 115.000000 125.000000))

Example 2:

In the following example, the lines of results have been reformatted for readability. The spacing in your results will vary according to your online display.

This example illustrates how ST_Polygon can be used to create and insert polygons using the GeoJSON input format. Three polygons are created and inserted. All of them are geometries in the default spatial reference system 4326. The coordinate data is taken from Example 1.


CREATE TABLE sample_polys (id INTEGER, geometry ST_Polygon)

INSERT INTO sample_polys
  VALUES (1100,
          ST_Polygon ('{ "type": "polygon", "coordinates": 
                       [ [[10, 20], [10, 40], [20, 30], [10, 20]] ] }'))

INSERT INTO sample_polys
  VALUES (1101,
          ST_Polygon ('{ "type": "polygon", "coordinates": 
                       [ [[110, 120], [110, 140], [120, 130], [110, 120]] ] }'))

INSERT INTO sample_polys
  VALUES (1102,
          ST_Polygon ('{ "type": "polygon", "coordinates": 
                       [ [[110, 120], [110, 140], [130, 140], [130, 120], [110, 120]],
                         [[115, 125], [115, 135], [125, 135], [125, 135], [115, 125]]
                       ] }'))

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


SELECT id, CAST( ST_AsText( geometry ) AS VARCHAR(500) ) POLYGONS
  FROM sample_polys

Results:


ID          POLYGONS
----------- -----------------------------------------------------------------------
       1100 POLYGON ((10.000000000 20.000000000, 20.000000000 30.000000000, 
                      10.000000000 40.000000000, 10.000000000 20.000000000)) 
       1101 POLYGON ((110.000000000 120.000000000, 120.000000000 130.000000000, 
                      110.000000000 140.000000000, 110.000000000 120.000000000)) 
       1102 POLYGON ((110.000000000 120.000000000, 130.000000000 120.000000000, 
                      130.000000000 140.000000000, 110.000000000 140.000000000, 
                      110.000000000 120.000000000),(115.000000000 125.000000000, 
                      115.000000000 135.000000000, 125.000000000 135.000000000, 
                      115.000000000 125.000000000))