postgis/doc/reference.xml
Regina Obe ca57a90d67 Move over Enable/Disable LongTransactions
git-svn-id: http://svn.osgeo.org/postgis/trunk@3351 b70326c6-7e19-0410-871a-916f4a2858ee
2008-12-01 22:06:57 +00:00

769 lines
22 KiB
XML

<?xml version="1.0" encoding="UTF-8"?>
<chapter>
<title>PostGIS Reference</title>
<para>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.</para>
<note>
<para>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. These will be
deprecated in a future release.</para>
</note>
<sect1>
<title>OpenGIS Functions</title>
<sect2>
<title>Geometry Constructors</title>
<variablelist>
<varlistentry>
<term>ST_LineFromText(text)</term>
<term>ST_LineFromText(text,srid integer)</term>
<listitem>
<para>Makes a Geometry from WKT with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
suite</para>
<para>Throws an error if the WKT is not a Line</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_LinestringFromText(text)</term>
<term>ST_LinestringFromText(text,srid integer)</term>
<listitem>
<para>Makes a Geometry from WKT with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>from the conformance suite</para>
<para>Throws an error if the WKT is not a Line</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_PolyFromText(text,[&lt;srid&gt;])</term>
<listitem>
<para>Makes a Geometry from WKT with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
suite</para>
<para>Throws an error if the WKT is not a Polygon</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_PolygonFromText(text,[&lt;srid&gt;])</term>
<listitem>
<para>Makes a Geometry from WKT with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>from the conformance suite</para>
<para>Throws an error if the WKT is not a Polygon</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_MPointFromText(text,[&lt;srid&gt;])</term>
<listitem>
<para>Makes a Geometry from WKT with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
suite</para>
<para>Throws an error if the WKT is not a MULTIPOINT</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_MLineFromText(text,[&lt;srid&gt;])</term>
<listitem>
<para>Makes a Geometry from WKT with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
suite</para>
<para>Throws an error if the WKT is not a MULTILINESTRING</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_MPolyFromText(text,[&lt;srid&gt;])</term>
<listitem>
<para>Makes a Geometry from WKT with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
suite</para>
<para>Throws an error if the WKT is not a MULTIPOLYGON</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_GeomCollFromText(text,[&lt;srid&gt;])</term>
<listitem>
<para>Makes a Geometry from WKT with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
suite</para>
<para>Throws an error if the WKT is not a
GEOMETRYCOLLECTION</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_GeometryFromWKB(bytea,[&lt;srid&gt;])</term>
<listitem>
<para>Makes a Geometry from WKB with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
suite</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_PointFromWKB(bytea,[&lt;srid&gt;])</term>
<listitem>
<para>Makes a Geometry from WKB with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
suite</para>
<para>throws an error if WKB is not a POINT</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_LineFromWKB(bytea,[&lt;srid&gt;])</term>
<listitem>
<para>Makes a Geometry from WKB with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
suite</para>
<para>throws an error if WKB is not a LINESTRING</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_LinestringFromWKB(bytea,[&lt;srid&gt;])</term>
<listitem>
<para>Makes a Geometry from WKB with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>from the conformance suite</para>
<para>throws an error if WKB is not a LINESTRING</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_PolyFromWKB(bytea,[&lt;srid&gt;])</term>
<listitem>
<para>Makes a Geometry from WKB with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
suite</para>
<para>throws an error if WKB is not a POLYGON</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_PolygonFromWKB(bytea,[&lt;srid&gt;])</term>
<listitem>
<para>Makes a Geometry from WKB with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>from the conformance suite</para>
<para>throws an error if WKB is not a POLYGON</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_MPointFromWKB(bytea,[&lt;srid&gt;])</term>
<listitem>
<para>Makes a Geometry from WKB with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
suite</para>
<para>throws an error if WKB is not a MULTIPOINT</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_MLineFromWKB(bytea,[&lt;srid&gt;])</term>
<listitem>
<para>Makes a Geometry from WKB with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
suite</para>
<para>throws an error if WKB is not a MULTILINESTRING</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_MPolyFromWKB(bytea,[&lt;srid&gt;])</term>
<listitem>
<para>Makes a Geometry from WKB with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
suite</para>
<para>throws an error if WKB is not a MULTIPOLYGON</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_GeomCollFromWKB(bytea,[&lt;srid&gt;])</term>
<listitem>
<para>Makes a Geometry from WKB with the given SRID. If SRID is
not give, it defaults to -1.</para>
<para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
suite</para>
<para>throws an error if WKB is not a GEOMETRYCOLLECTION</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
<sect1>
<title>PostGIS Extensions</title>
<sect2>
<title>Operators</title>
<variablelist>
<varlistentry>
<term>A = B</term>
<listitem>
<para>The "=" operator returns true if A's bounding box
is the same as B's bounding box.</para>
<note><para>This is cause for a lot of confusion. When you compare geometryA = geometryB it will return
true even when the geometries are clearly different if their bounding boxes are the same. To check for
true equality use <xref linkend="ST_OrderingEquals"/> or <xref linkend="ST_Equals"/></para></note>
</listitem>
</varlistentry>
<varlistentry>
<term>A &amp;&lt; B</term>
<listitem>
<para>The "&amp;&lt;" operator returns true if A's bounding box
overlaps or is to the left of B's bounding box.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>A &amp;&gt; B</term>
<listitem>
<para>The "&amp;&gt;" operator returns true if A's bounding box
overlaps or is to the right of B's bounding box.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>A &lt;&lt; B</term>
<listitem>
<para>The "&lt;&lt;" operator returns true if A's bounding box is
strictly to the left of B's bounding box.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>A &gt;&gt; B</term>
<listitem>
<para>The "&gt;&gt;" operator returns true if A's bounding box is
strictly to the right of B's bounding box.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>A &amp;&lt;| B</term>
<listitem>
<para>The "&amp;&lt;|" operator returns true if A's bounding box
overlaps or is below B's bounding box.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>A |&amp;&gt; B</term>
<listitem>
<para>The "|&amp;&gt;" operator returns true if A's bounding box
overlaps or is above B's bounding box.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>A &lt;&lt;| B</term>
<listitem>
<para>The "&lt;&lt;|" operator returns true if A's bounding box is
strictly below B's bounding box.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>A |&gt;&gt; B</term>
<listitem>
<para>The "|&gt;&gt;" operator returns true if A's bounding box is
strictly above B's bounding box.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>A ~= B</term>
<listitem>
<para>The "~=" operator is the "same as" operator. It tests actual
geometric equality of two features. So if A and B are the same
feature, vertex-by-vertex, the operator returns true.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>A @ B</term>
<listitem>
<para>The "@" operator returns true if A's bounding box is
completely contained by B's bounding box.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>A ~ B</term>
<listitem>
<para>The "~" operator returns true if A's bounding box completely
contains B's bounding box.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>A &amp;&amp; B</term>
<listitem>
<para>The "&amp;&amp;" operator is the "overlaps" operator. If A's
bounding box overlaps B's bounding box the operator returns
true.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2>
<title>Misc</title>
<variablelist>
<varlistentry>
<term>ST_box2d(geometry)</term>
<listitem>
<para>Returns a BOX2D representing the maximum extents of the
geometry.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_box3d(geometry)</term>
<listitem>
<para>Returns a BOX3D representing the maximum extents of the
geometry.</para>
</listitem>
</varlistentry>
<varlistentry id="zmflag">
<term>ST_zmflag(geometry)</term>
<listitem>
<para>Returns ZM (dimension semantic) flag of the geometries as a
small int. Values are: 0=2d, 1=3dm, 2=3dz, 3=4d.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_nrings(geometry)</term>
<listitem>
<para>If the geometry is a polygon or multi-polygon returns the
number of rings.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_find_srid(varchar,varchar,varchar)</term>
<listitem>
<para>The syntax is find_srid(&lt;db/schema&gt;, &lt;table&gt;,
&lt;column&gt;) and the function returns the integer SRID of the
specified column by searching through the GEOMETRY_COLUMNS table.
If the geometry column has not been properly added with the
AddGeometryColumns() function, this function will not work
either.</para>
</listitem>
</varlistentry>
<varlistentry id="ST_Point_Inside_Circle">
<term>ST_point_inside_circle(geometry, float, float, float)</term>
<listitem>
<para>The syntax for this functions is
point_inside_circle(&lt;geometry&gt;,&lt;circle_center_x&gt;,&lt;circle_center_y&gt;,&lt;radius&gt;).
Returns the true if the geometry is a point and is inside the
circle. Returns false otherwise.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_XMin(box3d) ST_YMin(box3d) ST_ZMin(box3d)</term>
<listitem>
<para>Returns the requested minima of a bounding box.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_XMax(box3d) ST_YMax(box3d) ST_ZMax(box3d)</term>
<listitem>
<para>Returns the requested maxima of a bounding box.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2>
<title>Long Transactions support</title>
<para>This module and associated pl/pgsql functions have been
implemented to provide long locking support required by <ulink
url="http://portal.opengeospatial.org/files/index.php?artifact_id=7176">Web
Feature Service</ulink> specification.</para>
<note>
<para>Users must use <ulink
url="http://www.postgresql.org/docs/8.3/static/transaction-iso.html">serializable
transaction level</ulink> otherwise locking mechanism would
break.</para>
</note>
<variablelist>
<varlistentry id="CheckAuth">
<term>CheckAuth([&lt;schema&gt;], &lt;table&gt;,
&lt;rowid_col&gt;)</term>
<listitem>
<para>Check updates and deletes of rows in given table for being
authorized. Identify rows using &lt;rowid_col&gt; column.</para>
<para>Availability: 1.1.3</para>
</listitem>
</varlistentry>
<varlistentry id="LockRow">
<term>LockRow([&lt;schema&gt;], &lt;table&gt;, &lt;rowid&gt;,
&lt;authid&gt;, [&lt;expires&gt;])</term>
<listitem>
<para>Set lock/authorization for specific row in table
&lt;authid&gt; is a text value, &lt;expires&gt; is a timestamp
defaulting to now()+1hour. Returns 1 if lock has been assigned, 0
otherwise (already locked by other auth)</para>
<para>Availability: 1.1.3</para>
</listitem>
</varlistentry>
<varlistentry id="UnlockRows">
<term>UnlockRows(&lt;authid&gt;)</term>
<listitem>
<para>Remove all locks held by specified authorization id. Returns
the number of locks released.</para>
<para>Availability: 1.1.3</para>
</listitem>
</varlistentry>
<varlistentry id="AddAuth">
<term>AddAuth(&lt;authid&gt;)</term>
<listitem>
<para>Add an authorization token to be used in current
transaction.</para>
<para>Availability: 1.1.3</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
<sect1>
<title>SQL-MM Functions</title>
<para>This is a listing of the SQL-MM defined functions that PostGIS
currently supports. The implementations of these functions follow the
ArcSDE implementation, and thus deviate somewhat from the spec. These
deviations will be noted.</para>
<para>As of version 1.2.0, these functions have been implemented by
wrapping existing PostGIS functions. As a result, full support for curved
geometries may not be in place for many functions.</para>
<note>
<para>SQL-MM defines the default SRID of all geometry constructors as 0.
PostGIS uses a default SRID of -1.</para>
</note>
<variablelist>
<varlistentry>
<term>ST_LineFromText</term>
<listitem>
<para>Return a specified ST_LineString value.</para>
<para>SQL-MM 3: 7.2.8</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_LineFromWKB</term>
<listitem>
<para>Return a specified ST_LineString value.</para>
<para>SQL-MM 3: 7.2.9</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_MLineFromText</term>
<listitem>
<para>Return a specified ST_MultiLineString value.</para>
<para>SQL-MM 3: 9.4.4</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_MLineFromWKB</term>
<listitem>
<para>Return a specified ST_MultiLineString value.</para>
<para>SQL-MM 3: 9.4.5</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_MPointFromText</term>
<listitem>
<para>Return a specified ST_MultiPoint value.</para>
<para>SQL-MM 3: 9.2.4</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_MPointFromWKB</term>
<listitem>
<para>Return a specified ST_MultiPoint value.</para>
<para>SQL-MM 3: 9.2.5</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_MPolyFromText</term>
<listitem>
<para>Return a specified ST_MultiPolygon value.</para>
<para>SQL-MM 3: 9.6.4</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_MPolyFromWKB</term>
<listitem>
<para>Return a specified ST_MultiPolygon value.</para>
<para>SQL-MM 3: 9.6.5</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_PointFromText</term>
<listitem>
<para>Return a specified ST_Point value.</para>
<para>SQL-MM 3: 6.1.8</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_PointFromWKB</term>
<listitem>
<para>Return a specified ST_Point value.</para>
<para>SQL-MM 3: 6.1.9</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_PolyFromText</term>
<listitem>
<para>Return a specified ST_Polygon value.</para>
<para>SQL-MM 3: 8.3.6</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ST_PolyFromWKB</term>
<listitem>
<para>Return a specified ST_Polygon value.</para>
<para>SQL-MM 3: 8.3.7</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1>
<title>ArcSDE Functions</title>
<para>Additional functions have been added to improve support for an
ArcSDE style interface.</para>
<variablelist>
<varlistentry>
<term>SE_EnvelopesIntersect</term>
<listitem>
<para>Returns t (TRUE) if the envelopes of two geometries intersect;
otherwise, it returns f (FALSE).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SE_Is3d</term>
<listitem>
<para>Test if a geometry value has z coordinate values.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SE_IsMeasured</term>
<listitem>
<para>Test if a geometry value has m coordinate values.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SE_LocateAlong</term>
<listitem>
<para>Return a derived geometry collection value with elements that
match the specified measur.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SE_LocateBetween</term>
<listitem>
<para>Return a derived geometry collection value with elements that
match the specified range of measures inclusively.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SE_M</term>
<listitem>
<para>Returns the m coordinate value of an ST_Point value.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SE_Z</term>
<listitem>
<para>Returns the z coordinate value of an ST_Point value</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>