IBM® Informix® 12.10

Spatial functions

Use specific spatial data type functions to perform operations on spatial data.

Spatial data type functions can perform the following types of operations on spatial data:

Determine spatial relationships: You can determine whether a specific relationship exists between a pair of geometries.
The distance that separates a hazardous waste disposal site and a school is an example of a spatial relationship.
Produce a new geometry: You can compare two existing geometries and return a new geometry that is based on how the two geometries are related.
For example, the ST_Difference() function returns that portion of the first geometry that is not intersected or overlapped by the second.
Transform geometries: You can generate a new geometry from an existing geometry and a formula.

Functions can compare two geometries if the SRIDs of the arguments are the same. To compare two geometries that have different SRIDs, use the ST_Transform() function to transform one of the geometries.

The Dimensionally Extended 9 Intersection Model (DE-9IM) is a mathematical approach that defines the pair-wise spatial relationship between geometries of different types and dimensions.

Most spatial data functions are compliant with OpenGIS and ISO/SQLMM standards and have the prefix ST_. Some spatial data functions extend the OpenGIS and ISO/SQLMM standards and have the prefix SE_.

The following OpenGIS and ISO/SQLMM-compliant functions replace deprecated functions that extend the standards:

Table 1. Compliant functions that replace extension functions
Compliant function	Extension function
ST_Is3D()	SE_Is3D()
ST_IsMeasured()	SE_IsMeasured()
ST_LocateAlong()	SE_LocateAlong()
ST_LocateBetween()	SE_LocateBetween()
ST_M()	SE_M()
ST_Z()	SE_Z()
ST_MaxM()	SE_MMax()
ST_MinM()	SE_MMin()
ST_MaxX()	SE_XMax()
ST_MinX()	SE_XMin()
ST_MaxY()	SE_YMax()
ST_MinY()	SE_YMin()
ST_MaxZ()	SE_ZMax()
ST_MaxZ()	SE_ZMin()

The Dimensionally Extended 9 Intersection Model
The Dimensionally Extended 9 Intersection Model (DE-9IM) developed by Clementini and others, dimensionally extends the 9 Intersection Model of Egenhofer and Herring. DE-9IM is a mathematical approach that defines the pair-wise spatial relationship between geometries of different types and dimensions. This model expresses spatial relationships among all types of geometry as pair-wise intersections of their interior, boundary, and exterior with consideration for the dimension of the resulting intersections.
Summary of spatial functions by task type
The spatial data type functions do different types of tasks, such as generating different formats, manipulating or comparing data, and obtaining information about data.
The ST_Area() function
The ST_Area() function returns the area of a polygon or multipolygon.
The ST_AsBinary() function
The ST_AsBinary() function takes a geometry object and returns its well-known binary representation.
The SE_AsBSON() function
The SE_AsBSON() function takes a geometry object and returns a BSON document in GeoJSON format.
The SE_AsGML() function
The SE_AsGML() function returns the Geography Markup Language (GML) representation of an ST_Geometry spatial type.
The ST_AsGML() function
The ST_AsGML() function returns the Geography Markup Language (GML) representation of an ST_Geometry spatial type that conforms to either the GML2 or GML3 standard.
The SE_AsKML() function
The SE_AsKML() function returns the Keyhole Markup Language (KML) representation of an ST_Geometry spatial type.
The ST_AsKML() function
The ST_AsKML() function returns the Keyhole Markup Language (KML) representation of an ST_Geometry spatial type.
The SE_AsShape() function
The SE_AsShape() function takes a geometry object and returns it in ESRI shapefile format.
The ST_AsText() function
The ST_AsText() function takes an ST_Geometry object and returns its well-known text representation.
The SE_BBoxFromBSON() function
The SE_BBoxFromBSON() function takes a bson value with spatial data following the GeoJSON specification and a JSON path in a VARCHAR string, and returns an ST_Polygon object.
The ST_Boundary() function
The ST_Boundary() function takes a geometry object and returns its combined boundary as a geometry object.
The SE_BoundingBox() function
The SE_BoundingBox() function returns a polygon which represents the spatial extent (the minimum and maximum X and Y values) of all the geometries in a spatial column of a table.
The ST_Buffer() function
The ST_Buffer() function encircles a geometry object at a specified distance and returns a geometry object that is the buffer that surrounds the source object.
The ST_Centroid() function
The ST_Centroid() function takes a polygon or multipolygon and returns the geometric center of the bounding box of the polygon or multipolygon as a point.
The ST_Contains() function
The ST_Contains() function takes two geometry objects and returns t (TRUE) if the first object completely contains the second; otherwise, it returns f (FALSE).
The ST_ConvexHull() function
The ST_ConvexHull() function returns the convex hull of any geometry object that has at least three vertices forming a convex.
The ST_CoordDim() function
The ST_CoordDim() function returns the coordinate dimensions of the ST_Geometry value.
The SE_CreateSRID() function
The SE_CreateSRID() function is a utility function that, given the X and Y extents of a spatial data set, computes the false origin and system units and creates a new entry in the spatial_references table. Appropriate offsets and scale factors for typical Z values and M values are also provided.
The SE_CreateSrtext() function
The SE_CreateSrtext() function returns the OGC well-known text representation of a spatial reference system, given the ESRI Projection Engine ID number for a coordinate system.
The SE_CreateSrtextCount() function
The SE_CreateSrtextCount() function returns the number of spatial reference systems that use the specified ESRI Projection Engine ID number.
The SE_CreateSrtextList() function
The SE_CreateSrtextList() function returns the OGC well-known text representation of every spatial reference system that uses the specified ESRI Projection Engine ID number. The text for each spatial reference system is separated by a new line character.
The ST_Crosses() function
The ST_Crosses() function returns t (TRUE) if the intersection of two geometry objects results in an ST_Geometry object whose dimension is one less than the maximum dimension of the source objects.
The ST_Difference() function
The ST_Difference() function takes two geometry objects and returns a geometry object that is the difference of the source objects. In other words, it returns the portion of the primary geometry that is not intersected by the secondary geometry, the logical AND NOT of space.
The ST_Dimension() function
The ST_Dimension() function returns the dimension of a geometry object.
The ST_Disjoint() function
The ST_Disjoint() function takes two geometries and returns t (TRUE) if the two geometries are completely non-intersecting; otherwise, it returns f (FALSE).
The SE_Dissolve() function
The SE_Dissolve() function is an aggregate function that computes the union of geometries of the same dimension. If just one geometry satisfies your query, it is returned unaltered.
The ST_Distance() function
The ST_Distance() function returns the shortest distance that separates two geometries.
The ST_DistanceToPoint() function
The ST_DistanceToPoint() function returns the distance from the start of the line to the specified point. Z coordinates and measures are ignored.
The ST_EndPoint() function
The ST_EndPoint() function returns the last point of a linestring.
The ST_Envelope() function
The ST_Envelope() function returns the bounding box of a geometry object.
The ST_EnvelopeAsGML() function
The ST_EnvelopeAsGML() function takes a geometry value returned by ST_Envelope and generates a GML3 Envelope element.
The SE_EnvelopeAsKML() function
The SE_EnvelopeAsKML() function takes a geometry value returned by ST_Envelope and returns it as a KML LatLonBox.
The ST_EnvelopeFromGML() function
The ST_EnvelopeFromGML() function takes a GML2 or GML3 string representation of an envelope and an optional spatial reference ID and returns a geometry object.
The SE_EnvelopeFromKML() function
The SE_EnvelopeFromKML() function takes a KML LatLonBox or LatLonAltBox and an optional spatial reference ID and returns a polygon.
The SE_EnvelopesIntersect() function
The SE_EnvelopesIntersect() function returns t (TRUE) if the envelopes of two geometries intersect; otherwise, it returns f (FALSE).
The ST_Equals() function
The ST_Equals() function compares two geometries and returns t (TRUE) if the geometries are spatially equal; otherwise, it returns f (FALSE).
The ST_ExteriorRing() function
The ST_ExteriorRing() function returns the exterior ring of a polygon as a linestring.
The SE_Generalize() function
The SE_Generalize() function reduces the number of vertices in an ST_LineString, ST_MultiLineString, ST_Polygon, or ST_MultiPolygon while preserving the general character of the geometric shape.
The ST_GeometryN() function
The ST_GeometryN() function takes an ST_GeomCollection (ST_MultiPoint, ST_MultiLineString, or ST_MultiPolygon) and an INTEGER index and returns the nth ST_Geometry object in the collection.
The ST_GeometryType() function
The ST_GeometryType() function takes an ST_Geometry object and returns its geometry type as a string.
The SE_GeomFromBSON() function
The SE_GeomFromBson() function takes a bson value with spatial data following the GeoJSON specification and a JSON path in a VARCHAR string, and returns an ST_Geometry object.
The ST_GeomFromGML() function
The ST_GeomFromGML() function takes a GML2 or GML version 3 string representation and an optional spatial reference ID and returns a geometry object.
The ST_GeomFromKML() function
The ST_GeomFromKML() function takes a KML fragment and returns an ST_Geometry corresponding to the fragment.
The SE_GeomFromShape() function
The SE_GeomFromShape() function takes a shape and a spatial reference ID and returns a geometry object.
The ST_GeomFromText() function
The ST_GeomFromText() function takes a well-known text representation and a spatial reference ID and returns a geometry object.
The ST_GeomFromWKB() function
The ST_GeomFromWKB() function takes a well-known binary representation and a spatial reference ID to return a geometry object.
The SE_InRowSize() function
The SE_InRowSize() function returns the size of the in-row portion of a geometry. Geometries which are less than 930 bytes are stored entirely in-row: that is, the entire value is stored in a table's dbspace.
The ST_InteriorRingN() function
The ST_InteriorRingN() function returns the nth interior ring of a polygon as an ST_LineString.
The ST_Intersection() function
The ST_Intersection() function takes two ST_Geometry objects and returns the intersection set as an ST_Geometry object. If the two objects do not intersect, the return value is an empty geometry.
The ST_Intersects() function
The ST_Intersects() function returns t (TRUE) if the intersection of two geometries does not result in an empty set; otherwise, returns f (FALSE).
The ST_Is3D() function
The SE_Is3d() function returns t (TRUE) if the ST_Geometry object has three-dimensional coordinates; otherwise, returns f (FALSE).
The ST_IsClosed() function
The ST_IsClosed() function takes an ST_LineString or ST_MultiLineString and returns t (TRUE) if it is closed; otherwise, it returns f (FALSE).
The ST_IsEmpty() function
The ST_IsEmpty() function returns t (TRUE) if the geometry is empty; otherwise, returns f (FALSE).
The ST_IsMeasured() function
The ST_IsMeasured() function returns t (TRUE) if the ST_Geometry object has measures; otherwise, returns f (FALSE).
The ST_IsRing() function
The ST_IsRing() function takes an ST_LineString and returns t (TRUE) if it is a ring (that is, the ST_LineString is closed and simple); otherwise, it returns f (FALSE).
The ST_IsSimple() function
The ST_IsValid() function
The ST_Length() function
The ST_Length() function returns the length of an ST_LineString or ST_MultiLineString.
The SE_LineFromBSON() function
The SE_LineFromBson() function takes a bson value with spatial data following the GeoJSON specification and a JSON path in a VARCHAR string, and returns an ST_LineString object.
The ST_LineFromGML() function
The ST_LineFromKML() function
The SE_LineFromShape() function
The ST_LineFromText() function
The ST_LineFromWKB() function
The ST_LocateAlong() function
The ST_LocateAlong() function takes a geometry object and a measure to return as an ST_MultiPoint the set of points found having that measure.
The ST_LocateBetween() function
The ST_LocateBetween() function takes an ST_Geometry object and two measure locations and returns an ST_Geometry that represents the set of disconnected paths between the two measure locations.
The ST_M() function
The ST_MaxM() and ST_MinM() functions
The ST_MaxX() and ST_MinX() functions
The ST_MaxY() and ST_MinY() functions
The ST_MaxZ() and ST_MinZ() functions
The SE_MetadataInit() function
The SE_MetadataInit() function reinitializes the spatial reference system large object and memory cache.
The SE_Midpoint() function
The SE_MLineFromBSON() function
The SE_MLineFromBSON() function takes a bson value with spatial data following the GeoJSON specification and a JSON path in a VARCHAR string, and returns an ST_MultiLineString object.
The ST_MLineFromGML() function
The ST_MLineFromKML() function
The SE_MLineFromShape() function
The ST_MLineFromText() function
The ST_MLineFromWKB() function
The SE_MPointFromBSON() function
The SE_MPointFromBSON() function takes a bson value with spatial data following the GeoJSON specification and a JSON path in a VARCHAR string, and returns an ST_MultiPoint object.
The ST_MPointFromGML() function
The ST_MPointFromKML() function
The SE_MPointFromShape() function
The ST_MPointFromText() function
The ST_MPointFromWKB() function
The SE_MPolyFromBSON() function
The SE_MPolyFromBSON() function takes a bson value with spatial data following the GeoJSON specification and a JSON path in a VARCHAR string, and returns an ST_MultiPolygon object.
The ST_MPolyFromGML() function
The ST_MPolyFromKML() function
The SE_MPolyFromShape() function
The ST_MPolyFromText() function
The ST_MPolyFromWKB() function
The SE_Nearest() and SE_NearestBbox() functions
The SE_Nearest() function returns the nearest-neighbors to a specified geometry. The SE_NearestBBox() function returns the nearest-neighbors that are based on the distance between bounding boxes.
The ST_NumGeometries() function
The ST_NumInteriorRing() function
The ST_NumPoints() function
The SE_OutOfRowSize() function
The ST_Overlaps() function
The ST_Overlaps() function returns t (TRUE) if the intersection of two ST_Geometry objects results in an ST_Geometry object of the same dimension but not equal to either source object. Otherwise, it returns f (FALSE).
The SE_ParamGet() function
The SE_ParamSet() function
The ST_Perimeter() function
The ST_Perimeter() function returns the perimeter of a polygon or multipolygon.
The SE_PerpendicularPoint() function
The ST_Point() function
The ST_PointAtDistance() function
The ST_PointAtDistance() function returns the point the specified distance from the start of the line. Z coordinates and measures are ignored.
The SE_PointFromBSON() function
The SE_PointFromBson() function takes a bson value with spatial data following the GeoJSON specification and a JSON path in a VARCHAR string, and returns an ST_Point object.
The ST_PointFromGML() function
The ST_PointFromKML() function
The SE_PointFromShape() function
The ST_PointFromText() function
The ST_PointFromWKB() function
The ST_PointN() function
The ST_PointOnSurface() function
The SE_PolyFromBSON() function
The SE_PolyFromBSON() function takes a bson value with spatial data following the GeoJSON specification and a JSON path in a VARCHAR string, and returns an ST_Polygon object.
The ST_PolyFromGML() function
The ST_PolyFromKML() function
The SE_PolyFromShape() function
The ST_PolyFromText() function
The ST_PolyFromWKB() function
The ST_Polygon() function
The ST_Relate() function
The SE_Release() function
The SE_Release() function returns a text string containing the installed version and release date of the IBM Informix spatial extension.
The SE_ShapeToSQL() function
The SE_SpatialKey() function
The SE_SpatialKey() function generates a sort key for an ST_Geometry. A sort key is a numeric value that can be used to sort spatial objects according to their proximity to one another.
The ST_SRID() function
The SE_SRID_Authority() function
The ST_StartPoint() function
The ST_SymDifference() function
The ST_SymDifference() function takes two ST_Geometry objects and returns an ST_Geometry object that is the logical XOR of space. In other words, it returns an object that is composed of the portions of the source objects that are not part of the intersection set.
The SE_TotalSize() function
The ST_Touches() function
The ST_Touches() function returns t (TRUE) if none of the points common to both geometries intersect the interiors of both geometries; otherwise, it returns f (FALSE). At least one geometry must be an ST_LineString, ST_Polygon, ST_MultiLineString, or ST_MultiPolygon.
The SE_Trace() function
The SE_Trace() function provides tracing for spatial data type functions.
The ST_Transform() function
The ST_Transform() function transforms an ST_Geometry into the specified spatial reference system.
The ST_Union() function
The ST_Union() function returns an ST_Geometry object that is the union of two source objects, the Boolean logical OR of space.
The SE_VertexAppend() function
The SE_VertexDelete() function
The SE_VertexUpdate() function
The ST_Within() function
The ST_Within() function returns t (TRUE) if the first object is completely within the second; otherwise, it returns f (FALSE).
The ST_WKBToSQL() function
The ST_WKBToSQL() function constructs an ST_Geometry given its well-known binary representation. The SRID of the ST_Geometry is 0.
The ST_WKTToSQL() function
The ST_X() function
The ST_Y() function
The ST_Z function

Parent topic: Spatial Data User's Guide

Examples exchange | Troubleshooting

To find the PDF, see Publications for the IBM Informix 12.10 family of products.
For the release notes, documentation notes, and/or machine notes, see the Release Notes page.