ST_MultiPolygon function

The ST_MultiPolygon constructs a multipolygon from a specified input.

The input can be specified in one of the following format:
  • 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 the resulting multipolygon is in.

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

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

Syntax

Read syntax diagramSkip visual syntax diagram ST_MultiPolygon ( wktwkbshapegeojsongml,srs_id )

Parameters

wkt
A value of type VARCHAR or CLOB(2G) that contains the WKT format of the resulting multipolygon.
wkb
A value of type VARBINARY or BLOB(2G) that contains the well-known binary format of the resulting multipolygon.
shape
A value of type VARBINARY or BLOB(2G) that represents the ESRI shape format of the resulting multipolygon.
geojson
A value of type VARCHAR or CLOB(2G) that represents the resulting multipolygon using GeoJSON.
gml
A value of type VARCHAR or CLOB(2G) that represents the resulting multipolygon using the Geography Markup Language.
srs_id
A value of type INTEGER that identifies the spatial reference system for the resulting multipolygon.

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_MultiPolygon

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_MultiPolygon can be used to create and insert a multipolygon from its WKT format. The record that is inserted has ID = 1110, and the geometry is a multipolygon in spatial reference system 1. The multipolygon is in the WKT format of a multipolygon. The X and Y coordinates for this geometry are:
  • Polygon 1: (3, 3) (4, 6) (5, 3) (3, 3)
  • Polygon 2: (8, 24) (9, 25) (1, 28) (8, 24)
  • Polygon 3: (13, 33) (7, 36) (1, 40) (10, 43) (13, 33)

CREATE TABLE sample_mpolys (id INTEGER, geometry ST_MultiPolygon)

INSERT INTO sample_mpolys
  VALUES (1110,
          ST_MultiPolygon ('multipolygon (( (3 3, 4 6, 5 3, 3 3),
                                   (8 24, 9 25, 1 28, 8 24),
                                   (13 33, 7 36, 1 40, 10 43, 13 33) ))', 1))
The following SELECT statement returns the multipolygon that was recorded in the table:

SELECT id, CAST( ST_AsText( geometry ) AS VARCHAR(350) ) MULTI_POLYGON
  FROM sample_mpolys
  WHERE id = 1110
Results:

ID     MULTI_POLYGON
-----  ----------------------------------------------------------------------
 1110  MULTIPOLYGON (((13.000000 33.000000, 10.000000 43.000000, 
              1.000000 40.000000, 7.000000 36.000000, 13.000000 33.000000)),
            ((8.000000 24.000000, 9.000000 25.000000, 1.000000 28.000000, 
              8.000000 24.000000)),
            ((3.000000 3.000000, 5.000000 3.000000, 4.000000 6.000000, 
              3.000000 3.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_MultiPolygon can be used to create and insert a multipolygon from its WKT format. The record that is inserted has ID = 1110, and the geometry is a multipolygon in spatial reference system 1. The multipolygon is in the WKT format of a multipolygon. The X and Y coordinates for this geometry are:
  • Polygon 1: (3, 3) (4, 6) (5, 3) (3, 3)
  • Polygon 2: (8, 24) (9, 25) (1, 28) (8, 24)
  • Polygon 3: (13, 33) (7, 36) (1, 40) (10, 43) (13, 33)

CREATE TABLE sample_mpolys (id INTEGER, geometry ST_MultiPolygon)

INSERT INTO sample_mpolys
  VALUES (1110,
          ST_MultiPolygon ('multipolygon (( (3 3, 4 6, 5 3, 3 3),
                                   (8 24, 9 25, 1 28, 8 24),
                                   (13 33, 7 36, 1 40, 10 43, 13 33) ))', 1))
The following SELECT statement returns the multipolygon that was recorded in the table:

SELECT id, CAST( ST_AsText( geometry ) AS VARCHAR(350) ) MULTI_POLYGON
  FROM sample_mpolys
  WHERE id = 1110
Results:

ID     MULTI_POLYGON
-----  ----------------------------------------------------------------------
 1110  MULTIPOLYGON (((13.000000 33.000000, 10.000000 43.000000, 
              1.000000 40.000000, 7.000000 36.000000, 13.000000 33.000000)),
            ((8.000000 24.000000, 9.000000 25.000000, 1.000000 28.000000, 
              8.000000 24.000000)),
            ((3.000000 3.000000, 5.000000 3.000000, 4.000000 6.000000, 
              3.000000 3.000000))) 
                                               
Example 2:
This example illustrates how ST_MultiPolygon can be used to create and insert a multipolygon from its GeoJSON format using the same geometry data from Example 1. The record that is inserted has ID = 1111, and the geometry is a multipolygon in spatial reference system 4326 (the default). The multipolygon is in the GeoJSON format of a multipolygon.

CREATE TABLE sample_mpolys (id INTEGER, geometry ST_MultiPolygon)

INSERT INTO sample_mpolys
  VALUES (1111,
          ST_MultiPolygon ('{ "type": "multipolygon", "coordinates": 
                            [ [[[3, 3], [4, 6], [5, 3], [3, 3]]],
                              [[[8, 24], [9, 25], [1, 28], [8, 24]]],
                              [[[13, 33], [7, 36], [1, 40], [10, 43], [13, 33]]]
                            ] } '))
The following SELECT statement returns the multipolygon that was recorded in the table:

SELECT id, CAST( ST_AsText( geometry ) AS VARCHAR(350) ) MULTI_POLYGON
  FROM sample_mpolys
  WHERE id = 1111
Results:

ID     MULTI_POLYGON
-----  ----------------------------------------------------------------------
1111   MULTIPOLYGON (((13.000000000 33.000000000, 10.000000000 43.000000000, 
                       1.000000000 40.000000000, 7.000000000 36.000000000, 
                       13.000000000 33.000000000)),((8.000000000 24.000000000, 
                       9.000000000 25.000000000, 1.000000000 28.000000000, 
                       8.000000000 24.000000000)),((3.000000000 3.000000000, 
                       5.000000000 3.000000000, 4.000000000 6.000000000, 
                       3.000000000 3.000000000)))