SDO_TOPO.RELATE

Format

SDO_TOPO.RELATE(     
  geom1  IN SDO_TOPO_GEOMETRY,      
  geom2  IN SDO_TOPO_GEOMETRY,      
  mask   IN VARCHAR2      
) RETURN VARCHAR2;

or

SDO_TOPO.RELATE(
  feature1  IN SDO_TOPO_GEOMETRY,
  feature2  IN SDO_GEOMETRY,
  mask      IN VARCHAR2
) RETURN VARCHAR2;

or

SDO_TOPO.RELATE(
  geom            IN SDO_TOPO_GEOMETRY,
  topo_elem_array IN SDO_TOPO_OBJECT_ARRAY,
  mask            IN VARCHAR2      
) RETURN VARCHAR2;

Description

Examines two topology geometry objects, or a topology geometry and a spatial geometry, or a topology geometry and a topology object array (SDO_TOPO_OBJECT_ARRAY object), to determine their spatial relationship.

Parameters

geom1: Topology geometry object.
geom2: Topology geometry object.
feature1: Topology geometry object.
feature2: Spatial geometry object.
geom: Topology geometry object.
topo_elem_array: Topology object array (of type SDO_TOPO_OBJECT_ARRAY, which is described in Constructors for Insert Operations: Specifying Topological Elements).
mask: Specifies one or more relationships to check. See the list of keywords in the Usage Notes.

Usage Notes

The topology operators (described in Topology Operators) provide better performance than the SDO_TOPO.RELATE function if you are checking a large number of objects; however, if you are checking just two objects or a small number, the SDO_TOPO.RELATE function provides better performance. In addition, sometimes you may need to use the SDO_TOPO.RELATE function instead of a topology operator. For example, you cannot specify the DETERMINE mask keyword with the topology operators.

The following keywords can be specified in the mask parameter to determine the spatial relationship between two objects:

ANYINTERACT: Returns TRUE if the objects are not disjoint.
CONTAINS: Returns TRUE if the second object is entirely within the first object and the object boundaries do not touch; otherwise, returns FALSE.
COVEREDBY: Returns TRUE if the first object is entirely within the second object and the object boundaries touch at one or more points; otherwise, returns FALSE.
COVERS: Returns TRUE if the second object is entirely within the first object and the boundaries touch in one or more places; otherwise, returns FALSE.
DETERMINE: Returns the one relationship keyword that best matches the geometries.
DISJOINT: Returns TRUE if the objects have no common boundary or interior points; otherwise, returns FALSE.
EQUAL: Returns TRUE if the objects share every point of their boundaries and interior, including any holes in the objects; otherwise, returns FALSE.
INSIDE: Returns TRUE if the first object is entirely within the second object and the object boundaries do not touch; otherwise, returns FALSE.
ON: Returns TRUE if the boundary and interior of a line (the first object) is completely on the boundary of a polygon (the second object); otherwise, returns FALSE.
OVERLAPBDYDISJOINT: Returns TRUE if the objects overlap, but their boundaries do not interact; otherwise, returns FALSE.
OVERLAPBDYINTERSECT: Returns TRUE if the objects overlap, and their boundaries intersect in one or more places; otherwise, returns FALSE.
TOUCH: Returns TRUE if the two objects share a common boundary point, but no interior points; otherwise, returns FALSE.

Values for mask (except for DETERMINE) can be combined using the logical Boolean operator OR. For example, 'INSIDE + TOUCH' returns the string TRUE or FALSE depending on the outcome of the test.

Examples

The following example finds whether or not the ANYINTERACT relationship exists between each topology geometry object in the CITY_STREETS table and the P3 land parcel (that is, which streets interact with that land parcel). (The example refers to definitions and data from Topology Examples (PL/SQL). The output is reformatted for readability.)

SELECT c.feature_name,
  SDO_TOPO.RELATE(c.feature, l.feature, 'anyinteract') Any_Interaction
  FROM city_streets c, land_parcels l WHERE l.feature_name = 'P3';
 
FEATURE_NAME  ANY_INTERACTION                                                                     
------------  ---------------        
R1            TRUE
R2            FALSE                
R3            FALSE                            
R4            FALSE

The following example finds whether or not the ANYINTERACT relationship exists between each topology geometry object in the CITY_STREETS table and an SDO_TOPO_OBJECT_ARRAY object that happens to be identical to the land parcel feature named P3. (This example uses definitions and data from Topology Examples (PL/SQL).) The output is identical to that in the preceding example, and is reformatted for readability.

SELECT c.feature_name, 
  SDO_TOPO.RELATE(c.feature,
    SDO_TOPO_OBJECT_ARRAY (SDO_TOPO_OBJECT (5, 3), SDO_TOPO_OBJECT (8, 3)), 
    'anyinteract') Any_Interaction 
  FROM city_streets c, land_parcels l WHERE l.feature_name = 'P3';
 
FEATURE_NAME  ANY_INTERACTION                                                                     
------------  ---------------        
R1            TRUE
R2            FALSE                
R3            FALSE                            
R4            FALSE