[mapserver-commits] r8272 - trunk/docs/input/vector

[svn at osgeo.org]

Author: pramsey
Date: 2008-12-22 19:09:29 -0500 (Mon, 22 Dec 2008)
New Revision: 8272

Modified:
   trunk/docs/input/vector/postgis.txt
Log:
Add more examples of postGIS configuration.


Modified: trunk/docs/input/vector/postgis.txt
===================================================================
--- trunk/docs/input/vector/postgis.txt	2008-12-22 19:54:12 UTC (rev 8271)
+++ trunk/docs/input/vector/postgis.txt	2008-12-23 00:09:29 UTC (rev 8272)
@@ -18,21 +18,60 @@
 
 PostGIS is supported directly by MapServer and must be compiled into MapServer to work.
 
-In most cases, PostgreSQL and PostGIS libraries (.dll or .so) must be present in the system's path environment for functionality to be present.  This includes the libpq and libpostgis libraries.
+The PostgreSQL client libraries (libpq.so or libpq.dll) must be present in the system's path environment for functionality to be present.
 
-The CONNECTION parameter must be used to specify the parameters to connect to the database.  CONNECTION  parameters can be in any order.  Most are optional.  dbname is required.  host defaults to localhost, port defaults to 5432 - the standard port for PostgreSQL.
+The CONNECTIONTYPE parameter must be set to POSTGIS.
 
-The DATA parameter must be used to specify the name of the geometry column, the table name, and any other information.  The geometry column could be named "the_geom" if the shp2pgsql utility is used to load data, or "wkb_geometry" if ogr2ogr was used.
+The CONNECTION parameter is used to specify the parameters to connect to the database.  CONNECTION  parameters can be in any order.  Most are optional.  dbname is required.  user is required.  host defaults to localhost, port defaults to 5432 (the standard port for PostgreSQL).
 
+The DATA parameter is used to specify the data used to draw the map.  The form of DATA is "[geometry_column] from [table_name|sql_subquery] using unique [unique_key] using srid=[spatial_reference_id]". The "using unique" and "using srid=" clauses are optional, but using them improves performance.  
+
+Here is a simple generic example:
+
 ::
   
   CONNECTIONTYPE POSTGIS
   CONNECTION "host=yourhostname dbname=yourdatabasename user=yourdbusername password=yourdbpassword port=yourpgport"
   DATA "geometrycolumn from yourtablename"
 
+This example shows specifying the unique key and srid in the DATA line:
+
+::
+
+  CONNECTIONTYPE POSTGIS
+  CONNECTION "dbname=yourdatabasename user=yourdbusername"
+  DATA "the_geom from the_database using unique gid using srid=4326"
+
+This example shows using a SQL subquery to perform a join inside the database and map the result in Mapserver. Note the "as subquery" string in the statement -- everything between "from" and "using" is sent to the database for evaluation:
+
+::
+
+  CONNECTIONTYPE POSTGIS
+  CONNECTION "dbname=yourdatabasename user=yourdbusername"
+  DATA "the_geom from (select g.gid, g.the_geom, a.attr1, a.attr2 from geotable g join attrtable a on g.gid = a.aid) as subquery unique gid using srid=4326"
+
+This example shows using a geometry function and database sort to limit the number of features and vertices returned to Mapserver:
+  
+::
+
+  CONNECTIONTYPE POSTGIS
+  CONNECTION "dbname=yourdatabasename user=yourdbusername"
+  DATA "the_geom from (select g.gid, ST_Simplify(g.the_geom, 10.0) as the_geom from geotable g order by ST_Area(g.the_geom) desc limit 10) as subquery unique gid using srid=4326"
+
+This example shows the use of the !BOX! substitution string to over-ride the default inclusion of the map bounding box in the SQL. By default the spatial box clause is appended to the SQL in the DATA clause, but you can use !BOX! to insert it anywhere you like in the statement. In general, you won't need to use !BOX!, because the PostgreSQL planner will generate the optimal plan from the generated SQL, but in some cases (complex sub-queries) a better plan can be generated by placing the !BOX! closer to the middle of the query:
+
+::
+
+  CONNECTIONTYPE POSTGIS
+  CONNECTION "dbname=yourdatabasename user=yourdbusername"
+  DATA "the_geom from (select g.gid, ST_Union(g.the_geom, 10.0) as the_geom from geotable g where ST_Intersects(g.geom,!BOX!)) as subquery unique gid using srid=4326"
+
+
 OGRINFO Examples
 ----------------
 
+OGRINFO can be used to read out metadata about PostGIS tables directly from the database.
+
 First you should make sure that your GDAL/OGR build contains the PostgreSQL driver, by using the '--formats' command:
 
 ::
@@ -92,7 +131,7 @@
     TYPE POLYGON
     CONNECTIONTYPE POSTGIS
     CONNECTION "host=127.0.0.1 port=5432 dbname=canada user=postgres password=postgres"
-    DATA "the_geom FROM province"
+    DATA "the_geom from province"
     CLASS
        ...
     END