PostGIS - Spatial and Geographic Objects for PostgreSQL

Chapter 8. PostGIS Reference
Prev		Next

8.1. PostgreSQL PostGIS Geometry/Geography/Box Types

Abstract

This section lists the PostgreSQL data types installed by PostGIS. Note we describe the casting behavior of these which is very important especially when designing your own functions.

A Cast is when one type is coerced into another type. PostgreSQL is unique from most databases in that it allows you to define casting behavior for custom types and the functions used for casting. A cast can be specified as automatic in which case, you do not have to do a CAST(myfoo As otherfootype) or myfoo::otherfootype if you are feeding it to a function that only works with otherfootype and there is an automatic cast in place for it.

The danger of relying on automatic cast behavior is when you have an overloaded function say one that takes a box2d and one that takes a box3d but no geometry. What happens is that both functions are equally good to use with geometry since geometry has an autocast for both -- so you end up with an ambiguous function error. To force PostgreSQL to choose, you do a CAST(mygeom As box3d) or mygeom::box3d.

At least as of PostgreSQL 8.3 - Everything can be CAST to text (presumably because of the magical unknown type), so no defined CASTS for that need to be present for you to CAST an object to text.

box2d — A box composed of x min, ymin, xmax, ymax. Often used to return the 2d enclosing box of a geometry.
box3d — A box composed of x min, ymin, zmin, xmax, ymax, zmax. Often used to return the 3d extent of a geometry or collection of geometries.
geometry — Planar spatial data type.
geometry_dump — A spatial datatype with two fields - geom (holding a geometry object) and path[] (a 1-d array holding the position of the geometry within the dumped object.)
geography — Ellipsoidal spatial data type.

8.2. PostGIS 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.3. Management Functions

AddGeometryColumn — Adds a geometry column to an existing table of attributes. By default uses type modifier to define rather than constraints. Pass in false for use_typmod to get old check constraint based behavior
DropGeometryColumn — Removes a geometry column from a spatial table.
DropGeometryTable — Drops a table and all its references in geometry_columns.
PostGIS_Full_Version — Reports full postgis version and build configuration infos.
PostGIS_GEOS_Version — Returns the version number of the GEOS library.
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_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.
Populate_Geometry_Columns — Ensures geometry columns are defined with type modifiers or have appropriate spatial constraints This ensures they will be registered correctly in geometry_columns view. By default will convert all geometry columns with no type modifier to ones with type modifiers. To get old behavior set use_typmod=false
UpdateGeometrySRID — Updates the SRID of all features in a geometry column, geometry_columns metadata and srid. If it was enforced with constraints, the constraints will be updated with new srid constraint. If the old was enforced by type definition, the type definition will be changed.

8.4. Geometry Constructors

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_Box2dFromGeoHash — Return a BOX2D from a GeoHash string.
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_GeogFromWKB — Creates a geography instance from a Well-Known Binary geometry representation (WKB) or extended Well Known Binary (EWKB).
ST_GeomFromTWKB Creates a geometry instance from a TWKB ("Tiny Well-Known Binary") geometry representation.
ST_GeomCollFromText — Makes a collection Geometry from collection WKT with the given SRID. If SRID is not give, it defaults to 0.
ST_GeomFromEWKB — Return a specified ST_Geometry value from Extended Well-Known Binary representation (EWKB).
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_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_GMLToSQL — Return a specified ST_Geometry value from GML representation. This is an alias name for ST_GeomFromGML
ST_GeomFromText — Return a specified ST_Geometry value from Well-Known Text representation (WKT).
ST_GeomFromWKB — Creates a geometry instance from a Well-Known Binary geometry representation (WKB) and optional SRID.
ST_LineFromEncodedPolyline — Creates a LineString from an Encoded Polyline.
ST_LineFromMultiPoint — Creates a LineString from a MultiPoint geometry.
ST_LineFromText — Makes a Geometry from WKT representation with the given SRID. If SRID is not given, it defaults to 0.
ST_LineFromWKB — Makes a LINESTRING from WKB with the given SRID
ST_LinestringFromWKB — Makes a geometry from WKB with the given SRID.
ST_MakeBox2D — Creates a BOX2D defined by the given point geometries.
ST_3DMakeBox — Creates a BOX3D defined by the given 3d point geometries.
ST_MakeLine — Creates a Linestring from point, multipoint, or line geometries.
ST_MakeEnvelope — Creates a rectangular Polygon formed from the given minimums and maximums. Input values must be in SRS specified by the SRID.
ST_MakePolygon — Creates a Polygon formed by the given shell. Input geometries must be closed LINESTRINGS.
ST_MakePoint — Creates a 2D,3DZ or 4D point geometry.
ST_MakePointM — Creates a point geometry with an x y and m coordinate.
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 give, it defaults to 0.
ST_MPolyFromText — Makes a MultiPolygon Geometry from WKT with the given SRID. If SRID is not give, it defaults to 0.
ST_Point — Returns an ST_Point with the given coordinate values. OGC alias for ST_MakePoint.
ST_PointFromGeoHash — Return a point from a GeoHash string.
ST_PointFromText — Makes a point Geometry from WKT with the given SRID. If SRID is not given, it defaults to unknown.
ST_PointFromWKB — Makes a geometry from WKB with the given SRID
ST_Polygon — Returns a polygon built from the specified linestring and SRID.
ST_PolygonFromText — Makes a Geometry from WKT with the given SRID. If SRID is not give, it defaults to 0.
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
ST_WKTToSQL — Return a specified ST_Geometry value from Well-Known Text representation (WKT). This is an alias name for ST_GeomFromText

8.5. Geometry Accessors

GeometryType — Returns the type of the geometry as a string. Eg: 'LINESTRING', 'POLYGON', 'MULTIPOINT', etc.
ST_Boundary — Returns the closure of the combinatorial boundary of this Geometry.
ST_CoordDim — Return the coordinate dimension of the ST_Geometry value.
ST_Dimension — The inherent dimension of this Geometry object, which must be less than or equal to the coordinate dimension.
ST_EndPoint — Returns the last point of a LINESTRING or CIRCULARLINESTRING geometry as a POINT .
ST_Envelope — Returns a geometry representing the double precision (float8) bounding box of the supplied geometry.
ST_BoundingDiagonal — Returns the diagonal of the supplied geometry's bounding box.
ST_ExteriorRing — Returns a line string representing the exterior ring of the POLYGON geometry. Return NULL if the geometry is not a polygon. Will not work with MULTIPOLYGON
ST_GeometryN — Return the 1-based Nth geometry if the geometry is a GEOMETRYCOLLECTION, (MULTI)POINT, (MULTI)LINESTRING, MULTICURVE or (MULTI)POLYGON, POLYHEDRALSURFACE Otherwise, return NULL.
ST_GeometryType — Return the geometry type of the ST_Geometry value.
ST_InteriorRingN — Return the Nth interior linestring ring of the polygon geometry. Return NULL if the geometry is not a polygon or the given N is out of range.
ST_IsClosed — Returns TRUE if the LINESTRING 's start and end points are coincident. For Polyhedral surface is closed (volumetric).
ST_IsCollection — Returns TRUE if the argument is a collection ( MULTI* , GEOMETRYCOLLECTION , ...)
ST_IsEmpty — Returns true if this Geometry is an empty geometrycollection, polygon, point etc.
ST_IsRing — Returns TRUE if this LINESTRING is both closed and simple.
ST_IsSimple — Returns (TRUE) if this Geometry has no anomalous geometric points, such as self intersection or self tangency.
ST_IsValid — Returns true if the ST_Geometry is well formed.
ST_IsValidReason — Returns text stating if a geometry is valid or not and if not valid, a reason why.
ST_IsValidDetail — Returns a valid_detail (valid,reason,location) row stating if a geometry is valid or not and if not valid, a reason why and a location where.
ST_M — Return the M coordinate of the point, or NULL if not available. Input must be a point.
ST_NDims — Returns coordinate dimension of the geometry as a small int. Values are: 2,3 or 4.
ST_NPoints — Return the number of points (vertexes) in a geometry.
ST_NRings — If the geometry is a polygon or multi-polygon returns the number of rings.
ST_NumGeometries — If geometry is a GEOMETRYCOLLECTION (or MULTI*) return the number of geometries, for single geometries will return 1, otherwise return NULL.
ST_NumInteriorRings — Return the number of interior rings of a polygon geometry.
ST_NumInteriorRing — Return the number of interior rings of a polygon in the geometry. Synonym for ST_NumInteriorRings.
ST_NumPatches — Return the number of faces on a Polyhedral Surface. Will return null for non-polyhedral geometries.
ST_NumPoints — Return the number of points in an ST_LineString or ST_CircularString value.
ST_PatchN — Return the 1-based Nth geometry (face) if the geometry is a POLYHEDRALSURFACE, POLYHEDRALSURFACEM. Otherwise, return NULL.
ST_PointN — Return the Nth point in the first LineString or circular LineString in the geometry. Negative values are counted backwards from the end of the LineString. Returns NULL if there is no linestring in the geometry.
ST_Points — Returns a MultiPoint containing all of the coordinates of a geometry.
ST_SRID — Returns the spatial reference identifier for the ST_Geometry as defined in spatial_ref_sys table.
ST_StartPoint — Returns the first point of a LINESTRING geometry as a POINT .
ST_Summary — Returns a text summary of the contents of the geometry.
ST_X — Return the X coordinate of the point, or NULL if not available. Input must be a point.
ST_XMax — Returns X maxima of a bounding box 2d or 3d or a geometry.
ST_XMin — Returns X minima of a bounding box 2d or 3d or a geometry.
ST_Y — Return the Y coordinate of the point, or NULL if not available. Input must be a point.
ST_YMax — Returns Y maxima of a bounding box 2d or 3d or a geometry.
ST_YMin — Returns Y minima of a bounding box 2d or 3d or a geometry.
ST_Z — Return the Z coordinate of the point, or NULL if not available. Input must be a point.
ST_ZMax — Returns Z minima of a bounding box 2d or 3d or a geometry.
ST_Zmflag — Returns ZM (dimension semantic) flag of the geometries as a small int. Values are: 0=2d, 1=3dm, 2=3dz, 3=4d.
ST_ZMin — Returns Z minima of a bounding box 2d or 3d or a geometry.

8.6. Geometry Editors

ST_AddPoint — Add a point to a LineString.
ST_Affine — Apply a 3d affine transformation to a geometry.
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_ForceCollection — Convert the geometry into a GEOMETRYCOLLECTION.
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_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_Multi — Return the geometry as a MULTI* geometry.
ST_Normalize — Return the geometry in its canonical form.
ST_RemovePoint — Remove point from a linestring.
ST_Reverse — Return the geometry with vertex order reversed.
ST_Rotate — Rotate a geometry rotRadians counter-clockwise about an origin.
ST_RotateX — Rotate a geometry rotRadians about the X axis.
ST_RotateY — Rotate a geometry rotRadians about the Y axis.
ST_RotateZ — Rotate a geometry rotRadians about the Z axis.
ST_Scale — Scale a geometry by given factors.
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_SetSRID — Set the SRID on a geometry to a particular integer value.
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_Transform — Return a new geometry with its coordinates transformed to a different spatial reference.
ST_Translate — Translate a geometry by given offsets.
ST_TransScale — Translate a geometry by given factors and offsets.

8.7. Geometry Outputs

ST_AsBinary — Return the Well-Known Binary (WKB) representation of the geometry/geography without SRID meta data.
ST_AsEncodedPolyline — Returns an Encoded Polyline from a LineString geometry.
ST_AsEWKB — Return the Well-Known Binary (WKB) representation of the geometry with SRID meta data.
ST_AsEWKT — Return the Well-Known Text (WKT) representation of the geometry with SRID meta data.
ST_AsGeoJSON — Return the geometry as a GeoJSON element.
ST_AsGML — Return the geometry as a GML version 2 or 3 element.
ST_AsHEXEWKB — Returns a Geometry in HEXEWKB format (as text) using either little-endian (NDR) or big-endian (XDR) encoding.
ST_AsKML — Return the geometry as a KML element. Several variants. Default version=2, default precision=15
ST_AsLatLonText — Return the Degrees, Minutes, Seconds representation of the given point.
ST_AsSVG — Returns a Geometry in SVG path data given a geometry or geography object.
ST_AsText — Return the Well-Known Text (WKT) representation of the geometry/geography without SRID metadata.
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.8. 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 A's bounding box is the same as B's. Uses double precision bounding box.
>> — 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.
<-> — 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.9. Spatial Relationships and Measurements

ST_3DClosestPoint — Returns the 3-dimensional point on g1 that is closest to g2. This is the first point of the 3D shortest line.
ST_3DDistance — For geometry type Returns the 3-dimensional cartesian minimum distance (based on spatial ref) between two geometries in projected units.
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_3DIntersects — Returns TRUE if the Geometries "spatially intersect" in 3d - only for points, linestrings, polygons, polyhedral surface (area). With SFCGAL backend enabled also supports TINS
ST_3DLongestLine — Returns the 3-dimensional longest line between two geometries
ST_3DMaxDistance — For geometry type Returns the 3-dimensional cartesian maximum distance (based on spatial ref) between two geometries in projected units.
ST_3DShortestLine — Returns the 3-dimensional shortest line between two geometries
ST_Area — Returns the area of the surface if it is a Polygon or MultiPolygon. For geometry, a 2D Cartesian area is determined with units specified by the SRID. For geography, area is determined on a curved surface with units in square meters.
ST_Azimuth — Returns the north-based azimuth as the angle in radians measured clockwise from the vertical on pointA to pointB.
ST_Centroid — Returns the geometric center of a geometry.
ST_ClosestPoint — Returns the 2-dimensional point on g1 that is closest to g2. This is the first point of the shortest line.
ST_ClusterDBSCAN — Windowing function that returns integer id for the cluster each input geometry is in based on 2D implementation of Density-based spatial clustering of applications with noise (DBSCAN) algorithm.
ST_ClusterIntersecting — Aggregate. Returns an array with the connected components of a set of geometries
ST_ClusterKMeans — Windowing function that returns integer id for the cluster each input geometry is in.
ST_ClusterWithin — Aggregate. Returns an array of GeometryCollections, where each GeometryCollection represents a set of geometries separated by no more than the specified distance.
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_Distance — For geometry type Returns the 2D Cartesian distance between two geometries in projected units (based on spatial ref). For geography type defaults to return minimum geodesic distance between two geographies in meters.
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_HausdorffDistance — Returns the Hausdorff distance between two geometries. Basically a measure of how similar or dissimilar 2 geometries are. Units are in the units of the spatial reference system of the geometries.
ST_MaxDistance — Returns the 2-dimensional largest distance between two geometries in projected units.
ST_DistanceSphere Returns minimum distance in meters between two lon/lat geometries. Uses a spherical earth and radius derived from the spheroid defined by the SRID. Faster than ST_DistanceSpheroid ST_DistanceSpheroid, but less accurate. PostGIS versions prior to 1.5 only implemented for points.
ST_DistanceSpheroid — Returns the minimum distance between two lon/lat geometries given a particular spheroid. PostGIS versions prior to 1.5 only support points.
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.
ST_Equals — Returns true if the given geometries represent the same geometry. Directionality is ignored.
ST_GeometricMedian — Returns the geometric median of a MultiPoint.
ST_HasArc — Returns true if a geometry or geometry collection contains a circular string
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_Length — Returns the 2D length of the geometry if it is a LineString or MultiLineString. geometry are in units of spatial reference and geography are in meters (default spheroid)
ST_Length2D — Returns the 2-dimensional length of the geometry if it is a linestring or multi-linestring. This is an alias for ST_Length
ST_3DLength — Returns the 3-dimensional or 2-dimensional length of the geometry if it is a linestring or multi-linestring.
ST_LengthSpheroid — Calculates the 2D or 3D length/perimeter of a geometry on an ellipsoid. This is useful if the coordinates of the geometry are in longitude/latitude and a length is desired without reprojection.
ST_Length2D_Spheroid — Calculates the 2D length/perimeter of a geometry on an ellipsoid. This is useful if the coordinates of the geometry are in longitude/latitude and a length is desired without reprojection.
ST_LongestLine — Returns the 2-dimensional longest line points of two geometries. The function will only return the first longest line if more than one, that the function finds. The line returned will always start in g1 and end in g2. The length of the line this function returns will always be the same as st_maxdistance returns for g1 and g2.
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_Perimeter — Return the length measurement of the boundary of an ST_Surface or ST_MultiSurface geometry or geography. (Polygon, MultiPolygon). geometry measurement is in units of spatial reference and geography is in meters.
ST_Perimeter2D — Returns the 2-dimensional perimeter of the geometry, if it is a polygon or multi-polygon. This is currently an alias for ST_Perimeter.
ST_3DPerimeter — Returns the 3-dimensional perimeter of the geometry, if it is a polygon or multi-polygon.
ST_PointOnSurface — Returns a POINT guaranteed to lie on the surface.
ST_Project — Returns a POINT projected from a start point using a distance in meters and bearing (azimuth) in radians.
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_ShortestLine — Returns the 2-dimensional shortest line between two geometries
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.10. SFCGAL Functions

Abstract

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

Installation instructions of the library can be found on SFCGAL home page http://www.sfcgal.org . To load the functions create extension postgis_sfcgal.

Some SFCGAL functions replace standard ones (ST_Intersects, ST_Intersection, ST_Difference, ST_Union, ST_Area and ST_Distance), to switch between standard functions and SFCGAL function use:

SET postgis.backend = sfcgal;

and

SET postgis.backend = geos;

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_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.11. 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_ClipByBox2D — Returns the portion of a geometry falling within a rectangle.
ST_Collect — Return a specified ST_Geometry value from a collection of other geometries.
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 — The convex hull of a geometry represents the minimum convex geometry that encloses all geometries within the set.
ST_CurveToLine — Converts a CIRCULARSTRING/CURVEPOLYGON to a LINESTRING/POLYGON
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_Dump — Returns a set of geometry_dump (geom,path) rows, that make up a geometry g1.
ST_DumpPoints — Returns a set of geometry_dump (geom,path) rows of all points that make up a geometry.
ST_DumpRings — Returns a set of geometry_dump rows, representing the exterior and interior rings of a polygon.
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_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_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_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_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_SwapOrdinates — Returns a version of the given geometry with given ordinate values swapped.
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.12. 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_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. Polygonal elements are not supported.
ST_LocateBetweenElevations — Return a derived geometry (collection) value with elements that intersect the specified range of elevations inclusively. Only 3D, 4D LINESTRINGS and MULTILINESTRINGS are supported.
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.13. Temporal Support

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

8.14. Long Transactions Support

AddAuth — Add an authorization token to be used in current transaction.
CheckAuth — Creates trigger on a table to prevent/allow updates and deletes of rows based on authorization token.
DisableLongTransactions — Disable long transaction support. This function removes the long transaction support metadata tables, and drops all triggers attached to lock-checked tables.
EnableLongTransactions — Enable long transaction support. This function creates the required metadata tables, needs to be called once before using the other functions in this section. Calling it twice is harmless.
LockRow — Set lock/authorization for specific row in table
UnlockRows — Remove all locks held by specified authorization id. Returns the number of locks released.

This module and associated pl/pgsql functions have been implemented to provide long locking support required by Web Feature Service specification.


	Users must use serializable transaction level otherwise locking mechanism would break.

8.15. Miscellaneous Functions

ST_Accum — Aggregate. Constructs an array of geometries.
Box2D — Returns a BOX2D representing the maximum extents of the geometry.
Box3D — Returns a BOX3D representing the maximum extents of the geometry.
ST_EstimatedExtent — Return the 'estimated' extent of the given spatial table. The estimated is taken from the geometry column's statistics. The current schema will be used if not specified.
ST_Expand — Returns bounding box expanded in all directions from the bounding box of the input geometry. Uses double-precision
ST_Extent — an aggregate function that returns the bounding box that bounds rows of geometries.
ST_3DExtent — an aggregate function that returns the box3D bounding box that bounds rows of geometries.
Find_SRID — The syntax is find_srid(a_db_schema, a_table, a_column) and the function returns the integer SRID of the specified column by searching through the GEOMETRY_COLUMNS table.
ST_MemSize — Returns the amount of space (in bytes) the geometry takes.
ST_PointInsideCircle — Is the point geometry insert circle defined by center_x, center_y, radius

8.16. Exceptional Functions

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.

These functions are rarely used functions that should only be used if your data is corrupted in someway. They are used for troubleshooting corruption and also fixing things that should under normal circumstances, never happen.

Chapter&nbsp;8.&nbsp;PostGIS Reference

Chapter 8. PostGIS Reference

8.1. PostgreSQL PostGIS Geometry/Geography/Box Types

8.2. PostGIS Grand Unified Custom Variables (GUCs)

8.3. Management Functions

8.4. Geometry Constructors

8.5. Geometry Accessors

8.6. Geometry Editors

8.7. Geometry Outputs

8.8. Operators

8.9. Spatial Relationships and Measurements

8.10. SFCGAL Functions

8.11. Geometry Processing

8.12. Linear Referencing

8.13. Temporal Support

8.14. Long Transactions Support

8.15. Miscellaneous Functions

8.16. Exceptional Functions

Chapter 8. PostGIS Reference