From: Paul Ramsey Date: Fri, 27 Nov 2009 19:17:13 +0000 (+0000) Subject: Update the using mapserver section a little X-Git-Tag: 1.5.0b1~166 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=5dc1acbef18fbdba712e45326350e70998af6623;p=postgis Update the using mapserver section a little git-svn-id: http://svn.osgeo.org/postgis/trunk@4916 b70326c6-7e19-0410-871a-916f4a2858ee --- diff --git a/doc/using_postgis_app.xml b/doc/using_postgis_app.xml index 68e2d5b93..fc147f1fc 100644 --- a/doc/using_postgis_app.xml +++ b/doc/using_postgis_app.xml @@ -1,33 +1,33 @@ Using PostGIS: Building Applications - - Using Mapserver + + Using MapServer - The Minnesota Mapserver is an internet web-mapping server which + The Minnesota MapServer is an internet web-mapping server which conforms to the OpenGIS Web Mapping Server specification. - The Mapserver homepage is at http://mapserver.gis.umn.edu. + The MapServer homepage is at http://mapserver.org. The OpenGIS Web Map Specification is at http://www.opengeospatial.org/standards. + url="http://www.opengeospatial.org/standards/wms">http://www.opengeospatial.org/standards/wms. Basic Usage - To use PostGIS with Mapserver, you will need to know about how to - configure Mapserver, which is beyond the scope of this documentation. + To use PostGIS with MapServer, you will need to know about how to + configure MapServer, which is beyond the scope of this documentation. This section will cover specific PostGIS issues and configuration details. - To use PostGIS with Mapserver, you will need: + To use PostGIS with MapServer, you will need: @@ -35,24 +35,24 @@ - Version 3.5 or newer of Mapserver. + Version 3.5 or newer of MapServer. - Mapserver accesses PostGIS/PostgreSQL data like any other - PostgreSQL client -- using libpq. This means that - Mapserver can be installed on any machine with network access to the - PostGIS server, as long as the system has the libpq - PostgreSQL client libraries. + MapServer accesses PostGIS/PostgreSQL data like any other + PostgreSQL client -- using the libpq interface. This means that + MapServer can be installed on any machine with network access to the + PostGIS server, and use PostGIS as a source of data. The faster the connection + between the systems, the better. - Compile and install Mapserver, with whatever options you + Compile and install MapServer, with whatever options you desire, including the "--with-postgis" configuration option. - In your Mapserver map file, add a PostGIS layer. For + In your MapServer map file, add a PostGIS layer. For example: LAYER @@ -62,7 +62,7 @@ CONNECTION "user=dbuser dbname=gisdatabase host=bigserver" PROCESSING "CLOSE_CONNECTION=DEFER" # Get the lines from the 'geom' column of the 'roads' table - DATA "geom from roads" + DATA "geom from roads using srid=4326 using unique gid" STATUS ON TYPE LINE # Of the lines in the extents, only render the wide highways @@ -119,9 +119,13 @@ END DATA - The form of this parameter is "<column> from - <tablename>" where the column is the spatial column to - be rendered to the map. + The form of this parameter is "<geocolumn> from + <tablename> using srid=<srid> using unique <primary key>" where the column is the spatial column to + be rendered to the map, the SRID is SRID used by the column and the primary key is the table primary key (or any + other uniquely-valued column with an index). + You can omit the "using srid" and "using unique" clauses and MapServer will automatically determine the + correct values if possible, but at the cost of running a few extra queries on the server for each map + draw. @@ -130,7 +134,7 @@ END Putting in a CLOSE_CONNECTION=DEFER if you have multiple layers reuses existing connections instead of closing them. This improves - speed. Refer to for Paul's Mapserver PostGIS Performance Tips for more detailed explanation. + speed. Refer to for MapServer PostGIS Performance Tips for a more detailed explanation. @@ -155,19 +159,13 @@ END - If you will be querying your layers using Mapserver you will - also need an "oid index". + If you will be querying your layers using MapServer you will + also need to use the "using unique" clause in your DATA statement. - Mapserver requires unique identifiers for each spatial record - when doing queries, and the PostGIS module of Mapserver uses the - PostgreSQL oid value to provide these unique - identifiers. A side-effect of this is that in order to do fast - random access of records during queries, an index on the - oid is needed. - - To build an "oid index", use the following SQL: - - CREATE INDEX [indexname] ON [tablename] ( oid ); + MapServer requires unique identifiers for each spatial record + when doing queries, and the PostGIS module of MapServer uses the + unique value you specify in order to provide these unique + identifiers. Using the table primary key is the best practice. @@ -201,7 +199,7 @@ END Unlike shape files, filters for PostGIS layers use SQL syntax (they are appended to the SQL statement the PostGIS - connector generates for drawing layers in Mapserver). + connector generates for drawing layers in MapServer). FILTER "type = 'highway' and numlanes >= 4" @@ -214,18 +212,18 @@ END - In general, expect PostGIS layers to be 10% slower than - equivalent Shape files layers, due to the extra overhead involved - in database connections, data transformations and data transit - between the database and Mapserver. - + In general, the more features you are drawing into a given map, + the more likely it is that PostGIS will be slower than Shape files. + For maps with relatively few features (100s), PostGIS will often be faster. + For maps with high feature density (1000s), PostGIS will always be slower. + + If you are finding substantial draw performance problems, it - is likely that you have not build a spatial index on your + is possible that you have not built a spatial index on your table. postgis# CREATE INDEX geotable_gix ON geotable USING GIST ( geocolumn ); -postgis# SELECT update_geometry_stats(); -- For PGSQL < 8.0 -postgis# VACUUM ANALYZE; -- For PGSQL >= 8.0 +postgis# VACUUM ANALYZE; @@ -246,15 +244,31 @@ postgis# VACUUM ANALYZE; -- For PGSQL >= 8.0 DATA "the_geom FROM geotable USING UNIQUE gid" - If your table does not have an explicit unique column, you - can "fake" a unique column by using the PostgreSQL row "oid" for - your unique column. "oid" is the default unique column if you do - not declare one, so enhancing your query speed is a matter of - building an index on your spatial table oid value. + + + + + + Can I use "geography" columns (new in PostGIS 1.5) as a source for + MapServer layers? + + + + Yes! MapServer understands geography columns as being the same as + geometry columns, but always using an SRID of 4326. Just make sure to include + a "using srid=4326" clause in your DATA statement and. Everything else + works exactly the same as for geometry. + + You can specify what unique key for mapserver to use with + the USING UNIQUE clause in your + DATA line: + + DATA "the_geom FROM geotable USING UNIQUE gid" - postgis# CREATE INDEX geotable_oid_idx ON geotable (oid); + + @@ -285,10 +299,10 @@ postgis# VACUUM ANALYZE; -- For PGSQL >= 8.0 USING UNIQUE <uniqueid> - Mapserver requires a unique id for each row in order to + MapServer requires a unique id for each row in order to identify the row when doing map queries. Normally, it would use the oid as the unique identifier, but views and subselects don't - automatically have an oid column. If you want to use Mapserver's + automatically have an oid column. If you want to use MapServer's query functionality, you need to add a unique column to your view or subselect, and declare it with USING UNIQUE. For example, you could explicitly select one of the table's oid @@ -331,7 +345,7 @@ postgis# VACUUM ANALYZE; -- For PGSQL >= 8.0 - The parser for Mapserver PostGIS layers is fairly primitive, and + The parser for MapServer PostGIS layers is fairly primitive, and is case sensitive in a few areas. Be careful to ensure that all SQL keywords and all your USING clauses are in upper case, and that your USING UNIQUE clause precedes @@ -343,7 +357,7 @@ postgis# VACUUM ANALYZE; -- For PGSQL >= 8.0 Examples Lets start with a simple example and work our way up. Consider the - following Mapserver layer definition: + following MapServer layer definition: LAYER CONNECTIONTYPE postgis