From: Regina Obe Date: Thu, 1 Dec 2011 13:32:10 +0000 (+0000) Subject: #1337 clarify what sql is good for and get rid of some other obsolete syntax (this... X-Git-Tag: 2.0.0alpha1~588 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=2aa8c6e7335509504fdcfa4c537b37180feb8124;p=postgis #1337 clarify what sql is good for and get rid of some other obsolete syntax (this really needs to be read with a fine-tooth comb). The amount of obsolete info in this chapter is mesmerizing git-svn-id: http://svn.osgeo.org/postgis/trunk@8280 b70326c6-7e19-0410-871a-916f4a2858ee --- diff --git a/doc/using_postgis_dataman.xml b/doc/using_postgis_dataman.xml index 1abe9adea..4d62dd46e 100644 --- a/doc/using_postgis_dataman.xml +++ b/doc/using_postgis_dataman.xml @@ -1912,9 +1912,10 @@ COMMIT; Using SQL - The most straightforward means of pulling data out of the database - is to use a SQL select query and dump the resulting columns into a - parsable text file: + The most straightforward means of pulling data out of the + database is to use a SQL select query to reduce the number of RECORDS and COLUMNS returned + and dump the resulting columns + into a parsable text file: db=# SELECT road_id, ST_AsText(road_geom) AS geom, road_name FROM roads; @@ -1968,11 +1969,12 @@ road_id | geom | road_name Next, you can use these operators in queries. Note that when specifying geometries and boxes on the SQL command line, you must explicitly turn the string representations into geometries by using the - "GeomFromText()" function. So, for example: + "ST_GeomFromText()" function. The 312 is a fictitious spatial reference system that matches our data. + So, for example: SELECT road_id, road_name FROM roads - WHERE roads_geom ~= ST_GeomFromText('LINESTRING(191232 243118,191108 243242)',-1); + WHERE roads_geom ~= ST_GeomFromText('LINESTRING(191232 243118,191108 243242)',312); The above query would return the single record from the "ROADS_GEOM" table in which the geometry was equal to that value. @@ -1984,7 +1986,7 @@ road_id | geom | road_name SELECT road_id, road_name FROM roads -WHERE roads_geom && ST_GeomFromText('POLYGON((...))',-1); +WHERE roads_geom && ST_GeomFromText('POLYGON((...))',312); The above query will use the bounding box of the polygon for comparison purposes. @@ -1997,10 +1999,9 @@ WHERE roads_geom && ST_GeomFromText('POLYGON((...))',-1);SELECT ST_AsText(roads_geom) AS geom FROM roads WHERE - roads_geom && SetSRID('BOX3D(191232 243117,191232 243119)'::box3d,-1); + roads_geom && ST_MakeEnvelope(191232, 243117,191232, 243119,312); - Note the use of the SRID, to specify the projection of the BOX3D. - The value -1 is used to indicate no specified SRID. + Note the use of the SRID 312, to specify the projection of the envelope. @@ -2249,7 +2250,14 @@ SELECT UPDATE_GEOMETRY_STATS([table_name], [column_name]); + appropriate indexes are in place to provide good performance. The SRID of 312 used in these + examples is purely for demonstration. You should be using a REAL SRID listed in the the spatial_ref_sys table + and one that matches the projection of your data. If your data has no spatial reference system + specified, you should be THINKING very thoughtfully why it doesn't and maybe it should. + If your reason is because you are modeling something that doesn't have a geographic spatial reference system defined such as the internals of a molecule + or a good location + on Mars to transport the human race in the event of a nuclear holocaust, + then simply leave out the SRID or make one up and insert it in the spatial_ref_sys table. Taking Advantage of Indexes @@ -2257,13 +2265,13 @@ SELECT UPDATE_GEOMETRY_STATS([table_name], [column_name]);When constructing a query it is important to remember that only the bounding-box-based operators such as && can take advantage of the GiST spatial index. Functions such as - distance() cannot use the index to optimize their + ST_Distance() cannot use the index to optimize their operation. For example, the following query would be quite slow on a large table: SELECT the_geom FROM geom_table -WHERE ST_Distance(the_geom, ST_GeomFromText('POINT(100000 200000)', -1)) < 100 +WHERE ST_Distance(the_geom, ST_GeomFromText('POINT(100000 200000)', 312)) < 100 This query is selecting all the geometries in geom_table which are within 100 units of the point (100000, 200000). It will be slow because @@ -2274,15 +2282,14 @@ WHERE ST_Distance(the_geom, ST_GeomFromText('POINT(100000 200000)', -1)) < 10 SELECT the_geom FROM geom_table -WHERE the_geom && 'BOX3D(90900 190900, 100100 200100)'::box3d - AND -ST_Distance(the_geom, ST_GeomFromText('POINT(100000 200000)', -1)) < 100 +WHERE ST_DWithin(the_geom, ST_MakeEnvelope(90900, 190900, 100100, 200100,312), 100) + This query selects the same geometries, but it does it in a more efficient way. Assuming there is a GiST index on the_geom, the query planner will recognize that it can use the index to reduce the number of - rows before calculating the result of the distance() - function. Notice that the BOX3D geometry which is + rows before calculating the result of the ST_distance() + function. Notice that the ST_MakeEnvelope geometry which is used in the && operation is a 200 unit square box centered on the original point - this is our "query box". The && operator uses the index to quickly reduce the result set down to only those