Constructor functions for ST_Geometry

Constructor functions create a geometry from a well-known text description or another data format, such as well-known binary or shapefiles.

When you provide a well-known text description to construct a geometry, the measure coordinate must be specified last. For example, if your text includes coordinates for x, y, z, and m, they must be provided in that order, not x, y, m, z.

A geometry can have zero or more points. A geometry is considered empty if it has zero points. The point subtype is the only geometry that is restricted to zero or one point; all other subtypes can have zero or more.

The following sections describe the geometry superclass and subclass geometries, and list the functions that can construct each one.

The geometry superclass

The ST_Geometry superclass cannot be instantiated; although you can define a column as an ST_Geometry type, the actual data inserted is defined as either point, linestring, polygon, multipoint, multilinestring, or multipolygon entities.

The following functions can be used to create a superclass to hold any of the aforementioned entity types.

Subclasses

You can define a feature as a specific subclass, in which case only the entity type allowed for that subclass can be inserted. For example, ST_PointFromWKB can only construct point entities.

ST_Point

An ST_Point is a zero-dimensional geometry that occupies a single location in coordinate space. An ST_Point has a single x,y coordinate value, is always simple, and has a NULL boundary. ST_Point can be used to define features such as oil wells, landmarks, and water sample collection sites.

Functions that create a point are as follows:

ST_MultiPoint

An ST_MultiPoint is a collection of ST_Points and, like its elements, has a dimension of 0. An ST_MultiPoint is simple if none of its elements occupy the same coordinate space. The boundary of an ST_MultiPoint is NULL. ST_MultiPoints can define such things as aerial broadcast patterns and incidents of a disease outbreak.

Functions that create a multipoint geometry are as follows:

ST_LineString

An ST_LineString is a one-dimensional object stored as a sequence of points defining a linear interpolated path. The ST_LineString is simple if it does not intersect its interior. The endpoints (the boundary) of a closed ST_LineString occupy the same point in space. An ST_LineString is a ring if it is both closed and simple. Like the other properties inherited from the superclass ST_Geometry, ST_LineStrings have length. ST_LineStrings are often used to define linear features such as roads, rivers, and power lines.

The endpoints normally form the boundary of an ST_LineString unless the ST_LineString is closed, in which case the boundary is NULL. The interior of an ST_LineString is the connected path that lies between the endpoints unless it is closed, in which case the interior is continuous.

Functions that create linestrings include the following:

ST_MultiLineString

An ST_MultiLineString is a collection of ST_LineStrings.

The boundary of an ST_MultiLineString is the nonintersected endpoints of the ST_LineString elements. The boundary of an ST_MultiLineString is NULL if all the endpoints of all the elements are intersected. In addition to the other properties inherited from the superclass ST_Geometry, ST_MultiLineStrings have length. ST_MultiLineStrings are used to define noncontiguous linear features, such as streams or road networks.

Functions that construct multilinestrings are as follows:

ST_Polygon

An ST_Polygon is a two-dimensional surface stored as a sequence of points defining its exterior bounding ring and 0 or more interior rings. ST_Polygons are always simple. ST_Polygons define features that have spatial extent, such as parcels of land, water bodies, and areas of jurisdiction.

This graphic shows examples of ST_Polygon objects: (1) is an ST_Polygon for which the boundary is defined by an exterior ring. (2) is an ST_Polygon with a boundary defined by an exterior ring and two interior rings. The area inside the interior rings is part of the ST_Polygon's exterior. (3) is a legal ST_Polygon, because the rings intersect at a single tangent point.

Examples of ST_Polygon

The exterior and any interior rings define the boundary of an ST_Polygon, and the space enclosed between the rings defines the ST_Polygon's interior. The rings of an ST_Polygon can intersect at a tangent point but never cross. In addition to the other properties inherited from the superclass ST_Geometry, ST_Polygon have area.

Functions that create polygons include the following:

ST_MultiPolygon

The boundary of an ST_MultiPolygon is the cumulative length of its elements' exterior and interior rings. The interior of an ST_MultiPolygon is defined as the cumulative interiors of its element ST_Polygons. The boundary of an ST_MultiPolygon's elements can only intersect at a tangent point. In addition to the other properties inherited from the superclass ST_Geometry, ST_MultiPolygons have area. ST_MultiPolygons define features such as a forest stratum or a noncontiguous parcel of land such as a Pacific island chain.

The graphic below provides examples of ST_MultiPolygon: (1) is ST_MultiPolygon with two ST_Polygon elements. The boundary is defined by the two exterior rings and the three interior rings. (2) is an ST_MultiPolygon with two ST_Polygon elements. The boundary is defined by the two exterior rings and the two interior rings. The two ST_Polygon elements intersect at a tangent point.

Examples of ST_MultiPolygon

The following functions create multipolygons:

Related Topics

6/19/2015