postgis/doc/reference_exception.xml

<?xml version="1.0" encoding="UTF-8"?>
 <sect1 id="Exceptional_Functions">
	<title>Exceptional Functions</title>
	<para>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.</para>

	<refentry id="PostGIS_AddBBox">
		  <refnamediv>
			<refname>PostGIS_AddBBox</refname>

			<refpurpose>Add bounding box to the geometry.</refpurpose>
		  </refnamediv>

		  <refsynopsisdiv>
			<funcsynopsis>
			  <funcprototype>
				<funcdef>geometry <function>PostGIS_AddBBox</function></funcdef>
				<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
			  </funcprototype>
			</funcsynopsis>
		  </refsynopsisdiv>

		  <refsection>
			<title>Description</title>

			<para>Add bounding box to the geometry. This would make bounding
			box based queries faster, but will increase the size of the
			geometry.</para>

			<note>
			  <para>Bounding boxes are automatically added to geometries so in general this is not needed
				unless the generated bounding box somehow becomes corrupted or you have an old install that is lacking bounding boxes.  Then you need to drop the old and readd.</para>
			</note>

			<para>&curve_support;</para>
		  </refsection>


		  <refsection>
			<title>Examples</title>

			<programlisting>UPDATE sometable
 SET the_geom =  PostGIS_AddBBox(the_geom)
 WHERE PostGIS_HasBBox(the_geom) = false;</programlisting>
		  </refsection>

		  <!-- Optionally add a "See Also" section -->
		  <refsection>
			<title>See Also</title>

			<para><xref linkend="PostGIS_DropBBox" />, <xref linkend="PostGIS_HasBBox" /></para>
		  </refsection>
	</refentry>

	<refentry id="PostGIS_DropBBox">
		  <refnamediv>
			<refname>PostGIS_DropBBox</refname>

			<refpurpose>Drop the bounding box cache from the geometry.</refpurpose>
		  </refnamediv>

		  <refsynopsisdiv>
			<funcsynopsis>
			  <funcprototype>
				<funcdef>geometry <function>PostGIS_DropBBox</function></funcdef>
				<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
			  </funcprototype>
			</funcsynopsis>
		  </refsynopsisdiv>

		  <refsection>
			<title>Description</title>

			<para>Drop the bounding box cache from the geometry. This reduces
			geometry size, but makes bounding-box based queries slower.  It is also used to drop a corrupt bounding box.  A tale-tell sign of a corrupt cached bounding box
				is when your ST_Intersects and other relation queries leave out geometries that rightfully should return true.</para>

			<note>
			  <para>Bounding boxes are automatically added to geometries and improve speed of queries so in general this is not needed
				unless the generated bounding box somehow becomes corrupted or you have an old install that is lacking bounding boxes.
				Then you need to drop the old and readd.  This kind of corruption has been observed in 8.3-8.3.6 series whereby cached bboxes were not always recalculated when a geometry changed and upgrading to a newer version without a dump reload will not
				correct already corrupted boxes.  So one can manually correct using below and readd the bbox or do a dump reload.</para>
			</note>

			<para>&curve_support;</para>
		  </refsection>


		  <refsection>
			<title>Examples</title>

			<programlisting>--This example drops bounding boxes where the cached box is not correct
			--The force to ST_AsBinary before applying Box2D forces a recalculation of the box, and Box2D applied to the table geometry always
			-- returns the cached bounding box.
			UPDATE sometable
 SET the_geom =  PostGIS_DropBBox(the_geom)
 WHERE Not (Box2D(ST_AsBinary(the_geom)) = Box2D(the_geom));

	UPDATE sometable
 SET the_geom =  PostGIS_AddBBox(the_geom)
 WHERE Not PostGIS_HasBBOX(the_geom);


 </programlisting>
		  </refsection>

		  <!-- Optionally add a "See Also" section -->
		  <refsection>
			<title>See Also</title>

			<para><xref linkend="PostGIS_AddBBox" />, <xref linkend="PostGIS_HasBBox" />, <xref linkend="Box2D" /></para>
		  </refsection>
	</refentry>


	<refentry id="PostGIS_HasBBox">
	  <refnamediv>
		<refname>PostGIS_HasBBox</refname>

		<refpurpose>Returns TRUE if the bbox of this geometry is cached, FALSE otherwise.</refpurpose>
	  </refnamediv>

	  <refsynopsisdiv>
		<funcsynopsis>
		  <funcprototype>
			<funcdef>boolean <function>PostGIS_HasBBox</function></funcdef>
			<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
		  </funcprototype>
		</funcsynopsis>
	  </refsynopsisdiv>

	  <refsection>
		<title>Description</title>

		<para>Returns TRUE if the bbox of this geometry is cached, FALSE
				otherwise. Use <xref linkend="PostGIS_AddBBox" /> and <xref linkend="PostGIS_DropBBox" /> to control caching.</para>

		<para>&curve_support;</para>
	  </refsection>


	  <refsection>
		<title>Examples</title>

		<programlisting>SELECT the_geom
FROM sometable WHERE PostGIS_HasBBox(the_geom) = false;</programlisting>
	  </refsection>

	  <!-- Optionally add a "See Also" section -->
	  <refsection>
		<title>See Also</title>

		<para><xref linkend="PostGIS_AddBBox" />, <xref linkend="PostGIS_DropBBox" /></para>
	  </refsection>
	</refentry>

 </sect1>