Oracle® Spatial Developer's Guide 11g Release 1 (11.1) Part Number B2840001 


View PDF 
Oracle Spatial is an integrated set of functions and procedures that enables spatial data to be stored, accessed, and analyzed quickly and efficiently in an Oracle database.
Spatial data represents the essential location characteristics of real or conceptual objects as those objects relate to the real or conceptual space in which they exist.
This chapter contains the following major sections:
Section 1.13, "Spatial Java Application Programming Interface"
Section 1.16, "Open Geospatial Consortium (OGC) Conformance"
Section 1.18, "Spatial Application Hardware Requirement Considerations"
Section 1.21, "README File for Spatial and Related Features"
Oracle Spatial, often referred to as Spatial, provides a SQL schema and functions that facilitate the storage, retrieval, update, and query of collections of spatial features in an Oracle database. Spatial consists of the following:
A schema (MDSYS) that prescribes the storage, syntax, and semantics of supported geometric data types
A spatial indexing mechanism
Operators, functions, and procedures for performing areaofinterest queries, spatial join queries, and other spatial analysis operations
Functions and procedures for utility and tuning operations
Topology data model for working with data about nodes, edges, and faces in a topology (described in Oracle Spatial Topology and Network Data Models Developer's Guide).
Network data model for representing capabilities or objects that are modeled as nodes and links in a network (described in Oracle Spatial Topology and Network Data Models Developer's Guide).
GeoRaster, a feature that lets you store, index, query, analyze, and deliver GeoRaster data, that is, raster image and gridded data and its associated metadata (described in Oracle Spatial GeoRaster Developer's Guide).
The spatial component of a spatial feature is the geometric representation of its shape in some coordinate space. This is referred to as its geometry.
Caution:
Do not modify any packages, tables, or other objects under the MDSYS schema. (The only exception is if you need to create a userdefined coordinate reference system, as explained in Section 6.9.)Spatial supports the objectrelational model for representing geometries. This model stores an entire geometry in the Oracle native spatial data type for vector data, SDO_GEOMETRY. An Oracle table can contain one or more SDO_GEOMETRY columns. The objectrelational model corresponds to a "SQL with Geometry Types" implementation of spatial feature tables in the Open GIS ODBC/SQL specification for geospatial features.
The benefits provided by the objectrelational model include:
Support for many geometry types, including arcs, circles, compound polygons, compound line strings, and optimized rectangles
Ease of use in creating and maintaining indexes and in performing spatial queries
Index maintenance by the Oracle database
Geometries modeled in a single column
Optimal performance
Oracle Spatial is designed to make spatial data management easier and more natural to users of locationenabled applications and geographic information system (GIS) applications. Once spatial data is stored in an Oracle database, it can be easily manipulated, retrieved, and related to all other data stored in the database.
A common example of spatial data can be seen in a road map. A road map is a twodimensional object that contains points, lines, and polygons that can represent cities, roads, and political boundaries such as states or provinces. A road map is a visualization of geographic information. The location of cities, roads, and political boundaries that exist on the surface of the Earth are projected onto a twodimensional display or piece of paper, preserving the relative positions and relative distances of the rendered objects.
The data that indicates the Earth location (such as longitude and latitude) of these rendered objects is the spatial data. When the map is rendered, this spatial data is used to project the locations of the objects on a twodimensional piece of paper. A GIS is often used to store, retrieve, and render this Earthrelative spatial data.
Types of spatial data (other than GIS data) that can be stored using Spatial include data from computeraided design (CAD) and computeraided manufacturing (CAM) systems. Instead of operating on objects on a geographic scale, CAD/CAM systems work on a smaller scale, such as for an automobile engine or printed circuit boards.
The differences among these systems are in the size and precision of the data, not the data's complexity. The systems might all involve the same number of data points. On a geographic scale, the location of a bridge can vary by a few tenths of an inch without causing any noticeable problems to the road builders, whereas if the diameter of an engine's pistons is off by a few tenths of an inch, the engine will not run.
In addition, the complexity of data is independent of the absolute scale of the area being represented. For example, a printed circuit board is likely to have many thousands of objects etched on its surface, containing in its small area information that may be more complex than the details shown on a road builder's blueprints.
These applications all store, retrieve, update, or query some collection of features that have both nonspatial and spatial attributes. Examples of nonspatial attributes are name, soil_type, landuse_classification, and part_number. The spatial attribute is a coordinate geometry, or vectorbased representation of the shape of the feature.
A geometry is an ordered sequence of vertices that are connected by straight line segments or circular arcs. The semantics of the geometry are determined by its type. Spatial supports several primitive types, and geometries composed of collections of these types, including twodimensional:
Points and point clusters
Line strings
npoint polygons
Arc line strings (All arcs are generated as circular arcs.)
Arc polygons
Compound polygons
Compound line strings
Circles
Optimized rectangles
Twodimensional points are elements composed of two ordinates, X and Y, often corresponding to longitude and latitude. Line strings are composed of one or more pairs of points that define line segments. Polygons are composed of connected line strings that form a closed ring, and the area of the polygon is implied. For example, a point might represent a building location, a line string might represent a road or flight path, and a polygon might represent a state, city, zoning district, or city block.
Selfcrossing polygons are not supported, although selfcrossing line strings are supported. If a line string crosses itself, it does not become a polygon. A selfcrossing line string does not have any implied area.
Figure 11 illustrates the geometric types.
Spatial also supports the storage and indexing of threedimensional and fourdimensional geometric types, where three or four coordinates are used to define each vertex of the object being defined. For information about support for threedimensional geometries, see Section 1.11.
The Spatial data model is a hierarchical structure consisting of elements, geometries, and layers. Layers are composed of geometries, which in turn are made up of elements.
An element is the basic building block of a geometry. The supported spatial element types are points, line strings, and polygons. For example, elements might model star constellations (point clusters), roads (line strings), and county boundaries (polygons). Each coordinate in an element is stored as an X,Y pair. The exterior ring and zero or more interior rings (holes) of a complex polygon are considered a single element.
Point data consists of one coordinate. Line data consists of two coordinates representing a line segment of the element. Polygon data consists of coordinate pair values, one vertex pair for each line segment of the polygon. Coordinates are defined in order around the polygon (counterclockwise for an exterior polygon ring, clockwise for an interior polygon ring).
A geometry (or geometry object) is the representation of a spatial feature, modeled as an ordered set of primitive elements. A geometry can consist of a single element, which is an instance of one of the supported primitive types, or a homogeneous or heterogeneous collection of elements. A multipolygon, such as one used to represent a set of islands, is a homogeneous collection. A heterogeneous collection is one in which the elements are of different types, for example, a point and a polygon.
An example of a geometry might describe the buildable land in a town. This could be represented as a polygon with holes where water or zoning prevents construction.
A layer is a collection of geometries having the same attribute set. For example, one layer in a GIS might include topographical features, while another describes population density, and a third describes the network of roads and bridges in the area (lines and points). The geometries and associated spatial index for each layer are stored in the database in standard tables.
A coordinate system (also called a spatial reference system) is a means of assigning coordinates to a location and establishing relationships between sets of such coordinates. It enables the interpretation of a set of coordinates as a representation of a position in a real world space.
Any spatial data has a coordinate system associated with it. The coordinate system can be georeferenced (related to a specific representation of the Earth) or not georeferenced (that is, Cartesian, and not related to a specific representation of the Earth). If the coordinate system is georeferenced, it has a default unit of measurement (such as meters) associated with it, but you can have Spatial automatically return results in another specified unit (such as miles). (For more information about unit of measurement support, see Section 2.10.)
Spatial data can be associated with a Cartesian, geodetic (geographical), projected, or local coordinate system:
Cartesian coordinates are coordinates that measure the position of a point from a defined origin along axes that are perpendicular in the represented twodimensional or threedimensional space.
If a coordinate system is not explicitly associated with a geometry, a Cartesian coordinate system is assumed.
Geodetic coordinates (sometimes called geographic coordinates) are angular coordinates (longitude and latitude), closely related to spherical polar coordinates, and are defined relative to a particular Earth geodetic datum. (A geodetic datum is a means of representing the figure of the Earth and is the reference for the system of geodetic coordinates.)
Projected coordinates are planar Cartesian coordinates that result from performing a mathematical mapping from a point on the Earth's surface to a plane. There are many such mathematical mappings, each used for a particular purpose.
Local coordinates are Cartesian coordinates in a nonEarth (nongeoreferenced) coordinate system. Local coordinate systems are often used for CAD applications and local surveys.
When performing operations on geometries, Spatial uses either a Cartesian or curvilinear computational model, as appropriate for the coordinate system associated with the spatial data.
For more information about coordinate system support in Spatial, including geodetic, projected, and local coordinates and coordinate system transformation, see Chapter 6.
Tolerance is used to associate a level of precision with spatial data. Tolerance reflects the distance that two points can be apart and still be considered the same (for example, to accommodate rounding errors). The tolerance value must be a positive number greater than zero. The significance of the value depends on whether or not the spatial data is associated with a geodetic coordinate system. (Geodetic and other types of coordinate systems are described in Section 1.5.4.)
For geodetic data (such as data identified by longitude and latitude coordinates), the tolerance value is a number of meters. For example, a tolerance value of 100 indicates a tolerance of 100 meters. The tolerance value for geodetic data should not be smaller than 0.05 (5 centimeters), and in most cases it should be larger. Spatial uses 0.05 as the tolerance value for geodetic data if you specify a smaller value.
For nongeodetic data, the tolerance value is a number of the units that are associated with the coordinate system associated with the data. For example, if the unit of measurement is miles, a tolerance value of 0.005 indicates a tolerance of 0.005 (that is, 1/200) mile (approximately 26 feet), and a tolerance value of 2 indicates a tolerance of 2 miles.
In both cases, the smaller the tolerance value, the more precision is to be associated with the data.
A tolerance value is specified in two cases:
In the geometry metadata definition for a layer (see Section 1.5.5.1)
As an input parameter to certain functions (see Section 1.5.5.2)
For additional information about tolerance with linear referencing system (LRS) data, see Section 7.6.
The dimensional information for a layer includes a tolerance value. Specifically, the DIMINFO column (described in Section 2.8.3) of the xxx_SDO_GEOM_METADATA views includes an SDO_TOLERANCE value for each dimension, and the value should be the same for each dimension.
If a function accepts an optional tolerance
parameter and this parameter is null or not specified, the SDO_TOLERANCE value of the layer is used. Using the nongeodetic data from the example in Section 2.1, the actual distance between geometries cola_b
and cola_d
is 0.846049894. If a query uses the SDO_GEOM.SDO_DISTANCE function to return the distance between cola_b
and cola_d
and does not specify a tolerance
parameter value, the result depends on the SDO_TOLERANCE value of the layer. For example:
If the SDO_TOLERANCE value of the layer is 0.005, this query returns .846049894.
If the SDO_TOLERANCE value of the layer is 0.5, this query returns 0.
The zero result occurs because Spatial first constructs an imaginary buffer of the tolerance value (0.5) around each geometry to be considered, and the buffers around cola_b
and cola_d
overlap in this case.
You can, therefore, take either of two approaches in selecting an SDO_TOLERANCE value for a layer:
The value can reflect the desired level of precision in queries for distances between objects. For example, if two nongeodetic geometries 0.8 units apart should be considered as separated, specify a small SDO_TOLERANCE value such as 0.05 or smaller.
The value can reflect the precision of the values associated with geometries in the layer. For example, if all geometries in a nongeodetic layer are defined using integers and if two objects 0.8 units apart should not be considered as separated, an SDO_TOLERANCE value of 0.5 is appropriate. To have greater precision in any query, you must override the default by specifying the tolerance
parameter.
With nongeodetic data, the guideline to follow for most instances of the second case (precision of the values of the geometries in the layer) is: take the highest level of precision in the geometry definitions, and use .5 at the next level as the SDO_TOLERANCE value. For example, if geometries are defined using integers (as in the simplified example in Section 2.1), the appropriate value is 0.5; however, if geometries are defined using numbers up to four decimal positions (for example, 31.2587), the appropriate value is 0.00005.
Note:
This guideline should not be used if the geometries include any polygons that are so narrow at any point that the distance between facing sides is less than the proposed tolerance value. Be sure that the tolerance value is less than the shortest distance between any two sides in any polygon.Moreover, if you encounter "invalid geometry" errors with inserted or updated geometries, and if the geometries are in fact valid, consider increasing the precision of the tolerance value (for example, changing 0.00005 to 0.000005).
Many Spatial functions accept a tolerance
parameter, which (if specified) overrides the default tolerance value for the layer (explained in Section 1.5.5.1). If the distance between two points is less than or equal to the tolerance value, Spatial considers the two points to be a single point. Thus, tolerance is usually a reflection of how accurate or precise users perceive their spatial data to be.
For example, assume that you want to know which restaurants are within 5 kilometers of your house. Assume also that Maria's Pizzeria is 5.1 kilometers from your house. If the spatial data has a geodetic coordinate system and if you ask, Find all restaurants within 5 kilometers and use a tolerance of 100 (or greater, such as 500), Maria's Pizzeria will be included, because 5.1 kilometers (5100 meters) is within 100 meters of 5 kilometers (5000 meters). However, if you specify a tolerance less than 100 (such as 50), Maria's Pizzeria will not be included.
Tolerance values for Spatial functions are typically very small, although the best value in each case depends on the kinds of applications that use or will use the data.
Spatial uses a twotier query model to resolve spatial queries and spatial joins. The term is used to indicate that two distinct operations are performed to resolve queries. The output of the two combined operations yields the exact result set.
The two operations are referred to as primary and secondary filter operations.
The primary filter permits fast selection of candidate records to pass along to the secondary filter. The primary filter compares geometry approximations to reduce computation complexity and is considered a lowercost filter. Because the primary filter compares geometric approximations, it returns a superset of the exact result set.
The secondary filter applies exact computations to geometries that result from the primary filter. The secondary filter yields an accurate answer to a spatial query. The secondary filter operation is computationally expensive, but it is only applied to the primary filter results, not the entire data set.
Figure 12 illustrates the relationship between the primary and secondary filters.
As shown in Figure 12, the primary filter operation on a large input data set produces a smaller candidate set, which contains at least the exact result set and may contain more records. The secondary filter operation on the smaller candidate set produces the exact result set.
Spatial uses a spatial index to implement the primary filter. Spatial does not require the use of both the primary and secondary filters. In some cases, just using the primary filter is sufficient. For example, a zoom feature in a mapping application queries for data that has any interaction with a rectangle representing visible boundaries. The primary filter very quickly returns a superset of the query. The mapping application can then apply clipping routines to display the target area.
The purpose of the primary filter is to quickly create a subset of the data and reduce the processing burden on the secondary filter. The primary filter, therefore, should be as efficient (that is, selective yet fast) as possible. This is determined by the characteristics of the spatial index on the data.
For more information about querying spatial data, see Section 5.2.
The introduction of spatial indexing capabilities into the Oracle database engine is a key feature of the Spatial product. A spatial index, like any other index, provides a mechanism to limit searches, but in this case the mechanism is based on spatial criteria such as intersection and containment. A spatial index is needed to:
Find objects within an indexed data space that interact with a given point or area of interest (window query)
Find pairs of objects from within two indexed data spaces that interact spatially with each other (spatial join)
A spatial index is considered a logical index. The entries in the spatial index are dependent on the location of the geometries in a coordinate space, but the index values are in a different domain. Index entries may be ordered using a linearly ordered domain, and the coordinates for a geometry may be pairs of integer, floatingpoint, or doubleprecision numbers.
Testing of spatial indexes with many workloads and operators is ongoing, and results and recommendations will be documented as they become available.
The following sections explain the concepts and options associated with Rtree indexing.
A spatial Rtree index can index spatial data of up to four dimensions. An Rtree index approximates each geometry by a single rectangle that minimally encloses the geometry (called the minimum bounding rectangle, or MBR), as shown in Figure 13.
For a layer of geometries, an Rtree index consists of a hierarchical index on the MBRs of the geometries in the layer, as shown in Figure 14.
Figure 14 RTree Hierarchical Index on MBRs
In Figure 14:
1 through 9 are geometries in a layer.
a, b, c, and d are the leaf nodes of the Rtree index, and contain minimum bounding rectangles of geometries, along with pointers to the geometries. For example, a contains the MBR of geometries 1 and 2, b contains the MBR of geometries 3 and 4, and so on.
A contains the MBR of a and b, and B contains the MBR of c and d.
The root contains the MBR of A and B (that is, the entire area shown).
An Rtree index is stored in the spatial index table (SDO_INDEX_TABLE in the USER_SDO_INDEX_METADATA view, described in Section 2.9). The Rtree index also maintains a sequence object (SDO_RTREE_SEQ_NAME in the USER_SDO_INDEX_METADATA view) to ensure that simultaneous updates by concurrent users can be made to the index.
A substantial number of insert and delete operations affecting an Rtree index may degrade the quality of the Rtree structure, which may adversely affect query performance.
The Rtree is a hierarchical tree structure with nodes at different heights of the tree. The performance of an Rtree index structure for queries is roughly proportional to the area and perimeter of the index nodes of the Rtree. The area covered at level 0 represents the area occupied by the minimum bounding rectangles of the data geometries, the area at level 1 indicates the area covered by leaflevel Rtree nodes, and so on. The original ratio of the area at the root (topmost level) to the area at level 0 can change over time based on updates to the table; and if there is a degradation in that ratio (that is, if it increases significantly), rebuilding the index may help the performance of queries.
If the performance of SDO_FILTER operations has degraded, and if there have been a large number of insert, update, or delete operations affecting geometries, the performance degradation may be due to a degradation in the quality of the associated Rtree index. You can check for degradation of index quality by using the SDO_TUNE.QUALITY_DEGRADATION function (described in Chapter 31); and if the function returns a number greater than 2, consider rebuilding the index. Note, however, that the Rtree index quality degradation number may not be significant in terms of overall query performance due to Oracle caching strategies and other significant Oracle capabilities, such as table pinning, which can essentially remove I/O overhead from Rtree index queries.
To rebuild an Rtree index, use the ALTER INDEX REBUILD statement, which is described in Chapter 18.
Spatial uses secondary filters to determine the spatial relationship between entities in the database. The spatial relationship is based on geometry locations. The most common spatial relationships are based on topology and distance. For example, the boundary of an area consists of a set of curves that separates the area from the rest of the coordinate space. The interior of an area consists of all points in the area that are not on its boundary. Given this, two areas are said to be adjacent if they share part of a boundary but do not share any points in their interior.
The distance between two spatial objects is the minimum distance between any points in them. Two objects are said to be within a given distance of one another if their distance is less than the given distance.
To determine spatial relationships, Spatial has several secondary filter methods:
The SDO_RELATE operator evaluates topological criteria.
The SDO_WITHIN_DISTANCE operator determines if two spatial objects are within a specified distance of each other.
The SDO_NN operator identifies the nearest neighbors for a spatial object.
The syntax of these operators is given in Chapter 19.
The SDO_RELATE operator implements a nineintersection model for categorizing binary topological relationships between points, lines, and polygons. Each spatial object has an interior, a boundary, and an exterior. The boundary consists of points or lines that separate the interior from the exterior. The boundary of a line string consists of its end points; however, if the end points overlap (that is, if they are the same point), the line string has no boundary. The boundaries of a multiline string are the end points of each of the component line strings; however, if the end points overlap, only the end points that overlap an odd number of times are boundaries. The boundary of a polygon is the line that describes its perimeter. The interior consists of points that are in the object but not on its boundary, and the exterior consists of those points that are not in the object.
Given that an object A has three components (a boundary Ab, an interior Ai, and an exterior Ae), any pair of objects has nine possible interactions between their components. Pairs of components have an empty (0) or not empty (1) set intersection. The set of interactions between two geometries is represented by a nineintersection matrix that specifies which pairs of components intersect and which do not. Figure 15 shows the nineintersection matrix for two polygons that are adjacent to one another. This matrix yields the following bit mask, generated in rowmajor form: "101001111".
Some of the topological relationships identified in the seminal work by Professor Max Egenhofer (University of Maine, Orono) and colleagues have names associated with them. Spatial uses the following names:
TOUCH: The boundaries intersect but the interiors do not intersect.
OVERLAPBDYDISJOINT: The interior of one object intersects the boundary and interior of the other object, but the two boundaries do not intersect. This relationship occurs, for example, when a line originates outside a polygon and ends inside that polygon.
OVERLAPBDYINTERSECT: The boundaries and interiors of the two objects intersect.
CONTAINS: The interior and boundary of one object is completely contained in the interior of the other object.
COVERS: The interior of one object is completely contained in the interior or the boundary of the other object and their boundaries intersect.
INSIDE: The opposite of CONTAINS. A INSIDE B implies B CONTAINS A.
COVEREDBY: The opposite of COVERS. A COVEREDBY B implies B COVERS A.
ON: The interior and boundary of one object is on the boundary of the other object (and the second object covers the first object). This relationship occurs, for example, when a line is on the boundary of a polygon.
Figure 16 illustrates these topological relationships.
The SDO_WITHIN_DISTANCE operator determines if two spatial objects, A and B, are within a specified distance of one another. This operator first constructs a distance buffer, D_{b}, around the reference object B. It then checks that A and D_{b} are nondisjoint. The distance buffer of an object consists of all points within the given distance from that object. Figure 17 shows the distance buffers for a point, a line, and a polygon.
Figure 17 Distance Buffers for Points, Lines, and Polygons
In the point, line, and polygon geometries shown in Figure 17:
The dashed lines represent distance buffers. Notice how the buffer is rounded near the corners of the objects.
The geometry on the right is a polygon with a hole: the large rectangle is the exterior polygon ring and the small rectangle is the interior polygon ring (the hole). The dashed line outside the large rectangle is the buffer for the exterior ring, and the dashed line inside the small rectangle is the buffer for the interior ring.
The SDO_NN operator returns a specified number of objects from a geometry column that are closest to a specified geometry (for example, the five closest restaurants to a city park). In determining how close two geometry objects are, the shortest possible distance between any two points on the surface of each object is used.
The Spatial PL/SQL application programming interface (API) includes several operators and many procedures and functions.
Spatial operators, such as SDO_FILTER and SDO_RELATE, provide optimum performance because they use the spatial index. (Spatial operators require that the geometry column in the first parameter have a spatial index defined on it.) Spatial operators must be used in the WHERE clause of a query. The first parameter of any operator specifies the geometry column to be searched, and the second parameter specifies a query window. If the query window does not have the same coordinate system as the geometry column, Spatial performs an implicit coordinate system transformation. For detailed information about the spatial operators, see Chapter 19.
Spatial procedures and functions are provided as subprograms in PL/SQL packages, such as SDO_GEOM, SDO_CS, and SDO_LRS. These subprograms do not require that a spatial index be defined, and they do not use a spatial index if it is defined. These subprograms can be used in the WHERE clause or in a subquery. If two geometries are input parameters to a Spatial procedure or function, both must have the same coordinate system.
The following performancerelated guidelines apply to the use of spatial operators, procedures, and functions:
If an operator and a procedure or function perform comparable operations, and if the operator satisfies your requirements, use the operator. For example, unless you need to do otherwise, use SDO_RELATE instead of SDO_GEOM.RELATE, and use SDO_WITHIN_DISTANCE instead of SDO_GEOM.WITHIN_DISTANCE.
With operators, always specify TRUE
in uppercase. That is, specify = 'TRUE'
, and do not specify <> 'FALSE'
or = 'true'
.
With operators, use the /*+ ORDERED */
optimizer hint if the query window comes from a table. (You must use this hint if multiple windows come from a table.) See the Usage Notes and Examples for specific operators for more information.
For information about using operators with topologies, see Oracle Spatial Topology and Network Data Models Developer's Guide.
SQL has long had aggregate functions, which are used to aggregate the results of a SQL query. The following example uses the SUM aggregate function to aggregate employee salaries by department:
SELECT SUM(salary), dept FROM employees GROUP BY dept;
Oracle Spatial aggregate functions aggregate the results of SQL queries involving geometry objects. Spatial aggregate functions return a geometry object of type SDO_GEOMETRY. For example, the following statement returns the minimum bounding rectangle of all geometries in a table (using the definitions and data from Section 2.1):
SELECT SDO_AGGR_MBR(shape) FROM cola_markets;
The following example returns the union of all geometries except cola_d
:
SELECT SDO_AGGR_UNION(SDOAGGRTYPE(c.shape, 0.005)) FROM cola_markets c WHERE c.name <> 'cola_d';
For reference information about the spatial aggregate functions and examples of their use, see Chapter 20.
Note:
Spatial aggregate functions are supported for twodimensional geometries only, except for SDO_AGGR_MBR, which is supported for both twodimensional and threedimensional geometries.Many spatial aggregate functions accept an input parameter of type SDOAGGRTYPE. Oracle Spatial defines the object type SDOAGGRTYPE as:
CREATE TYPE sdoaggrtype AS OBJECT ( geometry SDO_GEOMETRY, tolerance NUMBER);
Note:
Do not use SDOAGGRTYPE as the data type for a column in a table. Use this type only in calls to spatial aggregate functions.The tolerance
value in the SDOAGGRTYPE definition should be the same as the SDO_TOLERANCE value specified in the DIMINFO column in the xxx_SDO_GEOM_METADATA views for the geometries, unless you have a specific reason for wanting a different value. For more information about tolerance, see Section 1.5.5; for information about the xxx_SDO_GEOM_METADATA views, see Section 2.8.
The tolerance
value in the SDOAGGRTYPE definition can affect the result of a spatial aggregate function. Figure 18 shows a spatial aggregate union (SDO_AGGR_UNION) operation of two geometries using two different tolerance values: one smaller and one larger than the distance between the geometries.
Figure 18 Tolerance in an Aggregate Union Operation
In the first aggregate union operation in Figure 18, where the tolerance is less than the distance between the rectangles, the result is a compound geometry consisting of two rectangles. In the second aggregate union operation, where the tolerance is greater than the distance between the rectangles, the result is a single geometry.
Effective with Oracle Database Release 11.1, Oracle Spatial supports the storage and retrieval of threedimensional spatial data, which can include points, point clouds (collections of points), lines, polygons, surfaces, and solids. Table 11 show the SDO_GTYPE and SDO_ELEM_INFO attributes of the SDO_GEOMETRY type that are relevant to threedimensional geometries. (The SDO_GEOMETRY type is explained in Section 2.2.)
Table 11 SDO_GEOMETRY Attributes for ThreeDimensional Geometries
Type of 3D Data  SDO_GTYPE  Element Type, Interpretation in SDO_ELEM_INFO 

Point 
3001 
(Does not apply. Specify all 3 dimension values in the SDO_POINT_TYPE attribute.) 
Line 
3002 
2, 1 
Polygon 
3003 
1003, 1: planar exterior polygon 2003, 1: planar interior polygon 1003, 3: planar exterior rectangle 2003, 3: planar interior rectangle 
Surface 
3003 
1006, 1: surface (followed by element information for the polygons) 
Collection 
3004 
(Same considerations as for twodimensional) 
Multipoint (point cloud) 
3005 
1, n (where n is the number of points) 
Multiline 
3006 
(Same considerations as for twodimensional) 
Multisurface 
3007 
(Element definitions for one or more surfaces) 
Solid 
3008 
1007, 1: exterior surface (followed by element information for the surface) 2006, 1: interior surface (zero or more, each followed by element information for the surface) 
Multisolid 
3009 
(Element definitions for one or more solids) 
The following Spatial operators consider all three dimensions in their computations:
SDO_ANYINTERACT (and SDO_RELATE with the ANYINTERACT mask)
The other operators consider only the first two dimensions. (Spatial operators are described in Chapter 19.)
The SDO_GEOM.SDO_VOLUME function applies only to solid geometries, which are by definition threedimensional; however, this function cannot be used with geodetic data. (This function is described in Chapter 24.)
For distance computations with threedimensional geometries:
If the data is geodetic (geographic 3D), the distance computations are done on the geodetic surface.
If the data is nongeodetic (projected or local), the distance computations are valid only if the unit of measure is the same for all three dimensions.
To have any functions, procedures, or operators consider all three dimensions, you must specify PARAMETERS ('sdo_indx_dims=3')
in the CREATE INDEX statement when you create the spatial index on a spatial table.
For Spatial functions, procedures, and operators that consider all three dimensions, distance and length computations correctly factor in the height or elevation. For example, consider two threedimensional points, one at the origin of a Cartesian space (0,0,0), and the other at X=3 on the Y axis and a height (Z) of 4 (3,0,4).
If the operation considers all three dimensions, the distance between the two points is 5. (Think of the hypotenuse of a 345 right triangle.)
If the operation considers only two dimensions, the distance between the two points is 3. (That is, the third dimension, or height, is ignored.)
For examples of creating different types of threedimensional spatial geometries, see Section 2.7.9. That section also includes an example showing how to update the spatial metadata and create spatial indexes for threedimensional geometries.
For information about support for threedimensional coordinate reference systems, see Section 6.5.
Threedimensional support does not apply to many spatial aggregate functions and PL/SQL packages and subprograms. The following are supported for twodimensional geometries only:
Spatial aggregate functions, except for SDO_AGGR_MBR, which is supported for both twodimensional and threedimensional geometries.
SDO_GEOM (geometry) subprograms, except for the following, which are supported for both twodimensional and threedimensional geometries:
SDO_GEOM.RELATE with the ANYINTERACT mask
SDO_SAM (spatial analysis and mining) subprograms
SDO_MIGRATE.TO_CURRENT procedure
A surface contains an area but not a volume, and it can have two or three dimensions. A surface is often constructed by a set of planar regions.
Surfaces can be modeled as surfacetype SDO_GEOMETRY objects or, if they are very large, as SDO_TIN objects. The surfacetype in SDO_GEOMETRY can be an arbitrary surface defining a contiguous area bounded by adjacent threedimensional polygons. The number of polygons in the SDO_GEOMETRY is limited by the number of ordinates that can be in the SDO_ORDINATES_ARRAY. An SDO_TIN object, on the other hand, models the surface as a network of triangles with no explicit limit on the number of triangles.
Surfaces are stored as a network of triangles, called triangulated irregular networks, or TINs. The TIN model represents a surface as a set of contiguous, nonoverlapping triangles. Within each triangle the surface is represented by a plane. The triangles are made from a set of points called mass points. If mass points are carefully selected, the TIN represents an accurate the model of the surface. Wellplaced mass points occur where there is a major change in the shape of the surface, for example, at the peak of a mountain, the floor of a valley, or at the edge (top and bottom) of cliffs.
TINs are generally computed from a set of threedimensional points specifying coordinate values in the longitude (x), latitude (y), and elevation (z) dimensions. Oracle TIN generation software uses the Delaunay triangulation algorithm, but it is not required that TIN data be formed using only Delaunay triangulation techniques.
During and after the generation of TINs, you can specify break lines, stop lines, and planar surface areas:
Break lines typically represent road networks, cliffs, and ridges.
Stop lines typically indicate places where the elevation lines are not continuous, such as the slope from the top to the bottom of a cliff. Such regions are to be excluded from the TIN.
Planar surface areas typically represent natural features such as lakes. These features have a constant elevation and are typically stored as polygon geometries.
The general process for working with a TIN is as follows:
Initialize the TIN, using the SDO_TIN_PKG.INIT function.
Create the TIN, using the SDO_TIN_PKG.CREATE_TIN procedure.
As needed for queries, clip the TIN, using the SDO_TIN_PKG.CLIP_TIN function.
If necessary, use the SDO_TIN_PKG.TO_GEOMETRY function (for example, to convert the result of a clip operation into a single SDO_GEOMETRY object).
The PL/SQL subprograms for working with TINs are described in Chapter 30.
For a Java example of working with TINs, see the following files:
$ORACLE_HOME/md/demo/TIN/examples/java/README.txt $ORACLE_HOME/md/demo/TIN/examples/java/readTIN.java
The simplest types of solids can be represented as cuboids, such as a cube or a brick. A more complex solid is a frustum, which is a pyramid formed by cutting a larger pyramid (with three or more faces) by a plane parallel to the base of that pyramid. Frustums can only be used as query windows to spatial operators. Frustums and cubes are typically modeled as solidtype SDO_GEOMETRY objects. Figure 19 shows a frustum as a query window, with two spatial objects at different distances from the view point.
Figure 19 Frustum as Query Window for Spatial Objects
Point clouds, which are large collections of points, can sometimes be used to model the shape or structure of solid and surface geometries. Most applications that use point cloud data contain one of both of the following kinds of spatial queries: queries based on location, and queries based on both location and visibility (that is, visibility queries).
Most applications that use point cloud data seek to minimize data transfer by retrieving objects based on their distance from a view point. For example, in Figure 19, object B is farther from the view point than object A, and therefore the application might retrieve object A in great detail (high resolution) and object B in less detail (low resolution). In most scenarios, the number of objects increases significantly as the distance from the view point increases; and if farther objects are retrieved at lower resolutions than nearer objects, the number of bytes returned by the query and the rendering time for the objects decrease significantly.
The general process for working with a point cloud is as follows:
Initialize the point cloud, using the SDO_PC_PKG.INIT function.
Create the point cloud, using the SDO_PC_PKG.CREATE_PC procedure.
As needed for queries, clip the point cloud, using the SDO_PC_PKG.CLIP_PC function.
If necessary, use the SDO_PC_PKG.TO_GEOMETRY function (for example, to convert the result of a clip operation into a single SDO_GEOMETRY object).
The PL/SQL subprograms for working with point clouds are described in Chapter 28.
For a Java example of working with point clouds, see the following files:
$ORACLE_HOME/md/demo/PointCloud/examples/java/README.txt $ORACLE_HOME/md/demo/PointCloud/examples/java/readPointCloud.java
The SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT and SDO_GEOM.VALIDATE_LAYER_WITH_CONTEXT subprograms can validate twodimensional and threedimensional geometries. For a threedimensional geometry, these subprograms perform any necessary checks on any twodimensional geometries (see the Usage Notes for SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT) within the overall threedimensional geometry, but also several checks specific to the threedimensional nature of the overall object.
For a simple solid (one outer surface and any number of inner surfaces), these subprograms perform the following checks:
Closedness: The solid must be closed.
Reachability: Each face of a solid must have a fulledge intersection with its neighboring faces, and all faces must be reachable from any face.
Innerouter disjointedness: An inner surface must not intersect the outer surface at more than a point or a line; that is, there must be no overlapping areas with inner surfaces.
No surface patch: No additional surfaces can be defined on the surfaces that make up the solid.
Orientation: For all surfaces, the vertices must be aligned so that the normal vector (or surface normal, or "the normal") points to the outside of (away from) the outer solid. Thus, the volume of the outer solid must be greater than zero, and the volume of any inner solid must be less than zero.
For a composite solid (one or more solids connected to each other), these subprograms perform the following checks:
Connectedness: All solids of a composite solid must share at least one face.
Zerovolume intersections: Any intersections of the solids in a composite solid must have a volume of zero.
For a multisolid (one or more solids, each of which is a simple or composite solid), these subprograms perform the following check:
Disjointedness: Any two solids of a multisolid can share points or lines, but must not intersect in any other manner.
Geocoding is the process of converting tables of address data into standardized address, location, and possibly other data. The result of a geocoding operation includes the pair of longitude and latitude coordinates that correspond with the input address or location. For example, if the input address is 22 Monument Square, Concord, MA 01742, the longitude and latitude coordinates in the result of the geocoding operation may be (depending on the geocoding data provider) 71.34937 and 42.46101, respectively.
Given a geocoded address, you can perform proximity or location queries using a spatial engine, such as Oracle Spatial, or demographic analysis using tools and data from Oracle's business partners. In addition, you can use geocoded data with other spatial data such as block group, postal code, and county code for association with demographic information. Results of analyses or queries can be presented as maps, in addition to tabular formats, using thirdparty software integrated with Oracle Spatial.
For conceptual and usage information about the geocoding capabilities of Oracle Spatial, see Chapter 11. For reference information about the MDSYS.SDO_GCDR PL/SQL package, see Chapter 23.
Oracle Spatial provides a Java application programming interface (API) that includes the following packages:
oracle.spatial.geometry
provides support for the Spatial SQL SDO_GEOMETRY data type, which is documented in this guide.
oracle.spatial.network
provides support for the Oracle Spatial network data model, which is documented in Oracle Spatial Topology and Network Data Models Developer's Guide.
oracle.spatial.topo
provides support for the Oracle Spatial topology data model, which is documented in Oracle Spatial Topology and Network Data Models Developer's Guide.
oracle.spatial.util
provides classes that perform miscellaneous operations.
For detailed reference information about the classes and interfaces in these packages, see Oracle Spatial Java API Reference (Javadoc).
During installation, Spatial creates user accounts that have the minimum privileges needed to perform their jobs. These accounts are created locked and expired; so if you need to use the accounts, you must unlock them. Table 12 lists the predefined user accounts created by Spatial.
Table 12 Predefined User Accounts Created by Spatial
User Account  Description 

MDDATA 
The schema used by Oracle Spatial for storing data used by geocoding and routing applications. This is the default schema for Oracle software that accesses geocoding and routing data. 
SPATIAL_CSW_ADMIN_USR 
The Catalog Services for the Web (CSW) account. It is used by the Oracle Spatial CSW cache manager to load all record type metadata, and record instances from the database into the main memory for the record types that are cached. 
SPATIAL_WFS_ADMIN_USR 
he Web Feature Service (WFS) account. It is used by the Oracle Spatial WFS cache manager to load all feature type metadata, and feature instances from the database into main memory for the feature types that are cached. 
For information about Oracle Database predefined user accounts, including how to secure these accounts, see Oracle Database 2 Day + Security Guide.
Many factors can affect the performance of Oracle Spatial applications, such as the use of optimizer hints to influence the plan for query execution. This guide contains some information about performance and tuning where it is relevant to a particular topic. For example, Section 1.7.2 discusses Rtree quality and its possible effect on query performance, and Section 1.9 explains why spatial operators provide better performance than procedures and functions.
In addition, more Spatial performance and tuning information is available in one or more white papers through the Oracle Technology Network (OTN). That information is often more detailed than what is in this guide, and it is periodically updated as a result of internal testing and consultations with Spatial users. To find that information on the OTN, go to
http://www.oracle.com/technology/products/spatial/
Look for material relevant to Spatial performance and tuning.
Oracle Spatial is conformant with Open Geospatial Consortium (OGC) Simple Features Specification 1.1.1 (Document 99049), starting with Oracle Database release 10g (version 10.1.0.4). Conformance with the SQL92 with Geometry Types Implementation means that Oracle Spatial supports all the types, functions, and language constructs detailed in Section 3.2 of the specification.
Synonyms are created to match all OGC function names except for X(p Point)
and Y(p Point)
. For these functions, you must use the names OGC_X
and OGC_Y
instead of just X
and Y
.
To check which release of Spatial you are running, use the SDO_VERSION function. For example:
SELECT SDO_VERSION FROM DUAL; SDO_VERSION  11.1.0.0.0
This section discusses some general guidelines that affect the amount of disk storage space and CPU power needed for applications that use Oracle Spatial. These guidelines are intended to supplement, not replace, any other guidelines you use for general application sizing.
The following characteristics of spatial applications can affect the need for storage space and CPU power:
Data volumes: The amount of storage space needed for spatial objects depends on their complexity (precision of representation and number of points for each object). For example, storing one million point objects takes less space than storing one million road segments or land parcels. Complex natural features such as coastlines, seismic fault lines, rivers, and land types can require significant storage space if they are stored at a high precision.
Query complexity: The CPU requirements for simple mapping queries, such as Select all features in this rectangle, are lower than for more complex queries, such as Find all seismic fault lines that cross this coastline.
Spatial error message numbers are in the range of 13000 to 13499. The messages are documented in Oracle Database Error Messages.
Oracle error message documentation is only available in HTML. If you only have access to the Oracle Documentation DVD, you can browse the error messages by range. Once you find the specific range, use your browser's "find in page" feature to locate the specific message. When connected to the Internet, you can search for a specific error message using the error message search feature of the Oracle online documentation.
Oracle Spatial provides examples that you can use to reinforce your learning and to create models for coding certain operations. If you installed the demo files from the Oracle Database Examples media, several examples are provided in the following directory:
$ORACLE_HOME/md/demo/examples
The following files in that directory are helpful for applications that use the Oracle Call Interface (OCI):
readgeom.c
and readgeom.h
writegeom.c
and writegeom.h
This guide also includes many examples in SQL and PL/SQL. One or more examples are usually provided with the reference information for each function or procedure, and several simplified examples are provided that illustrate table and index creation, combinations of functions and procedures, and advanced features:
Inserting, indexing, and querying spatial data (Section 2.1)
Coordinate systems (spatial reference systems) (Section 6.12)
Linear referencing system (LRS) (Section 7.7)
SDO_GEOMETRY objects in functionbased indexes (Section 9.2)
Complex queries (Appendix C)
A README.txt
file supplements the information in the following manuals: Oracle Spatial Developer's Guide (this manual), Oracle Spatial GeoRaster Developer's Guide, and Oracle Spatial Topology and Network Data Models Developer's Guide. This file is located at:
$ORACLE_HOME/md/doc/README.txt