Author: paul
Date: 2006-01-19 16:38:54 +0100 (Thu, 19 Jan 2006)
New Revision: 930
Log:
r6429@frost: paul | 2006-01-19 09:37:13 -0600
General revisions.
Modified:
trunk/
trunk/refman-4.1/renamed-nodes.txt
trunk/refman-4.1/spatial-extensions.xml
trunk/refman-5.0/renamed-nodes.txt
trunk/refman-5.0/spatial-extensions.xml
trunk/refman-5.1/renamed-nodes.txt
trunk/refman-5.1/spatial-extensions.xml
trunk/refman-common/titles.en.ent
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:6428
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:2335
+ b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:6429
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:2335
Modified: trunk/refman-4.1/renamed-nodes.txt
===================================================================
--- trunk/refman-4.1/renamed-nodes.txt 2006-01-19 15:38:42 UTC (rev 929)
+++ trunk/refman-4.1/renamed-nodes.txt 2006-01-19 15:38:54 UTC (rev 930)
@@ -101,3 +101,7 @@
charset-config-file adding-character-set
open-tables table-cache
variables user-variables
+fetching-spatial-data-in-internal-format fetching-spatial-data
+fetching-spatial-data-in-wkb-format fetching-spatial-data
+fetching-spatial-data-in-wkt-format fetching-spatial-data
+gis-features-that-are-not-yet-implemented mysql-gis-conformance-and-compatibility
Modified: trunk/refman-4.1/spatial-extensions.xml
===================================================================
--- trunk/refman-4.1/spatial-extensions.xml 2006-01-19 15:38:42 UTC (rev 929)
+++ trunk/refman-4.1/spatial-extensions.xml 2006-01-19 15:38:54 UTC (rev 930)
@@ -65,11 +65,32 @@
</itemizedlist>
<para>
- If you have questions or concerns about the use of the spatial
- extensions to MySQL, you can discuss these in the GIS forum:
- <ulink url="&base-url-forum-list;?23"/>.
+ <emphasis role="bold">Additional resources</emphasis>
</para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ The Open Geospatial Consortium publishes the
+ <citetitle>OpenGIS® Simple Features Specifications For
+ SQL</citetitle>, a document that proposes several conceptual
+ ways for extending an SQL RDBMS to support spatial data. This
+ specification is available from the OGC Web site at
+ <ulink url="http://www.opengis.org/docs/99-049.pdf"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If you have questions or concerns about the use of the spatial
+ extensions to MySQL, you can discuss them in the GIS forum:
+ <ulink url="&base-url-forum-list;?23"/>.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
<section id="gis-introduction">
<title>&title-gis-introduction;</title>
@@ -88,20 +109,20 @@
<para>
MySQL implements spatial extensions following the specification of
- the <literal>Open GIS Consortium</literal> (OGC). This is an
- international consortium of more than 250 companies, agencies, and
- universities participating in the development of publicly
- available conceptual solutions that can be useful with all kinds
- of applications that manage spatial data. The OGC maintains a Web
- site at <ulink url="http://www.opengis.org/"/>.
+ the Open Geospatial Consortium (OGC). This is an international
+ consortium of more than 250 companies, agencies, and universities
+ participating in the development of publicly available conceptual
+ solutions that can be useful with all kinds of applications that
+ manage spatial data. The OGC maintains a Web site at
+ <ulink url="http://www.opengis.org/"/>.
</para>
<para>
- In 1997, the Open GIS Consortium published the
+ In 1997, the Open Geospatial Consortium published the
<citetitle>OpenGIS® Simple Features Specifications For
SQL</citetitle>, a document that proposes several conceptual ways
for extending an SQL RDBMS to support spatial data. This
- specification is available from the Open GIS Web site at
+ specification is available from the OGC Web site at
<ulink url="http://www.opengis.org/docs/99-049.pdf"/>. It contains
additional information relevant to this chapter.
</para>
@@ -111,7 +132,7 @@
Geometry Types</emphasis> environment proposed by OGC. This term
refers to an SQL environment that has been extended with a set of
geometry types. A geometry-valued SQL column is implemented as a
- column that has a geometry type. The specifications describe a set
+ column that has a geometry type. The specification describe a set
of SQL geometry types, as well as functions on those types to
create and analyze geometry values.
</para>
@@ -153,9 +174,8 @@
</indexterm>
<para>
- You can also find documents that use the term
- <emphasis role="bold">geospatial feature</emphasis> to refer to
- geographic features.
+ Some documents use the term <emphasis role="bold">geospatial
+ feature</emphasis> to refer to geographic features.
</para>
<indexterm>
@@ -175,16 +195,12 @@
<emphasis role="bold">geographic feature</emphasis>,
<emphasis role="bold">geospatial feature</emphasis>,
<emphasis role="bold">feature</emphasis>, or
- <emphasis role="bold">geometry</emphasis>. The term most commonly
- used here is <emphasis role="bold">geometry</emphasis>.
+ <emphasis role="bold">geometry</emphasis>. Here, the term most
+ commonly used is <emphasis role="bold">geometry</emphasis>,
+ defined as <emphasis>a point or an aggregate of points
+ representing anything in the world that has a location</emphasis>.
</para>
- <para>
- Let's define a <emphasis role="bold">geometry</emphasis> as
- <emphasis>a point or an aggregate of points representing anything
- in the world that has a location</emphasis>.
- </para>
-
</section>
<section id="opengis-geometry-model">
@@ -354,7 +370,7 @@
<remark role="help-description-begin"/>
<para>
- <literal>Geometry</literal> is the base class. It's an abstract
+ <literal>Geometry</literal> is the base class. It is an abstract
class. The instantiable subclasses of
<literal>Geometry</literal> are restricted to zero-, one-, and
two-dimensional geometric objects that exist in two-dimensional
@@ -445,8 +461,8 @@
It is a non-instantiable class but has a number of properties
that are common to all geometry values created from any of the
<literal>Geometry</literal> subclasses. These properties are
- described in the following list. (Particular subclasses have
- their own specific properties, described later.)
+ described in the following list. Particular subclasses have
+ their own specific properties, described later.
</para>
<para>
@@ -1408,7 +1424,7 @@
</remark>
<para>
- Examples of WKT representations of geometry objects are:
+ Examples of WKT representations of geometry objects:
</para>
<itemizedlist>
@@ -1514,7 +1530,7 @@
<para>
A Backus-Naur grammar that specifies the formal production rules
- for writing WKT values can be found in the OGC specification
+ for writing WKT values can be found in the OpenGIS specification
document referenced near the beginning of this chapter.
</para>
@@ -1534,8 +1550,8 @@
<para>
The Well-Known Binary (WKB) representation for geometric values
- is defined by the OpenGIS specifications. It is also defined in
- the ISO <quote>SQL/MM Part 3: Spatial</quote> standard.
+ is defined by the OpenGIS specification. It is also defined in
+ the ISO <citetitle>SQL/MM Part 3: Spatial</citetitle> standard.
</para>
<para>
@@ -1749,8 +1765,8 @@
<para>
<literal>GEOMETRY</literal> can store geometry values of any
- type. The other single-value types, <literal>POINT</literal> and
- <literal>LINESTRING</literal> and <literal>POLYGON</literal>,
+ type. The other single-value types (<literal>POINT</literal>,
+ <literal>LINESTRING</literal>, and <literal>POLYGON</literal>)
restrict their values to a particular geometry type.
</para>
@@ -1788,11 +1804,11 @@
<para>
<literal>GEOMETRYCOLLECTION</literal> can store a collection of
- objects of any type. The other collection types,
- <literal>MULTIPOINT</literal> and
- <literal>MULTILINESTRING</literal> and
- <literal>MULTIPOLYGON</literal> and
- <literal>GEOMETRYCOLLECTION</literal>, restrict collection
+ objects of any type. The other collection types
+ (<literal>MULTIPOINT</literal>,
+ <literal>MULTILINESTRING</literal>,
+ <literal>MULTIPOLYGON</literal>, and
+ <literal>GEOMETRYCOLLECTION</literal>) restrict collection
members to those having a particular geometry type.
</para>
@@ -2064,12 +2080,13 @@
</itemizedlist>
<para>
- The OpenGIS specification also describes optional functions
- for constructing <literal>Polygon</literal> or
+ The OpenGIS specification also defines the following optional
+ functions, which MySQL does not implement. These functions
+ construct <literal>Polygon</literal> or
<literal>MultiPolygon</literal> values based on the WKT
representation of a collection of rings or closed
<literal>LineString</literal> values. These values may
- intersect. MySQL does not implement these functions:
+ intersect.
</para>
<itemizedlist>
@@ -2426,14 +2443,15 @@
<title>&title-gis-mysql-specific-functions;</title>
<para>
- MySQL provides a set of useful functions for creating geometry
- WKB representations. The functions described in this section
- are MySQL extensions to the OpenGIS specifications. The
- results of these functions are <literal>BLOB</literal> values
- containing WKB representations of geometry values with no
- SRID. The results of these functions can be substituted as the
- first argument for any function in the
- <literal>GeomFromWKB()</literal> function family.
+ MySQL provides a set of useful non-standard functions for
+ creating geometry WKB representations. The functions described
+ in this section are MySQL extensions to the OpenGIS
+ specification. The results of these functions are
+ <literal>BLOB</literal> values containing WKB representations
+ of geometry values with no SRID. The results of these
+ functions can be substituted as the first argument for any
+ function in the <literal>GeomFromWKB()</literal> function
+ family.
</para>
<remark role="help-category" condition="Geometry constructors@Geographic Features"/>
@@ -2639,8 +2657,7 @@
<remark role="help-example"/>
<programlisting>
-mysql> <userinput>CREATE TABLE geom (g GEOMETRY);</userinput>
-Query OK, 0 rows affected (0.02 sec)
+CREATE TABLE geom (g GEOMETRY);
</programlisting>
</listitem>
@@ -2651,12 +2668,8 @@
</para>
<programlisting>
-mysql> <userinput>ALTER TABLE geom ADD pt POINT;</userinput>
-Query OK, 0 rows affected (0.00 sec)
-Records: 0 Duplicates: 0 Warnings: 0
-mysql> <userinput>ALTER TABLE geom DROP pt;</userinput>
-Query OK, 0 rows affected (0.00 sec)
-Records: 0 Duplicates: 0 Warnings: 0
+ALTER TABLE geom ADD pt POINT;
+ALTER TABLE geom DROP pt;
</programlisting>
</listitem>
@@ -2678,31 +2691,39 @@
convert them to that format from either Well-Known Text (WKT) or
Well-Known Binary (WKB) format. The following examples
demonstrate how to insert geometry values into a table by
- converting WKT values into internal geometry format.
+ converting WKT values into internal geometry format:
</para>
- <para>
- You can perform the conversion directly in the
- <literal>INSERT</literal> statement:
- </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Perform the conversion directly in the
+ <literal>INSERT</literal> statement:
+ </para>
+
<programlisting>
INSERT INTO geom VALUES (GeomFromText('POINT(1 1)'));
SET @g = 'POINT(1 1)';
INSERT INTO geom VALUES (GeomFromText(@g));
</programlisting>
+ </listitem>
- <para>
- Or you can perform the conversion prior to the
- <literal>INSERT</literal>:
- </para>
+ <listitem>
+ <para>
+ Perform the conversion prior to the
+ <literal>INSERT</literal>:
+ </para>
<programlisting>
SET @g = GeomFromText('POINT(1 1)');
INSERT INTO geom VALUES (@g);
</programlisting>
+ </listitem>
+ </itemizedlist>
+
<para>
The following examples insert more complex geometries into the
table:
@@ -2802,51 +2823,55 @@
format. You can also convert them into WKT or WKB format.
</para>
- <section id="fetching-spatial-data-in-internal-format">
+ <itemizedlist>
- <title>&title-fetching-spatial-data-in-internal-format;</title>
+ <listitem>
+ <para>
+ Fetching spatial data in internal format:
+ </para>
- <para>
- Fetching geometry values using internal format can be useful
- in table-to-table transfers:
- </para>
+ <para>
+ Fetching geometry values using internal format can be useful
+ in table-to-table transfers:
+ </para>
<programlisting>
CREATE TABLE geom2 (g GEOMETRY) SELECT g FROM geom;
</programlisting>
+ </listitem>
- </section>
+ <listitem>
+ <para>
+ Fetching spatial data in WKT format:
+ </para>
- <section id="fetching-spatial-data-in-wkt-format">
+ <para>
+ The <literal>AsText()</literal> function converts a geometry
+ from internal format into a WKT string.
+ </para>
- <title>&title-fetching-spatial-data-in-wkt-format;</title>
-
- <para>
- The <literal>AsText()</literal> function converts a geometry
- from internal format into a WKT string.
- </para>
-
<programlisting>
SELECT AsText(g) FROM geom;
</programlisting>
+ </listitem>
- </section>
+ <listitem>
+ <para>
+ Fetching spatial data in WKB format:
+ </para>
- <section id="fetching-spatial-data-in-wkb-format">
+ <para>
+ The <literal>AsBinary()</literal> function converts a
+ geometry from internal format into a <literal>BLOB</literal>
+ containing the WKB value.
+ </para>
- <title>&title-fetching-spatial-data-in-wkb-format;</title>
-
- <para>
- The <literal>AsBinary()</literal> function converts a geometry
- from internal format into a <literal>BLOB</literal> containing
- the WKB value.
- </para>
-
<programlisting>
SELECT AsBinary(g) FROM geom;
</programlisting>
+ </listitem>
- </section>
+ </itemizedlist>
</section>
@@ -3004,7 +3029,7 @@
internal geometry format and returns the result. A number of
type-specific functions are also supported, such as
<literal>PointFromText()</literal> and
- <literal>LineFromText()</literal>; see
+ <literal>LineFromText()</literal>. See
<xref linkend="gis-wkt-functions"/>.
</para>
</listitem>
@@ -3023,7 +3048,7 @@
internal geometry format and returns the result. A number of
type-specific functions are also supported, such as
<literal>PointFromWKB()</literal> and
- <literal>LineFromWKB()</literal>; see
+ <literal>LineFromWKB()</literal>. See
<xref linkend="gis-wkb-functions"/>.
</para>
</listitem>
@@ -3075,9 +3100,9 @@
<para>
Returns the inherent dimension of the geometry value
- <replaceable>g</replaceable>. The result can be −1, 0,
- 1, or 2. (The meaning of these values is given in
- <xref linkend="gis-class-geometry"/>.)
+ <replaceable>g</replaceable>. The result can be −1,
+ 0, 1, or 2. The meaning of these values is given in
+ <xref linkend="gis-class-geometry"/>.
</para>
<remark role="help-description-end"/>
@@ -3294,7 +3319,8 @@
The description of each instantiable geometric class given
earlier in the chapter includes the specific conditions
that cause an instance of that class to be classified as
- not simple.
+ not simple. (See
+ <xref linkend= "gis-geometry-class-hierarchy"/>.)
</para>
<remark role="help-description-end"/>
@@ -3340,12 +3366,13 @@
<remark role="help-example"/>
<programlisting>
-mysql> <userinput>SELECT X(GeomFromText('Point(56.7 53.34)'));</userinput>
-+--------------------------------------+
-| X(GeomFromText('Point(56.7 53.34)')) |
-+--------------------------------------+
-| 56.7 |
-+--------------------------------------+
+mysql> <userinput>SET @pt = 'Point(56.7 53.34)';</userinput>
+mysql> <userinput>SELECT X(GeomFromText(@pt));</userinput>
++----------------------+
+| X(GeomFromText(@pt)) |
++----------------------+
+| 56.7 |
++----------------------+
</programlisting>
</listitem>
@@ -3372,12 +3399,13 @@
<remark role="help-example"/>
<programlisting>
-mysql> <userinput>SELECT Y(GeomFromText('Point(56.7 53.34)'));</userinput>
-+--------------------------------------+
-| Y(GeomFromText('Point(56.7 53.34)')) |
-+--------------------------------------+
-| 53.34 |
-+--------------------------------------+
+mysql> <userinput>SET @pt = 'Point(56.7 53.34)';</userinput>
+mysql> <userinput>SELECT Y(GeomFromText(@pt));</userinput>
++----------------------+
+| Y(GeomFromText(@pt)) |
++----------------------+
+| 53.34 |
++----------------------+
</programlisting>
</listitem>
@@ -3467,6 +3495,12 @@
| 2.8284271247462 |
+----------------------------+
</programlisting>
+
+ <para>
+ <literal>GLength()</literal> is a non-standard name. It
+ corresponds to the OpenGIS <literal>Length()</literal>
+ function.
+ </para>
</listitem>
<listitem>
@@ -3483,8 +3517,8 @@
</para>
<para>
- Returns the number of points in the
- <literal>LineString</literal> value
+ Returns the number of <literal>Point</literal> objects in
+ the <literal>LineString</literal> value
<replaceable>ls</replaceable>.
</para>
@@ -3517,9 +3551,11 @@
</para>
<para>
- Returns the <replaceable>n</replaceable>-th point in the
+ Returns the <replaceable>n</replaceable>-th
+ <literal>Point</literal> in the
<literal>Linestring</literal> value
- <replaceable>ls</replaceable>. Point numbers begin at 1.
+ <replaceable>ls</replaceable>. Points are numbered
+ beginning with 1.
</para>
<remark role="help-description-end"/>
@@ -3615,6 +3651,12 @@
<itemizedlist>
<listitem>
+ <remark role="note">
+ There is no help-table markup for GLength because there is
+ another marked-up entry in the LineString functions
+ section.
+ </remark>
+
<para>
<indexterm type="function">
<primary>GLength()</primary>
@@ -3640,6 +3682,12 @@
| 4.2426406871193 |
+-----------------------------+
</programlisting>
+
+ <para>
+ <literal>GLength()</literal> is a non-standard name. It
+ corresponds to the OpenGIS <literal>Length()</literal>
+ function.
+ </para>
</listitem>
<listitem>
@@ -3658,8 +3706,8 @@
<literal>EndPoint()</literal> values are the same for each
<literal>LineString</literal> in
<replaceable>mls</replaceable>). Returns 0 if
- <replaceable>mls</replaceable> is not closed, and −1 if
- it is <literal>NULL</literal>.
+ <replaceable>mls</replaceable> is not closed, and −1
+ if it is <literal>NULL</literal>.
</para>
<programlisting>
@@ -3777,7 +3825,8 @@
Returns the <replaceable>n</replaceable>-th interior ring
for the <literal>Polygon</literal> value
<replaceable>poly</replaceable> as a
- <literal>LineString</literal>. Ring numbers begin at 1.
+ <literal>LineString</literal>. Rings are numbered
+ beginning with 1.
</para>
<remark role="help-description-end"/>
@@ -3948,8 +3997,8 @@
<para>
Returns the <replaceable>n</replaceable>-th geometry in
the <literal>GeometryCollection</literal> value
- <replaceable>gc</replaceable>. Geometry numbers begin at
- 1.
+ <replaceable>gc</replaceable>. Geometries are numbered
+ beginning with 1.
</para>
<remark role="help-description-end"/>
@@ -4020,9 +4069,9 @@
<title>&title-functions-that-produce-new-geometries;</title>
<para>
- In <xref linkend="geometry-property-functions"/>,
- we've discussed some functions that can construct new
- geometries from the existing ones:
+ <xref linkend="geometry-property-functions"/>, discusses
+ several functions that construct new geometries from existing
+ ones. See that section for descriptions of these functions:
</para>
<itemizedlist>
@@ -4251,9 +4300,10 @@
<remark role="help-category" condition="MBR@Geographic Features"/>
<para>
- MySQL provides some functions that can test relations between
+ MySQL provides several functions that test relations between
minimal bounding rectangles of two geometries
- <literal>g1</literal> and <literal>g2</literal>. They include:
+ <literal>g1</literal> and <literal>g2</literal>. The return
+ values 1 and 0 indicate true and false, respectively.
</para>
<itemizedlist>
@@ -4272,10 +4322,9 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangle of <replaceable>g1</replaceable> contains
- the Minimum Bounding Rectangle of
- <replaceable>g2</replaceable>.
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangle of <replaceable>g1</replaceable> contains the
+ Minimum Bounding Rectangle of <replaceable>g2</replaceable>.
</para>
<remark role="help-description-end"/>
@@ -4308,8 +4357,8 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangles of the two geometries
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangles of the two geometries
<replaceable>g1</replaceable> and
<replaceable>g2</replaceable> are disjoint (do not
intersect).
@@ -4332,8 +4381,8 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangles of the two geometries
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangles of the two geometries
<replaceable>g1</replaceable> and
<replaceable>g2</replaceable> are the same.
</para>
@@ -4355,8 +4404,8 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangles of the two geometries
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangles of the two geometries
<replaceable>g1</replaceable> and
<replaceable>g2</replaceable> intersect.
</para>
@@ -4378,8 +4427,8 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangles of the two geometries
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangles of the two geometries
<replaceable>g1</replaceable> and
<replaceable>g2</replaceable> overlap.
</para>
@@ -4401,8 +4450,8 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangles of the two geometries
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangles of the two geometries
<replaceable>g1</replaceable> and
<replaceable>g2</replaceable> touch.
</para>
@@ -4424,10 +4473,9 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangle of <replaceable>g1</replaceable> is
- within the Minimum Bounding Rectangle of
- <replaceable>g2</replaceable>.
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangle of <replaceable>g1</replaceable> is within the
+ Minimum Bounding Rectangle of <replaceable>g2</replaceable>.
</para>
<remark role="help-description-end"/>
@@ -4455,10 +4503,15 @@
<title>&title-functions-that-test-spatial-relationships-between-geometries;</title>
<para>
- The OpenGIS specification defines the following functions.
- Currently, MySQL does not implement them according to the
- specification. Those that are implemented return the same result
- as the corresponding MBR-based functions. This includes
+ The OpenGIS specification defines the following functions. They
+ test the relationship between two geometry values
+ <literal>g1</literal> and <literal>g2</literal>.
+ </para>
+
+ <para>
+ Currently, MySQL does not implement these functions according to
+ the specification. Those that are implemented return the same
+ result as the corresponding MBR-based functions. This includes
functions in the following list other than
<literal>Distance()</literal> and <literal>Related()</literal>.
</para>
@@ -4474,8 +4527,7 @@
</para>
<para>
- The functions operate on two geometry values
- <literal>g1</literal> and <literal>g2</literal>.
+ The return values 1 and 0 indicate true and false, respectively.
</para>
<remark role="help-category" condition="Geometry relations@Geographic Features"/>
@@ -4496,7 +4548,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> completely contains
<replaceable>g2</replaceable>.
</para>
@@ -4575,7 +4627,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> is spatially disjoint from
(does not intersect) <replaceable>g2</replaceable>.
</para>
@@ -4617,7 +4669,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> is spatially equal to
<replaceable>g2</replaceable>.
</para>
@@ -4639,7 +4691,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> spatially intersects
<replaceable>g2</replaceable>.
</para>
@@ -4661,7 +4713,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> spatially overlaps
<replaceable>g2</replaceable>. The term <emphasis>spatially
overlaps</emphasis> is used if two geometries intersect and
@@ -4687,14 +4739,13 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the spatial
- relationship specified by
- <replaceable>pattern_matrix</replaceable> exists between
- <replaceable>g1</replaceable> and
- <replaceable>g2</replaceable>. Returns −1 if the arguments
- are <literal>NULL</literal>. The pattern matrix is a string.
- Its specification will be noted here if this function is
- implemented.
+ Returns 1 or 0 to indicate whether the spatial relationship
+ specified by <replaceable>pattern_matrix</replaceable>
+ exists between <replaceable>g1</replaceable> and
+ <replaceable>g2</replaceable>. Returns −1 if the
+ arguments are <literal>NULL</literal>. The pattern matrix is
+ a string. Its specification will be noted here if this
+ function is implemented.
</para>
</listitem>
@@ -4712,7 +4763,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> spatially touches
<replaceable>g2</replaceable>. Two geometries
<emphasis>spatially touch</emphasis> if the interiors of the
@@ -4738,7 +4789,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> is spatially within
<replaceable>g2</replaceable>.
</para>
@@ -4809,10 +4860,10 @@
<para>
MySQL can create spatial indexes using syntax similar to that
for creating regular indexes, but extended with the
- <literal>SPATIAL</literal> keyword. Spatial columns that are
- indexed currently must be declared <literal>NOT NULL</literal>.
+ <literal>SPATIAL</literal> keyword. Currently, spatial columns
+ that are indexed must be declared <literal>NOT NULL</literal>.
The following examples demonstrate how to create spatial
- indexes.
+ indexes:
</para>
<itemizedlist>
@@ -4823,7 +4874,7 @@
</para>
<programlisting>
-mysql> <userinput>CREATE TABLE geom (g GEOMETRY NOT NULL, SPATIAL INDEX(g));</userinput>
+CREATE TABLE geom (g GEOMETRY NOT NULL, SPATIAL INDEX(g));
</programlisting>
</listitem>
@@ -4833,7 +4884,7 @@
</para>
<programlisting>
-mysql> <userinput>ALTER TABLE geom ADD SPATIAL INDEX(g);</userinput>
+ALTER TABLE geom ADD SPATIAL INDEX(g);
</programlisting>
</listitem>
@@ -4843,7 +4894,7 @@
</para>
<programlisting>
-mysql> <userinput>CREATE SPATIAL INDEX sp_index ON geom (g);</userinput>
+CREATE SPATIAL INDEX sp_index ON geom (g);
</programlisting>
</listitem>
@@ -4862,7 +4913,7 @@
</para>
<programlisting>
-mysql> <userinput>ALTER TABLE geom DROP INDEX g;</userinput>
+ALTER TABLE geom DROP INDEX g;
</programlisting>
</listitem>
@@ -4872,7 +4923,7 @@
</para>
<programlisting>
-mysql> <userinput>DROP INDEX sp_index ON geom;</userinput>
+DROP INDEX sp_index ON geom;
</programlisting>
</listitem>
@@ -4929,13 +4980,15 @@
be involved in the search for queries that use a function such
as <literal>MBRContains()</literal> or
<literal>MBRWithin()</literal> in the <literal>WHERE</literal>
- clause. For example, let's say we want to find all objects that
- are in the given rectangle:
+ clause. The following query finds all objects that are in the
+ given rectangle:
</para>
<programlisting>
+mysql> <userinput>SET @poly =</userinput>
+ -> <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
mysql> <userinput>SELECT fid,AsText(g) FROM geom WHERE</userinput>
-mysql> <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
+ -> <userinput>MBRContains(GeomFromText(@poly),g);</userinput>
+-----+-----------------------------------------------------------------------------+
| fid | AsText(g) |
+-----+-----------------------------------------------------------------------------+
@@ -4964,45 +5017,64 @@
</programlisting>
<para>
- Let's use <literal>EXPLAIN</literal> to check the way this query
- is executed (the <literal>id</literal> column has been removed
- so the output better fits the page):
+ Use <literal>EXPLAIN</literal> to check the way this query is
+ executed (the <literal>id</literal> column has been removed so
+ the output better fits the page):
</para>
<programlisting>
+mysql> <userinput>SET @poly =</userinput>
+ -> <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
mysql> <userinput>EXPLAIN SELECT fid,AsText(g) FROM geom WHERE</userinput>
-mysql> <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
-| select_type | table | type | possible_keys | key | key_len | ref | rows | Extra |
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
-| SIMPLE | geom | range | g | g | 32 | NULL | 50 | Using where |
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
+ -> <userinput>MBRContains(GeomFromText(@poly),g)\G</userinput>
+*************************** 1. row ***************************
+ id: 1
+ select_type: SIMPLE
+ table: geom
+ type: range
+possible_keys: g
+ key: g
+ key_len: 32
+ ref: NULL
+ rows: 50
+ Extra: Using where
1 row in set (0.00 sec)
</programlisting>
<para>
- Let's check what would happen without a spatial index:
+ Check what would happen without a spatial index:
</para>
<programlisting>
+mysql> <userinput>SET @poly =</userinput>
+ -> <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
mysql> <userinput>EXPLAIN SELECT fid,AsText(g) FROM g IGNORE INDEX (g) WHERE</userinput>
-mysql> <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
-| select_type | table | type | possible_keys | key | key_len | ref | rows | Extra |
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
-| SIMPLE | geom | ALL | NULL | NULL | NULL | NULL | 32376 | Using where |
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
+ -> <userinput>MBRContains(GeomFromText(@poly),g)\G</userinput>
+*************************** 1. row ***************************
+ id: 1
+ select_type: SIMPLE
+ table: geom
+ type: ALL
+possible_keys: NULL
+ key: NULL
+ key_len: NULL
+ ref: NULL
+ rows: 32376
+ Extra: Using where
1 row in set (0.00 sec)
</programlisting>
<para>
- Let's execute the <literal>SELECT</literal> statement, ignoring
- the spatial key we have:
+ Executing the <literal>SELECT</literal> statement without the
+ spatial index yields the same result but causes the execution
+ time to rise from 0.00 seconds to 0.46 seconds:
</para>
<programlisting>
+mysql> <userinput>SET @poly =</userinput>
+ -> <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
mysql> <userinput>SELECT fid,AsText(g) FROM geom IGNORE INDEX (g) WHERE</userinput>
-mysql> <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
+ -> <userinput>MBRContains(GeomFromText(@poly),g);</userinput>
+-----+-----------------------------------------------------------------------------+
| fid | AsText(g) |
+-----+-----------------------------------------------------------------------------+
@@ -5031,11 +5103,6 @@
</programlisting>
<para>
- When the index is not used, the execution time for this query
- rises from 0.00 seconds to 0.46 seconds.
- </para>
-
- <para>
In future releases, spatial indexes may also be used for
optimizing other functions. See
<xref linkend="functions-for-testing-spatial-relations-between-geometric-objects"/>.
@@ -5049,72 +5116,65 @@
<title>&title-mysql-gis-conformance-and-compatibility;</title>
- <remark role="todo">
- Add introductory descriptive sentence.
- </remark>
+ <para>
+ MySQL does not yet implement the following GIS features:
+ </para>
- <section id="gis-features-that-are-not-yet-implemented">
+ <itemizedlist>
- <title>&title-gis-features-that-are-not-yet-implemented;</title>
+ <listitem>
+ <para>
+ Additional Metadata Views
+ </para>
- <itemizedlist>
+ <para>
+ OpenGIS specifications propose several additional metadata
+ views. For example, a system view named
+ <literal>GEOMETRY_COLUMNS</literal> contains a description of
+ geometry columns, one row for each geometry column in the
+ database.
+ </para>
- <listitem>
- <para>
- Additional Metadata Views
- </para>
+ <remark>
+ @item Functions to add/drop spatial columns OpenGIS assumes
+ that columns can be added or dropped using special
+ @code{AddGeometryColumn()} and @code{DropGeometryColumn()}
+ functions. In MySQL, this is done using the @code{ALTER
+ TABLE}, @code{CREATE INDEX}, and @code{DROP INDEX} statements
+ instead. @item Factors related to Spatial Reference Systems
+ and their IDs (SRIDs): @itemize @bullet @item Functions like
+ @code{Length()} and @code{Area()} assume a planar coordinate
+ system. @item All objects currently are considered to be in
+ the same planar coordinate system. @end itemize
+ </remark>
+ </listitem>
- <para>
- OpenGIS specifications propose several additional metadata
- views. For example, a system view named
- <literal>GEOMETRY_COLUMNS</literal> contains a description
- of geometry columns, one row for each geometry column in the
- database.
- </para>
+ <listitem>
+ <para>
+ The OpenGIS function <literal>Length()</literal> on
+ <literal>LineString</literal> and
+ <literal>MultiLineString</literal> currently should be called
+ in MySQL as <literal>GLength()</literal>
+ </para>
- <remark>
- @item Functions to add/drop spatial columns OpenGIS assumes
- that columns can be added or dropped using special
- @code{AddGeometryColumn()} and @code{DropGeometryColumn()}
- functions. In MySQL, this is done using the @code{ALTER
- TABLE}, @code{CREATE INDEX}, and @code{DROP INDEX}
- statements instead. @item Factors related to Spatial
- Reference Systems and their IDs (SRIDs): @itemize @bullet
- @item Functions like @code{Length()} and @code{Area()}
- assume a planar coordinate system. @item All objects
- currently are considered to be in the same planar coordinate
- system. @end itemize
- </remark>
- </listitem>
+ <para>
+ The problem is that there is an existing SQL function
+ <literal>Length()</literal> that calculates the length of
+ string values, and sometimes it is not possible to distinguish
+ whether the function is called in a textual or spatial
+ context. We need either to solve this somehow, or decide on
+ another function name.
+ </para>
+ </listitem>
- <listitem>
- <para>
- The OpenGIS function <literal>Length()</literal> on
- <literal>LineString</literal> and
- <literal>MultiLineString</literal> currently should be
- called in MySQL as <literal>GLength()</literal>
- </para>
+ </itemizedlist>
- <para>
- The problem is that there is an existing SQL function
- <literal>Length()</literal> which calculates the length of
- string values, and sometimes it is not possible to
- distinguish whether the function is called in a textual or
- spatial context. We need either to solve this somehow, or
- decide on another function name.
- </para>
- </listitem>
+ <remark>
+ @node GIS writing a GIS application @section Writing a GIS
+ Application @node GIS Java GIS Object Model @section Java GIS
+ Object Model
+ </remark>
- </itemizedlist>
-
- <remark>
- @node GIS writing a GIS application @section Writing a GIS
- Application @node GIS Java GIS Object Model @section Java GIS
- Object Model
- </remark>
-
- </section>
-
</section>
</chapter>
Modified: trunk/refman-5.0/renamed-nodes.txt
===================================================================
--- trunk/refman-5.0/renamed-nodes.txt 2006-01-19 15:38:42 UTC (rev 929)
+++ trunk/refman-5.0/renamed-nodes.txt 2006-01-19 15:38:54 UTC (rev 930)
@@ -398,3 +398,7 @@
charset-config-file adding-character-set
open-tables table-cache
variables user-variables
+fetching-spatial-data-in-internal-format fetching-spatial-data
+fetching-spatial-data-in-wkb-format fetching-spatial-data
+fetching-spatial-data-in-wkt-format fetching-spatial-data
+gis-features-that-are-not-yet-implemented mysql-gis-conformance-and-compatibility
Modified: trunk/refman-5.0/spatial-extensions.xml
===================================================================
--- trunk/refman-5.0/spatial-extensions.xml 2006-01-19 15:38:42 UTC (rev 929)
+++ trunk/refman-5.0/spatial-extensions.xml 2006-01-19 15:38:54 UTC (rev 930)
@@ -72,20 +72,31 @@
<para>
<emphasis role="bold">Additional resources</emphasis>
+ </para>
- <itemizedlist>
+ <itemizedlist>
- <listitem>
- <para>
- If you have questions or concerns about the use of the spatial
- extensions to MySQL, you can discuss these in the GIS forum:
- <ulink url="&base-url-forum-list;?23"/>.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ The Open Geospatial Consortium publishes the
+ <citetitle>OpenGIS® Simple Features Specifications For
+ SQL</citetitle>, a document that proposes several conceptual
+ ways for extending an SQL RDBMS to support spatial data. This
+ specification is available from the OGC Web site at
+ <ulink url="http://www.opengis.org/docs/99-049.pdf"/>.
+ </para>
+ </listitem>
- </itemizedlist>
- </para>
+ <listitem>
+ <para>
+ If you have questions or concerns about the use of the spatial
+ extensions to MySQL, you can discuss them in the GIS forum:
+ <ulink url="&base-url-forum-list;?23"/>.
+ </para>
+ </listitem>
+ </itemizedlist>
+
<section id="gis-introduction">
<title>&title-gis-introduction;</title>
@@ -104,20 +115,20 @@
<para>
MySQL implements spatial extensions following the specification of
- the <literal>Open GIS Consortium</literal> (OGC). This is an
- international consortium of more than 250 companies, agencies, and
- universities participating in the development of publicly
- available conceptual solutions that can be useful with all kinds
- of applications that manage spatial data. The OGC maintains a Web
- site at <ulink url="http://www.opengis.org/"/>.
+ the Open Geospatial Consortium (OGC). This is an international
+ consortium of more than 250 companies, agencies, and universities
+ participating in the development of publicly available conceptual
+ solutions that can be useful with all kinds of applications that
+ manage spatial data. The OGC maintains a Web site at
+ <ulink url="http://www.opengis.org/"/>.
</para>
<para>
- In 1997, the Open GIS Consortium published the
+ In 1997, the Open Geospatial Consortium published the
<citetitle>OpenGIS® Simple Features Specifications For
SQL</citetitle>, a document that proposes several conceptual ways
for extending an SQL RDBMS to support spatial data. This
- specification is available from the Open GIS Web site at
+ specification is available from the OGC Web site at
<ulink url="http://www.opengis.org/docs/99-049.pdf"/>. It contains
additional information relevant to this chapter.
</para>
@@ -127,7 +138,7 @@
Geometry Types</emphasis> environment proposed by OGC. This term
refers to an SQL environment that has been extended with a set of
geometry types. A geometry-valued SQL column is implemented as a
- column that has a geometry type. The specifications describe a set
+ column that has a geometry type. The specification describe a set
of SQL geometry types, as well as functions on those types to
create and analyze geometry values.
</para>
@@ -169,9 +180,8 @@
</indexterm>
<para>
- You can also find documents that use the term
- <emphasis role="bold">geospatial feature</emphasis> to refer to
- geographic features.
+ Some documents use the term <emphasis role="bold">geospatial
+ feature</emphasis> to refer to geographic features.
</para>
<indexterm>
@@ -191,16 +201,12 @@
<emphasis role="bold">geographic feature</emphasis>,
<emphasis role="bold">geospatial feature</emphasis>,
<emphasis role="bold">feature</emphasis>, or
- <emphasis role="bold">geometry</emphasis>. The term most commonly
- used here is <emphasis role="bold">geometry</emphasis>.
+ <emphasis role="bold">geometry</emphasis>. Here, the term most
+ commonly used is <emphasis role="bold">geometry</emphasis>,
+ defined as <emphasis>a point or an aggregate of points
+ representing anything in the world that has a location</emphasis>.
</para>
- <para>
- Let's define a <emphasis role="bold">geometry</emphasis> as
- <emphasis>a point or an aggregate of points representing anything
- in the world that has a location</emphasis>.
- </para>
-
</section>
<section id="opengis-geometry-model">
@@ -370,7 +376,7 @@
<remark role="help-description-begin"/>
<para>
- <literal>Geometry</literal> is the base class. It's an abstract
+ <literal>Geometry</literal> is the base class. It is an abstract
class. The instantiable subclasses of
<literal>Geometry</literal> are restricted to zero-, one-, and
two-dimensional geometric objects that exist in two-dimensional
@@ -461,8 +467,8 @@
It is a non-instantiable class but has a number of properties
that are common to all geometry values created from any of the
<literal>Geometry</literal> subclasses. These properties are
- described in the following list. (Particular subclasses have
- their own specific properties, described later.)
+ described in the following list. Particular subclasses have
+ their own specific properties, described later.
</para>
<para>
@@ -1424,7 +1430,7 @@
</remark>
<para>
- Examples of WKT representations of geometry objects are:
+ Examples of WKT representations of geometry objects:
</para>
<itemizedlist>
@@ -1530,7 +1536,7 @@
<para>
A Backus-Naur grammar that specifies the formal production rules
- for writing WKT values can be found in the OGC specification
+ for writing WKT values can be found in the OpenGIS specification
document referenced near the beginning of this chapter.
</para>
@@ -1550,8 +1556,8 @@
<para>
The Well-Known Binary (WKB) representation for geometric values
- is defined by the OpenGIS specifications. It is also defined in
- the ISO <quote>SQL/MM Part 3: Spatial</quote> standard.
+ is defined by the OpenGIS specification. It is also defined in
+ the ISO <citetitle>SQL/MM Part 3: Spatial</citetitle> standard.
</para>
<para>
@@ -1765,8 +1771,8 @@
<para>
<literal>GEOMETRY</literal> can store geometry values of any
- type. The other single-value types, <literal>POINT</literal> and
- <literal>LINESTRING</literal> and <literal>POLYGON</literal>,
+ type. The other single-value types (<literal>POINT</literal>,
+ <literal>LINESTRING</literal>, and <literal>POLYGON</literal>)
restrict their values to a particular geometry type.
</para>
@@ -1804,11 +1810,11 @@
<para>
<literal>GEOMETRYCOLLECTION</literal> can store a collection of
- objects of any type. The other collection types,
- <literal>MULTIPOINT</literal> and
- <literal>MULTILINESTRING</literal> and
- <literal>MULTIPOLYGON</literal> and
- <literal>GEOMETRYCOLLECTION</literal>, restrict collection
+ objects of any type. The other collection types
+ (<literal>MULTIPOINT</literal>,
+ <literal>MULTILINESTRING</literal>,
+ <literal>MULTIPOLYGON</literal>, and
+ <literal>GEOMETRYCOLLECTION</literal>) restrict collection
members to those having a particular geometry type.
</para>
@@ -2080,12 +2086,13 @@
</itemizedlist>
<para>
- The OpenGIS specification also describes optional functions
- for constructing <literal>Polygon</literal> or
+ The OpenGIS specification also defines the following optional
+ functions, which MySQL does not implement. These functions
+ construct <literal>Polygon</literal> or
<literal>MultiPolygon</literal> values based on the WKT
representation of a collection of rings or closed
<literal>LineString</literal> values. These values may
- intersect. MySQL does not implement these functions:
+ intersect.
</para>
<itemizedlist>
@@ -2442,14 +2449,15 @@
<title>&title-gis-mysql-specific-functions;</title>
<para>
- MySQL provides a set of useful functions for creating geometry
- WKB representations. The functions described in this section
- are MySQL extensions to the OpenGIS specifications. The
- results of these functions are <literal>BLOB</literal> values
- containing WKB representations of geometry values with no
- SRID. The results of these functions can be substituted as the
- first argument for any function in the
- <literal>GeomFromWKB()</literal> function family.
+ MySQL provides a set of useful non-standard functions for
+ creating geometry WKB representations. The functions described
+ in this section are MySQL extensions to the OpenGIS
+ specification. The results of these functions are
+ <literal>BLOB</literal> values containing WKB representations
+ of geometry values with no SRID. The results of these
+ functions can be substituted as the first argument for any
+ function in the <literal>GeomFromWKB()</literal> function
+ family.
</para>
<remark role="help-category" condition="Geometry constructors@Geographic Features"/>
@@ -2660,8 +2668,7 @@
<remark role="help-example"/>
<programlisting>
-mysql> <userinput>CREATE TABLE geom (g GEOMETRY);</userinput>
-Query OK, 0 rows affected (0.02 sec)
+CREATE TABLE geom (g GEOMETRY);
</programlisting>
</listitem>
@@ -2672,12 +2679,8 @@
</para>
<programlisting>
-mysql> <userinput>ALTER TABLE geom ADD pt POINT;</userinput>
-Query OK, 0 rows affected (0.00 sec)
-Records: 0 Duplicates: 0 Warnings: 0
-mysql> <userinput>ALTER TABLE geom DROP pt;</userinput>
-Query OK, 0 rows affected (0.00 sec)
-Records: 0 Duplicates: 0 Warnings: 0
+ALTER TABLE geom ADD pt POINT;
+ALTER TABLE geom DROP pt;
</programlisting>
</listitem>
@@ -2699,31 +2702,39 @@
convert them to that format from either Well-Known Text (WKT) or
Well-Known Binary (WKB) format. The following examples
demonstrate how to insert geometry values into a table by
- converting WKT values into internal geometry format.
+ converting WKT values into internal geometry format:
</para>
- <para>
- You can perform the conversion directly in the
- <literal>INSERT</literal> statement:
- </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Perform the conversion directly in the
+ <literal>INSERT</literal> statement:
+ </para>
+
<programlisting>
INSERT INTO geom VALUES (GeomFromText('POINT(1 1)'));
SET @g = 'POINT(1 1)';
INSERT INTO geom VALUES (GeomFromText(@g));
</programlisting>
+ </listitem>
- <para>
- Or you can perform the conversion prior to the
- <literal>INSERT</literal>:
- </para>
+ <listitem>
+ <para>
+ Perform the conversion prior to the
+ <literal>INSERT</literal>:
+ </para>
<programlisting>
SET @g = GeomFromText('POINT(1 1)');
INSERT INTO geom VALUES (@g);
</programlisting>
+ </listitem>
+ </itemizedlist>
+
<para>
The following examples insert more complex geometries into the
table:
@@ -2823,51 +2834,55 @@
format. You can also convert them into WKT or WKB format.
</para>
- <section id="fetching-spatial-data-in-internal-format">
+ <itemizedlist>
- <title>&title-fetching-spatial-data-in-internal-format;</title>
+ <listitem>
+ <para>
+ Fetching spatial data in internal format:
+ </para>
- <para>
- Fetching geometry values using internal format can be useful
- in table-to-table transfers:
- </para>
+ <para>
+ Fetching geometry values using internal format can be useful
+ in table-to-table transfers:
+ </para>
<programlisting>
CREATE TABLE geom2 (g GEOMETRY) SELECT g FROM geom;
</programlisting>
+ </listitem>
- </section>
+ <listitem>
+ <para>
+ Fetching spatial data in WKT format:
+ </para>
- <section id="fetching-spatial-data-in-wkt-format">
+ <para>
+ The <literal>AsText()</literal> function converts a geometry
+ from internal format into a WKT string.
+ </para>
- <title>&title-fetching-spatial-data-in-wkt-format;</title>
-
- <para>
- The <literal>AsText()</literal> function converts a geometry
- from internal format into a WKT string.
- </para>
-
<programlisting>
SELECT AsText(g) FROM geom;
</programlisting>
+ </listitem>
- </section>
+ <listitem>
+ <para>
+ Fetching spatial data in WKB format:
+ </para>
- <section id="fetching-spatial-data-in-wkb-format">
+ <para>
+ The <literal>AsBinary()</literal> function converts a
+ geometry from internal format into a <literal>BLOB</literal>
+ containing the WKB value.
+ </para>
- <title>&title-fetching-spatial-data-in-wkb-format;</title>
-
- <para>
- The <literal>AsBinary()</literal> function converts a geometry
- from internal format into a <literal>BLOB</literal> containing
- the WKB value.
- </para>
-
<programlisting>
SELECT AsBinary(g) FROM geom;
</programlisting>
+ </listitem>
- </section>
+ </itemizedlist>
</section>
@@ -3025,7 +3040,7 @@
internal geometry format and returns the result. A number of
type-specific functions are also supported, such as
<literal>PointFromText()</literal> and
- <literal>LineFromText()</literal>; see
+ <literal>LineFromText()</literal>. See
<xref linkend="gis-wkt-functions"/>.
</para>
</listitem>
@@ -3044,7 +3059,7 @@
internal geometry format and returns the result. A number of
type-specific functions are also supported, such as
<literal>PointFromWKB()</literal> and
- <literal>LineFromWKB()</literal>; see
+ <literal>LineFromWKB()</literal>. See
<xref linkend="gis-wkb-functions"/>.
</para>
</listitem>
@@ -3096,9 +3111,9 @@
<para>
Returns the inherent dimension of the geometry value
- <replaceable>g</replaceable>. The result can be −1, 0,
- 1, or 2. (The meaning of these values is given in
- <xref linkend="gis-class-geometry"/>.)
+ <replaceable>g</replaceable>. The result can be −1,
+ 0, 1, or 2. The meaning of these values is given in
+ <xref linkend="gis-class-geometry"/>.
</para>
<remark role="help-description-end"/>
@@ -3315,7 +3330,8 @@
The description of each instantiable geometric class given
earlier in the chapter includes the specific conditions
that cause an instance of that class to be classified as
- not simple.
+ not simple. (See
+ <xref linkend= "gis-geometry-class-hierarchy"/>.)
</para>
<remark role="help-description-end"/>
@@ -3361,12 +3377,13 @@
<remark role="help-example"/>
<programlisting>
-mysql> <userinput>SELECT X(GeomFromText('Point(56.7 53.34)'));</userinput>
-+--------------------------------------+
-| X(GeomFromText('Point(56.7 53.34)')) |
-+--------------------------------------+
-| 56.7 |
-+--------------------------------------+
+mysql> <userinput>SET @pt = 'Point(56.7 53.34)';</userinput>
+mysql> <userinput>SELECT X(GeomFromText(@pt));</userinput>
++----------------------+
+| X(GeomFromText(@pt)) |
++----------------------+
+| 56.7 |
++----------------------+
</programlisting>
</listitem>
@@ -3393,12 +3410,13 @@
<remark role="help-example"/>
<programlisting>
-mysql> <userinput>SELECT Y(GeomFromText('Point(56.7 53.34)'));</userinput>
-+--------------------------------------+
-| Y(GeomFromText('Point(56.7 53.34)')) |
-+--------------------------------------+
-| 53.34 |
-+--------------------------------------+
+mysql> <userinput>SET @pt = 'Point(56.7 53.34)';</userinput>
+mysql> <userinput>SELECT Y(GeomFromText(@pt));</userinput>
++----------------------+
+| Y(GeomFromText(@pt)) |
++----------------------+
+| 53.34 |
++----------------------+
</programlisting>
</listitem>
@@ -3488,6 +3506,12 @@
| 2.8284271247462 |
+----------------------------+
</programlisting>
+
+ <para>
+ <literal>GLength()</literal> is a non-standard name. It
+ corresponds to the OpenGIS <literal>Length()</literal>
+ function.
+ </para>
</listitem>
<listitem>
@@ -3504,8 +3528,8 @@
</para>
<para>
- Returns the number of points in the
- <literal>LineString</literal> value
+ Returns the number of <literal>Point</literal> objects in
+ the <literal>LineString</literal> value
<replaceable>ls</replaceable>.
</para>
@@ -3538,9 +3562,11 @@
</para>
<para>
- Returns the <replaceable>n</replaceable>-th point in the
+ Returns the <replaceable>n</replaceable>-th
+ <literal>Point</literal> in the
<literal>Linestring</literal> value
- <replaceable>ls</replaceable>. Point numbers begin at 1.
+ <replaceable>ls</replaceable>. Points are numbered
+ beginning with 1.
</para>
<remark role="help-description-end"/>
@@ -3636,6 +3662,12 @@
<itemizedlist>
<listitem>
+ <remark role="note">
+ There is no help-table markup for GLength because there is
+ another marked-up entry in the LineString functions
+ section.
+ </remark>
+
<para>
<indexterm type="function">
<primary>GLength()</primary>
@@ -3661,6 +3693,12 @@
| 4.2426406871193 |
+-----------------------------+
</programlisting>
+
+ <para>
+ <literal>GLength()</literal> is a non-standard name. It
+ corresponds to the OpenGIS <literal>Length()</literal>
+ function.
+ </para>
</listitem>
<listitem>
@@ -3679,8 +3717,8 @@
<literal>EndPoint()</literal> values are the same for each
<literal>LineString</literal> in
<replaceable>mls</replaceable>). Returns 0 if
- <replaceable>mls</replaceable> is not closed, and −1 if
- it is <literal>NULL</literal>.
+ <replaceable>mls</replaceable> is not closed, and −1
+ if it is <literal>NULL</literal>.
</para>
<programlisting>
@@ -3798,7 +3836,8 @@
Returns the <replaceable>n</replaceable>-th interior ring
for the <literal>Polygon</literal> value
<replaceable>poly</replaceable> as a
- <literal>LineString</literal>. Ring numbers begin at 1.
+ <literal>LineString</literal>. Rings are numbered
+ beginning with 1.
</para>
<remark role="help-description-end"/>
@@ -3969,8 +4008,8 @@
<para>
Returns the <replaceable>n</replaceable>-th geometry in
the <literal>GeometryCollection</literal> value
- <replaceable>gc</replaceable>. Geometry numbers begin at
- 1.
+ <replaceable>gc</replaceable>. Geometries are numbered
+ beginning with 1.
</para>
<remark role="help-description-end"/>
@@ -4041,9 +4080,9 @@
<title>&title-functions-that-produce-new-geometries;</title>
<para>
- In <xref linkend="geometry-property-functions"/>,
- we've discussed some functions that can construct new
- geometries from the existing ones:
+ <xref linkend="geometry-property-functions"/>, discusses
+ several functions that construct new geometries from existing
+ ones. See that section for descriptions of these functions:
</para>
<itemizedlist>
@@ -4272,9 +4311,10 @@
<remark role="help-category" condition="MBR@Geographic Features"/>
<para>
- MySQL provides some functions that can test relations between
+ MySQL provides several functions that test relations between
minimal bounding rectangles of two geometries
- <literal>g1</literal> and <literal>g2</literal>. They include:
+ <literal>g1</literal> and <literal>g2</literal>. The return
+ values 1 and 0 indicate true and false, respectively.
</para>
<itemizedlist>
@@ -4293,10 +4333,9 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangle of <replaceable>g1</replaceable> contains
- the Minimum Bounding Rectangle of
- <replaceable>g2</replaceable>.
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangle of <replaceable>g1</replaceable> contains the
+ Minimum Bounding Rectangle of <replaceable>g2</replaceable>.
</para>
<remark role="help-description-end"/>
@@ -4329,8 +4368,8 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangles of the two geometries
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangles of the two geometries
<replaceable>g1</replaceable> and
<replaceable>g2</replaceable> are disjoint (do not
intersect).
@@ -4353,8 +4392,8 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangles of the two geometries
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangles of the two geometries
<replaceable>g1</replaceable> and
<replaceable>g2</replaceable> are the same.
</para>
@@ -4376,8 +4415,8 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangles of the two geometries
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangles of the two geometries
<replaceable>g1</replaceable> and
<replaceable>g2</replaceable> intersect.
</para>
@@ -4399,8 +4438,8 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangles of the two geometries
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangles of the two geometries
<replaceable>g1</replaceable> and
<replaceable>g2</replaceable> overlap.
</para>
@@ -4422,8 +4461,8 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangles of the two geometries
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangles of the two geometries
<replaceable>g1</replaceable> and
<replaceable>g2</replaceable> touch.
</para>
@@ -4445,10 +4484,9 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangle of <replaceable>g1</replaceable> is
- within the Minimum Bounding Rectangle of
- <replaceable>g2</replaceable>.
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangle of <replaceable>g1</replaceable> is within the
+ Minimum Bounding Rectangle of <replaceable>g2</replaceable>.
</para>
<remark role="help-description-end"/>
@@ -4476,10 +4514,15 @@
<title>&title-functions-that-test-spatial-relationships-between-geometries;</title>
<para>
- The OpenGIS specification defines the following functions.
- Currently, MySQL does not implement them according to the
- specification. Those that are implemented return the same result
- as the corresponding MBR-based functions. This includes
+ The OpenGIS specification defines the following functions. They
+ test the relationship between two geometry values
+ <literal>g1</literal> and <literal>g2</literal>.
+ </para>
+
+ <para>
+ Currently, MySQL does not implement these functions according to
+ the specification. Those that are implemented return the same
+ result as the corresponding MBR-based functions. This includes
functions in the following list other than
<literal>Distance()</literal> and <literal>Related()</literal>.
</para>
@@ -4495,8 +4538,7 @@
</para>
<para>
- The functions operate on two geometry values
- <literal>g1</literal> and <literal>g2</literal>.
+ The return values 1 and 0 indicate true and false, respectively.
</para>
<remark role="help-category" condition="Geometry relations@Geographic Features"/>
@@ -4517,7 +4559,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> completely contains
<replaceable>g2</replaceable>.
</para>
@@ -4596,7 +4638,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> is spatially disjoint from
(does not intersect) <replaceable>g2</replaceable>.
</para>
@@ -4638,7 +4680,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> is spatially equal to
<replaceable>g2</replaceable>.
</para>
@@ -4660,7 +4702,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> spatially intersects
<replaceable>g2</replaceable>.
</para>
@@ -4682,7 +4724,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> spatially overlaps
<replaceable>g2</replaceable>. The term <emphasis>spatially
overlaps</emphasis> is used if two geometries intersect and
@@ -4708,14 +4750,13 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the spatial
- relationship specified by
- <replaceable>pattern_matrix</replaceable> exists between
- <replaceable>g1</replaceable> and
- <replaceable>g2</replaceable>. Returns −1 if the arguments
- are <literal>NULL</literal>. The pattern matrix is a string.
- Its specification will be noted here if this function is
- implemented.
+ Returns 1 or 0 to indicate whether the spatial relationship
+ specified by <replaceable>pattern_matrix</replaceable>
+ exists between <replaceable>g1</replaceable> and
+ <replaceable>g2</replaceable>. Returns −1 if the
+ arguments are <literal>NULL</literal>. The pattern matrix is
+ a string. Its specification will be noted here if this
+ function is implemented.
</para>
</listitem>
@@ -4733,7 +4774,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> spatially touches
<replaceable>g2</replaceable>. Two geometries
<emphasis>spatially touch</emphasis> if the interiors of the
@@ -4759,7 +4800,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> is spatially within
<replaceable>g2</replaceable>.
</para>
@@ -4837,10 +4878,10 @@
<para>
MySQL can create spatial indexes using syntax similar to that
for creating regular indexes, but extended with the
- <literal>SPATIAL</literal> keyword. Spatial columns that are
- indexed currently must be declared <literal>NOT NULL</literal>.
+ <literal>SPATIAL</literal> keyword. Currently, spatial columns
+ that are indexed must be declared <literal>NOT NULL</literal>.
The following examples demonstrate how to create spatial
- indexes.
+ indexes:
</para>
<itemizedlist>
@@ -4851,7 +4892,7 @@
</para>
<programlisting>
-mysql> <userinput>CREATE TABLE geom (g GEOMETRY NOT NULL, SPATIAL INDEX(g));</userinput>
+CREATE TABLE geom (g GEOMETRY NOT NULL, SPATIAL INDEX(g));
</programlisting>
</listitem>
@@ -4861,7 +4902,7 @@
</para>
<programlisting>
-mysql> <userinput>ALTER TABLE geom ADD SPATIAL INDEX(g);</userinput>
+ALTER TABLE geom ADD SPATIAL INDEX(g);
</programlisting>
</listitem>
@@ -4871,7 +4912,7 @@
</para>
<programlisting>
-mysql> <userinput>CREATE SPATIAL INDEX sp_index ON geom (g);</userinput>
+CREATE SPATIAL INDEX sp_index ON geom (g);
</programlisting>
</listitem>
@@ -4880,7 +4921,7 @@
<para>
For <literal>MyISAM</literal> tables, <literal>SPATIAL
INDEX</literal> creates an R-tree index. For other storage
- engines that support spatial index, <literal>SPATIAL
+ engines that support spatial indexing, <literal>SPATIAL
INDEX</literal> creates a B-tree index. A B-tree index on
spatial values will be useful for exact-value lookups, but not
for range scans.
@@ -4899,7 +4940,7 @@
</para>
<programlisting>
-mysql> <userinput>ALTER TABLE geom DROP INDEX g;</userinput>
+ALTER TABLE geom DROP INDEX g;
</programlisting>
</listitem>
@@ -4909,7 +4950,7 @@
</para>
<programlisting>
-mysql> <userinput>DROP INDEX sp_index ON geom;</userinput>
+DROP INDEX sp_index ON geom;
</programlisting>
</listitem>
@@ -4966,13 +5007,15 @@
be involved in the search for queries that use a function such
as <literal>MBRContains()</literal> or
<literal>MBRWithin()</literal> in the <literal>WHERE</literal>
- clause. For example, let's say we want to find all objects that
- are in the given rectangle:
+ clause. The following query finds all objects that are in the
+ given rectangle:
</para>
<programlisting>
+mysql> <userinput>SET @poly =</userinput>
+ -> <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
mysql> <userinput>SELECT fid,AsText(g) FROM geom WHERE</userinput>
-mysql> <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
+ -> <userinput>MBRContains(GeomFromText(@poly),g);</userinput>
+-----+-----------------------------------------------------------------------------+
| fid | AsText(g) |
+-----+-----------------------------------------------------------------------------+
@@ -5001,45 +5044,64 @@
</programlisting>
<para>
- Let's use <literal>EXPLAIN</literal> to check the way this query
- is executed (the <literal>id</literal> column has been removed
- so the output better fits the page):
+ Use <literal>EXPLAIN</literal> to check the way this query is
+ executed (the <literal>id</literal> column has been removed so
+ the output better fits the page):
</para>
<programlisting>
+mysql> <userinput>SET @poly =</userinput>
+ -> <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
mysql> <userinput>EXPLAIN SELECT fid,AsText(g) FROM geom WHERE</userinput>
-mysql> <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
-| select_type | table | type | possible_keys | key | key_len | ref | rows | Extra |
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
-| SIMPLE | geom | range | g | g | 32 | NULL | 50 | Using where |
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
+ -> <userinput>MBRContains(GeomFromText(@poly),g)\G</userinput>
+*************************** 1. row ***************************
+ id: 1
+ select_type: SIMPLE
+ table: geom
+ type: range
+possible_keys: g
+ key: g
+ key_len: 32
+ ref: NULL
+ rows: 50
+ Extra: Using where
1 row in set (0.00 sec)
</programlisting>
<para>
- Let's check what would happen without a spatial index:
+ Check what would happen without a spatial index:
</para>
<programlisting>
+mysql> <userinput>SET @poly =</userinput>
+ -> <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
mysql> <userinput>EXPLAIN SELECT fid,AsText(g) FROM g IGNORE INDEX (g) WHERE</userinput>
-mysql> <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
-| select_type | table | type | possible_keys | key | key_len | ref | rows | Extra |
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
-| SIMPLE | geom | ALL | NULL | NULL | NULL | NULL | 32376 | Using where |
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
+ -> <userinput>MBRContains(GeomFromText(@poly),g)\G</userinput>
+*************************** 1. row ***************************
+ id: 1
+ select_type: SIMPLE
+ table: geom
+ type: ALL
+possible_keys: NULL
+ key: NULL
+ key_len: NULL
+ ref: NULL
+ rows: 32376
+ Extra: Using where
1 row in set (0.00 sec)
</programlisting>
<para>
- Let's execute the <literal>SELECT</literal> statement, ignoring
- the spatial key we have:
+ Executing the <literal>SELECT</literal> statement without the
+ spatial index yields the same result but causes the execution
+ time to rise from 0.00 seconds to 0.46 seconds:
</para>
<programlisting>
+mysql> <userinput>SET @poly =</userinput>
+ -> <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
mysql> <userinput>SELECT fid,AsText(g) FROM geom IGNORE INDEX (g) WHERE</userinput>
-mysql> <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
+ -> <userinput>MBRContains(GeomFromText(@poly),g);</userinput>
+-----+-----------------------------------------------------------------------------+
| fid | AsText(g) |
+-----+-----------------------------------------------------------------------------+
@@ -5068,11 +5130,6 @@
</programlisting>
<para>
- When the index is not used, the execution time for this query
- rises from 0.00 seconds to 0.46 seconds.
- </para>
-
- <para>
In future releases, spatial indexes may also be used for
optimizing other functions. See
<xref linkend="functions-for-testing-spatial-relations-between-geometric-objects"/>.
@@ -5086,72 +5143,65 @@
<title>&title-mysql-gis-conformance-and-compatibility;</title>
- <remark role="todo">
- Add introductory descriptive sentence.
- </remark>
+ <para>
+ MySQL does not yet implement the following GIS features:
+ </para>
- <section id="gis-features-that-are-not-yet-implemented">
+ <itemizedlist>
- <title>&title-gis-features-that-are-not-yet-implemented;</title>
+ <listitem>
+ <para>
+ Additional Metadata Views
+ </para>
- <itemizedlist>
+ <para>
+ OpenGIS specifications propose several additional metadata
+ views. For example, a system view named
+ <literal>GEOMETRY_COLUMNS</literal> contains a description of
+ geometry columns, one row for each geometry column in the
+ database.
+ </para>
- <listitem>
- <para>
- Additional Metadata Views
- </para>
+ <remark>
+ @item Functions to add/drop spatial columns OpenGIS assumes
+ that columns can be added or dropped using special
+ @code{AddGeometryColumn()} and @code{DropGeometryColumn()}
+ functions. In MySQL, this is done using the @code{ALTER
+ TABLE}, @code{CREATE INDEX}, and @code{DROP INDEX} statements
+ instead. @item Factors related to Spatial Reference Systems
+ and their IDs (SRIDs): @itemize @bullet @item Functions like
+ @code{Length()} and @code{Area()} assume a planar coordinate
+ system. @item All objects currently are considered to be in
+ the same planar coordinate system. @end itemize
+ </remark>
+ </listitem>
- <para>
- OpenGIS specifications propose several additional metadata
- views. For example, a system view named
- <literal>GEOMETRY_COLUMNS</literal> contains a description
- of geometry columns, one row for each geometry column in the
- database.
- </para>
+ <listitem>
+ <para>
+ The OpenGIS function <literal>Length()</literal> on
+ <literal>LineString</literal> and
+ <literal>MultiLineString</literal> currently should be called
+ in MySQL as <literal>GLength()</literal>
+ </para>
- <remark>
- @item Functions to add/drop spatial columns OpenGIS assumes
- that columns can be added or dropped using special
- @code{AddGeometryColumn()} and @code{DropGeometryColumn()}
- functions. In MySQL, this is done using the @code{ALTER
- TABLE}, @code{CREATE INDEX}, and @code{DROP INDEX}
- statements instead. @item Factors related to Spatial
- Reference Systems and their IDs (SRIDs): @itemize @bullet
- @item Functions like @code{Length()} and @code{Area()}
- assume a planar coordinate system. @item All objects
- currently are considered to be in the same planar coordinate
- system. @end itemize
- </remark>
- </listitem>
+ <para>
+ The problem is that there is an existing SQL function
+ <literal>Length()</literal> that calculates the length of
+ string values, and sometimes it is not possible to distinguish
+ whether the function is called in a textual or spatial
+ context. We need either to solve this somehow, or decide on
+ another function name.
+ </para>
+ </listitem>
- <listitem>
- <para>
- The OpenGIS function <literal>Length()</literal> on
- <literal>LineString</literal> and
- <literal>MultiLineString</literal> currently should be
- called in MySQL as <literal>GLength()</literal>
- </para>
+ </itemizedlist>
- <para>
- The problem is that there is an existing SQL function
- <literal>Length()</literal> which calculates the length of
- string values, and sometimes it is not possible to
- distinguish whether the function is called in a textual or
- spatial context. We need either to solve this somehow, or
- decide on another function name.
- </para>
- </listitem>
+ <remark>
+ @node GIS writing a GIS application @section Writing a GIS
+ Application @node GIS Java GIS Object Model @section Java GIS
+ Object Model
+ </remark>
- </itemizedlist>
-
- <remark>
- @node GIS writing a GIS application @section Writing a GIS
- Application @node GIS Java GIS Object Model @section Java GIS
- Object Model
- </remark>
-
- </section>
-
</section>
</chapter>
Modified: trunk/refman-5.1/renamed-nodes.txt
===================================================================
--- trunk/refman-5.1/renamed-nodes.txt 2006-01-19 15:38:42 UTC (rev 929)
+++ trunk/refman-5.1/renamed-nodes.txt 2006-01-19 15:38:54 UTC (rev 930)
@@ -102,3 +102,7 @@
charset-config-file adding-character-set
open-tables table-cache
variables user-variables
+fetching-spatial-data-in-internal-format fetching-spatial-data
+fetching-spatial-data-in-wkb-format fetching-spatial-data
+fetching-spatial-data-in-wkt-format fetching-spatial-data
+gis-features-that-are-not-yet-implemented mysql-gis-conformance-and-compatibility
Modified: trunk/refman-5.1/spatial-extensions.xml
===================================================================
--- trunk/refman-5.1/spatial-extensions.xml 2006-01-19 15:38:42 UTC (rev 929)
+++ trunk/refman-5.1/spatial-extensions.xml 2006-01-19 15:38:54 UTC (rev 930)
@@ -72,20 +72,31 @@
<para>
<emphasis role="bold">Additional resources</emphasis>
+ </para>
- <itemizedlist>
+ <itemizedlist>
- <listitem>
- <para>
- If you have questions or concerns about the use of the spatial
- extensions to MySQL, you can discuss these in the GIS forum:
- <ulink url="&base-url-forum-list;?23"/>.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ The Open Geospatial Consortium publishes the
+ <citetitle>OpenGIS® Simple Features Specifications For
+ SQL</citetitle>, a document that proposes several conceptual
+ ways for extending an SQL RDBMS to support spatial data. This
+ specification is available from the OGC Web site at
+ <ulink url="http://www.opengis.org/docs/99-049.pdf"/>.
+ </para>
+ </listitem>
- </itemizedlist>
- </para>
+ <listitem>
+ <para>
+ If you have questions or concerns about the use of the spatial
+ extensions to MySQL, you can discuss them in the GIS forum:
+ <ulink url="&base-url-forum-list;?23"/>.
+ </para>
+ </listitem>
+ </itemizedlist>
+
<section id="gis-introduction">
<title>&title-gis-introduction;</title>
@@ -104,20 +115,20 @@
<para>
MySQL implements spatial extensions following the specification of
- the <literal>Open GIS Consortium</literal> (OGC). This is an
- international consortium of more than 250 companies, agencies, and
- universities participating in the development of publicly
- available conceptual solutions that can be useful with all kinds
- of applications that manage spatial data. The OGC maintains a Web
- site at <ulink url="http://www.opengis.org/"/>.
+ the Open Geospatial Consortium (OGC). This is an international
+ consortium of more than 250 companies, agencies, and universities
+ participating in the development of publicly available conceptual
+ solutions that can be useful with all kinds of applications that
+ manage spatial data. The OGC maintains a Web site at
+ <ulink url="http://www.opengis.org/"/>.
</para>
<para>
- In 1997, the Open GIS Consortium published the
+ In 1997, the Open Geospatial Consortium published the
<citetitle>OpenGIS® Simple Features Specifications For
SQL</citetitle>, a document that proposes several conceptual ways
for extending an SQL RDBMS to support spatial data. This
- specification is available from the Open GIS Web site at
+ specification is available from the OGC Web site at
<ulink url="http://www.opengis.org/docs/99-049.pdf"/>. It contains
additional information relevant to this chapter.
</para>
@@ -127,7 +138,7 @@
Geometry Types</emphasis> environment proposed by OGC. This term
refers to an SQL environment that has been extended with a set of
geometry types. A geometry-valued SQL column is implemented as a
- column that has a geometry type. The specifications describe a set
+ column that has a geometry type. The specification describe a set
of SQL geometry types, as well as functions on those types to
create and analyze geometry values.
</para>
@@ -169,9 +180,8 @@
</indexterm>
<para>
- You can also find documents that use the term
- <emphasis role="bold">geospatial feature</emphasis> to refer to
- geographic features.
+ Some documents use the term <emphasis role="bold">geospatial
+ feature</emphasis> to refer to geographic features.
</para>
<indexterm>
@@ -191,16 +201,12 @@
<emphasis role="bold">geographic feature</emphasis>,
<emphasis role="bold">geospatial feature</emphasis>,
<emphasis role="bold">feature</emphasis>, or
- <emphasis role="bold">geometry</emphasis>. The term most commonly
- used here is <emphasis role="bold">geometry</emphasis>.
+ <emphasis role="bold">geometry</emphasis>. Here, the term most
+ commonly used is <emphasis role="bold">geometry</emphasis>,
+ defined as <emphasis>a point or an aggregate of points
+ representing anything in the world that has a location</emphasis>.
</para>
- <para>
- Let's define a <emphasis role="bold">geometry</emphasis> as
- <emphasis>a point or an aggregate of points representing anything
- in the world that has a location</emphasis>.
- </para>
-
</section>
<section id="opengis-geometry-model">
@@ -370,7 +376,7 @@
<remark role="help-description-begin"/>
<para>
- <literal>Geometry</literal> is the base class. It's an abstract
+ <literal>Geometry</literal> is the base class. It is an abstract
class. The instantiable subclasses of
<literal>Geometry</literal> are restricted to zero-, one-, and
two-dimensional geometric objects that exist in two-dimensional
@@ -461,8 +467,8 @@
It is a non-instantiable class but has a number of properties
that are common to all geometry values created from any of the
<literal>Geometry</literal> subclasses. These properties are
- described in the following list. (Particular subclasses have
- their own specific properties, described later.)
+ described in the following list. Particular subclasses have
+ their own specific properties, described later.
</para>
<para>
@@ -1424,7 +1430,7 @@
</remark>
<para>
- Examples of WKT representations of geometry objects are:
+ Examples of WKT representations of geometry objects:
</para>
<itemizedlist>
@@ -1530,7 +1536,7 @@
<para>
A Backus-Naur grammar that specifies the formal production rules
- for writing WKT values can be found in the OGC specification
+ for writing WKT values can be found in the OpenGIS specification
document referenced near the beginning of this chapter.
</para>
@@ -1550,8 +1556,8 @@
<para>
The Well-Known Binary (WKB) representation for geometric values
- is defined by the OpenGIS specifications. It is also defined in
- the ISO <quote>SQL/MM Part 3: Spatial</quote> standard.
+ is defined by the OpenGIS specification. It is also defined in
+ the ISO <citetitle>SQL/MM Part 3: Spatial</citetitle> standard.
</para>
<para>
@@ -1765,8 +1771,8 @@
<para>
<literal>GEOMETRY</literal> can store geometry values of any
- type. The other single-value types, <literal>POINT</literal> and
- <literal>LINESTRING</literal> and <literal>POLYGON</literal>,
+ type. The other single-value types (<literal>POINT</literal>,
+ <literal>LINESTRING</literal>, and <literal>POLYGON</literal>)
restrict their values to a particular geometry type.
</para>
@@ -1804,11 +1810,11 @@
<para>
<literal>GEOMETRYCOLLECTION</literal> can store a collection of
- objects of any type. The other collection types,
- <literal>MULTIPOINT</literal> and
- <literal>MULTILINESTRING</literal> and
- <literal>MULTIPOLYGON</literal> and
- <literal>GEOMETRYCOLLECTION</literal>, restrict collection
+ objects of any type. The other collection types
+ (<literal>MULTIPOINT</literal>,
+ <literal>MULTILINESTRING</literal>,
+ <literal>MULTIPOLYGON</literal>, and
+ <literal>GEOMETRYCOLLECTION</literal>) restrict collection
members to those having a particular geometry type.
</para>
@@ -2080,12 +2086,13 @@
</itemizedlist>
<para>
- The OpenGIS specification also describes optional functions
- for constructing <literal>Polygon</literal> or
+ The OpenGIS specification also defines the following optional
+ functions, which MySQL does not implement. These functions
+ construct <literal>Polygon</literal> or
<literal>MultiPolygon</literal> values based on the WKT
representation of a collection of rings or closed
<literal>LineString</literal> values. These values may
- intersect. MySQL does not implement these functions:
+ intersect.
</para>
<itemizedlist>
@@ -2442,14 +2449,15 @@
<title>&title-gis-mysql-specific-functions;</title>
<para>
- MySQL provides a set of useful functions for creating geometry
- WKB representations. The functions described in this section
- are MySQL extensions to the OpenGIS specifications. The
- results of these functions are <literal>BLOB</literal> values
- containing WKB representations of geometry values with no
- SRID. The results of these functions can be substituted as the
- first argument for any function in the
- <literal>GeomFromWKB()</literal> function family.
+ MySQL provides a set of useful non-standard functions for
+ creating geometry WKB representations. The functions described
+ in this section are MySQL extensions to the OpenGIS
+ specification. The results of these functions are
+ <literal>BLOB</literal> values containing WKB representations
+ of geometry values with no SRID. The results of these
+ functions can be substituted as the first argument for any
+ function in the <literal>GeomFromWKB()</literal> function
+ family.
</para>
<remark role="help-category" condition="Geometry constructors@Geographic Features"/>
@@ -2658,8 +2666,7 @@
<remark role="help-example"/>
<programlisting>
-mysql> <userinput>CREATE TABLE geom (g GEOMETRY);</userinput>
-Query OK, 0 rows affected (0.02 sec)
+CREATE TABLE geom (g GEOMETRY);
</programlisting>
</listitem>
@@ -2670,12 +2677,8 @@
</para>
<programlisting>
-mysql> <userinput>ALTER TABLE geom ADD pt POINT;</userinput>
-Query OK, 0 rows affected (0.00 sec)
-Records: 0 Duplicates: 0 Warnings: 0
-mysql> <userinput>ALTER TABLE geom DROP pt;</userinput>
-Query OK, 0 rows affected (0.00 sec)
-Records: 0 Duplicates: 0 Warnings: 0
+ALTER TABLE geom ADD pt POINT;
+ALTER TABLE geom DROP pt;
</programlisting>
</listitem>
@@ -2697,31 +2700,39 @@
convert them to that format from either Well-Known Text (WKT) or
Well-Known Binary (WKB) format. The following examples
demonstrate how to insert geometry values into a table by
- converting WKT values into internal geometry format.
+ converting WKT values into internal geometry format:
</para>
- <para>
- You can perform the conversion directly in the
- <literal>INSERT</literal> statement:
- </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Perform the conversion directly in the
+ <literal>INSERT</literal> statement:
+ </para>
+
<programlisting>
INSERT INTO geom VALUES (GeomFromText('POINT(1 1)'));
SET @g = 'POINT(1 1)';
INSERT INTO geom VALUES (GeomFromText(@g));
</programlisting>
+ </listitem>
- <para>
- Or you can perform the conversion prior to the
- <literal>INSERT</literal>:
- </para>
+ <listitem>
+ <para>
+ Perform the conversion prior to the
+ <literal>INSERT</literal>:
+ </para>
<programlisting>
SET @g = GeomFromText('POINT(1 1)');
INSERT INTO geom VALUES (@g);
</programlisting>
+ </listitem>
+ </itemizedlist>
+
<para>
The following examples insert more complex geometries into the
table:
@@ -2821,51 +2832,55 @@
format. You can also convert them into WKT or WKB format.
</para>
- <section id="fetching-spatial-data-in-internal-format">
+ <itemizedlist>
- <title>&title-fetching-spatial-data-in-internal-format;</title>
+ <listitem>
+ <para>
+ Fetching spatial data in internal format:
+ </para>
- <para>
- Fetching geometry values using internal format can be useful
- in table-to-table transfers:
- </para>
+ <para>
+ Fetching geometry values using internal format can be useful
+ in table-to-table transfers:
+ </para>
<programlisting>
CREATE TABLE geom2 (g GEOMETRY) SELECT g FROM geom;
</programlisting>
+ </listitem>
- </section>
+ <listitem>
+ <para>
+ Fetching spatial data in WKT format:
+ </para>
- <section id="fetching-spatial-data-in-wkt-format">
+ <para>
+ The <literal>AsText()</literal> function converts a geometry
+ from internal format into a WKT string.
+ </para>
- <title>&title-fetching-spatial-data-in-wkt-format;</title>
-
- <para>
- The <literal>AsText()</literal> function converts a geometry
- from internal format into a WKT string.
- </para>
-
<programlisting>
SELECT AsText(g) FROM geom;
</programlisting>
+ </listitem>
- </section>
+ <listitem>
+ <para>
+ Fetching spatial data in WKB format:
+ </para>
- <section id="fetching-spatial-data-in-wkb-format">
+ <para>
+ The <literal>AsBinary()</literal> function converts a
+ geometry from internal format into a <literal>BLOB</literal>
+ containing the WKB value.
+ </para>
- <title>&title-fetching-spatial-data-in-wkb-format;</title>
-
- <para>
- The <literal>AsBinary()</literal> function converts a geometry
- from internal format into a <literal>BLOB</literal> containing
- the WKB value.
- </para>
-
<programlisting>
SELECT AsBinary(g) FROM geom;
</programlisting>
+ </listitem>
- </section>
+ </itemizedlist>
</section>
@@ -3023,7 +3038,7 @@
internal geometry format and returns the result. A number of
type-specific functions are also supported, such as
<literal>PointFromText()</literal> and
- <literal>LineFromText()</literal>; see
+ <literal>LineFromText()</literal>. See
<xref linkend="gis-wkt-functions"/>.
</para>
</listitem>
@@ -3042,7 +3057,7 @@
internal geometry format and returns the result. A number of
type-specific functions are also supported, such as
<literal>PointFromWKB()</literal> and
- <literal>LineFromWKB()</literal>; see
+ <literal>LineFromWKB()</literal>. See
<xref linkend="gis-wkb-functions"/>.
</para>
</listitem>
@@ -3094,9 +3109,9 @@
<para>
Returns the inherent dimension of the geometry value
- <replaceable>g</replaceable>. The result can be −1, 0,
- 1, or 2. (The meaning of these values is given in
- <xref linkend="gis-class-geometry"/>.)
+ <replaceable>g</replaceable>. The result can be −1,
+ 0, 1, or 2. The meaning of these values is given in
+ <xref linkend="gis-class-geometry"/>.
</para>
<remark role="help-description-end"/>
@@ -3313,7 +3328,8 @@
The description of each instantiable geometric class given
earlier in the chapter includes the specific conditions
that cause an instance of that class to be classified as
- not simple.
+ not simple. (See
+ <xref linkend= "gis-geometry-class-hierarchy"/>.)
</para>
<remark role="help-description-end"/>
@@ -3359,12 +3375,13 @@
<remark role="help-example"/>
<programlisting>
-mysql> <userinput>SELECT X(GeomFromText('Point(56.7 53.34)'));</userinput>
-+--------------------------------------+
-| X(GeomFromText('Point(56.7 53.34)')) |
-+--------------------------------------+
-| 56.7 |
-+--------------------------------------+
+mysql> <userinput>SET @pt = 'Point(56.7 53.34)';</userinput>
+mysql> <userinput>SELECT X(GeomFromText(@pt));</userinput>
++----------------------+
+| X(GeomFromText(@pt)) |
++----------------------+
+| 56.7 |
++----------------------+
</programlisting>
</listitem>
@@ -3391,12 +3408,13 @@
<remark role="help-example"/>
<programlisting>
-mysql> <userinput>SELECT Y(GeomFromText('Point(56.7 53.34)'));</userinput>
-+--------------------------------------+
-| Y(GeomFromText('Point(56.7 53.34)')) |
-+--------------------------------------+
-| 53.34 |
-+--------------------------------------+
+mysql> <userinput>SET @pt = 'Point(56.7 53.34)';</userinput>
+mysql> <userinput>SELECT Y(GeomFromText(@pt));</userinput>
++----------------------+
+| Y(GeomFromText(@pt)) |
++----------------------+
+| 53.34 |
++----------------------+
</programlisting>
</listitem>
@@ -3486,6 +3504,12 @@
| 2.8284271247462 |
+----------------------------+
</programlisting>
+
+ <para>
+ <literal>GLength()</literal> is a non-standard name. It
+ corresponds to the OpenGIS <literal>Length()</literal>
+ function.
+ </para>
</listitem>
<listitem>
@@ -3502,8 +3526,8 @@
</para>
<para>
- Returns the number of points in the
- <literal>LineString</literal> value
+ Returns the number of <literal>Point</literal> objects in
+ the <literal>LineString</literal> value
<replaceable>ls</replaceable>.
</para>
@@ -3536,9 +3560,11 @@
</para>
<para>
- Returns the <replaceable>n</replaceable>-th point in the
+ Returns the <replaceable>n</replaceable>-th
+ <literal>Point</literal> in the
<literal>Linestring</literal> value
- <replaceable>ls</replaceable>. Point numbers begin at 1.
+ <replaceable>ls</replaceable>. Points are numbered
+ beginning with 1.
</para>
<remark role="help-description-end"/>
@@ -3634,6 +3660,12 @@
<itemizedlist>
<listitem>
+ <remark role="note">
+ There is no help-table markup for GLength because there is
+ another marked-up entry in the LineString functions
+ section.
+ </remark>
+
<para>
<indexterm type="function">
<primary>GLength()</primary>
@@ -3659,6 +3691,12 @@
| 4.2426406871193 |
+-----------------------------+
</programlisting>
+
+ <para>
+ <literal>GLength()</literal> is a non-standard name. It
+ corresponds to the OpenGIS <literal>Length()</literal>
+ function.
+ </para>
</listitem>
<listitem>
@@ -3677,8 +3715,8 @@
<literal>EndPoint()</literal> values are the same for each
<literal>LineString</literal> in
<replaceable>mls</replaceable>). Returns 0 if
- <replaceable>mls</replaceable> is not closed, and −1 if
- it is <literal>NULL</literal>.
+ <replaceable>mls</replaceable> is not closed, and −1
+ if it is <literal>NULL</literal>.
</para>
<programlisting>
@@ -3796,7 +3834,8 @@
Returns the <replaceable>n</replaceable>-th interior ring
for the <literal>Polygon</literal> value
<replaceable>poly</replaceable> as a
- <literal>LineString</literal>. Ring numbers begin at 1.
+ <literal>LineString</literal>. Rings are numbered
+ beginning with 1.
</para>
<remark role="help-description-end"/>
@@ -3967,8 +4006,8 @@
<para>
Returns the <replaceable>n</replaceable>-th geometry in
the <literal>GeometryCollection</literal> value
- <replaceable>gc</replaceable>. Geometry numbers begin at
- 1.
+ <replaceable>gc</replaceable>. Geometries are numbered
+ beginning with 1.
</para>
<remark role="help-description-end"/>
@@ -4039,9 +4078,9 @@
<title>&title-functions-that-produce-new-geometries;</title>
<para>
- In <xref linkend="geometry-property-functions"/>,
- we've discussed some functions that can construct new
- geometries from the existing ones:
+ <xref linkend="geometry-property-functions"/>, discusses
+ several functions that construct new geometries from existing
+ ones. See that section for descriptions of these functions:
</para>
<itemizedlist>
@@ -4270,9 +4309,10 @@
<remark role="help-category" condition="MBR@Geographic Features"/>
<para>
- MySQL provides some functions that can test relations between
+ MySQL provides several functions that test relations between
minimal bounding rectangles of two geometries
- <literal>g1</literal> and <literal>g2</literal>. They include:
+ <literal>g1</literal> and <literal>g2</literal>. The return
+ values 1 and 0 indicate true and false, respectively.
</para>
<itemizedlist>
@@ -4291,10 +4331,9 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangle of <replaceable>g1</replaceable> contains
- the Minimum Bounding Rectangle of
- <replaceable>g2</replaceable>.
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangle of <replaceable>g1</replaceable> contains the
+ Minimum Bounding Rectangle of <replaceable>g2</replaceable>.
</para>
<remark role="help-description-end"/>
@@ -4327,8 +4366,8 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangles of the two geometries
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangles of the two geometries
<replaceable>g1</replaceable> and
<replaceable>g2</replaceable> are disjoint (do not
intersect).
@@ -4351,8 +4390,8 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangles of the two geometries
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangles of the two geometries
<replaceable>g1</replaceable> and
<replaceable>g2</replaceable> are the same.
</para>
@@ -4374,8 +4413,8 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangles of the two geometries
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangles of the two geometries
<replaceable>g1</replaceable> and
<replaceable>g2</replaceable> intersect.
</para>
@@ -4397,8 +4436,8 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangles of the two geometries
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangles of the two geometries
<replaceable>g1</replaceable> and
<replaceable>g2</replaceable> overlap.
</para>
@@ -4420,8 +4459,8 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangles of the two geometries
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangles of the two geometries
<replaceable>g1</replaceable> and
<replaceable>g2</replaceable> touch.
</para>
@@ -4443,10 +4482,9 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the Minimum
- Bounding Rectangle of <replaceable>g1</replaceable> is
- within the Minimum Bounding Rectangle of
- <replaceable>g2</replaceable>.
+ Returns 1 or 0 to indicate whether the Minimum Bounding
+ Rectangle of <replaceable>g1</replaceable> is within the
+ Minimum Bounding Rectangle of <replaceable>g2</replaceable>.
</para>
<remark role="help-description-end"/>
@@ -4474,10 +4512,15 @@
<title>&title-functions-that-test-spatial-relationships-between-geometries;</title>
<para>
- The OpenGIS specification defines the following functions.
- Currently, MySQL does not implement them according to the
- specification. Those that are implemented return the same result
- as the corresponding MBR-based functions. This includes
+ The OpenGIS specification defines the following functions. They
+ test the relationship between two geometry values
+ <literal>g1</literal> and <literal>g2</literal>.
+ </para>
+
+ <para>
+ Currently, MySQL does not implement these functions according to
+ the specification. Those that are implemented return the same
+ result as the corresponding MBR-based functions. This includes
functions in the following list other than
<literal>Distance()</literal> and <literal>Related()</literal>.
</para>
@@ -4493,8 +4536,7 @@
</para>
<para>
- The functions operate on two geometry values
- <literal>g1</literal> and <literal>g2</literal>.
+ The return values 1 and 0 indicate true and false, respectively.
</para>
<remark role="help-category" condition="Geometry relations@Geographic Features"/>
@@ -4515,7 +4557,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> completely contains
<replaceable>g2</replaceable>.
</para>
@@ -4594,7 +4636,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> is spatially disjoint from
(does not intersect) <replaceable>g2</replaceable>.
</para>
@@ -4636,7 +4678,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> is spatially equal to
<replaceable>g2</replaceable>.
</para>
@@ -4658,7 +4700,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> spatially intersects
<replaceable>g2</replaceable>.
</para>
@@ -4680,7 +4722,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> spatially overlaps
<replaceable>g2</replaceable>. The term <emphasis>spatially
overlaps</emphasis> is used if two geometries intersect and
@@ -4706,14 +4748,13 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not the spatial
- relationship specified by
- <replaceable>pattern_matrix</replaceable> exists between
- <replaceable>g1</replaceable> and
- <replaceable>g2</replaceable>. Returns −1 if the arguments
- are <literal>NULL</literal>. The pattern matrix is a string.
- Its specification will be noted here if this function is
- implemented.
+ Returns 1 or 0 to indicate whether the spatial relationship
+ specified by <replaceable>pattern_matrix</replaceable>
+ exists between <replaceable>g1</replaceable> and
+ <replaceable>g2</replaceable>. Returns −1 if the
+ arguments are <literal>NULL</literal>. The pattern matrix is
+ a string. Its specification will be noted here if this
+ function is implemented.
</para>
</listitem>
@@ -4731,7 +4772,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> spatially touches
<replaceable>g2</replaceable>. Two geometries
<emphasis>spatially touch</emphasis> if the interiors of the
@@ -4757,7 +4798,7 @@
</para>
<para>
- Returns 1 or 0 to indicate whether or not
+ Returns 1 or 0 to indicate whether
<replaceable>g1</replaceable> is spatially within
<replaceable>g2</replaceable>.
</para>
@@ -4834,10 +4875,10 @@
<para>
MySQL can create spatial indexes using syntax similar to that
for creating regular indexes, but extended with the
- <literal>SPATIAL</literal> keyword. Spatial columns that are
- indexed currently must be declared <literal>NOT NULL</literal>.
+ <literal>SPATIAL</literal> keyword. Currently, spatial columns
+ that are indexed must be declared <literal>NOT NULL</literal>.
The following examples demonstrate how to create spatial
- indexes.
+ indexes:
</para>
<itemizedlist>
@@ -4848,7 +4889,7 @@
</para>
<programlisting>
-mysql> <userinput>CREATE TABLE geom (g GEOMETRY NOT NULL, SPATIAL INDEX(g));</userinput>
+CREATE TABLE geom (g GEOMETRY NOT NULL, SPATIAL INDEX(g));
</programlisting>
</listitem>
@@ -4858,7 +4899,7 @@
</para>
<programlisting>
-mysql> <userinput>ALTER TABLE geom ADD SPATIAL INDEX(g);</userinput>
+ALTER TABLE geom ADD SPATIAL INDEX(g);
</programlisting>
</listitem>
@@ -4868,7 +4909,7 @@
</para>
<programlisting>
-mysql> <userinput>CREATE SPATIAL INDEX sp_index ON geom (g);</userinput>
+CREATE SPATIAL INDEX sp_index ON geom (g);
</programlisting>
</listitem>
@@ -4877,7 +4918,7 @@
<para>
For <literal>MyISAM</literal> tables, <literal>SPATIAL
INDEX</literal> creates an R-tree index. For other storage
- engines that support spatial index, <literal>SPATIAL
+ engines that support spatial indexing, <literal>SPATIAL
INDEX</literal> creates a B-tree index. A B-tree index on
spatial values will be useful for exact-value lookups, but not
for range scans.
@@ -4896,7 +4937,7 @@
</para>
<programlisting>
-mysql> <userinput>ALTER TABLE geom DROP INDEX g;</userinput>
+ALTER TABLE geom DROP INDEX g;
</programlisting>
</listitem>
@@ -4906,7 +4947,7 @@
</para>
<programlisting>
-mysql> <userinput>DROP INDEX sp_index ON geom;</userinput>
+DROP INDEX sp_index ON geom;
</programlisting>
</listitem>
@@ -4963,13 +5004,15 @@
be involved in the search for queries that use a function such
as <literal>MBRContains()</literal> or
<literal>MBRWithin()</literal> in the <literal>WHERE</literal>
- clause. For example, let's say we want to find all objects that
- are in the given rectangle:
+ clause. The following query finds all objects that are in the
+ given rectangle:
</para>
<programlisting>
+mysql> <userinput>SET @poly =</userinput>
+ -> <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
mysql> <userinput>SELECT fid,AsText(g) FROM geom WHERE</userinput>
-mysql> <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
+ -> <userinput>MBRContains(GeomFromText(@poly),g);</userinput>
+-----+-----------------------------------------------------------------------------+
| fid | AsText(g) |
+-----+-----------------------------------------------------------------------------+
@@ -4998,45 +5041,64 @@
</programlisting>
<para>
- Let's use <literal>EXPLAIN</literal> to check the way this query
- is executed (the <literal>id</literal> column has been removed
- so the output better fits the page):
+ Use <literal>EXPLAIN</literal> to check the way this query is
+ executed (the <literal>id</literal> column has been removed so
+ the output better fits the page):
</para>
<programlisting>
+mysql> <userinput>SET @poly =</userinput>
+ -> <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
mysql> <userinput>EXPLAIN SELECT fid,AsText(g) FROM geom WHERE</userinput>
-mysql> <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
-| select_type | table | type | possible_keys | key | key_len | ref | rows | Extra |
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
-| SIMPLE | geom | range | g | g | 32 | NULL | 50 | Using where |
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
+ -> <userinput>MBRContains(GeomFromText(@poly),g)\G</userinput>
+*************************** 1. row ***************************
+ id: 1
+ select_type: SIMPLE
+ table: geom
+ type: range
+possible_keys: g
+ key: g
+ key_len: 32
+ ref: NULL
+ rows: 50
+ Extra: Using where
1 row in set (0.00 sec)
</programlisting>
<para>
- Let's check what would happen without a spatial index:
+ Check what would happen without a spatial index:
</para>
<programlisting>
+mysql> <userinput>SET @poly =</userinput>
+ -> <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
mysql> <userinput>EXPLAIN SELECT fid,AsText(g) FROM g IGNORE INDEX (g) WHERE</userinput>
-mysql> <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
-| select_type | table | type | possible_keys | key | key_len | ref | rows | Extra |
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
-| SIMPLE | geom | ALL | NULL | NULL | NULL | NULL | 32376 | Using where |
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
+ -> <userinput>MBRContains(GeomFromText(@poly),g)\G</userinput>
+*************************** 1. row ***************************
+ id: 1
+ select_type: SIMPLE
+ table: geom
+ type: ALL
+possible_keys: NULL
+ key: NULL
+ key_len: NULL
+ ref: NULL
+ rows: 32376
+ Extra: Using where
1 row in set (0.00 sec)
</programlisting>
<para>
- Let's execute the <literal>SELECT</literal> statement, ignoring
- the spatial key we have:
+ Executing the <literal>SELECT</literal> statement without the
+ spatial index yields the same result but causes the execution
+ time to rise from 0.00 seconds to 0.46 seconds:
</para>
<programlisting>
+mysql> <userinput>SET @poly =</userinput>
+ -> <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
mysql> <userinput>SELECT fid,AsText(g) FROM geom IGNORE INDEX (g) WHERE</userinput>
-mysql> <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
+ -> <userinput>MBRContains(GeomFromText(@poly),g);</userinput>
+-----+-----------------------------------------------------------------------------+
| fid | AsText(g) |
+-----+-----------------------------------------------------------------------------+
@@ -5065,11 +5127,6 @@
</programlisting>
<para>
- When the index is not used, the execution time for this query
- rises from 0.00 seconds to 0.46 seconds.
- </para>
-
- <para>
In future releases, spatial indexes may also be used for
optimizing other functions. See
<xref linkend="functions-for-testing-spatial-relations-between-geometric-objects"/>.
@@ -5083,72 +5140,65 @@
<title>&title-mysql-gis-conformance-and-compatibility;</title>
- <remark role="todo">
- Add introductory descriptive sentence.
- </remark>
+ <para>
+ MySQL does not yet implement the following GIS features:
+ </para>
- <section id="gis-features-that-are-not-yet-implemented">
+ <itemizedlist>
- <title>&title-gis-features-that-are-not-yet-implemented;</title>
+ <listitem>
+ <para>
+ Additional Metadata Views
+ </para>
- <itemizedlist>
+ <para>
+ OpenGIS specifications propose several additional metadata
+ views. For example, a system view named
+ <literal>GEOMETRY_COLUMNS</literal> contains a description of
+ geometry columns, one row for each geometry column in the
+ database.
+ </para>
- <listitem>
- <para>
- Additional Metadata Views
- </para>
+ <remark>
+ @item Functions to add/drop spatial columns OpenGIS assumes
+ that columns can be added or dropped using special
+ @code{AddGeometryColumn()} and @code{DropGeometryColumn()}
+ functions. In MySQL, this is done using the @code{ALTER
+ TABLE}, @code{CREATE INDEX}, and @code{DROP INDEX} statements
+ instead. @item Factors related to Spatial Reference Systems
+ and their IDs (SRIDs): @itemize @bullet @item Functions like
+ @code{Length()} and @code{Area()} assume a planar coordinate
+ system. @item All objects currently are considered to be in
+ the same planar coordinate system. @end itemize
+ </remark>
+ </listitem>
- <para>
- OpenGIS specifications propose several additional metadata
- views. For example, a system view named
- <literal>GEOMETRY_COLUMNS</literal> contains a description
- of geometry columns, one row for each geometry column in the
- database.
- </para>
+ <listitem>
+ <para>
+ The OpenGIS function <literal>Length()</literal> on
+ <literal>LineString</literal> and
+ <literal>MultiLineString</literal> currently should be called
+ in MySQL as <literal>GLength()</literal>
+ </para>
- <remark>
- @item Functions to add/drop spatial columns OpenGIS assumes
- that columns can be added or dropped using special
- @code{AddGeometryColumn()} and @code{DropGeometryColumn()}
- functions. In MySQL, this is done using the @code{ALTER
- TABLE}, @code{CREATE INDEX}, and @code{DROP INDEX}
- statements instead. @item Factors related to Spatial
- Reference Systems and their IDs (SRIDs): @itemize @bullet
- @item Functions like @code{Length()} and @code{Area()}
- assume a planar coordinate system. @item All objects
- currently are considered to be in the same planar coordinate
- system. @end itemize
- </remark>
- </listitem>
+ <para>
+ The problem is that there is an existing SQL function
+ <literal>Length()</literal> that calculates the length of
+ string values, and sometimes it is not possible to distinguish
+ whether the function is called in a textual or spatial
+ context. We need either to solve this somehow, or decide on
+ another function name.
+ </para>
+ </listitem>
- <listitem>
- <para>
- The OpenGIS function <literal>Length()</literal> on
- <literal>LineString</literal> and
- <literal>MultiLineString</literal> currently should be
- called in MySQL as <literal>GLength()</literal>
- </para>
+ </itemizedlist>
- <para>
- The problem is that there is an existing SQL function
- <literal>Length()</literal> which calculates the length of
- string values, and sometimes it is not possible to
- distinguish whether the function is called in a textual or
- spatial context. We need either to solve this somehow, or
- decide on another function name.
- </para>
- </listitem>
+ <remark>
+ @node GIS writing a GIS application @section Writing a GIS
+ Application @node GIS Java GIS Object Model @section Java GIS
+ Object Model
+ </remark>
- </itemizedlist>
-
- <remark>
- @node GIS writing a GIS application @section Writing a GIS
- Application @node GIS Java GIS Object Model @section Java GIS
- Object Model
- </remark>
-
- </section>
-
</section>
</chapter>
Modified: trunk/refman-common/titles.en.ent
===================================================================
--- trunk/refman-common/titles.en.ent 2006-01-19 15:38:42 UTC (rev 929)
+++ trunk/refman-common/titles.en.ent 2006-01-19 15:38:54 UTC (rev 930)
@@ -379,9 +379,6 @@
<!ENTITY title-federated-use "How to use <literal>FEDERATED</literal> Tables">
<!ENTITY title-fetch "Cursor <literal>FETCH</literal> Statement">
<!ENTITY title-fetching-spatial-data "Fetching Spatial Data">
-<!ENTITY title-fetching-spatial-data-in-internal-format "Fetching Spatial Data in Internal Format">
-<!ENTITY title-fetching-spatial-data-in-wkb-format "Fetching Spatial Data in WKB Format">
-<!ENTITY title-fetching-spatial-data-in-wkt-format "Fetching Spatial Data in WKT Format">
<!ENTITY title-file-permissions "Problems with File Permissions">
<!ENTITY title-file-space-management "<literal>InnoDB</literal> File Space Management and Disk I/O">
<!ENTITY title-flow-control-constructs "Flow Control Constructs">
@@ -425,7 +422,6 @@
<!ENTITY title-gis-class-point "Class <literal>Point</literal>">
<!ENTITY title-gis-class-polygon "Class <literal>Polygon</literal>">
<!ENTITY title-gis-class-surface "Class <literal>Surface</literal>">
-<!ENTITY title-gis-features-that-are-not-yet-implemented "GIS Features That Are Not Yet Implemented">
<!ENTITY title-gis-geometry-class-hierarchy "The Geometry Class Hierarchy">
<!ENTITY title-gis-introduction "Introduction to MySQL Spatial Support">
<!ENTITY title-gis-mysql-specific-functions "Creating Geometry Values Using MySQL-Specific Functions">
@@ -1251,7 +1247,7 @@
<!ENTITY title-news-5-1-2 "Changes in release 5.1.2 (Not released)">
<!ENTITY title-news-5-1-3 "Changes in release 5.1.3 (29 November 2005)">
<!ENTITY title-news-5-1-4 "Changes in release 5.1.4 (21 December 2005)">
-<!ENTITY title-news-5-1-5 "Changes in release 5.1.5 (Not yet released)">
+<!ENTITY title-news-5-1-5 "Changes in release 5.1.5 (10 January 2006)">
<!ENTITY title-news-5-1-6 "Changes in release 5.1.6 (Not yet released)">
<!ENTITY title-news-5-1-x "Changes in release 5.1.x (Development)">
<!ENTITY title-no-matching-rows "Solving Problems with No Matching Rows">
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r930 - in trunk: . refman-4.1 refman-5.0 refman-5.1 refman-common | paul | 19 Jan |
