Chapter 8. PostGIS Reference
Prev		Next

Chapter 8. PostGIS Reference

Table of Contents

The functions given below are the ones which a user of PostGIS is likely to need. There are other functions which are required support functions to the PostGIS objects which are not of use to a general user.

PostGIS has begun a transition from the existing naming convention to an SQL-MM-centric convention. As a result, most of the functions that you know and love have been renamed using the standard spatial type (ST) prefix. Previous functions are still available, though are not listed in this document where updated functions are equivalent. The non ST_ functions not listed in this documentation are deprecated and will be removed in a future release so STOP USING THEM.

8.1. PostGIS Geometry/Geography/Box Data Types

Abstract

This section lists the custom PostgreSQL data types installed by PostGIS to represent spatial data.

Each data type describes its type casting behaviour. A type cast converts values of one data type into another type. PostgreSQL allows defining casting behavior for custom types, along with the functions used to convert type values. Casts can have automatic behaviour, which allows automatic conversion of a function argument to a type supported by the function.

Some casts have explicit behaviour, which means the cast must be specified using the syntax CAST(myval As sometype) or myval::sometype. Explicit casting avoids the issue of ambiguous casts, which can occur when using an overloaded function which does not support a given type. For example, a function may accept a box2d or a box3d, but not a geometry. Since geometry has an automatic cast to both box types, this produces an "ambiguous function" error. To prevent the error use an explicit cast to the desired box type.

All data types can be cast to text, so this does not need to be specified explicitly.

box2d — A 2-dimensional bounding box. Used to describe the 2D extent of a geometry or collection of geometries.
box3d — A 3-dimensional bounding box. Used to describe the 3D extent of a geometry or collection of geometries.
geometry — The type representing spatial features with planar coordinate systems.
geometry_dump — A composite type used to describe the parts of complex geometry.
geography — The type representing spatial features with geodetic (ellipsoidal) coordinate systems.

8.2. Table Management Functions

Abstract

These functions assist in defining tables containing geometry columns.

AddGeometryColumn — Adds a geometry column to an existing table.
DropGeometryColumn — Removes a geometry column from a spatial table.
DropGeometryTable — Drops a table and all its references in geometry_columns.
Find_SRID — Returns the SRID defined for a geometry column.
Populate_Geometry_Columns — Ensures geometry columns are defined with type modifiers or have appropriate spatial constraints.
UpdateGeometrySRID — Updates the SRID of all features in a geometry column, and the table metadata.

8.3. Geometry Constructors

ST_Collect — Creates a GeometryCollection or Multi* geometry from a set of geometries.
ST_LineFromMultiPoint — Creates a LineString from a MultiPoint geometry.
ST_MakeEnvelope — Creates a rectangular Polygon from minimum and maximum coordinates.
ST_MakeLine — Creates a Linestring from Point, MultiPoint, or LineString geometries.
ST_MakePoint — Creates a 2D, 3DZ or 4D Point.
ST_MakePointM — Creates a Point from X, Y and M values.
ST_MakePolygon — Creates a Polygon from a shell and optional list of holes.
ST_Point — Creates a Point with the given coordinate values. Alias for ST_MakePoint.
ST_Polygon — Creates a Polygon from a LineString with a specified SRID.
ST_TileEnvelope — Creates a rectangular Polygon in Web Mercator (SRID:3857) using the XYZ tile system.

8.4. Geometry Accessors

GeometryType — Returns the type of a geometry as text.
ST_Boundary — Returns the boundary of a geometry.
ST_CoordDim — Return the coordinate dimension of a geometry.
ST_Dimension — Returns the topological dimension of a geometry.
ST_Dump — Returns a set of geometry_dump rows for the components of a geometry.
ST_DumpPoints — Returns a set of geometry_dump rows for the points in a geometry.
ST_DumpRings — Returns a set of geometry_dump rows for the exterior and interior rings of a Polygon.
ST_EndPoint — Returns the last point of a LineString or CircularLineString.
ST_Envelope — Returns a geometry representing the bounding box of a geometry.
ST_BoundingDiagonal — Returns the diagonal of a geometry's bounding box.
ST_ExteriorRing — Returns a LineString representing the exterior ring of a Polygon.
ST_GeometryN — Return the Nth geometry element of a geometry collection.
ST_GeometryType — Returns the SQL-MM type of a geometry as text.
ST_HasArc — Tests if a geometry contains a circular arc
ST_InteriorRingN — Returns the Nth interior ring (hole) of a Polygon.
ST_IsPolygonCCW — Tests if Polygons have exterior rings oriented counter-clockwise and interior rings oriented clockwise.
ST_IsPolygonCW — Tests if Polygons have exterior rings oriented clockwise and interior rings oriented counter-clockwise.
ST_IsClosed — Tests if a LineStrings's start and end points are coincident. For a PolyhedralSurface tests if it is closed (volumetric).
ST_IsCollection — Tests if a geometry is a geometry collection type.
ST_IsEmpty — Tests if a geometry is empty.
ST_IsRing — Tests if a LineString is closed and simple.
ST_IsSimple — Tests if a geometry has no points of self-intersection or self-tangency.
ST_M — Returns the M coordinate of a Point.
ST_MemSize — Returns the amount of memory space a geometry takes.
ST_NDims — Returns the coordinate dimension of a geometry.
ST_NPoints — Returns the number of points (vertices) in a geometry.
ST_NRings — Returns the number of rings in a polygonal geometry.
ST_NumGeometries — Returns the number of elements in a geometry collection.
ST_NumInteriorRings — Returns the number of interior rings (holes) of a Polygon.
ST_NumInteriorRing — Returns the number of interior rings (holes) of a Polygon. Aias for ST_NumInteriorRings
ST_NumPatches — Return the number of faces on a Polyhedral Surface. Will return null for non-polyhedral geometries.
ST_NumPoints — Returns the number of points in a LineString or CircularString.
ST_PatchN — Returns the Nth geometry (face) of a PolyhedralSurface.
ST_PointN — Returns the Nth point in the first LineString or circular LineString in a geometry.
ST_Points — Returns a MultiPoint containing all the coordinates of a geometry.
ST_StartPoint — Returns the first point of a LineString.
ST_Summary — Returns a text summary of the contents of a geometry.
ST_X — Returns the X coordinate of a Point.
ST_Y — Returns the Y coordinate of a Point.
ST_Z — Returns the Z coordinate of a Point.
ST_Zmflag — Returns a code indicating the ZM coordinate dimension of a geometry.

8.5. Geometry Editors

ST_AddPoint — Add a point to a LineString.
ST_CollectionExtract — Given a (multi)geometry, return a (multi)geometry consisting only of elements of the specified type.
ST_CollectionHomogenize — Given a geometry collection, return the "simplest" representation of the contents.
ST_Force2D — Force the geometries into a "2-dimensional mode".
ST_Force3D — Force the geometries into XYZ mode. This is an alias for ST_Force3DZ.
ST_Force3DZ — Force the geometries into XYZ mode.
ST_Force3DM — Force the geometries into XYM mode.
ST_Force4D — Force the geometries into XYZM mode.
ST_ForcePolygonCCW — Orients all exterior rings counter-clockwise and all interior rings clockwise.
ST_ForceCollection — Convert the geometry into a GEOMETRYCOLLECTION.
ST_ForcePolygonCW — Orients all exterior rings clockwise and all interior rings counter-clockwise.
ST_ForceSFS — Force the geometries to use SFS 1.1 geometry types only.
ST_ForceRHR — Force the orientation of the vertices in a polygon to follow the Right-Hand-Rule.
ST_ForceCurve — Upcast a geometry into its curved type, if applicable.
ST_LineMerge — Return a (set of) LineString(s) formed by sewing together a MULTILINESTRING.
ST_Multi — Return the geometry as a MULTI* geometry.
ST_Normalize — Return the geometry in its canonical form.
ST_QuantizeCoordinates — Sets least significant bits of coordinates to zero
ST_RemovePoint — Remove point from a linestring.
ST_Reverse — Return the geometry with vertex order reversed.
ST_Segmentize — Return a modified geometry/geography having no segment longer than the given distance.
ST_SetPoint — Replace point of a linestring with a given point.
ST_SnapToGrid — Snap all points of the input geometry to a regular grid.
ST_Snap — Snap segments and vertices of input geometry to vertices of a reference geometry.
ST_SwapOrdinates — Returns a version of the given geometry with given ordinate values swapped.

8.6. Geometry Validation

Abstract

These functions test whether geometries are valid according to the OGC SFS standard. They also provide information about the nature and location of invalidity.

ST_IsValid — Tests if a geometry is well-formed in 2D.
ST_IsValidDetail — Returns a valid_detail row stating if a geometry is valid, and if not a reason why and a location.
ST_IsValidReason — Returns text stating if a geometry is valid, or a reason for invalidity.

8.7. Spatial Reference System Functions

Abstract

These functions work with the Spatial Reference System of geometries.

ST_SetSRID — Set the SRID on a geometry to a particular integer value.
ST_SRID — Returns the spatial reference identifier for the ST_Geometry as defined in spatial_ref_sys table.
ST_Transform — Return a new geometry with its coordinates transformed to a different spatial reference system.

8.8. Geometry Input

Abstract

These functions create geometry objects from various textual or binary formats.

8.8.1. Well-Known Text (WKT)
8.8.2. Well-Known Binary (WKB)
8.8.3. Other Formats

8.8.1. Well-Known Text (WKT)

ST_BdPolyFromText — Construct a Polygon given an arbitrary collection of closed linestrings as a MultiLineString Well-Known text representation.
ST_BdMPolyFromText — Construct a MultiPolygon given an arbitrary collection of closed linestrings as a MultiLineString text representation Well-Known text representation.
ST_GeogFromText — Return a specified geography value from Well-Known Text representation or extended (WKT).
ST_GeographyFromText — Return a specified geography value from Well-Known Text representation or extended (WKT).
ST_GeomCollFromText — Makes a collection Geometry from collection WKT with the given SRID. If SRID is not given, it defaults to 0.
ST_GeomFromEWKT — Return a specified ST_Geometry value from Extended Well-Known Text representation (EWKT).
ST_GeometryFromText — Return a specified ST_Geometry value from Well-Known Text representation (WKT). This is an alias name for ST_GeomFromText
ST_GeomFromText — Return a specified ST_Geometry value from Well-Known Text representation (WKT).
ST_LineFromText — Makes a Geometry from WKT representation with the given SRID. If SRID is not given, it defaults to 0.
ST_MLineFromText — Return a specified ST_MultiLineString value from WKT representation.
ST_MPointFromText — Makes a Geometry from WKT with the given SRID. If SRID is not given, it defaults to 0.
ST_MPolyFromText — Makes a MultiPolygon Geometry from WKT with the given SRID. If SRID is not given, it defaults to 0.
ST_PointFromText — Makes a point Geometry from WKT with the given SRID. If SRID is not given, it defaults to unknown.
ST_PolygonFromText — Makes a Geometry from WKT with the given SRID. If SRID is not given, it defaults to 0.
ST_WKTToSQL — Return a specified ST_Geometry value from Well-Known Text representation (WKT). This is an alias name for ST_GeomFromText

8.8.2. Well-Known Binary (WKB)

ST_GeogFromWKB — Creates a geography instance from a Well-Known Binary geometry representation (WKB) or extended Well Known Binary (EWKB).
ST_GeomFromEWKB — Return a specified ST_Geometry value from Extended Well-Known Binary representation (EWKB).
ST_GeomFromWKB — Creates a geometry instance from a Well-Known Binary geometry representation (WKB) and optional SRID.
ST_LineFromWKB — Makes a LINESTRING from WKB with the given SRID
ST_LinestringFromWKB — Makes a geometry from WKB with the given SRID.
ST_PointFromWKB — Makes a geometry from WKB with the given SRID
ST_WKBToSQL — Return a specified ST_Geometry value from Well-Known Binary representation (WKB). This is an alias name for ST_GeomFromWKB that takes no srid

8.8.3. Other Formats

ST_Box2dFromGeoHash — Return a BOX2D from a GeoHash string.
ST_GeomFromGeoHash — Return a geometry from a GeoHash string.
ST_GeomFromGML — Takes as input GML representation of geometry and outputs a PostGIS geometry object
ST_GeomFromGeoJSON — Takes as input a geojson representation of a geometry and outputs a PostGIS geometry object
ST_GeomFromKML — Takes as input KML representation of geometry and outputs a PostGIS geometry object
ST_GeomFromTWKB — Creates a geometry instance from a TWKB ("Tiny Well-Known Binary") geometry representation.
ST_GMLToSQL — Return a specified ST_Geometry value from GML representation. This is an alias name for ST_GeomFromGML
ST_LineFromEncodedPolyline — Creates a LineString from an Encoded Polyline.
ST_PointFromGeoHash — Return a point from a GeoHash string.

8.9. Geometry Output

Abstract

These functions convert geometry objects into various textual or binary formats.

8.9.1. Well-Known Text (WKT)
8.9.2. Well-Known Binary (WKB)
8.9.3. Other Formats

8.9.1. Well-Known Text (WKT)

ST_AsEWKT — Return the Well-Known Text (WKT) representation of the geometry with SRID meta data.
ST_AsText — Return the Well-Known Text (WKT) representation of the geometry/geography without SRID metadata.

8.9.2. Well-Known Binary (WKB)

ST_AsBinary — Return the Well-Known Binary (WKB) representation of the geometry/geography without SRID meta data.
ST_AsEWKB — Return the Well-Known Binary (WKB) representation of the geometry with SRID meta data.
ST_AsHEXEWKB — Returns a Geometry in HEXEWKB format (as text) using either little-endian (NDR) or big-endian (XDR) encoding.

8.9.3. Other Formats

ST_AsEncodedPolyline — Returns an Encoded Polyline from a LineString geometry.
ST_AsGeobuf — Return a Geobuf representation of a set of rows.
ST_AsGeoJSON — Return the geometry as a GeoJSON element.
ST_AsGML — Return the geometry as a GML version 2 or 3 element.
ST_AsKML — Return the geometry as a KML element. Several variants. Default version=2, default maxdecimaldigits=15
ST_AsLatLonText — Return the Degrees, Minutes, Seconds representation of the given point.
ST_AsMVTGeom — Transform a geometry into the coordinate space of a Mapbox Vector Tile.
ST_AsMVT — Aggregate function returning a Mapbox Vector Tile representation of a set of rows.
ST_AsSVG — Returns SVG path data for a geometry.
ST_AsTWKB — Returns the geometry as TWKB, aka "Tiny Well-Known Binary"
ST_AsX3D — Returns a Geometry in X3D xml node element format: ISO-IEC-19776-1.2-X3DEncodings-XML
ST_GeoHash — Return a GeoHash representation of the geometry.

8.10. Operators

8.10.1. Bounding Box Operators
8.10.2. Distance Operators

8.10.1. Bounding Box Operators

&& — Returns TRUE if A's 2D bounding box intersects B's 2D bounding box.
&&(geometry,box2df) — Returns TRUE if a geometry's (cached) 2D bounding box intersects a 2D float precision bounding box (BOX2DF).
&&(box2df,geometry) — Returns TRUE if a 2D float precision bounding box (BOX2DF) intersects a geometry's (cached) 2D bounding box.
&&(box2df,box2df) — Returns TRUE if two 2D float precision bounding boxes (BOX2DF) intersect each other.
&&& — Returns TRUE if A's n-D bounding box intersects B's n-D bounding box.
&&&(geometry,gidx) — Returns TRUE if a geometry's (cached) n-D bounding box intersects a n-D float precision bounding box (GIDX).
&&&(gidx,geometry) — Returns TRUE if a n-D float precision bounding box (GIDX) intersects a geometry's (cached) n-D bounding box.
&&&(gidx,gidx) — Returns TRUE if two n-D float precision bounding boxes (GIDX) intersect each other.
&< — Returns TRUE if A's bounding box overlaps or is to the left of B's.
&<| — Returns TRUE if A's bounding box overlaps or is below B's.
&> — Returns TRUE if A' bounding box overlaps or is to the right of B's.
<< — Returns TRUE if A's bounding box is strictly to the left of B's.
<<| — Returns TRUE if A's bounding box is strictly below B's.
= — Returns TRUE if the coordinates and coordinate order geometry/geography A are the same as the coordinates and coordinate order of geometry/geography B.
>> — Returns TRUE if A's bounding box is strictly to the right of B's.
@ — Returns TRUE if A's bounding box is contained by B's.
@(geometry,box2df) — Returns TRUE if a geometry's 2D bounding box is contained into a 2D float precision bounding box (BOX2DF).
@(box2df,geometry) — Returns TRUE if a 2D float precision bounding box (BOX2DF) is contained into a geometry's 2D bounding box.
@(box2df,box2df) — Returns TRUE if a 2D float precision bounding box (BOX2DF) is contained into another 2D float precision bounding box.
|&> — Returns TRUE if A's bounding box overlaps or is above B's.
|>> — Returns TRUE if A's bounding box is strictly above B's.
~ — Returns TRUE if A's bounding box contains B's.
~(geometry,box2df) — Returns TRUE if a geometry's 2D bonding box contains a 2D float precision bounding box (GIDX).
~(box2df,geometry) — Returns TRUE if a 2D float precision bounding box (BOX2DF) contains a geometry's 2D bonding box.
~(box2df,box2df) — Returns TRUE if a 2D float precision bounding box (BOX2DF) contains another 2D float precision bounding box (BOX2DF).
~= — Returns TRUE if A's bounding box is the same as B's.

8.10.2. Distance Operators

<-> — Returns the 2D distance between A and B.
|=| — Returns the distance between A and B trajectories at their closest point of approach.
<#> — Returns the 2D distance between A and B bounding boxes.
<<->> — Returns the n-D distance between the centroids of A and B bounding boxes.
<<#>> — Returns the n-D distance between A and B bounding boxes.

8.11. Spatial Relationships

Abstract

These functions determine spatial relationships between geometries.

8.11.1. Topological Relationships
8.11.2. Distance Relationships

8.11.1. Topological Relationships

ST_3DIntersects — Returns TRUE if the Geometries "spatially intersect" in 3D - only for points, linestrings, polygons, polyhedral surface (area).
ST_Contains — Returns true if and only if no points of B lie in the exterior of A, and at least one point of the interior of B lies in the interior of A.
ST_ContainsProperly — Returns true if B intersects the interior of A but not the boundary (or exterior). A does not contain properly itself, but does contain itself.
ST_Covers — Returns 1 (TRUE) if no point in Geometry B is outside Geometry A
ST_CoveredBy — Returns 1 (TRUE) if no point in Geometry/Geography A is outside Geometry/Geography B
ST_Crosses — Returns TRUE if the supplied geometries have some, but not all, interior points in common.
ST_LineCrossingDirection — Given 2 linestrings, returns a number between -3 and 3 denoting what kind of crossing behavior. 0 is no crossing.
ST_Disjoint — Returns TRUE if the Geometries do not "spatially intersect" - if they do not share any space together.
ST_Equals — Returns true if the given geometries represent the same geometry. Directionality is ignored.
ST_Intersects — Returns TRUE if the Geometries/Geography "spatially intersect in 2D" - (share any portion of space) and FALSE if they don't (they are Disjoint). For geography tolerance is 0.00001 meters (so any points that close are considered to intersect)
ST_OrderingEquals — Returns true if the given geometries represent the same geometry and points are in the same directional order.
ST_Overlaps — Returns TRUE if the Geometries share space, are of the same dimension, but are not completely contained by each other.
ST_PointInsideCircle — Is the point geometry inside the circle defined by center_x, center_y, radius
ST_Relate — Returns true if this Geometry is spatially related to anotherGeometry, by testing for intersections between the Interior, Boundary and Exterior of the two geometries as specified by the values in the intersectionMatrixPattern. If no intersectionMatrixPattern is passed in, then returns the maximum intersectionMatrixPattern that relates the 2 geometries.
ST_RelateMatch — Returns true if intersectionMattrixPattern1 implies intersectionMatrixPattern2
ST_Touches — Returns TRUE if the geometries have at least one point in common, but their interiors do not intersect.
ST_Within — Returns true if the geometry A is completely inside geometry B

8.11.2. Distance Relationships

ST_3DDWithin — For 3d (z) geometry type Returns true if two geometries 3d distance is within number of units.
ST_3DDFullyWithin — Returns true if all of the 3D geometries are within the specified distance of one another.
ST_DFullyWithin — Returns true if all of the geometries are within the specified distance of one another
ST_DWithin — Returns true if the geometries are within the specified distance of one another. For geometry units are in those of spatial reference and for geography units are in meters and measurement is defaulted to use_spheroid=true (measure around spheroid), for faster check, use_spheroid=false to measure along sphere.

8.12. Measurement Functions

Abstract

These functions compute measurements of distance, area and angles. There are also functions to compute geometry values determined by measurements.

ST_Area — Returns the area of a polygonal geometry.
ST_Azimuth — Returns the north-based azimuth as the angle in radians measured clockwise from the vertical on pointA to pointB.
ST_Angle — Returns the angle between 3 points, or between 2 vectors (4 points or 2 lines).
ST_ClosestPoint — Returns the 2D point on g1 that is closest to g2. This is the first point of the shortest line.
ST_3DClosestPoint — Returns the 3D point on g1 that is closest to g2. This is the first point of the 3D shortest line.
ST_Distance — Returns the distance between two geometry or geography values.
ST_3DDistance — Returns the 3D cartesian minimum distance (based on spatial ref) between two geometries in projected units.
ST_DistanceSphere — Returns minimum distance in meters between two lon/lat geometries using a spherical earth model.
ST_DistanceSpheroid — Returns the minimum distance between two lon/lat geometries using a spheroidal earth model.
ST_FrechetDistance — Returns the Fréchet distance between two geometries.
ST_HausdorffDistance — Returns the Hausdorff distance between two geometries.
ST_Length — Returns the 2D length of a linear geometry.
ST_Length2D — Returns the 2D length of a linear geometry. Alias for ST_Length
ST_3DLength — Returns the 3D length of a linear geometry.
ST_LengthSpheroid — Returns the 2D or 3D length/perimeter of a lon/lat geometry on a spheroid.
ST_LongestLine — Returns the 2D longest line between two geometries.
ST_3DLongestLine — Returns the 3D longest line between two geometries
ST_MaxDistance — Returns the 2D largest distance between two geometries in projected units.
ST_3DMaxDistance — Returns the 3D cartesian maximum distance (based on spatial ref) between two geometries in projected units.
ST_MinimumClearance — Returns the minimum clearance of a geometry, a measure of a geometry's robustness.
ST_MinimumClearanceLine — Returns the two-point LineString spanning a geometry's minimum clearance.
ST_Perimeter — Returns the length of the boundary of a polygonal geometry or geography.
ST_Perimeter2D — Returns the 2D perimeter of a polygonal geometry. Alias for ST_Perimeter.
ST_3DPerimeter — Returns the 3D perimeter of a polygonal geometry.
ST_Project — Returns a point projected from a start point by a distance and bearing (azimuth).
ST_ShortestLine — Returns the 2D shortest line between two geometries
ST_3DShortestLine — Returns the 3D shortest line between two geometries

8.13. Geometry Processing

ST_Buffer — (T) Returns a geometry covering all points within a given distance from the input geometry.
ST_BuildArea — Creates an areal geometry formed by the constituent linework of given geometry
ST_Centroid — Returns the geometric center of a geometry.
ST_ClipByBox2D — Returns the portion of a geometry falling within a rectangle.
ST_ConcaveHull — The concave hull of a geometry represents a possibly concave geometry that encloses all geometries within the set. You can think of it as shrink wrapping.
ST_ConvexHull — Computes the convex hull of a geometry.
ST_CurveToLine — Converts a CIRCULARSTRING/CURVEPOLYGON/MULTISURFACE to a LINESTRING/POLYGON/MULTIPOLYGON
ST_DelaunayTriangles — Return a Delaunay triangulation around the given input points.
ST_Difference — Returns a geometry that represents that part of geometry A that does not intersect with geometry B.
ST_FlipCoordinates — Returns a version of the given geometry with X and Y axis flipped. Useful for people who have built latitude/longitude features and need to fix them.
ST_GeneratePoints — Converts a polygon or multi-polygon into a multi-point composed of randomly location points within the original areas.
ST_GeometricMedian — Returns the geometric median of a MultiPoint.
ST_Intersection — (T) Returns a geometry that represents the shared portion of geomA and geomB.
ST_LineToCurve — Converts a LINESTRING/POLYGON to a CIRCULARSTRING, CURVEPOLYGON
ST_MakeValid — Attempts to make an invalid geometry valid without losing vertices.
ST_MemUnion — Same as ST_Union, only memory-friendly (uses less memory and more processor time).
ST_MinimumBoundingCircle — Returns the smallest circle polygon that can fully contain a geometry. Default uses 48 segments per quarter circle.
ST_MinimumBoundingRadius — Returns the center point and radius of the smallest circle that can fully contain a geometry.
ST_OrientedEnvelope — Returns a minimum rotated rectangle enclosing a geometry.
ST_Polygonize — Aggregate. Creates a GeometryCollection containing possible polygons formed from the constituent linework of a set of geometries.
ST_Node — Node a set of linestrings.
ST_OffsetCurve — Return an offset line at a given distance and side from an input line. Useful for computing parallel lines about a center line
ST_PointOnSurface — Returns a POINT guaranteed to lie on the surface.
ST_RemoveRepeatedPoints — Returns a version of the given geometry with duplicated points removed.
ST_SharedPaths — Returns a collection containing paths shared by the two input linestrings/multilinestrings.
ST_ShiftLongitude — Toggle geometry coordinates between -180..180 and 0..360 ranges.
ST_WrapX — Wrap a geometry around an X value.
ST_Simplify — Returns a "simplified" version of the given geometry using the Douglas-Peucker algorithm.
ST_SimplifyPreserveTopology — Returns a "simplified" version of the given geometry using the Douglas-Peucker algorithm. Will avoid creating derived geometries (polygons in particular) that are invalid.
ST_SimplifyVW — Returns a "simplified" version of the given geometry using the Visvalingam-Whyatt algorithm
ST_ChaikinSmoothing — Returns a "smoothed" version of the given geometry using the Chaikin algorithm
ST_FilterByM — Filters vertex points based on their m-value
ST_SetEffectiveArea — Sets the effective area for each vertex, storing the value in the M ordinate. A simplified geometry can then be generated by filtering on the M ordinate.
ST_Split — Returns a collection of geometries resulting by splitting a geometry.
ST_SymDifference — Returns a geometry that represents the portions of A and B that do not intersect. It is called a symmetric difference because ST_SymDifference(A,B) = ST_SymDifference(B,A).
ST_Subdivide — Returns a set of geometry where no geometry in the set has more than the specified number of vertices.
ST_Union — Returns a geometry that represents the point set union of the Geometries.
ST_UnaryUnion — Like ST_Union, but working at the geometry component level.
ST_VoronoiLines — Returns the boundaries between the cells of the Voronoi diagram constructed from the vertices of a geometry.
ST_VoronoiPolygons — Returns the cells of the Voronoi diagram constructed from the vertices of a geometry.

8.14. Affine Transformations

Abstract

These functions change the position and shape of geometries using affine transformations.

ST_Affine — Apply a 3D affine transformation to a geometry.
ST_Rotate — Rotates a geometry about an origin point.
ST_RotateX — Rotates a geometry about the X axis.
ST_RotateY — Rotates a geometry about the Y axis.
ST_RotateZ — Rotates a geometry about the Z axis.
ST_Scale — Scales a geometry by given factors.
ST_Translate — Translates a geometry by given offsets.
ST_TransScale — Translates and scales a geometry by given offsets and factors.

8.15. Clustering Functions

Abstract

These functions implement clustering algorithms for sets of geometries.

ST_ClusterDBSCAN — Window function that returns a cluster id for each input geometry using the DBSCAN algorithm.
ST_ClusterIntersecting — Aggregate function that clusters the input geometries into connected sets.
ST_ClusterKMeans — Window function that returns a cluster id for each input geometry using the K-means algorithm.
ST_ClusterWithin — Aggregate function that clusters the input geometries by separation distance.

8.16. Bounding Box Functions

Abstract

These functions produce or operate on bounding boxes. They can also provide and accept geometry values, by using automatic or explicit casts.

Box2D — Returns a BOX2D representing the 2D extent of the geometry.
Box3D — Returns a BOX3D representing the 3D extent of the geometry.
ST_EstimatedExtent — Return the 'estimated' extent of a spatial table.
ST_Expand — Returns a bounding box expanded from another bounding box or a geometry.
ST_Extent — an aggregate function that returns the bounding box that bounds rows of geometries.
ST_3DExtent — an aggregate function that returns the 3D bounding box that bounds rows of geometries.
ST_MakeBox2D — Creates a BOX2D defined by two 2D point geometries.
ST_3DMakeBox — Creates a BOX3D defined by two 3D point geometries.
ST_XMax — Returns the X maxima of a 2D or 3D bounding box or a geometry.
ST_XMin — Returns the X minima of a 2D or 3D bounding box or a geometry.
ST_YMax — Returns the Y maxima of a 2D or 3D bounding box or a geometry.
ST_YMin — Returns the Y minima of a 2D or 3D bounding box or a geometry.
ST_ZMax — Returns the Z maxima of a 2D or 3D bounding box or a geometry.
ST_ZMin — Returns the Z minima of a 2D or 3D bounding box or a geometry.

8.17. Linear Referencing

ST_LineInterpolatePoint — Returns a point interpolated along a line. Second argument is a float8 between 0 and 1 representing fraction of total length of linestring the point has to be located.
ST_3DLineInterpolatePoint — Returns a point interpolated along a line in 3D. Second argument is a float8 between 0 and 1 representing fraction of total length of linestring the point has to be located.
ST_LineInterpolatePoints — Returns one or more points interpolated along a line.
ST_LineLocatePoint — Returns a float between 0 and 1 representing the location of the closest point on LineString to the given Point, as a fraction of total 2d line length.
ST_LineSubstring — Return a linestring being a substring of the input one starting and ending at the given fractions of total 2d length. Second and third arguments are float8 values between 0 and 1.
ST_LocateAlong — Return a derived geometry collection value with elements that match the specified measure. Polygonal elements are not supported.
ST_LocateBetween — Return a derived geometry collection value with elements that match the specified range of measures inclusively.
ST_LocateBetweenElevations — Return a derived geometry (collection) value with elements that intersect the specified range of elevations inclusively.
ST_InterpolatePoint — Return the value of the measure dimension of a geometry at the point closed to the provided point.
ST_AddMeasure — Return a derived geometry with measure elements linearly interpolated between the start and end points.

8.18. Trajectory Functions

Abstract

These functions support working with trajectories. A trajectory is a linear geometry with a measure (M value) on each coordinate. The measure values must increase along the line. Spatio-temporal data can be modelled by using relative times (such as the epoch) as the measure values.

ST_IsValidTrajectory — Returns true if the geometry is a valid trajectory.
ST_ClosestPointOfApproach — Returns the measure at which points interpolated along two trajectories are closest.
ST_DistanceCPA — Returns the distance between the closest point of approach of two trajectories.
ST_CPAWithin — Returns true if the closest point of approach of two trajectories is within the specified distance.

8.19. SFCGAL Functions

Abstract

SFCGAL is a C++ wrapper library around CGAL that provides advanced 2D and 3D spatial functions. For robustness, geometry coordinates have an exact rational number representation.

Installation instructions for the library can be found on the SFCGAL home page (http://www.sfcgal.org). To enable the functions use create extension postgis_sfcgal.

postgis_sfcgal_version — Returns the version of SFCGAL in use
ST_Extrude — Extrude a surface to a related volume
ST_StraightSkeleton — Compute a straight skeleton from a geometry
ST_ApproximateMedialAxis — Compute the approximate medial axis of an areal geometry.
ST_IsPlanar — Check if a surface is or not planar
ST_Orientation — Determine surface orientation
ST_ForceLHR — Force LHR orientation
ST_MinkowskiSum — Performs Minkowski sum
ST_ConstrainedDelaunayTriangles — Return a constrained Delaunay triangulation around the given input geometry.
ST_3DIntersection — Perform 3D intersection
ST_3DDifference — Perform 3D difference
ST_3DUnion — Perform 3D union
ST_3DArea — Computes area of 3D surface geometries. Will return 0 for solids.
ST_Tesselate — Perform surface Tesselation of a polygon or polyhedralsurface and returns as a TIN or collection of TINS
ST_Volume — Computes the volume of a 3D solid. If applied to surface (even closed) geometries will return 0.
ST_MakeSolid — Cast the geometry into a solid. No check is performed. To obtain a valid solid, the input geometry must be a closed Polyhedral Surface or a closed TIN.
ST_IsSolid — Test if the geometry is a solid. No validity check is performed.

8.20. Long Transaction Support

Abstract

These functions implement a row locking mechanism to support long transactions. They are provided primarily for implementors of the Web Feature Service specification.

AddAuth — Adds an authorization token to be used in the current transaction.
CheckAuth — Creates a trigger on a table to prevent/allow updates and deletes of rows based on authorization token.
DisableLongTransactions — Disables long transaction support.
EnableLongTransactions — Enables long transaction support.
LockRow — Sets lock/authorization for a row in a table.
UnlockRows — Removes all locks held by an authorization token.


	For the locking mechanism to operate correctly the serializable transaction isolation level must be used.

8.21. Version Functions

Abstract

These functions report and upgrade PostGIS versions.

PostGIS_Extensions_Upgrade — Packages and upgrades postgis extensions (e.g. postgis_raster, postgis_topology, postgis_sfcgal) to latest available version.
PostGIS_Full_Version — Reports full postgis version and build configuration infos.
PostGIS_GEOS_Version — Returns the version number of the GEOS library.
PostGIS_Liblwgeom_Version — Returns the version number of the liblwgeom library. This should match the version of PostGIS.
PostGIS_LibXML_Version — Returns the version number of the libxml2 library.
PostGIS_Lib_Build_Date — Returns build date of the PostGIS library.
PostGIS_Lib_Version — Returns the version number of the PostGIS library.
PostGIS_PROJ_Version — Returns the version number of the PROJ4 library.
PostGIS_Wagyu_Version — Returns the version number of the internal Wagyu library.
PostGIS_Scripts_Build_Date — Returns build date of the PostGIS scripts.
PostGIS_Scripts_Installed — Returns version of the postgis scripts installed in this database.
PostGIS_Scripts_Released — Returns the version number of the postgis.sql script released with the installed postgis lib.
PostGIS_Version — Returns PostGIS version number and compile-time options.

8.22. Grand Unified Custom Variables (GUCs)

Abstract

This section lists custom PostGIS Grand Unified Custom Variables (GUC). These can be set globally, by database, by session or by transaction. Best set at global or database level.

postgis.backend — The backend to service a function where GEOS and SFCGAL overlap. Options: geos or sfcgal. Defaults to geos.
postgis.gdal_datapath — A configuration option to assign the value of GDAL's GDAL_DATA option. If not set, the environmentally set GDAL_DATA variable is used.
postgis.gdal_enabled_drivers — A configuration option to set the enabled GDAL drivers in the PostGIS environment. Affects the GDAL configuration variable GDAL_SKIP.
postgis.enable_outdb_rasters — A boolean configuration option to enable access to out-db raster bands.

8.23. Troubleshooting Functions

Abstract

These functions are utilities for troubleshooting and repairing geometry data. They are only needed if the geometry data is corrupted in some way, which should never happen under normal circumstances.

PostGIS_AddBBox — Add bounding box to the geometry.
PostGIS_DropBBox — Drop the bounding box cache from the geometry.
PostGIS_HasBBox — Returns TRUE if the bbox of this geometry is cached, FALSE otherwise.